Skip to main content
The Worker Module opens a WebSocket server that SDK workers connect to. Through this connection, workers register functions, receive invocations, manage triggers, and stream data via channels. 
modules::worker::WorkerModule
The WorkerModule is mandatory and always loaded. When explicitly configured in the modules: section, the first entry’s port sets the main engine WebSocket port. Additional entries start separate listeners — optionally with an rbac block for role-based access control. Multiple WorkerModule entries are supported.

​
Architecture

Workers connect via WebSocket, send a registration message with metadata (runtime, version, OS), and then exchange messages with the engine for the lifetime of the connection. On disconnect, the worker and any session-scoped triggers are cleaned up automatically.

​
Sample Configuration

iii-config.yaml
modules:
  # Main engine port — workers connect here by default
  - class: modules::worker::WorkerModule
    config:
      port: 49134

  # Additional listener with middleware and RBAC
  - class: modules::worker::WorkerModule
    config:
      host: 0.0.0.0
      port: 49135
      middleware_function_id: my-project::middleware-function
      rbac:
        auth_function_id: my-project::auth-function
        on_trigger_registration_function_id: my-project::on-trigger-reg
        on_trigger_type_registration_function_id: my-project::on-trigger-type-reg
        expose_functions:
          - match("engine::*")
          - match("*::public")
          - metadata:
              public: true
          - metadata:
              name: match("*public*")

​
Configuration

Top-level fields on the config object:
​
port
number
required
The port to listen on. For the first WorkerModule entry this sets the main engine WebSocket port. Additional entries start separate listeners. Defaults to 49134.
​
host
string
The host to bind to. Defaults to 0.0.0.0.
​
middleware_function_id
string
Function ID to invoke before every function call from a worker on this port. Receives a MiddlewareFunctionInput with the target function ID, payload, action, and auth context. The middleware is responsible for calling the target function and returning the result.
​
rbac
RbacConfig
RBAC configuration block. When present, the listener applies role-based access control to all connections. See RBAC below.

​
Middleware

When middleware_function_id is configured, every worker invocation on that port is routed through the middleware instead of calling the target function directly. Middleware can be used on any port, with or without RBAC.

​
MiddlewareFunctionInput

The middleware function receives: The middleware is responsible for calling the target function (e.g. via trigger()) and returning the result. This gives you full control to modify, validate, or audit requests.

​
RBAC

When the rbac block is present in a WorkerModule entry, that listener enforces role-based access control: authentication on connect, function-level authorization, and trigger registration controls.
For step-by-step instructions on enabling RBAC, writing auth and middleware functions, and connecting workers, see Worker RBAC.

​
RBAC Architecture

On connection to an RBAC port, the optional auth function is called with the request headers, query parameters, and client IP address. Once authenticated, workers can invoke exposed functions and register triggers subject to RBAC rules.

​
RBAC Configuration

​
auth_function_id
string
Function ID to invoke for authentication when a worker connects. Receives an AuthInput with headers, query parameters, and IP address. Must return an AuthResult object. If the function fails or returns no result, the connection is rejected.
​
expose_functions
FunctionFilter[]
List of filters that determine which functions are accessible to workers on the RBAC port. A function is accessible if it matches any filter. Two filter types are supported:
  • match(“pattern”) — Wildcard pattern on the function ID. * matches any characters.
  • metadata — Key-value conditions on function metadata.
​
on_trigger_registration_function_id
string
Function ID to invoke when a worker attempts to register a trigger. Receives the trigger details and auth context. Must return true to allow the registration.
​
on_trigger_type_registration_function_id
string
Function ID to invoke when a worker attempts to register a trigger type. Receives the trigger type details and auth context. Must return true to allow the registration.

​
Function Filters

​
Wildcard Match

Match functions by their ID using * as a wildcard: 
expose_functions:
  - match("engine::*")       # all functions starting with engine::
  - match("*::public")       # all functions ending with ::public
  - match("api::*::read")    # e.g. api::users::read, api::orders::read

​
Metadata Match

Match functions by their registered metadata. Values can be exact or use match() for wildcard patterns: 
expose_functions:
  - metadata:
      public: true                   # metadata.public === true
  - metadata:
      name: match("*public*")        # metadata.name contains "public"
      tier: "free"                   # metadata.tier === "free"
All keys in a metadata filter must match for the filter to pass (AND logic). Multiple filters in expose_functions use OR logic — a function is exposed if any filter matches.

​
Authentication

When auth_function_id is configured, the function is called on every new WebSocket connection before the worker can invoke any functions.

​
Auth Input

The auth function receives:

​
Auth Result

The auth function must return:

​
Access Resolution Order

  1. If the function is in forbidden_functions — denied
  2. If the function is in allowed_functions — allowed
  3. If the function is engine::channels::create — allowed (always whitelisted for channel support)
  4. If any expose_functions filter matches — allowed
  5. Otherwise — denied

​
Trigger Registration

Workers on an RBAC port can register trigger types and triggers when permitted by the auth result. Trigger type registration requires both conditions:
  1. allow_trigger_type_registration is true in the auth result
  2. If on_trigger_type_registration_function_id is configured, the hook returns true
Trigger registration requires both conditions:
  1. The trigger’s trigger_type is in allowed_trigger_types from the auth result
  2. If on_trigger_registration_function_id is configured, the hook returns true
Triggers registered by a session are automatically cleaned up when the worker disconnects.

​
Channel Support

Channels work on every WorkerModule port. The module mounts the channel WebSocket endpoint at /ws/channels/{channel_id} on the same port. SDK workers can use createChannel() without any changes. On RBAC ports, the engine::channels::create function is automatically whitelisted to enable channel creation. Channel data transfer uses the standard channel WebSocket endpoint, which validates access via the access_key capability token.

​
Protocol

The Worker module uses the standard iii engine WebSocket protocol. SDK workers connect with registerWorker() and everything works out of the box.

​
Worker to Server

TypeFieldsDescription
registerworkerruntime, version, name, os, telemetry, pidRegister the worker and send metadata.
registerfunctionfunction_id, metadataRegister a function. Not allowed on RBAC ports.
unregisterfunctionfunction_idUnregister a function. Not allowed on RBAC ports.
invokefunctioninvocation_id, function_id, dataInvoke a function. RBAC checks apply on RBAC ports.
registertriggertypeid, descriptionRegister a new trigger type. On RBAC ports, requires allow_trigger_type_registration.
registertriggerid, trigger_type, function_id, configRegister a trigger. On RBAC ports, requires the type to be in allowed_trigger_types.
unregistertriggeridUnregister a trigger owned by this session.
ping—Keepalive ping.

​
Server to Worker

TypeFieldsDescription
workerregisteredworker_idSent after successful connection and auth. The worker_id serves as the session ID.
invokefunctioninvocation_id, function_id, dataEngine invoking a function on the worker.
invocationresultinvocation_id, function_id, result?, error?Result of an invokefunction request.
pong—Response to ping.
If authentication fails on an RBAC port, the server sends a JSON error message ({"type":"error","error":{...}}) and closes the connection.

​
Security Considerations

  • The RBAC port should be the only port exposed to external networks. The main engine port should remain internal.
  • Always configure auth_function_id in production to prevent unauthenticated access on RBAC ports.
  • Use expose_functions to limit the blast radius. Prefer explicit patterns over broad wildcards like match("*").
  • The middleware function is the right place for request validation, rate limiting, and audit logging.
  • forbidden_functions from the auth result takes precedence over all other allow rules, providing a hard deny mechanism per worker.
  • Trigger registrations are scoped to the session and cleaned up on disconnect.