> ## Documentation Index > Fetch the complete documentation index at: https://iii.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Helpers (Python) > API reference for the iii-helpers package (Python). ## Installation ```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} pip install iii-helpers ``` API reference for the iii-helpers package (Python). ## http HTTP request/response types, auth config, and the `http` helper. **Import** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} from iii_helpers.http import ... ``` ### Functions ### http Wrap a streaming handler so it receives typed StreamRequest and StreamResponse. Takes a callback `(req, res) -> HttpResponse | None` and returns a function the iii engine can invoke directly. The wrapper converts the raw dict (or `InternalHttpRequest`) delivered by the engine into the typed `StreamRequest` / `StreamResponse` pair that the callback expects. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} http(callback: Callable[[StreamRequest, StreamResponse], Awaitable[HttpResponse[Any] | None]]) -> Callable[[Any], Awaitable[HttpResponse[Any] | None]] ``` #### Parameters Async handler `(req, res) -> HttpResponse | None` invoked with the typed StreamRequest and StreamResponse. ### Types [`HttpAuthApiKey`](#httpauthapikey) · [`HttpAuthBearer`](#httpauthbearer) · [`HttpAuthHmac`](#httpauthhmac) · [`HttpInvocationConfig`](#httpinvocationconfig) · [`HttpRequest`](#httprequest) · [`HttpResponse`](#httpresponse) ### HttpAuthApiKey API key sent via a custom header. | Name | Type | Required | Description | | ----------- | -------------------- | -------- | ------------------------------------------------------- | | `header` | `str` | Yes | HTTP header name for the API key. | | `type` | `Literal['api_key']` | No | - | | `value_key` | `str` | Yes | Environment variable name containing the API key value. | *** ### HttpAuthBearer Bearer token authentication. | Name | Type | Required | Description | | ----------- | ------------------- | -------- | ------------------------------------------------------ | | `token_key` | `str` | Yes | Environment variable name containing the bearer token. | | `type` | `Literal['bearer']` | No | - | *** ### HttpAuthHmac HMAC signature verification using a shared secret. | Name | Type | Required | Description | | ------------ | ----------------- | -------- | ------------------------------------------------------------ | | `secret_key` | `str` | Yes | Environment variable name containing the HMAC shared secret. | | `type` | `Literal['hmac']` | No | - | *** ### HttpInvocationConfig Configuration for an HTTP-invoked function (Lambda, Cloudflare Workers, etc.). | Name | Type | Required | Description | | ------------ | ------------------------ | -------- | -------------------------------------------------------- | | `auth` | `HttpAuthConfig \| None` | No | Authentication configuration (bearer, HMAC, or API key). | | `headers` | `dict[str, str] \| None` | No | Additional HTTP headers to include in the request. | | `method` | `HttpMethod` | No | HTTP method. Defaults to `'POST'`. | | `timeout_ms` | `int \| None` | No | Request timeout in milliseconds. | | `url` | `str` | Yes | Target URL for the HTTP invocation. | *** ### HttpRequest Incoming buffered HTTP request received by a function handler. | Name | Type | Required | Description | | -------------- | ----------------------------- | -------- | ------------------------------------------------- | | `body` | `Any \| None` | No | Parsed request body. | | `headers` | `dict[str, str \| list[str]]` | No | Request headers. | | `method` | `str` | No | HTTP method of the request (e.g. `GET`, `POST`). | | `path_params` | `dict[str, str]` | No | Path parameters extracted from the matched route. | | `query_params` | `dict[str, str \| list[str]]` | No | Query-string parameters from the request URL. | *** ### HttpResponse Structured buffered HTTP response returned from function handlers. | Name | Type | Required | Description | | ------------- | ---------------- | -------- | ----------------- | | `body` | `Any \| None` | No | Response body. | | `headers` | `dict[str, str]` | No | Response headers. | | `status_code` | `int` | Yes | HTTP status code. | ## observability Logger, OpenTelemetry config, and span helpers. **Import** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} from iii_helpers.observability import ... ``` ### Functions ### current\_span\_id Return current active span\_id as 16-char hex, or None when unavailable. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} current_span_id() -> str | None ``` *** ### current\_span\_is\_recording Returns `False` when there is no active span or the sampler dropped it. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} current_span_is_recording() -> bool ``` *** ### current\_trace\_id Return current active trace\_id as 32-char hex, or None when unavailable. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} current_trace_id() -> str | None ``` *** ### execute\_traced\_request Execute an httpx Request inside an OTel CLIENT span. * Injects W3C traceparent into outgoing request headers. * Records HTTP semantic-convention attributes on the span. * Sets ERROR span status for responses with status >= 400. * Records exceptions for network-level errors. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} async (client, request) ``` #### Parameters httpx async client used to send the request. The httpx request to execute. *** ### extract\_baggage Extract baggage from a W3C baggage header string. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} extract_baggage(baggage: str) -> Any ``` #### Parameters W3C `baggage` header value. *** ### extract\_traceparent Extract a trace context from a W3C traceparent header string. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} extract_traceparent(traceparent: str) -> Any ``` #### Parameters W3C `traceparent` header value. *** ### flush\_otel Force-flush all OTel providers without tearing them down. Counterpart to :func:`shutdown_otel`. Use before short-lived process exits where you want pending spans/metrics/logs delivered but plan to keep using OTel afterwards. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} async () -> None ``` *** ### init\_otel Initialize OpenTelemetry. Subsequent calls are no-ops. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} init_otel(config: OtelConfig | None = None, loop: None = None) -> None ``` #### Parameters OTel configuration. Running asyncio event loop. When provided, SharedEngineConnection starts immediately. When None, the connection is started lazily on first use (pre-start buffer absorbs early frames). *** ### inject\_baggage Inject the current baggage into a W3C baggage header string. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} inject_baggage() -> str | None ``` *** ### inject\_traceparent Inject the current trace context into a W3C traceparent header string. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} inject_traceparent() -> str | None ``` *** ### record\_span\_event No-op when the current span is not recording. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} record_span_event(name: str, attrs: dict[str, Any] | None = None) -> None ``` #### Parameters Name of the event to record on the current span. Optional attributes attached to the event. *** ### redact Recursively redact values of sensitive keys. Returns a new value. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} redact(value: Any) -> Any ``` #### Parameters Value to redact; dicts, lists, and tuples are traversed recursively. *** ### redact\_and\_truncate Redact then serialize to JSON, optionally capped at `max_bytes`. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} redact_and_truncate(value: Any, max_bytes: Optional[int] = None) -> tuple[str, bool] ``` #### Parameters Value to redact and serialize. Optional cap on the serialized byte length; unset, zero, or negative means no cap. *** ### resolve\_max\_bytes\_from\_env **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} resolve_max_bytes_from_env() -> Optional[int] ``` *** ### set\_current\_span\_attribute No-op when the current span is not recording. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} set_current_span_attribute(key: str, value: Any) -> None ``` #### Parameters Attribute name to set on the current span. Attribute value. *** ### set\_current\_span\_error No-op when there is no active span. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} set_current_span_error(message: str) -> None ``` #### Parameters Error message recorded on the current span's status. *** ### shutdown\_otel Shut down OTel synchronously (best-effort; does not await WS flush). **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} shutdown_otel() -> None ``` *** ### with\_span Start a new span and run *fn(span)* within it. If the tracer is not initialized, *fn* is called with a no-op span that silently ignores attribute/event calls. **Signature** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} async (name: str, fn: Any, *, kind: Any = None, traceparent: str | None = None) -> Any ``` #### Parameters Span name. Async callable `(span) -> T`. Optional `SpanKind`. Defaults to `INTERNAL`. Optional W3C traceparent to use as parent context. ### Types [`BaggageSpanProcessor`](#baggagespanprocessor) · [`Logger`](#logger) · [`OtelConfig`](#otelconfig) · [`ReconnectionConfig`](#reconnectionconfig) ### BaggageSpanProcessor OpenTelemetry span processor that copies OTel baggage entries onto each started span as attributes. | Name | Type | Required | Description | | ------------- | -------------------------------------------------------------- | -------- | ----------- | | `force_flush` | `(timeout_millis: int = 30000) -> bool` | Yes | - | | `on_end` | `(span: ReadableSpan) -> None` | Yes | - | | `on_start` | `(span: Span, parent_context: Context \| None = None) -> None` | Yes | - | | `shutdown` | `() -> None` | Yes | - | *** ### Logger Structured logger that emits logs as OpenTelemetry LogRecords. 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, Logger gracefully falls back to Python `logging`. Pass structured data as the second argument to any log method. Using a dict of key-value pairs (instead of string interpolation) lets you filter, aggregate, and build dashboards in your observability backend. | Name | Type | Required | Description | | ------- | ------------------------------------------ | -------- | ---------------------------- | | `debug` | `(message: str, data: Any = None) -> None` | Yes | Log a debug-level message. | | `error` | `(message: str, data: Any = None) -> None` | Yes | Log an error-level message. | | `info` | `(message: str, data: Any = None) -> None` | Yes | Log an info-level message. | | `warn` | `(message: str, data: Any = None) -> None` | Yes | Log a warning-level message. | *** ### OtelConfig Configuration for OpenTelemetry initialization. | Name | Type | Required | Description | | ------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | `bool \| None` | No | Enable OTel. Defaults to True. Set OTEL\_ENABLED=false/0/no/off to disable. | | `engine_ws_url` | `str \| None` | No | III Engine WebSocket URL. Defaults to env III\_URL or 'ws\://localhost:49134'. | | `fetch_instrumentation_enabled` | `bool` | No | Auto-instrument urllib HTTP calls via URLLibInstrumentor. Defaults to True. | | `logs_batch_size` | `int \| None` | No | Maximum number of log records exported per batch. Defaults to 1 when not set. | | `logs_enabled` | `bool \| None` | No | Enable OTel log export via EngineLogExporter. Defaults to True when OTel is enabled. | | `logs_flush_interval_ms` | `int \| None` | No | Log processor flush delay in milliseconds. Defaults to 100ms when not set. | | `metrics_enabled` | `bool` | No | Enable OTel metrics export via EngineMetricsExporter. Defaults to True. | | `metrics_export_interval_ms` | `int` | No | Metrics export interval in milliseconds. Defaults to 60000 (60 seconds). | | `service_instance_id` | `str \| None` | No | Service instance ID. Defaults to a random UUID. | | `service_name` | `str \| None` | No | Service name. Defaults to env OTEL\_SERVICE\_NAME or 'iii-python-sdk'. | | `service_namespace` | `str \| None` | No | Service namespace attribute. | | `service_version` | `str \| None` | No | Service version. Defaults to env SERVICE\_VERSION or 'unknown'. | | `spans_flush_interval_ms` | `int \| None` | 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. | *** ### ReconnectionConfig Configuration for WebSocket reconnection behavior. | Name | Type | Required | Description | | -------------------- | ------- | -------- | -------------------------------------------------------- | | `backoff_multiplier` | `float` | No | Exponential backoff multiplier. Default `2.0`. | | `initial_delay_ms` | `int` | No | Starting delay in milliseconds. Default `1000`. | | `jitter_factor` | `float` | No | Random jitter factor (0--1). Default `0.3`. | | `max_delay_ms` | `int` | No | Maximum delay cap in milliseconds. Default `30000`. | | `max_retries` | `int` | No | Maximum retry attempts. `-1` for infinite. Default `-1`. | ## queue Queue enqueue result types. **Import** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} from iii_helpers.queue import ... ``` ### Types [`EnqueueResult`](#enqueueresult) ### EnqueueResult Result returned when a function is invoked with `TriggerAction.Enqueue`. | Name | Type | Required | Description | | ------------------ | ----- | -------- | ------------------------------------------- | | `messageReceiptId` | `str` | Yes | Unique receipt ID for the enqueued message. | ## stream Stream trigger configs, change events, IO inputs, and update operations. **Import** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} from iii_helpers.stream import ... ``` ### Types [`StreamAuthInput`](#streamauthinput) · [`StreamAuthResult`](#streamauthresult) · [`StreamChangeEvent`](#streamchangeevent) · [`StreamChangeEventDetail`](#streamchangeeventdetail) · [`StreamDeleteInput`](#streamdeleteinput) · [`StreamDeleteResult`](#streamdeleteresult) · [`StreamGetInput`](#streamgetinput) · [`StreamJoinLeaveEvent`](#streamjoinleaveevent) · [`StreamJoinLeaveTriggerConfig`](#streamjoinleavetriggerconfig) · [`StreamJoinResult`](#streamjoinresult) · [`StreamListGroupsInput`](#streamlistgroupsinput) · [`StreamListInput`](#streamlistinput) · [`StreamSetInput`](#streamsetinput) · [`StreamSetResult`](#streamsetresult) · [`StreamTriggerConfig`](#streamtriggerconfig) · [`StreamUpdateInput`](#streamupdateinput) · [`StreamUpdateResult`](#streamupdateresult) · [`UpdateAppend`](#updateappend) · [`UpdateDecrement`](#updatedecrement) · [`UpdateIncrement`](#updateincrement) · [`UpdateMerge`](#updatemerge) · [`UpdateOpError`](#updateoperror) · [`UpdateRemove`](#updateremove) · [`UpdateSet`](#updateset) ### StreamAuthInput Input for stream authentication. | Name | Type | Required | Description | | -------------- | ---------------------- | -------- | ----------------- | | `addr` | `str` | Yes | Client address. | | `headers` | `dict[str, str]` | Yes | Request headers. | | `path` | `str` | Yes | Request path. | | `query_params` | `dict[str, list[str]]` | Yes | Query parameters. | *** ### StreamAuthResult Result of stream authentication. | Name | Type | Required | Description | | --------- | ------------- | -------- | ----------------------------------------------------------------- | | `context` | `Any \| None` | No | Arbitrary context passed to stream handlers after authentication. | *** ### StreamChangeEvent Handler input for `stream` triggers, fired when an item changes via `stream::set`, `stream::update`, or `stream::delete`. | Name | Type | Required | Description | | ------------ | ----------------------------------------------------- | -------- | --------------------------------------------------- | | `event` | [`StreamChangeEventDetail`](#streamchangeeventdetail) | Yes | The event detail containing mutation type and data. | | `groupId` | `str` | Yes | The group where the change occurred. | | `id` | `str \| None` | No | The item ID that changed. | | `streamName` | `str` | Yes | The stream where the change occurred. | | `timestamp` | `int` | Yes | Unix timestamp of the event. | | `type` | `Literal['stream']` | Yes | The event type. | *** ### StreamChangeEventDetail Detail of a stream change event containing the mutation type and data. | Name | Type | Required | Description | | ------ | --------------------------------------- | -------- | ------------------------------------------------- | | `data` | `Any` | Yes | The data associated with the event. | | `type` | `Literal['create', 'update', 'delete']` | Yes | The kind of mutation (create, update, or delete). | *** ### StreamDeleteInput Input for stream delete operation. | Name | Type | Required | Description | | ------------- | ----- | -------- | ------------------- | | `group_id` | `str` | Yes | Group identifier. | | `item_id` | `str` | Yes | Item identifier. | | `stream_name` | `str` | Yes | Name of the stream. | *** ### StreamDeleteResult Result of stream delete operation. | Name | Type | Required | Description | | ----------- | ------------- | -------- | ------------------------------- | | `old_value` | `Any \| None` | No | Previous value (if it existed). | *** ### StreamGetInput Input for stream get operation. | Name | Type | Required | Description | | ------------- | ----- | -------- | ------------------- | | `group_id` | `str` | Yes | Group identifier. | | `item_id` | `str` | Yes | Item identifier. | | `stream_name` | `str` | Yes | Name of the stream. | *** ### StreamJoinLeaveEvent Event for stream join/leave. | Name | Type | Required | Description | | ----------------- | ------------- | -------- | -------------------------------------------- | | `context` | `Any \| None` | No | Auth context from :class:`StreamAuthResult`. | | `group_id` | `str` | Yes | Group identifier. | | `id` | `str \| None` | No | Item identifier (if applicable). | | `stream_name` | `str` | Yes | Name of the stream. | | `subscription_id` | `str` | Yes | Unique subscription identifier. | *** ### StreamJoinLeaveTriggerConfig Trigger config for `stream:join` and `stream:leave` triggers. | Name | Type | Required | Description | | ----------------------- | ------------- | -------- | ------------------------------------------------------------------------------------- | | `condition_function_id` | `str \| None` | No | Function ID for conditional execution. If it returns `False`, the handler is skipped. | *** ### StreamJoinResult Result of stream join. | Name | Type | Required | Description | | -------------- | ------ | -------- | ---------------------------------- | | `unauthorized` | `bool` | Yes | Whether the join was unauthorized. | *** ### StreamListGroupsInput Input for stream list groups operation. | Name | Type | Required | Description | | ------------- | ----- | -------- | ------------------- | | `stream_name` | `str` | Yes | Name of the stream. | *** ### StreamListInput Input for stream list operation. | Name | Type | Required | Description | | ------------- | ----- | -------- | ------------------- | | `group_id` | `str` | Yes | Group identifier. | | `stream_name` | `str` | Yes | Name of the stream. | *** ### StreamSetInput Input for stream set operation. | Name | Type | Required | Description | | ------------- | ----- | -------- | ------------------- | | `data` | `Any` | Yes | Data to store. | | `group_id` | `str` | Yes | Group identifier. | | `item_id` | `str` | Yes | Item identifier. | | `stream_name` | `str` | Yes | Name of the stream. | *** ### StreamSetResult Result of stream set operation. | Name | Type | Required | Description | | ----------- | --------------- | -------- | ------------------------------- | | `new_value` | `TData` | Yes | New value that was stored. | | `old_value` | `TData \| None` | No | Previous value (if it existed). | *** ### StreamTriggerConfig Trigger config for `stream` triggers. Filters which item changes fire the handler. | Name | Type | Required | Description | | ----------------------- | ------------- | -------- | ------------------------------------------------------------------------------------- | | `condition_function_id` | `str \| None` | No | Function ID for conditional execution. If it returns `False`, the handler is skipped. | | `group_id` | `str \| None` | No | If set, only changes within this group fire the handler. | | `item_id` | `str \| None` | No | If set, only changes to this specific item fire the handler. | | `stream_name` | `str` | Yes | Stream name to watch. Only changes on this stream fire the handler. | *** ### StreamUpdateInput Input for stream update operation. | Name | Type | Required | Description | | ------------- | ------------------ | -------- | ------------------------------------------------------ | | `group_id` | `str` | Yes | Group identifier. | | `item_id` | `str` | Yes | Item identifier. | | `ops` | `list['UpdateOp']` | Yes | Ordered list of update operations to apply atomically. | | `stream_name` | `str` | Yes | Name of the stream. | *** ### StreamUpdateResult Result of stream update operation. | Name | Type | Required | Description | | ----------- | ---------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `errors` | list\[[`UpdateOpError`](#updateoperror)] | No | Per-op errors. Emitted by `merge` and `append` for validation rejections (path depth/size, value depth, or a `__proto__` / `constructor` / `prototype` segment or top-level key) and by `append` for the `append.type_mismatch` and `append.target_not_object` surfaces. Successfully applied ops are still reflected in `new_value`. The field is omitted from the JSON wire when empty. | | `new_value` | `TData` | Yes | New value after the update. | | `old_value` | `TData \| None` | No | Previous value (if it existed). | *** ### UpdateAppend Append an element to an array, concatenate a string, or push at a nested path. The target is the root (when `path` is omitted, an empty string, or an empty list), a single first-level key (when `path` is a non-empty string), or an arbitrary nested location (when `path` is a list of literal segments). Path forms accepted (mirrors :class:`UpdateMerge` after #1547): * `None` / `""` / `[]`: append at the root. * `"foo"`: append at the first-level key `foo`. A dotted string like `"a.b"` is the literal key `"a.b"`, *not* traversed as `a -> b`. * `["a", "b", "c"]`: nested path; each element is a literal segment. Engine semantics: * Missing/non-object intermediates along a nested path are auto-created/replaced with `\{\}`. * At the leaf: * missing/null + nested path -> `[value]` (always an array) * missing/null + single-string path -> string-as-string for the string-concat tier, otherwise `[value]` * existing array -> push * existing string + string value -> concatenate * existing object/scalar at the leaf -> `append.type_mismatch` Validation: invalid paths (depth > 32 segments, segment > 256 bytes, or any `__proto__` / `constructor` / `prototype` segment) are rejected with a structured error in the `errors` field of the `state::update` / `stream::update` response. The append does not apply when an error is returned for that op. | Name | Type | Required | Description | | ------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `path` | `MergePath \| None` | No | Optional path to the append target. Accepts a single first-level key (legacy string) or a list of literal segments for nested append. See :data:`MergePath`. | | `type` | `str` | No | - | | `value` | `Any` | Yes | Value to append. String targets only accept string values. | *** ### UpdateDecrement Decrement a numeric field by a given amount. | Name | Type | Required | Description | | ------ | -------------- | -------- | ----------------------- | | `by` | `int \| float` | Yes | Amount to decrement by. | | `path` | `str` | Yes | First-level field path. | | `type` | `str` | No | - | *** ### UpdateIncrement Increment a numeric field by a given amount. | Name | Type | Required | Description | | ------ | -------------- | -------- | ----------------------- | | `by` | `int \| float` | Yes | Amount to increment by. | | `path` | `str` | Yes | First-level field path. | | `type` | `str` | No | - | *** ### UpdateMerge Shallow merge an object into the target. The target is the root (when `path` is omitted, an empty string, or an empty list) or an arbitrary nested location specified by an array of literal segments. Path forms accepted: * `None` / `""` / `[]`: merge at the root. * `"foo"`: equivalent to `["foo"]`; single first-level key. * `["a", "b", "c"]`: nested path. Each element is a *literal* key. `["a.b"]` writes a single key named `"a.b"`, not `a -> b`. Engine semantics: * Missing or non-object intermediates along the path are auto-replaced with `\{\}`. * The merge is shallow at the target node (top-level keys of `value` overwrite same-named keys; siblings preserved). Validation: invalid paths/values (depth > 32 segments, segment > 256 bytes, value depth > 16, > 1024 top-level keys, or any `__proto__` / `constructor` / `prototype` segment or top-level key) are rejected with a structured error in the `errors` array of the `state::update` / `stream::update` response. The merge does not apply when an error is returned. | Name | Type | Required | Description | | ------- | ------------------- | -------- | --------------------------------------------------------- | | `path` | `MergePath \| None` | No | Optional path to the merge target. See :data:`MergePath`. | | `type` | `str` | No | - | | `value` | `Any` | Yes | Object to merge. Must be a JSON object. | *** ### UpdateOpError Per-op error returned by `state::update` / `stream::update`. Emitted by the `merge` and `append` ops when input violates the validation bounds, and by `append` for its type-mismatch and target-not-object cases. Successfully applied ops are still reflected in the response's `new_value`. | Name | Type | Required | Description | | ---------- | ------------- | -------- | ----------------------------------------------------------------- | | `code` | `str` | Yes | Stable error code, e.g. `"merge.path.too_deep"`. | | `doc_url` | `str \| None` | No | Optional documentation URL. | | `message` | `str` | Yes | Human-readable description with concrete numbers when applicable. | | `op_index` | `int` | Yes | Index of the offending op within the original `ops` array. | *** ### UpdateRemove Remove a field at the given path. | Name | Type | Required | Description | | ------ | ----- | -------- | ----------------------- | | `path` | `str` | Yes | First-level field path. | | `type` | `str` | No | - | *** ### UpdateSet Set a field at the given path to a value. | Name | Type | Required | Description | | ------- | ----- | -------- | --------------------------------------------------------------------- | | `path` | `str` | Yes | First-level field path. Use an empty string to target the root value. | | `type` | `str` | No | - | | `value` | `Any` | Yes | Value to set. | ## worker\_connection\_manager RBAC auth and registration callback types. **Import** ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} from iii_helpers.worker_connection_manager import ... ``` ### Types [`AuthInput`](#authinput) · [`AuthResult`](#authresult) · [`OnFunctionRegistrationInput`](#onfunctionregistrationinput) · [`OnFunctionRegistrationResult`](#onfunctionregistrationresult) · [`OnTriggerRegistrationInput`](#ontriggerregistrationinput) · [`OnTriggerRegistrationResult`](#ontriggerregistrationresult) · [`OnTriggerTypeRegistrationInput`](#ontriggertyperegistrationinput) · [`OnTriggerTypeRegistrationResult`](#ontriggertyperegistrationresult) ### 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` | `dict[str, str]` | Yes | HTTP headers from the WebSocket upgrade request. | | `ip_address` | `str` | Yes | IP address of the connecting client. | | `query_params` | `dict[str, list[str]]` | Yes | Query parameters from the upgrade URL. Each key maps to a list of values to support repeated keys. | *** ### 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 | | --------------------------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------ | | `allow_function_registration` | `bool` | No | Whether the worker may register new functions. Defaults to `True` if omitted. | | `allow_trigger_type_registration` | `bool` | No | Whether the worker may register new trigger types. | | `allowed_functions` | `list[str]` | No | Additional function IDs to allow beyond `expose_functions`. | | `allowed_trigger_types` | `list[str] \| None` | No | Trigger type IDs the worker may register triggers for. When `None`, all types are allowed. | | `context` | `dict[str, Any]` | No | Arbitrary context forwarded to the middleware function on every invocation. | | `forbidden_functions` | `list[str]` | No | Function IDs to deny even if they match `expose_functions`. | | `function_registration_prefix` | `str \| None` | 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 raise an exception to deny the registration. | Name | Type | Required | Description | | ------------- | ------------------------ | -------- | -------------------------------------------------------- | | `context` | `dict[str, Any]` | Yes | Auth context from `AuthResult.context` for this session. | | `description` | `str \| None` | No | Human-readable description of the function. | | `function_id` | `str` | Yes | ID of the function being registered. | | `metadata` | `dict[str, Any] \| None` | No | Arbitrary metadata attached to the function. | *** ### 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 | | ------------- | ------------------------ | -------- | ------------------- | | `description` | `str \| None` | No | Mapped description. | | `function_id` | `str \| None` | No | Mapped function ID. | | `metadata` | `dict[str, Any] \| None` | No | Mapped metadata. | *** ### OnTriggerRegistrationInput Input passed to the `on_trigger_registration_function_id` hook when a worker attempts to register a trigger through the RBAC port. Return an `OnTriggerRegistrationResult` with the (possibly mapped) fields, or raise an exception to deny the registration. | Name | Type | Required | Description | | -------------- | ------------------------ | -------- | -------------------------------------------------------- | | `config` | `Any` | No | Trigger-specific configuration. | | `context` | `dict[str, Any]` | Yes | Auth context from `AuthResult.context` for this session. | | `function_id` | `str` | Yes | ID of the function this trigger is bound to. | | `metadata` | `dict[str, Any] \| None` | No | Arbitrary metadata attached to the trigger. | | `trigger_id` | `str` | Yes | ID of the trigger being registered. | | `trigger_type` | `str` | Yes | Trigger type identifier. | *** ### OnTriggerRegistrationResult Result returned from the `on_trigger_registration_function_id` hook. Omitted fields keep the original value from the registration request. | Name | Type | Required | Description | | -------------- | ------------- | -------- | ----------------------------- | | `config` | `Any` | No | Mapped trigger configuration. | | `function_id` | `str \| None` | No | Mapped function ID. | | `trigger_id` | `str \| None` | No | Mapped trigger ID. | | `trigger_type` | `str \| None` | No | Mapped trigger type. | *** ### OnTriggerTypeRegistrationInput Input passed to the `on_trigger_type_registration_function_id` hook when a worker attempts to register a new trigger type through the RBAC port. Return an `OnTriggerTypeRegistrationResult` with the (possibly mapped) fields, or raise an exception to deny the registration. | Name | Type | Required | Description | | ----------------- | ---------------- | -------- | -------------------------------------------------------- | | `context` | `dict[str, Any]` | Yes | Auth context from `AuthResult.context` for this session. | | `description` | `str` | Yes | Human-readable description of the trigger type. | | `trigger_type_id` | `str` | Yes | ID of the trigger type being registered. | *** ### OnTriggerTypeRegistrationResult Result returned from the `on_trigger_type_registration_function_id` hook. Omitted fields keep the original value from the registration request. | Name | Type | Required | Description | | ----------------- | ------------- | -------- | ----------------------- | | `description` | `str \| None` | No | Mapped description. | | `trigger_type_id` | `str \| None` | No | Mapped trigger type ID. |