Skip to content

Extension backends

A Screenplay system declares what the business can ask an outside system to do: post to a chat channel, book a pickup, take a payment. The model names the abilities; an extension backend is the code that realizes them. Stage hosts backends outside its own process and talks to them over a two-way gRPC protocol, so a backend can be written in any language and needs as little infrastructure of its own as possible: it asks Stage for its settings, its secrets and its telemetry instead of building them.

This section is the reference for that protocol, the services Stage offers, and the SDKs that implement the extension side for C#, Kotlin, Go and TypeScript. It implements section 9 of decision 0159.

.play model Stage (this repository) Extension backend
----------- ------------------------------ -----------------
system Slack durable invocation (Choreography) your code, any language
ability Post ───────► IAbilityBackend ──── ExtensionBackend (gRPC) ──► describe / invoke /
trigger Replied ▲ handle HTTP / health
│
StageHost (gRPC) ◄────────────────────────────── settings, secrets, raise
host services trigger, answer later,
logs and metrics
  • Screenplay defines the contract: the system, its abilities, their effect classes and outcomes. Read the systems and abilities page.

  • Stage runs each ability invocation as a durable, retried, deduplicated message. See Durable ability invocations and the Choreography page on answers that arrive later and reconciliation.

  • Inbound traffic, such as a webhook, is stored and acknowledged by Stage, then delivered to the extension, which raises the contract’s triggers. See inbound traffic and webhooks and the Screenplay triggers page.

  • The extension protocol is the seam between the two: for every attempt Stage calls the backend, and the backend answers with what happened.

  • A model reaches a running extension through the catalogs Stage builds from the compiled model and the locked packages. See From a model to a running extension.

Decision, recorded here because it was left open by decision 0159: the protocol and the SDKs live in the Cratis/Stage repository, under Source/Extensions.

What Where
The protocol, as versioned .proto files Source/Extensions/Protocol
C# SDK (Cratis.Stage.Extensions) Source/Extensions/DotNET
Kotlin SDK (io.cratis.stage:stage-extensions) Source/Extensions/Kotlin
Go SDK (github.com/Cratis/Stage/Source/Extensions/Go) Source/Extensions/Go
TypeScript SDK (@cratis/stage-extensions) Source/Extensions/TypeScript
The conformance suite every SDK passes Source/Extensions/Conformance

Why one repository: the protocol and the host that implements it change together, an SDK is only correct against the protocol it was built from, and one conformance suite is easiest to keep honest when every SDK sits beside it. Splitting an SDK out later is a move, not a redesign, because each one depends on the .proto files alone.

Included: every direction the protocol needs to realize abilities durably.

Direction Service Included
Stage to extension ExtensionBackend Describe (handshake against the contract), Invoke (one attempt), HandleHttp (routed inbound HTTP), Health
Extension to Stage StageHost GetSetting, GetSecret, RaiseTrigger, Answer, Log, RecordMetrics

Every request carries the tenant, the invocation identity, the idempotency key, the attempt, the deadline and the trace context.

Left out of version one, deliberately:

  • A key-value state store scoped to system and tenant. An extension that needs to remember something between calls has the idempotency key and the invocation identity Stage already keeps durably, and can use its own store. A host-owned store would make Stage responsible for another persistence surface with its own tenant isolation, size limits, retention and migration story, and it cannot be removed once extensions depend on it. Adding a service to the protocol is a backward-compatible minor version, so it can follow when a real extension needs it.
  • An outbound credential proxy. The point is that a secret never enters the extension. That is a real security gain, but it needs a declarative way to say which hosts an extension may reach and how a credential is attached, and that belongs in the contract the language defines (Cratis/Screenplay#1254), not in the transport. Until then secrets reach the extension only through GetSecret, held in memory, never in an environment variable or a file Stage writes.

Both are reserved: a future minor version adds them as new services without changing the ones above.

The frontend side of an extension, the components it ships for screens, is separate. See the Scene blueprint components for how screens are composed, and Cratis/Stage#1070 for how Stage hosts them.