Host services reference
Stage offers extensions the services below through service StageHost, defined in
host.proto. An extension needs
no infrastructure of its own for any of them.
Calling the host services
Section titled “Calling the host services”- Stage listens on its own gRPC port, separate from the application’s. It is off until
Stage:Extensions:HostPortis set. See Connect a backend to Stage. - Every call carries
authorization: Bearer <session_token>metadata. The token comes from theDescribehandshake, is scoped to one system, and lives as long as the Stage process. - The system always comes from the token, never from the request. An extension cannot read another system’s settings, answer another system’s invocations or raise another system’s triggers by naming them.
- Call the host services only after
Describehas returned. A call before that is refused withFAILED_PRECONDITION, because Stage learns what the extension declared from the handshake. - A call without a token, or with one Stage did not issue, is refused with
UNAUTHENTICATED. - Pass the
RequestContextof the invocation you are working on, so what you report is tied to it.
Settings and secrets
Section titled “Settings and secrets”| Rpc | Returns |
|---|---|
GetSetting(name) |
A public setting: FOUND with the value, NOT_SET, UNKNOWN (not declared by the extension), or IS_SECRET (declared as a secret; ask GetSecret). |
GetSecret(name) |
A secret: FOUND with the value, NOT_SET, UNKNOWN, or NOT_SECRET (declared as a public setting; ask GetSetting). |
The two are separate on purpose. A value declared secret is never returned by GetSetting, so a public setting that can reach a browser and
a secret that never does cannot be mixed up by a typo.
Where Stage reads values from: configuration, under systems:<System>:<name>, which is the environment variable systems__<System>__<name> on
the Stage process or any other configuration provider, such as a secret store mounted by the deployment. This matches the default of
decision 0159: a
setting is systems.<System>.<setting> unless the model names a secret explicitly. The model-side naming (secret <Name>, setting <name> from secret <Name>) is language work tracked in Cratis/Screenplay#1254; the lookup is behind
ISystemSettings, so it plugs in without changing the protocol.
How secrets are kept:
- A secret reaches the extension only through
GetSecret. Stage never puts one in the extension’s environment or in a file. - Stage never logs a secret value.
- The extension should keep a secret in memory only, never log it, and never put it in an ability’s output, which Stage persists.
Raise a trigger
Section titled “Raise a trigger”RaiseTrigger(trigger, deduplication_key, payload_json, correlation_key) raises a trigger the extension’s contract declares, so a workflow that waits for it
resumes. Starting the reactions to a trigger needs trigger routes, which no language support registers yet (see below). A webhook handler or a poll uses it; see inbound traffic and webhooks.
| Status | Meaning |
|---|---|
RAISED |
Every reaction was started, or already had been for this key, or a run that waits for the trigger resumed. |
UNKNOWN_TRIGGER |
The extension did not declare this trigger at the handshake. |
NOT_ROUTED |
Nothing in the model reacts to the trigger and no run waiting for it resumed. It is reported, never silently accepted, because a raise that does nothing is a bug worth seeing. |
REFUSED |
The deduplication key is missing, or the runtime did not admit a reaction. detail says which. |
The deduplication key is required. Once trigger routes exist, raising the same trigger with the same key again will find the runs the first raise started instead of starting more. Today Stage does not deduplicate a resume: the same wait cannot be resolved twice, but a repeated raise resumes any wait about the same correlation that is open by then, including a later wait in a run the first raise resumed. Deduplicate a retry, or a webhook the provider delivers twice, before raising. Inside an invocation use its idempotency key; for a webhook use the external message’s own identity.
The optional correlation key says what the trigger is about, such as the payment a webhook reports on. Runs that wait for <System>.<Trigger> about the same
correlation resume, with the payload as the wait’s data. Once trigger routes exist, the reactions will run as the actor extension:<System>, never as the
anonymous sender of a webhook.
Only the C# SDK’s Trigger accepts a correlation key; the TypeScript, Kotlin and Go SDKs raise a trigger without one, so from them a trigger resumes no
waiting run.
Stage will start each reacting workflow as a Choreography Signal trigger, deduplicated on the trigger, the key and the workflow. Which workflows
react to which trigger is supplied by the language support for reactions (IContractTriggerRoutes). No language support registers routes yet,
so a raise that resumes no waiting run is answered NOT_ROUTED.
Answer later
Section titled “Answer later”An ability that returns Accepted completes later with Answer(context.invocation_id, outlet, payload_json). The outlet is returned or one
of the outcomes the ability declares.
| Status | Meaning |
|---|---|
ANSWERED |
The answer was taken. Answering twice is harmless. |
UNKNOWN_INVOCATION |
No invocation has this identity. |
NOT_WAITING |
The invocation is not waiting for an answer: it already finished or has not been accepted yet. |
FORBIDDEN |
The invocation belongs to another system. |
UNKNOWN_OUTLET |
The ability does not declare this outlet. |
A backend answers as the system it serves. It may answer only the invocations of its own system, and the persona or policy meant for people
who answer (AnswerPolicy) does not apply to it. Who answered is recorded with the invocation.
The identity is the key: keep invocation_id so a later event, such as a callback arriving over HTTP, can complete the invocation without Stage
holding a worker meanwhile.
Logs and metrics
Section titled “Logs and metrics”Log(records) and RecordMetrics(metrics) are tied to the invocation named in the context.
- Logs are written to Stage’s logging under the category
Cratis.Stage.Extensions.<System>, with a scope holdingsystem,tenant,invocation,attempt,originandcausation, and each attribute asattr.<key>. They go wherever Stage’s logs go. - Metrics are recorded on the meter
Cratis.Stage.Extensionsas the instrumentstage.extension.<name>, a counter or a histogram, tagged withstage.extension.system,stage.tenantand the attributes. They are exported wherever Stage’s OpenTelemetry metrics go. A system may record 64 distinct metrics; the rest are ignored, so a bug cannot flood the host. A metric of an unspecified kind is ignored. - Traces. Stage starts an activity
extension.invokeon theCratis.Stage.Extensionssource for each attempt and sends its W3C trace context inRequestContext.traceparent. An extension that uses OpenTelemetry continues that trace by using the context as its parent, and exports its own spans itself. The protocol carries no span data in version one.
The system on every log and metric comes from the token. Attributes are free-form: put no secret and no personal data in them or in a message.
See also
Section titled “See also”- Protocol reference
- Connect a backend to Stage
- Inbound traffic and webhooks
- Screenplay triggers and reactions, the model side of raising a trigger