Helpers (Rust)

Installation

cargo add iii-helpers

API reference for the iii-helpers crate (Rust).

http

HTTP request/response types, auth config, and the http helper. Import

use iii_helpers::http;

Types

HttpAuthConfig · HttpInvocationConfig · HttpMethod · HttpRequest · HttpResponse

HttpAuthConfig

Authentication configuration for HTTP-invoked functions.

Hmac: HMAC signature verification using a shared secret.
Bearer: Bearer token authentication.
ApiKey: API key sent via a custom header.

Name	Type	Required	Description
`Hmac`	`{ secret_key: String }`	Yes	-
`Bearer`	`{ token_key: String }`	Yes	-
`ApiKey`	`{ header: String, value_key: String }`	Yes	-

HttpInvocationConfig

Configuration for an HTTP-invoked function (Lambda, Cloudflare Workers, etc.).

Name	Type	Required	Description
`url`	`String`	Yes	URL to invoke.
`method`	`HttpMethod`	Yes	HTTP method. Defaults to `POST`.
`timeout_ms`	`Option<u64>`	No	Timeout in milliseconds.
`headers`	`HashMap<String, String>`	Yes	Custom headers to send with the request.
`auth`	Option<`HttpAuthConfig`>	No	Authentication configuration.

HttpMethod

HTTP method accepted by HttpInvocationConfig.

Name	Type	Required	Description
`Get`	`unit`	Yes	-
`Post`	`unit`	Yes	-
`Put`	`unit`	Yes	-
`Patch`	`unit`	Yes	-
`Delete`	`unit`	Yes	-

HttpRequest

Buffered HTTP request received by a function handler.

Name	Type	Required	Description
`query_params`	`HashMap<String, String>`	Yes	Query-string parameters from the request URL.
`path_params`	`HashMap<String, String>`	Yes	Path parameters extracted from the matched route.
`headers`	`HashMap<String, String>`	Yes	Request headers.
`path`	`String`	Yes	Request path.
`method`	`String`	Yes	HTTP method of the request (e.g. `GET`, `POST`).
`body`	`T`	Yes	Parsed request body.

HttpResponse

Buffered HTTP response returned from a function handler.

Name	Type	Required	Description
`status_code`	`u16`	Yes	HTTP status code.
`headers`	`HashMap<String, String>`	Yes	Response headers.
`body`	`T`	Yes	Response body.

observability

Logger, OpenTelemetry config, and span helpers. Import

use iii_helpers::observability;

Types

BaggageSpanProcessor · ConnectionState · Logger · OtelConfig · ReconnectionConfig · WorkerGaugesOptions

BaggageSpanProcessor

OpenTelemetry span processor that copies OTel baggage entries onto each started span as attributes.

Name	Type	Required	Description
`new`	`fn() -> Self`	Yes	-

ConnectionState

Connection state for the shared WebSocket

Name	Type	Required	Description
`Disconnected`	`unit`	Yes	-
`Connecting`	`unit`	Yes	-
`Connected`	`unit`	Yes	-
`Reconnecting`	`unit`	Yes	-
`Failed`	`unit`	Yes	-

Logger

Structured logger that sends logs to the engine as OpenTelemetry LogRecords. The engine prints them in its own output and stores them (engine::logs::list); they do not appear in the worker’s own output. Every log call automatically captures the active trace and span context, correlating your logs with distributed traces without any manual wiring. When OTel is not initialized (before the worker’s OpenTelemetry export starts, or with OTEL_ENABLED=false), Logger falls back to the tracing crate, which prints nothing unless the program installs a subscriber, for example tracing_subscriber::fmt().init(). Pass structured data as the second argument to any log method. Using a serde_json::Value object of key-value pairs (instead of string interpolation) lets you filter, aggregate, and build dashboards in your observability backend.

