Helpers (Node.js)

Installation

npm install @iii-dev/helpers

API reference for the @iii-dev/helpers package (Node.js / TypeScript).

http

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

import { ... } from '@iii-dev/helpers/http'

Functions

http

Helper that wraps an HTTP-style handler (with separate req/res arguments) into the function handler format expected by the SDK. Signature

http(callback: (req: HttpStreamingRequest, res: HttpStreamingResponse) => Promise<void | HttpResponse<number, string | Buffer<ArrayBufferLike> | Record<string, unknown>>>) => (req: HttpInternalRequest) => Promise<void | HttpResponse<number, string | Buffer<ArrayBufferLike> | Record<string, unknown>>>

Parameters
Example

callback

(req: HttpStreamingRequest, res: HttpStreamingResponse) => Promise<void | HttpResponse<number, string | Buffer<ArrayBufferLike> | Record<string, unknown>>>

required

Async handler receiving a streaming request and response.

import { http } from '@iii-dev/helpers/http'

worker.registerFunction(
  'my-api',
  http(async (req, res) => {
    res.status(200)
    res.headers({ 'content-type': 'application/json' })
    res.stream.end(JSON.stringify({ hello: 'world' }))
    res.close()
  }),
)

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.
api_key: API key sent via a custom header.

type HttpAuthConfig = { secret_key: string; type: "hmac" } | { token_key: string; type: "bearer" } | { header: string; type: "api_key"; value_key: string }

HttpInvocationConfig

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

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

HttpMethod

HTTP method accepted by HttpInvocationConfig. Distinct from the core builtin_triggers HTTP method enum, which also covers HEAD/OPTIONS.

type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE"

HttpRequest

Incoming buffered HTTP request received by a function handler.

Name	Type	Required	Description
`body`	`TBody`	Yes	Parsed request body.
`headers`	`Record<string, string \| string[]>`	Yes	Request headers.
`method`	`string`	Yes	HTTP method of the request (e.g. `GET`, `POST`).
`path_params`	`Record<string, string>`	Yes	Path parameters extracted from the matched route.
`query_params`	`Record<string, string \| string[]>`	Yes	Query-string parameters from the request URL.
`request_body`	`HttpStreamReader`	Yes	Streaming reader for the raw request body.

HttpResponse

Structured buffered HTTP response returned from function handlers.

Name	Type	Required	Description
`body`	`TBody`	No	Response body.
`headers`	`Record<string, string>`	No	Response headers.
`status_code`	`TStatus`	Yes	HTTP status code.

observability

Logger, OpenTelemetry config, and span helpers. Import

import { ... } from '@iii-dev/helpers/observability'

Functions

currentSpanId

Extract the current span ID from the active span context. Signature

currentSpanId() => string | undefined

currentSpanIsRecording

Returns false when there is no active span or the sampler dropped it. Signature

currentSpanIsRecording() => boolean

currentTraceId

Extract the current trace ID from the active span context. Signature

currentTraceId() => string | undefined

executeTracedRequest

Execute a fetch request inside an OTel CLIENT span. Mirrors the Rust execute_traced_request shape: injects W3C traceparent into outgoing headers, records HTTP semantic-convention attributes, and sets ERROR span status for HTTP responses with status >= 400 or network errors. Signature

executeTracedRequest(input: RequestInfo | URL, init?: TracedFetchInit) => Promise<Response>

Parameters

input

RequestInfo | URL

required

The resource to fetch: a URL string, URL, or Request.

init

TracedFetchInit

Fetch options, plus an optional tracer to create the span.

extractBaggage

Extract baggage from a W3C baggage header string. Signature

extractBaggage(baggage: string) => Context

Parameters

baggage

string

required

W3C baggage header value to parse.

extractContext

Extract both trace context and baggage from their respective headers. Signature

extractContext(traceparent?: string, baggage?: string) => Context

Parameters

traceparent

string

W3C traceparent header value to parse.

baggage

string

W3C baggage header value to parse.

extractTraceparent

Extract a trace context from a W3C traceparent header string. Signature

