Skip to content

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.

  • Stage listens on its own gRPC port, separate from the application’s. It is off until Stage:Extensions:HostPort is set. See Connect a backend to Stage.
  • Every call carries authorization: Bearer <session_token> metadata. The token comes from the Describe handshake, 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 Describe has returned. A call before that is refused with FAILED_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 RequestContext of the invocation you are working on, so what you report is tied to it.
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.

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.

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.

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 holding system, tenant, invocation, attempt, origin and causation, and each attribute as attr.<key>. They go wherever Stage’s logs go.
  • Metrics are recorded on the meter Cratis.Stage.Extensions as the instrument stage.extension.<name>, a counter or a histogram, tagged with stage.extension.system, stage.tenant and 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.invoke on the Cratis.Stage.Extensions source for each attempt and sends its W3C trace context in RequestContext.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.