Rust Runtime

Rust Runtime

sigMAXruntimeRuststandardized runtimeroutingvalidationagreementsWasmtime

The Rust runtime is the host process that turns generated component artifacts into HTTP behavior.

It loads generated route metadata, exposes HTTP endpoints, executes WASM handlers through Wasmtime, registers sigMAX primitives, prepares typed inputs, collects ObjectIR output and returns JSON responses.

It should remain generic. Business-specific behavior belongs in contracts, route metadata, bindings, agreements, storage declarations and WASM artifacts.

Runtime role

The runtime is not the business application. It is the standardized execution boundary used by generated components.

What It Loads

At startup, the runtime reads a generated routes file and resolves the WASM modules referenced by each route.

Runtime input	Purpose
SIGMAX_ROUTES	Path to generated/routes.yaml; defaults to ../generated/routes.yaml.
Route definitions	HTTP method, path, handler export, WASM path, request shape, response shape, limits and bindings.
Type definitions	c_repr layouts used to encode typed request bodies into WASM memory.
WASM modules	Compiled handlers referenced by the generated route metadata.
Bindings	Declared service/storage invocation targets available to the route.
Capabilities	Runtime permissions attached to the active route.

If a route references a missing WASM module, startup fails instead of serving a partially broken component.

Request Flow

The runtime uses Axum as the HTTP server and Wasmtime as the WASM host.

For each incoming route, the runtime:

1. matches the HTTP method and path;
2. extracts route parameters or JSON body data;
3. prepares typed inputs when the route declares c_repr data;
4. creates a fresh request context;
5. attaches route capabilities and bindings;
6. loads the WASM module with Wasmtime;
7. registers sigMAX imports in the Wasmtime linker;
8. calls the exported handler function;
9. reads status and ObjectIR output from the runtime context;
10. returns a JSON response with the declared or emitted status.

Runtime Context

Each request receives a dedicated runtime context shared with WASM primitives through a thread-safe wrapper.

Context area	What it stores
Route data	Path parameters, typed inputs and available type definitions.
Policy data	Route capabilities and resolved runtime bindings.
Response state	Status, headers and ObjectIR root value.
Error state	Recorded runtime or validation errors.
Local state	In-memory state values accessible through state primitives.
ObjectIR stack	Temporary nested object/array construction state.

This context is the controlled bridge between the sandboxed module and the host runtime.

Primitive Surface

The runtime registers the host imports that generated WASM modules are allowed to call.

Primitive family	Runtime responsibility
Input	Read route parameters, headers and typed request objects.
Response	Set HTTP status and response headers.
ObjectIR	Build structured output objects and arrays.
Errors	Emit validation or runtime errors in a predictable shape.
Observability	Log messages and expose trace/metric hooks.
Capabilities	Check whether a route is allowed to use a sensitive primitive.
Regex, JSON, crypto, time	Execute bounded helper operations on the host side.
HTTP, secrets, random, invocation, state	Gate host-facing behavior through policy and limits.

The primitive layer owns pointer checks, length checks, buffer writes and stable error codes. WASM code does not receive direct access to host memory, files, sockets or process APIs.

Built-In Endpoints

The runtime also exposes a small operational surface.

Endpoint	Purpose
/healthz	Health check returning ok.
/docs and /docs/	Serves generated component documentation.
/openapi.yaml	Serves the generated OpenAPI document.
/.well-known/component	Returns component discovery metadata pointing to docs and OpenAPI.

The documentation and OpenAPI paths can be configured with SIGMAX_DOCS_INDEX_PATH and SIGMAX_OPENAPI_PATH.

Configuration

Variable	Default	Meaning
SIGMAX_ROUTES	../generated/routes.yaml	Generated routes file loaded at startup.
SIGMAX_BIND	0.0.0.0:8080	HTTP bind address for the component runtime.
SIGMAX_DOCS_INDEX_PATH	/app/generated/docs/index.html	Static generated docs entry.
SIGMAX_OPENAPI_PATH	/app/generated/openapi.yaml	Generated OpenAPI document.
DAPR_HTTP_ENDPOINT	unset	Enables Dapr invocation when bindings require it.
SIGMAX_TIME_FIXED_UNIX_MS	unset	Optional deterministic time source for time primitives.
SIGMAX_RANDOM_DETERMINISTIC_SEED	unset	Optional deterministic random source for repeatable runs.

HTTP, secret and external target primitives also use SIGMAX_HTTP_* and SIGMAX_SECRET_* policy variables when those capabilities are enabled.

Limits And Failures

The runtime enforces route timeout and memory limits when they are declared.

Failure mode	Runtime response
Invalid request shape	400 with VALIDATION_ERROR.
WASM execution timeout	504 with TIMEOUT.
Missing handler export	Runtime error.
Missing or invalid WASM module	Startup or execution failure.
Unsupported response format	Runtime error.
Memory above route limit	Runtime error.
Undeclared status	Logged as a warning and returned as emitted.

The current response path expects successful output to be JSON built from ObjectIR. Other response formats should be declared only when the runtime supports them.

What It Must Not Own

The Rust runtime should stay business-neutral.

It should not:

• encode invoice, customer, payment or domain-specific behavior;
• decide architecture boundaries;
• invent route capabilities;
• bypass Binary Contracts or Agreements;
• expose raw database or filesystem access to WASM;
• silently accept drift between generated metadata and executable artifacts.

Its job is to provide the same execution contract for every generated component: load declared routes, run validated WASM, expose controlled primitives and return observable results.

https://sigmax.dev/docs/runtime/rust-runtime/