Name	Type	Required	Description
`debug`	`fn(message: &str, data: Option<Value>)`	Yes	Log a debug-level message.
`error`	`fn(message: &str, data: Option<Value>)`	Yes	Log an error-level message.
`info`	`fn(message: &str, data: Option<Value>)`	Yes	Log an info-level message.
`new`	`fn() -> Self`	Yes	Create a new Logger instance.
`warn`	`fn(message: &str, data: Option<Value>)`	Yes	Log a warning-level message.

OtelConfig

Configuration for OpenTelemetry initialization

Name	Type	Required	Description
`enabled`	`Option<bool>`	No	Whether OpenTelemetry export is enabled. Defaults to true. Set to false or `OTEL_ENABLED=false/0/no/off` to disable.
`service_name`	`Option<String>`	No	The service name to report. Defaults to the `OTEL_SERVICE_NAME` env var, then the program’s file name, then `iii-rust-sdk`.
`service_version`	`Option<String>`	No	The service version to report. Defaults to the `SERVICE_VERSION` env var or “unknown”.
`service_namespace`	`Option<String>`	No	The service namespace to report. Defaults to the `SERVICE_NAMESPACE` env var.
`service_instance_id`	`Option<String>`	No	The service instance ID to report. Defaults to the `SERVICE_INSTANCE_ID` env var or an auto-generated UUID.
`engine_ws_url`	`Option<String>`	No	III Engine WebSocket URL. Defaults to the `III_URL` env var or “ws://localhost:49134”.
`engine_ws_headers`	`Option<HashMap<String, String>>`	No	HTTP headers sent on the telemetry WebSocket handshake (e.g. `Authorization`).
`metrics_enabled`	`Option<bool>`	No	Whether metrics export is enabled. Defaults to true. Set to false or `OTEL_METRICS_ENABLED=false/0/no/off` to disable.
`metrics_export_interval_ms`	`Option<u64>`	No	Metrics export interval in milliseconds. Defaults to 60000 (60 seconds).
`reconnection_config`	Option<`ReconnectionConfig`>	No	Optional reconnection configuration for the WebSocket connection.
`shutdown_timeout_ms`	`Option<u64>`	No	Timeout in milliseconds for the shutdown sequence (default: 10,000)
`channel_capacity`	`Option<usize>`	No	Capacity of the internal telemetry message channel (default: 10,000). This controls the in-flight message buffer between exporters and the WebSocket connection loop. Intentionally larger than `ReconnectionConfig::max_pending_messages` to absorb bursts during normal operation while limiting stale data across reconnects.
`spans_flush_interval_ms`	`Option<u64>`	No	Span processor flush delay in milliseconds. Defaults to 100ms when not set. The OpenTelemetry default of 5000ms is what makes traces appear seconds after the action. Env override: OTEL_SPANS_FLUSH_INTERVAL_MS.
`logs_enabled`	`Option<bool>`	No	Whether to enable the log exporter (default: true)
`logs_flush_interval_ms`	`Option<u64>`	No	Log processor flush delay in milliseconds. Defaults to 100ms when not set.
`logs_batch_size`	`Option<usize>`	No	Maximum number of log records exported per batch. Defaults to 1 when not set.
`fetch_instrumentation_enabled`	`Option<bool>`	No	Whether to auto-instrument outgoing HTTP calls. When `Some(true)` (default), `execute_traced_request()` can be used to create CLIENT spans for reqwest requests. Set `Some(false)` to opt out. `None` is treated as `true`.
`live_spans`	`Option<bool>`	No	Announce span STARTS to the engine as zero-end OTLP snapshots so live trace views render in-progress work (`LiveSpanStartProcessor`). One extra frame per span; the engine stores it as `pending` (or drops it when its live-span storage is off) and the final span replaces it in place. Default: enabled. Env override: `OTEL_LIVE_SPANS`, the same switch the engine uses for its own start mirroring.

ReconnectionConfig

Configuration for WebSocket reconnection behavior

