Installation
Initialization
register_worker
SignatureParameters
&str
required
InitOptions
required
Methods
register_trigger
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 withobserve.
Signature
- Parameters
- Example
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
- Parameters
- Example
trigger
Invoke a function. The routing behavior depends on theaction field of the request:
- No action: synchronous, waits for the function to return.
TriggerAction::Enqueue: async via named queue.TriggerAction::Void: fire-and-forget.
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
- Parameters
- Example
impl Into<TriggerRequestWithMetadata>
required
register_trigger_type
Register a custom trigger type with the engine. Returns aTriggerTypeRef 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
- Parameters
- Example
RegisterTriggerType<H, C, R>
required
unregister_trigger_type
Unregister a previously registered trigger type. Deprecated since 0.25.0 withregister_trigger_type.
Signature
- Parameters
- Example
impl Into<String>
required
fatal_error
Fatal error that stopped the worker, if any. Set when the engine rejects registration (seeError::RegistrationRejected); the worker does not
reconnect once this is populated.
Signature
get_connection_state
Get the current connection state. SignatureExample
namespace
The effective worker namespace (resolved fromInitOptions.namespace /
III_NAMESPACE), or None for the engine’s default.
Signature
observe
Observessource 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 byregister_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. SignatureExample
shutdown_async
Shutdown the III client. This stops the connection loop and sends a shutdown signal, but it does not joinconnection_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. ReturnsError::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, orNone outside any
handler (and in a task spawned from a handler without scope).
Signature
scope
Runsfut 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 withTriggerAction.Enqueue.
InitOptions
Configuration options passed toregister_worker.
RegisterFunction
Function registration builder. The function ID is supplied separately at registration time viaIIIClient::register_function, RegisterFunction only carries the handler
and optional metadata.
Constructors:
RegisterFunction::new: sync function. Accepts both typed handlers (schemas auto-extracted viaschemars) andFn(Value, Option<Value>) -> Result<Value, Error>closures. The second argument is the per-invocation metadata sidecar and isNonewhen absent.RegisterFunction::new_async: async equivalent ofnew.RegisterFunction::http: function invoked over HTTP (Lambda, Cloudflare Workers, etc.).
self):
descriptionmetadatarequest_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 withIIIClient::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:
Ctracks the trigger registration type (set via.trigger_request_format::<T>())Rtracks the call request type (set via.call_request_format::<T>())
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 PythonInvocationError.
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, forRegisterFunction::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 withObserver::emitorObserver::call.
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 andon. 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 itsready() fails with.
iii_sdk::observe
Observed · ObservedError · ObserverHandle · ObserverOptions · ObserverReason · ObserverStatus · Source · StateListener · Target
Observed
What an observer’s target receives with the defaultdeliver: envelope:
the observed invocation (auto) or emitted event (owner emit), per the
observer’s capture.
ObservedError
Observed::error.
ObserverHandle
Handle to an observer created byIIIClient::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 withObserverHandle::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 pathIIIClient::trigger takes.
A call to a function registered by this same worker runs in-process
(“local dispatch”) when all of these hold:
- the function has a handler here (not
RegisterFunction::http) and was not registered withRegisterFunction::local_dispatch(false); - the engine confirmed it with
functionregistered { local_dispatch: true }; - the call resolves to the namespace the function is registered in;
- the action is not
TriggerAction::Enqueue(aVoidcall runs locally, fire-and-forget); - the dispatch is not
Dispatch::Remote.
DroppedReportStats
SDK-side report drops inlocalinvocationstats.
ErrorBody
FunctionMessage
InvocationStatus
Outcome of an observed invocation. An emitted event is alwayssuccess.
LegacyTrigger
The oldregisterTrigger an observer was created from by the engine’s
legacy shim. The owner reads config as the observer’s args.
LocalFunctionStats
Per-function counts inlocalinvocationstats.
Message
ObserveDescriptor
registerfunction.observe: the wire half of a function’s observe hooks.
ObservedItem
One item ofinvocationsobserved: 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 ofiii.observe on the wire. Absent fields stay absent; the
engine applies the defaults.
ObserveTarget
The right side ofiii.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 forIIIClient::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 forTriggerRequest. 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 fortrigger().
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 byengine::functions::list
FunctionRef
IIIConnectionState
Connection state for the III WebSocket clientTriggerInfo
Trigger information returned byengine::triggers::list
TriggerTypeRef
Typed handle returned byIIIClient::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 forregister_triggerR: call request type forregister_function
WorkerIdentityMode
Selects where a worker connection gets its engine identity.WorkerInfo
Worker information returned byengine::workers::list
WorkerMetadata
Worker metadata for auto-registrationiii_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 throughcreate_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 withIIIClient::register_trigger;
see the module docs.
Use .for_function() to create a RegisterTriggerInput:
Trigger
Handle returned byIIIClient::register_trigger.
Call unregister to remove the trigger from the engine.
TriggerConfig
Configuration passed to aTriggerHandler when a trigger instance is
registered or unregistered.
TriggerHandler
Handler trait for custom trigger types. Implement this and pass toIIIClient::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-invocationmetadata 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 ofiii_helpers::http::HttpRequest.
StreamResponse
Streaming response type, mirroring the Node and PythonStreamResponse.
Alias of iii_helpers::http::HttpResponse; added for cross-language parity.