extractTraceparent(traceparent: string) => Context

Parameters

traceparent

string

required

W3C traceparent header value to parse.

flushOtel

Force-flush all OTel providers without tearing them down. Counterpart to shutdownOtel. Use before short-lived process exits where you want pending spans/metrics/logs delivered but plan to keep using OTel afterwards. Signature

flushOtel() => Promise<void>

getAllBaggage

Get all baggage entries from the current context. Signature

getAllBaggage() => Record<string, string>

getBaggageEntry

Get a baggage entry from the current context. Signature

getBaggageEntry(key: string) => string | undefined

Parameters

key

string

required

Baggage entry key to read.

getLogger

Get the OpenTelemetry logger instance. Signature

getLogger() => Logger | null

initOtel

Initialize OpenTelemetry with the given configuration. This should be called once at application startup. Signature

initOtel(config: OtelConfig) => void

Parameters

config

OtelConfig

required

OpenTelemetry configuration; env vars fill in unset fields.

injectBaggage

Inject the current baggage into a W3C baggage header string. Signature

injectBaggage() => string | undefined

injectTraceparent

Inject the current trace context into a W3C traceparent header string. Signature

injectTraceparent() => string | undefined

patchGlobalFetch

Patch globalThis.fetch to create OTel CLIENT spans for every HTTP request. Signature

patchGlobalFetch(tracer: Tracer) => void

Parameters

tracer

Tracer

required

Tracer used to create the client span for each request.

recordSpanEvent

No-op when the current span is not recording. Signature

recordSpanEvent(name: string, attrs?: Attributes) => void

Parameters

name

string

required

Name of the event to add to the active span.

attrs

Attributes

Optional attributes to attach to the event.

redact

Recursively redact values of sensitive keys. Returns a new value. Signature

redact(value: unknown) => unknown

Parameters

value

unknown

required

The value to recursively redact.

redactAndTruncate

Redact then serialize to JSON, optionally capped at maxBytes. Signature

redactAndTruncate(value: unknown, maxBytes: number | null) => { json: string; truncated: boolean }

Parameters

value

unknown

required

The value to redact and serialize.

maxBytes

number | null

required

Maximum serialized size in bytes; null leaves it uncapped.

registerWorkerGauges

Register OpenTelemetry observable gauges that report worker resource metrics (CPU, memory, event-loop) on each collection cycle. Signature

registerWorkerGauges(meter: Meter, options: WorkerGaugesOptions) => void

Parameters

meter

Meter

required

options

WorkerGaugesOptions

required

removeBaggageEntry

Remove a baggage entry from the current context. Signature

removeBaggageEntry(key: string) => Context

Parameters

key

string

required

Baggage entry key to remove.

resolveMaxBytesFromEnv

Resolve the payload byte cap from the environment, returning undefined when unset. Signature

resolveMaxBytesFromEnv() => number | null

safeStringify

Safely stringify a value, handling circular references, BigInt, and other edge cases. Returns “[unserializable]” if serialization fails for any reason. Signature

safeStringify(value: unknown) => string

Parameters

value

unknown

required

The value to serialize to JSON.

setBaggageEntry

Set a baggage entry in the current context. Signature

setBaggageEntry(key: string, value: string) => Context

Parameters

key

string

required

Baggage entry key to set.

value

string

required

Baggage entry value to set.

setCurrentSpanAttribute

No-op when the current span is not recording. Signature

setCurrentSpanAttribute(key: string, value: AttributeValue) => void

Parameters

key

string

required

Attribute key to set on the active span.

value

AttributeValue

required

Attribute value to set.

setCurrentSpanError

No-op when there is no active span. Signature

setCurrentSpanError(message: string) => void

Parameters

message

string

required

Error message to set as the span’s error status.

shutdownOtel

Shut down OpenTelemetry, best-effort flushing any pending data before teardown. Signature

shutdownOtel() => Promise<void>

stopWorkerGauges

Stop and unregister the worker resource gauges. Signature

stopWorkerGauges() => void

unpatchGlobalFetch

Restore globalThis.fetch to its original implementation. Signature