Name	Type	Required	Description
`initial_delay_ms`	`u64`	Yes	Starting delay in milliseconds (default: 1000).
`max_delay_ms`	`u64`	Yes	Maximum delay cap in milliseconds (default: 30000).
`backoff_multiplier`	`f64`	Yes	Exponential backoff multiplier (default: 2).
`jitter_factor`	`f64`	Yes	Random jitter factor, 0-1 (default: 0.3).
`max_retries`	`Option<u64>`	No	Maximum retry attempts; `None` for infinite (default: `None`).
`max_pending_messages`	`usize`	Yes	Maximum messages preserved across reconnects. Messages beyond this limit are dropped to prevent delivering stale data after a long disconnect. This is intentionally smaller than `OtelConfig::channel_capacity` (the in-flight buffer between exporters and the WebSocket loop).
`effective_initial_delay_ms`	`fn() -> u64`	Yes	Returns initial_delay_ms, clamped to a minimum of 1ms to prevent division by zero.

WorkerGaugesOptions

Options for registering worker gauges.

Name	Type	Required	Description
`worker_id`	`String`	Yes	Stable identifier of the worker the gauges are reported for.
`worker_name`	`Option<String>`	No	Human-readable name of the worker.

queue

Queue enqueue result types. Import

use iii_helpers::queue;

Types

EnqueueResult

EnqueueResult

Result returned when a function is called with CallAction::Enqueue.

Name	Type	Required	Description
`message_receipt_id`	`String`	Yes	Unique receipt ID for the enqueued message.

stream

Stream change events, IO inputs, and update operations. Import

use iii_helpers::stream;

Types

MergePath · StreamDeleteResult · StreamSetResult · StreamUpdateResult · UpdateOp · UpdateOpError

MergePath

Path target for a UpdateOp::Merge operation. Accepts either a single string (legacy / first-level field) or an array of literal segments (nested path). Path normalization rules applied by the engine:

absent / Single("") / Segments(vec![]) → root merge
Single("foo") is equivalent to Segments(vec!["foo".into()])
Segments(["a", "b", "c"]) walks three literal keys, never interpreting dots specially. Segments(vec!["a.b".into()]) is a single literal key named "a.b".

Variant ordering is load-bearing. #[serde(untagged)] tries variants in declaration order, Single MUST come before Segments so a JSON string deserializes into Single rather than failing the array match first.

Name	Type	Required	Description
`Single`	`(String)`	Yes	-
`Segments`	`(Vec<String>)`	Yes	-

StreamDeleteResult

Result of a stream delete operation.

Name	Type	Required	Description
`old_value`	`Option<Value>`	No	Previous value (if it existed).

StreamSetResult

Result of a stream set operation.

Name	Type	Required	Description
`old_value`	`Option<Value>`	No	Previous value (if it existed).
`new_value`	`Value`	Yes	The value after the update

StreamUpdateResult

Result of an atomic update operation

Name	Type	Required	Description
`old_value`	`Option<Value>`	No	Previous value (if it existed).
`new_value`	`Value`	Yes	The value after the update
`errors`	Vec<`UpdateOpError`>	Yes	Errors encountered while applying ops. Successfully applied ops are still reflected in `new_value`. Field is omitted from JSON when empty for backward compatibility.

UpdateOp

Operations that can be performed atomically on a stream value

