Skip to main content

Installation

Initialization

register_worker

Signature

Parameters

&str
required
InitOptions
required

Methods

register_trigger

Deprecated since 0.25.0. Use iii.observe(Source::function(..).args(..), target) instead; see https://iii.dev/docs/upgrading/from-0-24-x
Bind a trigger configuration to a registered function. It keeps working in 0.25 and logs one warning per process. The http, cron, queue, state, stream, pubsub and database workers still publish trigger types, so keep using it for them until they ship source functions; observe any other function with observe. Signature
RegisterTriggerInput
required
Trigger registration input with trigger_type, function_id, and config.

register_function

Register a function with the engine. Argument order matches the Node and Python SDKs: (id, registration). Signature
impl Into<String>
required
Unique identifier for the function.
RegisterFunction
required
Built via [RegisterFunction::new], [RegisterFunction::new_async], or [RegisterFunction::http]. Chain .description(...), .metadata(...), .request_format(...), .response_format(...) as needed.

trigger

Invoke a function. The routing behavior depends on the action field of the request:
  • No action: synchronous, waits for the function to return.
  • TriggerAction::Enqueue: async via named queue.
  • TriggerAction::Void: fire-and-forget.
A function this worker registered itself runs in-process once the engine allowed it (“local dispatch”, see Dispatch): same result, error shape and timeout, and nothing on the wire unless an observer’s filters match the call. A sync handler then runs inline on the caller’s task, where the timeout cannot interrupt it: a sync handler that can block should be async, or registered with RegisterFunction::local_dispatch(false). TriggerRequest::dispatch with Dispatch::Remote forces the engine path. Calls made from inside a handler carry that handler as their caller. Signature
impl Into<TriggerRequestWithMetadata>
required

register_trigger_type

Deprecated since 0.25.0. Register a function with RegisterFunction::observe(Observe::owner()..) instead; see https://iii.dev/docs/upgrading/from-0-24-x
Register a custom trigger type with the engine. Returns a TriggerTypeRef handle that can register triggers and functions with compile-time validated types. It keeps working in 0.25 and logs one warning per process. A new provider registers a function with an observe descriptor instead (RegisterFunction::new(..).observe(Observe::owner().args_format::<Config>().handler(..))): ObserveHandler replaces TriggerHandler, and observers’ args replace trigger configs. Signature
RegisterTriggerType<H, C, R>
required

unregister_trigger_type

Deprecated since 0.25.0. Unregister the function registered with RegisterFunction::observe instead; see https://iii.dev/docs/upgrading/from-0-24-x
Unregister a previously registered trigger type. Deprecated since 0.25.0 with register_trigger_type. Signature
impl Into<String>
required

fatal_error

Fatal error that stopped the worker, if any. Set when the engine rejects registration (see Error::RegistrationRejected); the worker does not reconnect once this is populated. Signature

get_connection_state

Get the current connection state. Signature

Example


namespace

The effective worker namespace (resolved from InitOptions.namespace / III_NAMESPACE), or None for the engine’s default. Signature

observe

Observes source and invokes target once per matching event. Returns at once, before the engine answered: the handle starts pending; ObserverHandle::ready resolves on active and fails on error (INVALID_ARGS, INVALID_FILTER, FORBIDDEN, an owner rejection, UNSUPPORTED against an engine without observe). There is no inline handler: target is a registered function, and the observer stays pending until it is registered. Signature

Parameters

Source
required
impl Into<Target>
required

observe_with

observe with the observer’s id, policy and metadata. Signature

Parameters

Source
required
impl Into<Target>
required
ObserverOptions
required

set_namespace

Override the worker’s target namespace (call before connect). Applied by register_worker after resolving InitOptions.namespace and III_NAMESPACE. Signature

Parameters

impl Into<String>
required

shutdown

Shutdown the III client and wait for the connection thread to finish. This stops the connection loop, sends a shutdown signal, and joins the background connection thread. OpenTelemetry is flushed inside the connection thread before it exits. Signature

Example


shutdown_async

Shutdown the III client. This stops the connection loop and sends a shutdown signal, but it does not join connection_thread. This method returns without waiting for run_connection() to finish, making it safe to call from an async context without stalling the executor; shutdown blocks and joins the thread. The OpenTelemetry flush (telemetry::shutdown_otel()) still runs inside the connection thread after run_connection() returns, so it may not complete unless shutdown is used to join the thread. Signature