unpatchGlobalFetch() => void

withSpan

Start a new span with the given name and run the callback within it. Signature

withSpan(name: string, options: { kind?: SpanKind; traceparent?: string }, fn: (span: Span) => Promise<T>) => Promise<T>

Parameters

name

string

required

Name of the span to create.

options

{ kind?: SpanKind; traceparent?: string }

required

Span options: kind sets the span kind, traceparent sets the parent context from a W3C traceparent header.

(span: Span) => Promise<T>

required

Callback run inside the active span; its result is returned.

Types

BaggageSpanProcessor · Logger · OtelConfig · OtelLogEvent · ReconnectionConfig · TracedFetchInit · WorkerGaugesOptions · WorkerMetricsCollector · WorkerMetricsCollectorOptions

BaggageSpanProcessor

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

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 console.*. Pass structured data as the second argument to any log method. Using an object of key-value pairs (instead of string interpolation) lets you filter, aggregate, and build dashboards in your observability backend.

OtelConfig

Configuration for OpenTelemetry initialization.

Name	Type	Required	Description
`enabled`	`boolean`	No	Whether OpenTelemetry export is enabled. Defaults to true. Set to false or OTEL_ENABLED=false/0/no/off to disable.
`engineWsUrl`	`string`	No	III Engine WebSocket URL. Defaults to III_URL or “ws://localhost:49134”.
`fetchInstrumentationEnabled`	`boolean`	No	Whether to auto-instrument globalThis.fetch calls. Defaults to true. Works on Node.js, Bun, and Deno. Set to false to disable.
`instrumentations`	`Instrumentation<InstrumentationConfig>[]`	No	OpenTelemetry instrumentations to register (e.g., PrismaInstrumentation).
`logsBatchSize`	`number`	No	Maximum number of log records exported per batch. Defaults to 1.
`logsFlushIntervalMs`	`number`	No	Log processor flush delay in milliseconds. Defaults to 100ms. Env override: OTEL_LOGS_FLUSH_INTERVAL_MS.
`metricsEnabled`	`boolean`	No	Whether OpenTelemetry metrics export is enabled. Defaults to true. Set to false or OTEL_METRICS_ENABLED=false/0/no/off to disable.
`metricsExportIntervalMs`	`number`	No	Metrics export interval in milliseconds. Defaults to 60000 (60 seconds).
`reconnectionConfig`	Partial<`ReconnectionConfig`>	No	Optional reconnection configuration for the WebSocket connection.
`serviceInstanceId`	`string`	No	The service instance ID to report. Defaults to SERVICE_INSTANCE_ID env var or auto-generated UUID.
`serviceName`	`string`	No	The service name to report. Defaults to OTEL_SERVICE_NAME or “iii-node”.
`serviceNamespace`	`string`	No	The service namespace to report. Defaults to SERVICE_NAMESPACE env var.
`serviceVersion`	`string`	No	The service version to report. Defaults to SERVICE_VERSION env var or “unknown”.
`spansFlushIntervalMs`	`number`	No	Span processor flush delay in milliseconds. Defaults to 100ms. This is how long an ended span waits in the batch buffer before it is flushed to the engine, the OpenTelemetry default of 5000ms is what makes traces appear seconds after the action. Env override: OTEL_SPANS_FLUSH_INTERVAL_MS.

OtelLogEvent

OTEL Log Event from the engine

Name	Type	Required	Description
`attributes`	`Record<string, unknown>`	Yes	Structured attributes
`body`	`string`	Yes	Log message body
`instrumentation_scope_name`	`string`	No	Instrumentation scope name (if available)
`instrumentation_scope_version`	`string`	No	Instrumentation scope version (if available)
`observed_timestamp_unix_nano`	`number`	Yes	Observed timestamp in Unix nanoseconds
`resource`	`Record<string, string>`	Yes	Resource attributes from the emitting service
`service_name`	`string`	Yes	Service name that emitted the log
`severity_number`	`number`	Yes	OTEL severity number (1-24): TRACE=1-4, DEBUG=5-8, INFO=9-12, WARN=13-16, ERROR=17-20, FATAL=21-24
`severity_text`	`string`	Yes	Severity text (e.g., “INFO”, “WARN”, “ERROR”)
`span_id`	`string`	No	Span ID for correlation (if available)
`timestamp_unix_nano`	`number`	Yes	Timestamp in Unix nanoseconds
`trace_id`	`string`	No	Trace ID for correlation (if available)