Name	Type	Required	Description
`Set`	`{ path: String, value: Option<Value> }`	Yes	Set a value at path (overwrite)
`Merge`	{ path: Option<`MergePath`>, value: Value }	Yes	Merge object into existing value (object-only). Path may be omitted (root merge), a single first-level key, or an array of literal segments for nested merge. See `MergePath`.
`Increment`	`{ path: String, by: i64 }`	Yes	Increment numeric value
`Decrement`	`{ path: String, by: i64 }`	Yes	Decrement numeric value
`Append`	{ path: Option<`MergePath`>, value: Value }	Yes	Append an element to an array or concatenate a string at the optional path. Path may be omitted (root append), a single first-level key, or an array of literal segments for nested append. See `MergePath` for the variant shape.
`Remove`	`{ path: String }`	Yes	Remove a field
`append`	fn(path: impl Into<`MergePath`>, value: impl Into<Value>) -> Self	Yes	Create an Append operation at a specific path. Accepts a single first-level key (`"foo"`) or any type that converts into `MergePath` (e.g. `Vec<String>` for nested paths).
`append_at_path`	`fn(segments: I, value: impl Into<Value>) -> Self`	Yes	Create an Append operation at a nested path of literal segments. Convenience wrapper for `append(vec!["a", "b"], v)`.
`append_root`	`fn(value: impl Into<Value>) -> Self`	Yes	Create an Append operation at the root level (no path).
`decrement`	`fn(path: impl Into<String>, by: i64) -> Self`	Yes	Create a Decrement operation
`increment`	`fn(path: impl Into<String>, by: i64) -> Self`	Yes	Create an Increment operation
`merge`	`fn(value: impl Into<Value>) -> Self`	Yes	Create a Merge operation at root level
`merge_at`	fn(path: impl Into<`MergePath`>, value: impl Into<Value>) -> Self	Yes	Create a Merge operation at a specific path. Accepts a single first-level key (`"foo"`) or any type that converts into `MergePath` (e.g. `Vec<String>` for nested paths).
`merge_at_path`	`fn(segments: I, value: impl Into<Value>) -> Self`	Yes	Create a Merge operation at a nested path of literal segments. Convenience wrapper for `merge_at(vec!["a", "b"], v)`.
`remove`	`fn(path: impl Into<String>) -> Self`	Yes	Create a Remove operation
`set`	`fn(path: impl Into<String>, value: impl Into<Option<Value>>) -> Self`	Yes	Create a Set operation

UpdateOpError

Per-op error reported by an atomic update operation.

Name	Type	Required	Description
`op_index`	`usize`	Yes	Index of the offending op within the original `ops` array.
`code`	`String`	Yes	Stable error code, e.g. `"merge.path.too_deep"`.
`message`	`String`	Yes	Human-readable description with concrete numbers when applicable.
`doc_url`	`Option<String>`	No	Optional documentation URL for this error class.

worker_connection_manager

RBAC auth and registration callback types. Import

use iii_helpers::worker_connection_manager;

Types

AuthInput · AuthResult · OnFunctionRegistrationInput · OnFunctionRegistrationResult

AuthInput

Input passed to the RBAC auth function during WebSocket upgrade. Contains the HTTP headers, query parameters, and client IP from the connecting worker’s upgrade request.

Name	Type	Required	Description
`headers`	`HashMap<String, String>`	Yes	HTTP headers from the WebSocket upgrade request.
`query_params`	`HashMap<String, Vec<String>>`	Yes	Query parameters from the upgrade URL. Each key maps to a vec of values to support repeated keys (e.g. `?a=1&a=2`).
`ip_address`	`String`	Yes	IP address of the connecting client.

AuthResult

Return value from the RBAC auth function. Controls which functions the authenticated worker can invoke and what context is forwarded to the middleware.

Name	Type	Required	Description
`namespaces`	`HashMap<String, Vec<String>>`	Yes	Grants scoped to one namespace each: `{ "orders": ["svc::"] }`. A value is an exact function ID or a wildcard, in either the bare (`svc::`) or the `match("svc::*")` spelling. The keys are also the namespaces the session may declare on `engine::workers::register`. Leave it empty to add no namespace-scoped grants: the session may declare any namespace, and only `allowed_functions` and `expose_functions` apply.
`allowed_functions`	`Vec<String>`	Yes	Additional function IDs to allow beyond the `expose_functions` config, in the `default` namespace only. Put per-namespace grants in `AuthResult::namespaces`.
`forbidden_functions`	`Vec<String>`	Yes	Function IDs to deny even if they match `expose_functions`. Takes precedence over allowed.
`allow_function_registration`	`bool`	Yes	Whether the worker may register new functions. Defaults to `true`.
`context`	`Value`	Yes	Arbitrary context forwarded to the middleware function on every invocation.
`function_registration_prefix`	`Option<String>`	No	Optional prefix applied to all function IDs registered by this worker.