Example


wait_until_registered

Wait until the engine accepts this worker’s initial registration. Returns Error::RegistrationRejected for a fatal identity conflict, Error::Timeout when the deadline expires, and Error::NotConnected when called before the client starts or after it stops. Signature

Parameters

Duration
required

Functions

current_invocation

The invocation the calling task is running for, or None outside any handler (and in a task spawned from a handler without scope). Signature

scope

Runs fut with ctx as its current invocation. Use it to keep the handler’s context in a task it spawns; None runs fut outside any invocation. The local-call nesting of the calling task is carried too, so recursing through spawned tasks stays bounded. Signature

Parameters

impl Into<Option<InvocationCtx>>
required
F
required

Types

iii_sdk

EnqueueResult · InitOptions · RegisterFunction · RegisterTriggerType · TelemetryOptions

EnqueueResult

Result returned when a function is invoked with TriggerAction.Enqueue.

InitOptions

Configuration options passed to register_worker.

RegisterFunction

Function registration builder. The function ID is supplied separately at registration time via IIIClient::register_function, RegisterFunction only carries the handler and optional metadata. Constructors:
  • RegisterFunction::new: sync function. Accepts both typed handlers (schemas auto-extracted via schemars) and Fn(Value, Option<Value>) -> Result<Value, Error> closures. The second argument is the per-invocation metadata sidecar and is None when absent.
  • RegisterFunction::new_async: async equivalent of new.
  • RegisterFunction::http: function invoked over HTTP (Lambda, Cloudflare Workers, etc.).
Builder methods (all consume self):
  • description
  • metadata
  • request_format: overrides any auto-extracted schema.
  • response_format: overrides any auto-extracted schema.
  • observe: how observers of the function are delivered, and the hooks that run when one is added or removed.
  • local_dispatch: opt out of in-process calls.

RegisterTriggerType

Builder for registering a custom trigger type with optional format schemas. Deprecated since 0.25.0 together with IIIClient::register_trigger_type: register a function with an observe descriptor (RegisterFunction::observe) instead. Migration guide: https://iii.dev/docs/upgrading/from-0-24-x. Type parameters:
  • C tracks the trigger registration type (set via .trigger_request_format::<T>())
  • R tracks the call request type (set via .call_request_format::<T>())
Both default to Value (untyped) and change when the respective builder method is called. This allows IIIClient::register_trigger_type to return a TriggerTypeRef<C, R> with compile-time safety for both config and function input types.

TelemetryOptions

Worker metadata reported to the engine (language, framework, project).

iii_sdk::builtin_triggers

CronCallRequest · CronTriggerConfig · HttpCallRequest · HttpMethod · HttpTriggerConfig · LogCallRequest · LogLevel · LogTriggerConfig · QueueTriggerConfig · StateCallRequest · StateEventType · StateTriggerConfig · SubscribeTriggerConfig

CronCallRequest


CronTriggerConfig


HttpCallRequest


HttpMethod


HttpTriggerConfig


LogCallRequest


LogLevel


LogTriggerConfig


QueueTriggerConfig


StateCallRequest


StateEventType


StateTriggerConfig


SubscribeTriggerConfig

iii_sdk::channel

Channel · ChannelReader · ChannelWriter · StreamChannelRef

Channel

A streaming channel pair for worker-to-worker data transfer.

ChannelReader

WebSocket-backed reader for streaming binary data and text messages.

ChannelWriter

WebSocket-backed writer for streaming binary data and text messages.

StreamChannelRef

iii_sdk::channels

ChannelDirection · ChannelItem

ChannelDirection


ChannelItem

iii_sdk::context

InvocationCtx

InvocationCtx

The invocation a handler is running for.

iii_sdk::engine

EngineFunctions · EngineTriggers

EngineFunctions

Engine function ids for internal operations.

EngineTriggers

Engine trigger ids.

iii_sdk::errors

Error · InvocationError

Error

Errors returned by the III SDK.

InvocationError

Structured invocation failure, mirroring the Node and Python InvocationError. Produced from the Error::Remote variant via Error::invocation_error. function_id is None from that accessor because the wire Remote payload does not carry it.

iii_sdk::observable

Observe · ObserveHandler · Observer · ObserveRejection

Observe

The observe descriptor of a function, for RegisterFunction::observe.
  • Observe::auto: the function’s invocations are the events; every observer is offered every invocation and the SDK reports the matching ones. It takes no args.
  • Observe::owner: the function’s owner reads each observer’s args, sets up what they ask for and hands each event to the observers it belongs to with Observer::emit or Observer::call.