ReconnectionConfig

Configuration for WebSocket reconnection behavior

Name	Type	Required	Description
`backoffMultiplier`	`number`	Yes	Exponential backoff multiplier (default: 2)
`initialDelayMs`	`number`	Yes	Starting delay in milliseconds (default: 1000ms)
`jitterFactor`	`number`	Yes	Random jitter factor 0-1 (default: 0.3)
`maxDelayMs`	`number`	Yes	Maximum delay cap in milliseconds (default: 30000ms)
`maxRetries`	`number`	Yes	Maximum retry attempts, -1 for infinite (default: -1)

TracedFetchInit

Name	Type	Required	Description
`tracer`	`Tracer`	No	Tracer used to create the client span for the outgoing request.

WorkerGaugesOptions

Name	Type	Required	Description
`workerId`	`string`	Yes	Stable identifier of the worker the gauges are reported for.
`workerName`	`string`	No	Human-readable name of the worker.

WorkerMetricsCollector

Collects worker resource metrics including CPU, memory, and event loop lag. Uses the Node.js monitorEventLoopDelay API for high-precision event loop delay measurements instead of manual setImmediate timing.

WorkerMetricsCollectorOptions

Configuration options for the WorkerMetricsCollector.

Name	Type	Required	Description
`eventLoopResolutionMs`	`number`	No	Event loop delay histogram resolution in milliseconds. Lower values provide more accurate measurements but use more resources.

queue

Queue enqueue result types. Import

import { ... } from '@iii-dev/helpers/queue'

Types

EnqueueResult

EnqueueResult

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

Name	Type	Required	Description
`messageReceiptId`	`string`	Yes	Unique receipt ID for the enqueued message.

stream

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

import { ... } from '@iii-dev/helpers/stream'

Types

MergePath · StreamAuthInput · StreamAuthResult · StreamChangeEvent · StreamChangeEventDetail · StreamContext · StreamDeleteInput · StreamDeleteResult · StreamGetInput · StreamJoinLeaveEvent · StreamJoinLeaveTriggerConfig · StreamJoinResult · StreamListGroupsInput · StreamListInput · StreamSetInput · StreamSetResult · StreamTriggerConfig · StreamUpdateInput · StreamUpdateResult · UpdateAppend · UpdateDecrement · UpdateIncrement · UpdateMerge · UpdateOp · UpdateOpError · UpdateRemove · UpdateSet

MergePath

Path target for a UpdateMerge op. Accepts:

a single string (legacy / first-level field)
an array of literal segments (nested path; each element is one literal key, dots are NOT interpreted as separators)

Omit path, pass "", or pass [] to target the root value.

type MergePath = string | string[]

StreamAuthInput

Input for stream authentication.

Name	Type	Required	Description
`addr`	`string`	Yes	Client address.
`headers`	`Record<string, string>`	Yes	Request headers.
`path`	`string`	Yes	Request path.
`query_params`	`Record<string, string[]>`	Yes	Query parameters.

StreamAuthResult

Result of stream authentication.

Name	Type	Required	Description
`context`	`any`	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`	Yes	The event detail containing mutation type and data.
`groupId`	`string`	Yes	The group where the change occurred.
`id`	`string`	No	The item ID that changed.
`streamName`	`string`	Yes	The stream where the change occurred.
`timestamp`	`number`	Yes	Unix timestamp of the event.
`type`	`"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`	`"create" \| "update" \| "delete"`	Yes	The kind of mutation (create, update, or delete).

StreamContext

Context type extracted from StreamAuthResult.

type StreamContext = StreamAuthResult["context"]

StreamDeleteInput

Input for deleting a stream item.