OnFunctionRegistrationInput

Input passed to the on_function_registration_function_id hook when a worker attempts to register a function through the RBAC port. Return an OnFunctionRegistrationResult with the (possibly mapped) fields, or return an error to deny the registration.

Name	Type	Required	Description
`function_id`	`String`	Yes	ID of the function being registered.
`description`	`Option<String>`	No	Human-readable description of the function.
`metadata`	`Option<Value>`	No	Arbitrary metadata attached to the function.
`namespace`	`String`	Yes	Namespace the function registers in. The same id can exist in several namespaces, so the hook needs this to authorize per namespace.
`private`	`bool`	Yes	Only the registering worker may call the function.
`observable`	`bool`	Yes	Whether the function may be observed. An older engine omits it: `true`.
`args_format`	`Option<Value>`	No	JSON Schema of the function’s observer args, when it takes any.
`context`	`Value`	Yes	Auth context from `AuthResult.context` for this session.

OnFunctionRegistrationResult

Result returned from the on_function_registration_function_id hook. Omitted fields keep the original value from the registration request.

Name	Type	Required	Description
`function_id`	`Option<String>`	No	Mapped function ID.
`description`	`Option<String>`	No	Mapped description.
`metadata`	`Option<Value>`	No	Mapped metadata.
`private`	`Option<bool>`	No	Replaces the registration’s `private`.
`observable`	`Option<bool>`	No	Replaces the registration’s `observable`.
`args_format`	`Option<Value>`	No	Replaces the registration’s `args_format`.

Engine protocol

Language SDKs

Helpers

CLI reference

Helpers (Rust)

Installation

http

Types

HttpAuthConfig

HttpInvocationConfig

HttpMethod

HttpRequest

HttpResponse

observability

Types

BaggageSpanProcessor

ConnectionState

Logger

OtelConfig

ReconnectionConfig

WorkerGaugesOptions

queue

Types

EnqueueResult

stream

Types

MergePath

StreamDeleteResult

StreamSetResult

StreamUpdateResult

UpdateOp

UpdateOpError

worker_connection_manager

Types

AuthInput

AuthResult

OnFunctionRegistrationInput

OnFunctionRegistrationResult

​Installation

​http

​Types

​HttpAuthConfig

​HttpInvocationConfig

​HttpMethod

​HttpRequest

​HttpResponse

​observability

​Types

​BaggageSpanProcessor

​ConnectionState

​Logger

​OtelConfig

​ReconnectionConfig

​WorkerGaugesOptions

​queue

​Types

​EnqueueResult

​stream

​Types

​MergePath

​StreamDeleteResult

​StreamSetResult

​StreamUpdateResult

​UpdateOp

​UpdateOpError

​worker_connection_manager

​Types

​AuthInput

​AuthResult

​OnFunctionRegistrationInput

​OnFunctionRegistrationResult

Installation

http

Types

HttpAuthConfig

HttpInvocationConfig

HttpMethod

HttpRequest

HttpResponse

observability

Types

BaggageSpanProcessor

ConnectionState

Logger

OtelConfig

ReconnectionConfig

WorkerGaugesOptions

queue

Types

EnqueueResult

stream

Types

MergePath

StreamDeleteResult

StreamSetResult

StreamUpdateResult

UpdateOp

UpdateOpError

worker_connection_manager

Types

AuthInput

AuthResult

OnFunctionRegistrationInput

OnFunctionRegistrationResult