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.
Turn it on
Section titled “Turn it on”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.
What happens on the first call
Section titled “What happens on the first call”- 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. - Stage calls
Describewith the host endpoint and a credential for the system. - The backend answers what it realizes. Stage checks it against the contract and checks the protocol major.
- 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.
Run order
Section titled “Run order”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.
Security notes
Section titled “Security notes”- 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.
What is available today
Section titled “What is available today”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.