Name	Type	Required	Description
`group_id`	`string`	Yes	Group identifier.
`item_id`	`string`	Yes	Item identifier.
`stream_name`	`string`	Yes	Name of the stream.

StreamDeleteResult

Result of a stream delete operation.

Name	Type	Required	Description
`old_value`	`any`	No	Previous value (if it existed).

StreamGetInput

Input for retrieving a single stream item.

Name	Type	Required	Description
`group_id`	`string`	Yes	Group identifier.
`item_id`	`string`	Yes	Item identifier.
`stream_name`	`string`	Yes	Name of the stream.

StreamJoinLeaveEvent

Event payload for stream join/leave events.

Name	Type	Required	Description
`context`	`any`	No	Auth context from StreamAuthResult.
`group_id`	`string`	Yes	Group identifier.
`id`	`string`	No	Item identifier (if applicable).
`stream_name`	`string`	Yes	Name of the stream.
`subscription_id`	`string`	Yes	Unique subscription identifier.

StreamJoinLeaveTriggerConfig

Trigger config for stream:join and stream:leave triggers.

Name	Type	Required	Description
`condition_function_id`	`string`	No	Function ID for conditional execution. If it returns `false`, the handler is skipped.

StreamJoinResult

Result of a stream join request.

Name	Type	Required	Description
`unauthorized`	`boolean`	Yes	Whether the join was unauthorized.

StreamListGroupsInput

Input for listing all groups in a stream.

Name	Type	Required	Description
`stream_name`	`string`	Yes	Name of the stream.

StreamListInput

Input for listing all items in a stream group.

Name	Type	Required	Description
`group_id`	`string`	Yes	Group identifier.
`stream_name`	`string`	Yes	Name of the stream.

StreamSetInput

Input for setting a stream item.

Name	Type	Required	Description
`data`	`any`	Yes	Data to store.
`group_id`	`string`	Yes	Group identifier.
`item_id`	`string`	Yes	Item identifier.
`stream_name`	`string`	Yes	Name of the stream.

StreamSetResult

Result of a stream set operation.

Name	Type	Required	Description
`new_value`	`TData`	Yes	New value that was stored.
`old_value`	`TData`	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`	`string`	No	Function ID for conditional execution. If it returns `false`, the handler is skipped.
`group_id`	`string`	No	If set, only changes within this group fire the handler.
`item_id`	`string`	No	If set, only changes to this specific item fire the handler.
`stream_name`	`string`	Yes	Stream name to watch. Only changes on this stream fire the handler.

StreamUpdateInput

Input for atomically updating a stream item.

Name	Type	Required	Description
`group_id`	`string`	Yes	Group identifier.
`item_id`	`string`	Yes	Item identifier.
`ops`	`UpdateOp`[]	Yes	Ordered list of update operations to apply atomically.
`stream_name`	`string`	Yes	Name of the stream.

StreamUpdateResult

Result of a stream update operation.

Name	Type	Required	Description
`errors`	`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 case-2 `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`	No	Previous value (if it existed).

UpdateAppend

Append an element to an array, concatenate a string, or push a new value at a nested path. The target is the root (when path is omitted, empty, or []), a single first-level key (when path is a non-empty string), or an arbitrary nested location (when path is an array of literal segments). Engine semantics:

Missing or non-object intermediates along a nested path are auto-replaced with {} so a stray null or scalar never blocks future appends.
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
Each path segment is a literal key. ["a.b"] targets a single key named "a.b", not a → b.

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`	No	Optional path to the append target. Accepts a single first-level key (legacy `string`) or an array of literal segments for nested append. See MergePath (the same shape is reused).
`type`	`"append"`	Yes	-
`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`	`number`	Yes	Amount to decrement by.
`path`	`string`	Yes	First-level field path.
`type`	`"decrement"`	Yes	-

UpdateIncrement

Increment a numeric field by a given amount.

Name	Type	Required	Description
`by`	`number`	Yes	Amount to increment by.
`path`	`string`	Yes	First-level field path.
`type`	`"increment"`	Yes	-

UpdateMerge

Shallow-merge an object into the target. The target is the root (when path is omitted/empty) or an arbitrary nested location specified by an array of literal segments. Engine semantics:

Missing or non-object intermediates along the path are auto-replaced with {} so a stray null or scalar never blocks future merges.
The merge is shallow at the target, top-level keys of value replace same-named keys; siblings are preserved.
Each path segment is a literal key. ["a.b"] writes a single key named "a.b", not a → b.

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 field of the state::update / stream::update response. The merge does not apply when an error is returned for that op.

Name	Type	Required	Description
`path`	`MergePath`	No	Optional path to the merge target. See MergePath.
`type`	`"merge"`	Yes	-
`value`	`any`	Yes	Object to merge. Must be a JSON object.

UpdateOp

Union of all atomic update operations supported by streams.

type UpdateOp = UpdateSet | UpdateIncrement | UpdateDecrement | UpdateAppend | UpdateRemove | UpdateMerge

UpdateOpError

Per-op error returned by state::update / stream::update.

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

UpdateRemove

Remove a field at the given path.

Name	Type	Required	Description
`path`	`string`	Yes	First-level field path.
`type`	`"remove"`	Yes	-

UpdateSet

Set a field at the given path to a value.

Name	Type	Required	Description
`path`	`string`	Yes	First-level field path. Use an empty string to target the root value.
`type`	`"set"`	Yes	-
`value`	`any`	Yes	Value to set.

worker-connection-manager

RBAC auth and registration callback types. Import

import { ... } from '@iii-dev/helpers/worker-connection-manager'

Types

AuthInput · AuthResult · OnFunctionRegistrationInput · OnFunctionRegistrationResult · OnTriggerRegistrationInput · OnTriggerRegistrationResult · OnTriggerTypeRegistrationInput · 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`	`Record<string, string>`	Yes	HTTP headers from the WebSocket upgrade request.
`ip_address`	`string`	Yes	IP address of the connecting client.
`query_params`	`Record<string, string[]>`	Yes	Query parameters from the upgrade URL. Each key maps to an array 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`	`boolean`	No	Whether the worker may register new functions. Defaults to `true` if omitted.
`allow_trigger_type_registration`	`boolean`	No	Whether the worker may register new trigger types. Defaults to `false` if omitted.
`allowed_functions`	`string[]`	No	Additional function IDs to allow beyond the `expose_functions` config. Defaults to `[]` if omitted.
`allowed_trigger_types`	`string[]`	No	Trigger type IDs the worker may register triggers for. When omitted, all types are allowed.
`context`	`Record<string, unknown>`	No	Arbitrary context forwarded to the middleware function on every invocation. Defaults to `{}` if omitted.
`forbidden_functions`	`string[]`	No	Function IDs to deny even if they match `expose_functions`. Takes precedence over allowed. Defaults to `[]` if omitted.
`function_registration_prefix`	`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 throw to deny the registration.

Name	Type	Required	Description
`context`	`Record<string, unknown>`	Yes	Auth context from `AuthResult.context` for this session.
`description`	`string`	No	Human-readable description of the function.
`function_id`	`string`	Yes	ID of the function being registered.
`metadata`	`Record<string, unknown>`	No	Arbitrary metadata attached to the function.

OnFunctionRegistrationResult

Result returned from the on_function_registration_function_id hook. All fields are optional; omitted fields keep the original value from the registration request.

Name	Type	Required	Description
`description`	`string`	No	Mapped description.
`function_id`	`string`	No	Mapped function ID.
`metadata`	`Record<string, unknown>`	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 throw to deny the registration.

Name	Type	Required	Description
`config`	`unknown`	Yes	Trigger-specific configuration.
`context`	`Record<string, unknown>`	Yes	Auth context from `AuthResult.context` for this session.
`function_id`	`string`	Yes	ID of the function this trigger is bound to.
`metadata`	`Record<string, unknown>`	No	Arbitrary metadata attached to the trigger.
`trigger_id`	`string`	Yes	ID of the trigger being registered.
`trigger_type`	`string`	Yes	Trigger type identifier.

OnTriggerRegistrationResult