A function registered without one is still observable, as auto without hooks.

ObserveHandler

Callbacks of an observable function, run once per observer added or removed, one at a time per function and in the engine’s order. on_observer_added runs before the SDK acknowledges the observer, so what it puts in the owner’s index is in place before the engine marks the observer active. Returning an error rejects the observer: an ObserveRejection sets the code, a plain error is OBSERVE_REJECTED, and a callback still running after 30 s is OWNER_TIMEOUT. A callback past the timeout is cancelled (its future is dropped at its next .await) so the function’s next callback can run; anything it spawned keeps running and may overlap that next callback. Callbacks run on the connection’s runtime: do not block in them.

Observer

One observer of a function this worker hosts, as its owner sees it: its id, args, filters, target, capture and on. Never its metadata, policy or observing worker. Cheap to clone (an Arc), so owners keep it in their own index. Two Observers are equal when their ids are.

ObserveRejection

An owner’s refusal of an observer, with the code its ready() fails with.

iii_sdk::observe

Observed · ObservedError · ObserverHandle · ObserverOptions · ObserverReason · ObserverStatus · Source · StateListener · Target

Observed

What an observer’s target receives with the default deliver: envelope: the observed invocation (auto) or emitted event (owner emit), per the observer’s capture.

ObservedError

Observed::error.

ObserverHandle

Handle to an observer created by IIIClient::observe. Cheap to clone. The observer exists until dispose (or its policy runs out); dropping the handle does not remove it. It works before the connection is up and is replayed with the same id after a reconnect.

ObserverOptions

The observer itself: its id, policy and metadata sidecar.

ObserverReason

Why an observer is in its state: { code, message }.

ObserverStatus

An observer’s state, why, and how often it fired.

Source

The left side of an observer: what is observed.

StateListener

A listener added with ObserverHandle::on_state_change.

Target

The right side of an observer: a registered function.

iii_sdk::protocol

Activation · Caller · Capture · Deliver · Delivery · Dispatch · DroppedReportStats · ErrorBody · FunctionMessage · InvocationStatus · LegacyTrigger · LocalFunctionStats · Message · ObserveDescriptor · ObservedItem · ObserverState · ObserverView · ObserveSource · ObserveTarget · On · ParentCaller · RegisterFunctionMessage · RegisterTriggerInput · RegisterTriggerMessage · RegisterTriggerTypeMessage · TriggerAction · TriggerRequest · TriggerRequestWithMetadata · UnregisterTriggerMessage · UnregisterTriggerTypeMessage

Activation

invokefunction.activation.

Caller

Who made an invocation. worker_id / worker_name are stamped by the engine from the calling connection; function_id, invocation_id and parent are asserted by the calling SDK.

Capture

What an activation ships to the target. A filter may read any root, whatever is captured.

Deliver

What the target’s first argument is.

Delivery

How a function’s observers are delivered.

Dispatch

Which path IIIClient::trigger takes. A call to a function registered by this same worker runs in-process (“local dispatch”) when all of these hold:
  1. the function has a handler here (not RegisterFunction::http) and was not registered with RegisterFunction::local_dispatch(false);
  2. the engine confirmed it with functionregistered { local_dispatch: true };
  3. the call resolves to the namespace the function is registered in;
  4. the action is not TriggerAction::Enqueue (a Void call runs locally, fire-and-forget);
  5. the dispatch is not Dispatch::Remote.
Otherwise the call goes through the engine as before. A local call returns the same result, error shape and timeout as a remote one, and is reported to the engine only when an observer’s filters match it.

DroppedReportStats

SDK-side report drops in localinvocationstats.

ErrorBody


FunctionMessage


InvocationStatus

Outcome of an observed invocation. An emitted event is always success.

LegacyTrigger

The old registerTrigger an observer was created from by the engine’s legacy shim. The owner reads config as the observer’s args.

LocalFunctionStats

Per-function counts in localinvocationstats.

Message


ObserveDescriptor

registerfunction.observe: the wire half of a function’s observe hooks.

ObservedItem

One item of invocationsobserved: a matched local invocation of an auto function, or an emitted event of an owner function. input / output / error / metadata keep null apart from absent.

ObserverState

Observer lifecycle states.

ObserverView

