Skip to content

Connect a backend to Stage

The extension protocol is off by default. Nothing listens and no backend is called until you configure it, and without it abilities answer that nothing was sent, exactly as before.

Configure Stage under Stage:Extensions, in cratis-stage.json, appsettings or the environment (Stage__Extensions__HostPort):

{
"Stage": {
"Extensions": {
"HostPort": 50100,
"HostAddress": "127.0.0.1",
"AdvertisedHostEndpoint": "",
"DescribeTimeout": "00:00:10",
"Backends": {
"Slack": { "Endpoint": "http://localhost:50051" }
}
}
}
}
Option Default Meaning
HostPort 0 (off) The port Stage’s host services listen on. Setting it turns the protocol on.
HostAddress 127.0.0.1 The address they listen on. Keep loopback unless an extension runs in another container or machine.
AdvertisedHostEndpoint empty The address extensions are told to reach the host services on, when it differs from where they listen, such as http://stage:50100. Empty means http://<HostAddress>:<HostPort>.
DescribeTimeout 10 seconds How long the handshake with a backend may take.
Backends none The backend of each system by name: its gRPC Endpoint.

Settings and secrets the extension reads come from configuration under systems:<System>:<name>, for example the environment variable systems__Slack__channel or systems__Slack__token. See Host services.

  1. A model invokes an ability of the system. Stage finds the backend in Backends, or, for a system whose extension came from a locked package, starts it first; see Execution tiers and activation.
  2. Stage calls Describe with the host endpoint and a credential for the system.
  3. The backend answers what it realizes. Stage checks it against the contract and checks the protocol major.
  4. Stage keeps the connection and sends the attempt. A mismatch, an unreachable backend or a timed-out handshake is NotSent, with the reason in the invocation’s record.

Start the backend first or let Stage retry: an unreachable backend is a NotSent answer and the invocation retries it by its effect class’s rules. Start Stage with the host port configured before the backend is asked to call it, because the backend only learns the endpoint at the handshake.

  • The host services are plaintext HTTP/2 on loopback by default. If a backend runs elsewhere, keep the traffic on a private network or behind a mesh or proxy that provides TLS. Native TLS for the host services is not part of version one. Stage can call a backend at an https:// endpoint.
  • The session token is the extension’s only credential for the host services. It is delivered in the handshake and nowhere else. A backend should keep it in memory.
  • The inbound HTTP endpoint (/extensions/<System>/...) is anonymous and only exists when the protocol is on. A backend must verify what it receives; see inbound traffic and webhooks.
  • Cookies and authorization headers of Stage’s own users are never forwarded to a backend.

The protocol, the host services and the SDKs are complete. Three inputs come from other work and are empty until it lands, so no model drives them yet:

Input Filled by Until then
The abilities each system declares (IAbilityCatalog) The semantic host builds the catalog from the bound model once the packages are loaded: the abilities of each system a loaded package realizes. See from the model to a running extension. A system that no loaded package realizes has no abilities in the catalog, so an invocation of it is refused. Without a semantic model the catalog is empty, so no model invocation reaches a backend; a backend still connects, serves HTTP and its abilities can use the host services.
What reacts to each trigger (IContractTriggerRoutes) Reactions and triggers declared on a system. The inbound traffic that raises them is stored, acknowledged and delivered RaiseTrigger answers NOT_ROUTED.
Finding and starting a backend from a locked package, lazily Execution tiers and activation, on top of loaded packages A system that names no loaded package has its backend found in the Backends configuration above, and it runs where you run it.

Each is a seam in the host: register your own IExtensionEndpoints, IAbilityCatalog or IContractTriggerRoutes before the extension services, and Stage keeps it.