Result returned from the on_trigger_registration_function_id hook. All fields are optional; omitted fields keep the original value from the registration request.

Name	Type	Required	Description
`config`	`unknown`	No	Mapped trigger configuration.
`function_id`	`string`	No	Mapped function ID.
`trigger_id`	`string`	No	Mapped trigger ID.
`trigger_type`	`string`	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 throw to deny the registration.

Name	Type	Required	Description
`context`	`Record<string, unknown>`	Yes	Auth context from `AuthResult.context` for this session.
`description`	`string`	Yes	Human-readable description of the trigger type.
`trigger_type_id`	`string`	Yes	ID of the trigger type being registered.

OnTriggerTypeRegistrationResult

Result returned from the on_trigger_type_registration_function_id hook. All fields are optional; omitted fields keep the original value from the registration request.

Name	Type	Required	Description
`description`	`string`	No	Mapped description.
`trigger_type_id`	`string`	No	Mapped trigger type ID.

Browser SDK Helpers python

⌘I

​Installation

​http

​Functions

​http

​Types

​HttpAuthConfig

​HttpInvocationConfig

​HttpMethod

​HttpRequest

​HttpResponse

​observability

​Functions

​currentSpanId

​currentSpanIsRecording

​currentTraceId

​executeTracedRequest

​Parameters

​extractBaggage

​Parameters

​extractContext

​Parameters

​extractTraceparent

​Parameters

​flushOtel

​getAllBaggage

​getBaggageEntry

​Parameters

​getLogger

​initOtel

​Parameters

​injectBaggage

​injectTraceparent

​patchGlobalFetch

​Parameters

​recordSpanEvent

​Parameters

​redact

​Parameters

​redactAndTruncate

​Parameters

​registerWorkerGauges

​Parameters

​removeBaggageEntry

​Parameters

​resolveMaxBytesFromEnv

​safeStringify

​Parameters

​setBaggageEntry

​Parameters

​setCurrentSpanAttribute

​Parameters

​setCurrentSpanError

​Parameters

​shutdownOtel

​stopWorkerGauges

​unpatchGlobalFetch

​withSpan

​Parameters

​Types

​BaggageSpanProcessor

​Logger

​OtelConfig

​OtelLogEvent

​ReconnectionConfig

​TracedFetchInit

​WorkerGaugesOptions

​WorkerMetricsCollector

​WorkerMetricsCollectorOptions

​queue

​Types

​EnqueueResult

​stream

​Types

​MergePath

​StreamAuthInput

​StreamAuthResult

​StreamChangeEvent

​StreamChangeEventDetail

​StreamContext

​StreamDeleteInput

Installation

http

Functions

http

Types

HttpAuthConfig

HttpInvocationConfig

HttpMethod

HttpRequest

HttpResponse

observability

Functions

currentSpanId

currentSpanIsRecording

currentTraceId

executeTracedRequest

Parameters

extractBaggage

Parameters

extractContext

Parameters

extractTraceparent

Parameters

flushOtel

getAllBaggage

getBaggageEntry

Parameters

getLogger

initOtel

Parameters

injectBaggage

injectTraceparent

patchGlobalFetch

Parameters

recordSpanEvent

Parameters

redact

Parameters

redactAndTruncate

Parameters

registerWorkerGauges

Parameters

removeBaggageEntry

Parameters

resolveMaxBytesFromEnv

safeStringify

Parameters

setBaggageEntry

Parameters

setCurrentSpanAttribute

Parameters

setCurrentSpanError

Parameters

shutdownOtel

stopWorkerGauges

unpatchGlobalFetch

withSpan

Parameters

Types

BaggageSpanProcessor

Logger

OtelConfig

OtelLogEvent

ReconnectionConfig

TracedFetchInit

WorkerGaugesOptions

WorkerMetricsCollector

WorkerMetricsCollectorOptions

queue

Types

EnqueueResult

stream

Types

MergePath

StreamAuthInput

StreamAuthResult

StreamChangeEvent

StreamChangeEventDetail

StreamContext

StreamDeleteInput