An observer as its function’s owner sees it (functionregistered, observeradded): never the observer’s metadata, policy or observing worker.

ObserveSource

The left side of iii.observe on the wire. Absent fields stay absent; the engine applies the defaults.

ObserveTarget

The right side of iii.observe on the wire: a registered function.

On

Which outcomes of an auto function’s invocation activate an observer.

ParentCaller

Caller::parent: a caller without a parent of its own.

RegisterFunctionMessage


RegisterTriggerInput

Input for IIIClient::register_trigger. The id is auto-generated internally. Deprecated since 0.25.0 with register_trigger: use IIIClient::observe with a Source instead. Migration guide: https://iii.dev/docs/upgrading/from-0-24-x. Build it with RegisterTriggerInput::new, or with IIITrigger for a type the engine provides. A struct literal has to name every field, so each field added here breaks it: namespace did that once and trigger_namespace did it again, which is why the constructors exist. The two are different questions. namespace is where the target function resolves; trigger_namespace is where the trigger type’s provider is found, and None there asks the engine to take this worker’s namespace first and the engine’s own second.

RegisterTriggerMessage


RegisterTriggerTypeMessage


TriggerAction

Routing action for TriggerRequest. Determines how the engine handles the invocation.
  • Enqueue: Routes through a named queue for async processing.
  • Void: Fire-and-forget, no response.

TriggerRequest

Request object for trigger().

TriggerRequestWithMetadata

Trigger request plus optional per-invocation metadata, target namespace and dispatch.

UnregisterTriggerMessage


UnregisterTriggerTypeMessage

iii_sdk::runtime

FunctionInfo · FunctionRef · IIIConnectionState · TriggerInfo · TriggerTypeRef · WorkerIdentityMode · WorkerInfo · WorkerMetadata

FunctionInfo

Function information returned by engine::functions::list

FunctionRef


IIIConnectionState

Connection state for the III WebSocket client

TriggerInfo

Trigger information returned by engine::triggers::list

TriggerTypeRef

Typed handle returned by IIIClient::register_trigger_type. Deprecated since 0.25.0 with it; see https://iii.dev/docs/upgrading/from-0-24-x. Type parameters:
  • C: trigger registration type for register_trigger
  • R: call request type for register_function

WorkerIdentityMode

Selects where a worker connection gets its engine identity.

WorkerInfo

Worker information returned by engine::workers::list

WorkerMetadata

Worker metadata for auto-registration

iii_sdk::stream_provider

IStream

IStream

Custom stream-provider trait. Implementors override the engine’s built-in stream storage for a specific stream name when registered through create_stream in the helpers submodule.

iii_sdk::structs

MiddlewareFunctionInput

MiddlewareFunctionInput

Input passed to the RBAC middleware function on every function invocation through the RBAC port. The middleware can inspect, modify, or reject the call before it reaches the target function.

iii_sdk::trigger

IIITrigger · Trigger · TriggerConfig · TriggerHandler

IIITrigger

Enum of all built-in trigger types with typed configuration. Deprecated since 0.25.0 with IIIClient::register_trigger; see the module docs. Use .for_function() to create a RegisterTriggerInput:

Trigger

Handle returned by IIIClient::register_trigger. Call unregister to remove the trigger from the engine.

TriggerConfig

Configuration passed to a TriggerHandler when a trigger instance is registered or unregistered.

TriggerHandler

Handler trait for custom trigger types. Implement this and pass to IIIClient::register_trigger_type. Deprecated since 0.25.0 with register_trigger_type: implement ObserveHandler on an observable function instead (on_observer_added / on_observer_removed, with the observer’s args in place of the trigger config). Migration guide: https://iii.dev/docs/upgrading/from-0-24-x.

iii_sdk::types

RemoteFunctionData · RemoteFunctionHandler · RemoteTriggerTypeData · StreamRequest · StreamResponse

RemoteFunctionData


RemoteFunctionHandler

A dispatchable function handler. Receives the invocation payload. Handlers that also want the optional per-invocation metadata sidecar use RemoteFunctionHandlerWithMetadata; this single-argument shape is kept for backward compatibility.

RemoteTriggerTypeData


StreamRequest

Incoming streaming request received by a function registered with a stream trigger. Alias of iii_helpers::http::HttpRequest.

StreamResponse

Streaming response type, mirroring the Node and Python StreamResponse. Alias of iii_helpers::http::HttpResponse; added for cross-language parity.