# "Relay" _Path: en/framework/relay_ > "Configure Wippy Relay hubs, WebSocket clients, prefixed plugins, user isolation, and connection lifecycle." ## Table of Contents - Relay ## Content # Relay The `wippy/relay` module routes WebSocket connections through a central hub and per-user hubs. User hubs manage client connections and dispatch messages to prefixed plugins. This page is a partial integration recipe and protocol reference, not a standalone WebSocket application. The setup and plugin blocks assume an existing Wippy project, a real security scope at the configured `user_security_scope`, and an HTTP WebSocket endpoint connected to the relay as described in [WebSocket Relay](http/websocket-relay.md). Protocol payloads and lifecycle blocks are reference shapes. ## Architecture ``` Central Hub ├── User Hub (alice) │ ├── Plugin: session_ │ ├── Plugin: ai_ │ ├── WebSocket Client 1 │ └── WebSocket Client 2 ├── User Hub (bob) │ ├── Plugin: session_ │ └── WebSocket Client 1 └── ... ``` The central hub runs as a service. When a WebSocket client connects, it finds or creates a hub for that user. The user hub manages the connection lifecycle and routes messages by command prefix. ## Setup Add the module to your project: ```bash wippy add wippy/relay wippy install ``` Declare the dependency with required parameters: ```yaml version: "1.0" namespace: app entries: - name: os_env kind: env.storage.os - name: processes kind: process.host lifecycle: auto_start: true - name: dep.relay kind: ns.dependency component: wippy/relay version: "*" parameters: - name: application_host value: app:processes - name: env_storage value: app:os_env - name: user_security_scope value: app.security:user_scope ``` ### Configuration Parameters | Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | `application_host` | yes | — | Process host for relay processes | | `env_storage` | no | internal | Environment variable storage | | `user_security_scope` | yes | — | Security scope for user hubs | | `max_connections_per_user` | no | `5` | WebSocket connections per user | | `queue_multiplier` | no | `100` | Message queue = connections × multiplier | | `user_hub_inactivity_timeout` | no | `7200s` | Idle time before hub cleanup | ## Client Connection Flow 1. WebSocket client connects with `user_id` in metadata 2. Central hub validates the connection and checks per-user limits 3. Central hub creates or reuses a user hub for the user 4. User hub sends a `welcome` message to the client: ```json { "user_id": "alice", "client_count": 1, "plugins": [ { "prefix": "session_", "process_id": "...", "status": "running" }, { "prefix": "ai_", "process_id": "...", "status": "pending" } ] } ``` Plugin `status` can be `"not_started"` (registered but never spawned), `"pending"` (spawn in progress), `"running"`, `"failed"`, or `"stopped"`. ## Message Routing Clients send JSON messages with a `type` field. The user hub matches the type prefix against registered plugins and routes the message: ```json { "type": "session_get_state", "data": { "key": "value" } } ``` The `session_` prefix selects the session plugin. The hub removes the prefix and sends the message to the plugin process, using the remaining type as the topic: ```lua -- process topic: "get_state" -- payload: { conn_pid = client_pid, type = "session_get_state", -- original full type preserved data = { key = "value" }, request_id = "...", session_id = "..." } ``` Plugins respond by sending messages back to `conn_pid`. ## Plugins Plugins are `process.lua` entries with `meta.type: relay.plugin`: ```yaml entries: - name: session_plugin kind: process.lua meta: type: relay.plugin command_prefix: session_ auto_start: true source: file://session_plugin.lua modules: [json, time, logger] method: run ``` ### Plugin Metadata | Field | Type | Description | |-------|------|-------------| | `meta.type` | string | Must be `relay.plugin` | | `meta.command_prefix` | string | Message type prefix this plugin handles | | `meta.auto_start` | boolean | Start when user hub initializes | | `meta.default_host` | string | Override process host | ### Plugin Lifecycle The user hub spawns each plugin with these startup arguments: ```lua function run(args) local user_id = args.user_id local user_metadata = args.user_metadata local user_hub_pid = args.user_hub_pid local config = args.config end ``` The `session_` plugin receives lifecycle messages: | Message | When | |---------|------| | `"resume"` | First client connects to user hub | | `"shutdown"` | Last client disconnects from user hub | Plugins get 1 automatic restart on crash. After a second crash, the plugin is marked as `"failed"` and not restarted. ### Plugin Implementation Plugins receive messages through their process inbox. Each message has a topic derived from the command type and a payload containing the original message data and `conn_pid` for responses. ```lua local json = require("json") local function handle_message(topic, payload) if topic == "get_state" then if not payload.conn_pid then return nil, "Relay message is missing conn_pid" end local encoded, encode_err = json.encode({ type = "session_state", data = { status = "active" } }) if encode_err then return nil, encode_err end local sent, send_err = process.send(payload.conn_pid, "ws.message", encoded) if not sent then return nil, send_err or "Relay response was not sent" end end return true end local function run(args) local user_id = args.user_id local inbox = process.inbox() local events = process.events() while true do local result = channel.select({ inbox:case_receive(), events:case_receive() }) if not result.ok then break end if result.channel == inbox then local msg = result.value local topic = msg:topic() local payload = msg:payload():data() if topic == "resume" then -- first client connected elseif topic == "shutdown" then -- last client disconnected else local ok, err = handle_message(topic, payload) if not ok then error("Failed to handle relay message: " .. tostring(err)) end end elseif result.channel == events then local event = result.value if event.kind == process.event.CANCEL then break end end end end return { run = run } ``` ## Attention UI-action routing The private route carries both trait-authorized inspection and separately permitted interactive actions. Requests bind to the submitting Host tab for the active turn. Automatic context, message-context capability and overlay permission are not prerequisites for read-only inspection. Attention inspection and clarification use the session plugin rather than a general broadcast topic. The private broker binds each action to the authenticated user, session, session process, current WebSocket connection process, Host instance, request ID, action ID, and expiry. It sends `session_ui_action_request` directly to that connection. The Host replies with the on-wire command `session_ui_action_result`; relay prefix handling delivers that command to the plugin as `ui_action_result`. The Session plugin is the sole WebSocket inbox owner. It verifies sender and request, action, session, Host, connection, and target correlation before routing an accepted result to the requesting tool's private per-call mailbox, `session_ui_action_result:`. Framework tools wait on that mailbox and never create a second WebSocket subscription. The broker never places its delivery handle, connection PID, capability token, or other live authority in persisted messages, history, model context, or the target reference. A target reference is correlation data only: snapshot and target IDs, Host instance, mount generation, path digest, rectangle, and an optional label. Only one action can be pending for a session. The first valid terminal result wins. A wrong connection, session, Host instance, request/action correlation, target, or status is rejected. Expiry is capped at 120 seconds; disconnect, session cancellation, navigation/remount staleness, and process exit terminate the pending action without rerouting it to another connection. Reconnect requires a fresh action request. This protocol is internal. Application relay plugins and micro frontends must not publish `session_ui_action_request` or `session_ui_action_result` themselves. See [Agents](./agents.md#attention-context-and-ui-actions) and [Web Host Attention Context](../frontend/web-host/attention-context.md#agent-clarification-actions). ## Error Handling The relay reports client errors using these codes: | Error Code | Description | |------------|-------------| | `max_connections_reached` | User at connection limit | | `missing_user_id` | No user_id in connection metadata | | `hub_creation_failed` | Failed to spawn user hub | | `invalid_json` | Message decode error | | `unknown_command` | Message missing type field | | `plugin_not_found` | No plugin matches the command prefix | | `plugin_failed` | Plugin unavailable or crashed | ### User Hub Creation The first client connection for a user creates that user's hub. The hub runs with the user's security actor and scope. ### Garbage Collection The central hub periodically checks for inactive user hubs. A hub with no connected clients for longer than `user_hub_inactivity_timeout` (default 2 hours) is gracefully terminated with a 10-second cancel timeout. The GC check interval is automatically derived: `inactivity_timeout / 2.5`. ### Security The central hub runs under its own security group (`wippy.relay.security:root`) with full access. Each user hub spawns with the configured `user_security_scope`, isolating user-level operations. ## Internal Topics | Topic | Direction | Description | |-------|-----------|-------------| | `ws.join` | Client → Central/User Hub | Connection request | | `ws.leave` | Client → Central/User Hub | Disconnection | | `ws.message` | Client → User Hub | WebSocket message | | `ws.cancel` | Central → User Hub | Graceful shutdown | | `ws.control` | Central → Client | Redirects the client connection's target PID to its user hub | | `hub.activity_update` | User Hub → Central | Client count update | ## See Also - [WebSocket Relay](../http/websocket-relay.md) — HTTP WebSocket endpoint configuration - [Process Model](concepts/process-model.md) — Process lifecycle and messaging - [Security](system/security.md) — Security actors and scopes - [Framework Overview](framework/overview.md) — Install and import framework modules ## Navigation Previous: "Dataflow" (framework/dataflow) Next: "Views" (framework/views)