Skip to main content
Version: v2

Trigger services

The runtime model that pins a component instance and dispatches external work to it through ingresses.​

A trigger service is a wasmCloud runtime construct: one long-lived component instance is pinned under a single store, and the host delivers external invocations into that same instance through one or more ingresses. If the component exports wasi:cli/run, that runs as a background task; inbound invocations run alongside it as concurrent per-invocation tasks against the same instance, so in-memory state (e.g., pools, caches, counters, connections) is visible to every handler and to any long-running work.

The trigger-service model backs two user-facing roles in wasmCloud today:

  • Services: the stateful component in a workload's service: slot, providing localhost/TCP and persistent state to companion components.
  • Host component plugins: a component that provides a host capability to other workloads, called across a store boundary.

Both are driven by the same runtime construct. The differences are which ingresses they use and what role they play in the platform.

Ingresses​

An ingress is a channel the host delivers external invocations through. Each host-invoked export a trigger service declares wires up exactly one ingress; all ingress traffic lands on the same pinned instance.

Three ingress kinds are available:

HTTP ingress​

A trigger service that exports wasi:http/handler@0.3.0 receives inbound HTTP requests through the HTTP ingress. Responses stream back to the client incrementally as the handler produces them; WASH_HTTP_RESPONSE_TIMEOUT_SECS is the overall-timeout backstop.

When a service runs with multiple replicas on a host, the HTTP ingress distributes inbound requests across the replicas (as of wasmCloud 2.6.0). Each replica is its own pinned instance with its own in-memory state; replicas that stop leave the rotation.

Messaging ingress​

A trigger service that exports wasmcloud:messaging/handler receives inbound messages through the messaging ingress. As of wasmCloud 2.6.0, the built-in messaging plugins deliver through this ingress for service workloads: a service exporting the handler receives every message on its pinned instance, while a plain component exporting the same handler is instantiated fresh per message.

As of wasmCloud 2.8.0, the messaging ingress invokes the async wasmcloud:messaging/handler@0.3.0 interface. A service must export handler@0.3.0; a service exporting only the sync handler@0.2.0 fails to start at 2.8.0. Plain components still run per message and may export either revision (the host prefers 0.3.0 when a component exports both). Messaging deliveries are bounded by WASH_MESSAGING_DELIVER_TIMEOUT_SECS (default 600 seconds, added in 2.8.0). See Interfaces for the differences between the revisions.

Capability ingress​

The capability ingress carries invocations from other workloads to a trigger service's exported capability interface. It is the ingress used by host component plugins: the plugin's capability exports (for example, a wasmcloud:messaging/consumer implementation) are dispatched to the same pinned plugin instance via this ingress. Because the caller and the plugin live in different stores, resource handles, streams, and futures that cross the boundary are relocated by the runtime rather than shared.

As of wasmCloud 2.7.0, a host component plugin can also call in the opposite direction — invoking interfaces that workloads export, via wasmcloud:host/workload-call. Those calls do not involve an ingress or any pinned instance: each runs on one of the callee workload's warm pooled instances (or a fresh store), and resource handles cannot cross in that direction at all (refused at plugin load or workload deploy). See the authoring guide for the full contract.

Instance lifecycle​

A trigger service is instantiated when its owning workload starts. The runtime instantiates the component into a dedicated store and drives that instance concurrently. From that point on:

  • Any wasi:cli/run export runs as a background task on the instance.
  • Each declared ingress is registered with the host and starts delivering invocations.
  • Every inbound invocation is spawned as a concurrent task against the pinned instance.

Supervision. If the guest instance traps, the runtime re-instantiates it within a bounded restart budget; in-flight invocations to the failed incarnation fail promptly rather than hanging. The budget is spent only on the trigger service's own faults — as of wasmCloud 2.7.0, a failure in a workload that a plugin calls via workload-call is reported to the plugin as an error value and never traps the pinned instance or consumes its restart budget.

Runaway guests. As of wasmCloud 2.8.0, guest code that spins the CPU without yielding is subject to a host backstop. When a call passes its ingress deadline (or its client disconnects), no other call on the instance is still wanted, and the guest is measurably pinned, the host traps the instance: a pooled warm instance is replaced, a service is restarted under supervision, and a host component plugin is warned first and restarted only after an escalation window (losing its in-memory state). The caller sees an error at roughly the ingress deadline instead of a hang. A guest that yields normally is never affected, and a slow guest with a disconnected client is not trapped as long as it keeps yielding. Capability calls into plugins are bounded by WASH_PLUGIN_CAPABILITY_CALL_TIMEOUT_SECS (default 600 seconds); the grace and escalation windows are tunable with WASH_ABANDONED_CALL_GRACE_SECS (default 10) and WASH_ABANDONED_CALL_ESCALATION_SECS (default 60).

Cancellation and host awareness​

Trigger services can import wasmcloud:host to observe and cooperate with their environment:

  • wasmcloud:host/identity: the pinned instance can query the workload and component identifiers of the caller currently invoking it. Resolved per-invocation from the caller's own guest task, so the answer is exact under concurrent, interleaved calls — useful for partitioning state per caller.
  • wasmcloud:host/cancel: per-invocation cooperative cancellation. A handler can identify its current job, check whether it has been asked to stop, and observe cancellation signals for long-running work — the guest chooses when to yield.
  • wasmcloud:host/workload-call (added in wasmCloud 2.7.0, host component plugins): invoke interfaces that workloads export, targeting the current caller implicitly or an explicitly opened workload.

See the authoring guide for details on using these interfaces in a component.

Considerations​

  • Single instance, not a pool. A trigger service is one instance. Blocking work in a handler blocks the tasks scheduled on the same async runtime; use non-blocking APIs and structured concurrency.
  • Shared state. All ingress handlers, wasi:cli/run, and any inter-handler background tasks share the instance's linear memory. Guard shared mutable state accordingly.
  • WASI target. The HTTP ingress requires WASI P3 (wasi:http/handler@0.3.0); the messaging ingress uses wasmcloud:messaging/handler@0.3.0 as of wasmCloud 2.8.0; the capability ingress uses the capability's own package. A trigger service that only exports wasi:cli/run can target P2 or P3 to match its imports.

Keep reading​