Server Runtime Overview

WebSocket server runtime for AIRI integrations and module communication

Overview

The @proj-airi/server-runtime package provides a WebSocket-based server runtime that enables real-time communication between AIRI modules, plugins, and clients. It handles authentication, routing, heartbeat management, and module registry synchronization.

Installation

npm install @proj-airi/server-runtime

Key Features

• WebSocket Communication: Real-time bidirectional communication using H3 and crossws
• Authentication: Token-based authentication for secure connections
• Module Registry: Automatic discovery and synchronization of connected modules
• Routing Middleware: Flexible routing with policy-based access control
• Heartbeat Management: Automatic connection health monitoring
• Event Broadcasting: Intelligent event routing to appropriate peers

Basic Usage

import { setupApp } from '@proj-airi/server-runtime'
import { listen } from 'listhen'

const { app, closeAllPeers } = setupApp({
  instanceId: 'my-server',
  auth: {
    token: 'your-secret-token'
  },
  logger: {
    app: { level: 'log', format: 'pretty' }
  }
})

// Start the server
const server = await listen(app, {
  port: 6121,
  hostname: 'localhost'
})

console.log(`Server running at ${server.url}`)

Configuration

instanceId · string

Unique identifier for the server instance. Defaults to a generated nanoid.

auth.token · string

Authentication token required for client connections. If not provided, authentication is disabled.

logger.app.level · LogLevelString

Application log level: 'trace', 'debug', 'log', 'warn', 'error'. Defaults to 'log'.

logger.app.format · Format

Log format: 'pretty' or 'json'. Defaults to 'pretty'.

logger.websocket.level · LogLevelString

WebSocket-specific log level. Defaults to app log level.

routing.middleware · RouteMiddleware[]

Custom routing middleware functions for event filtering and routing decisions.

routing.allowBypass · boolean

Allow devtools peers to bypass routing policies. Defaults to true.

routing.policy · RoutingPolicy

Routing policy for plugin and label-based access control.

heartbeat.readTimeout · number

Heartbeat timeout in milliseconds. Defaults to 60000 (60 seconds).

heartbeat.message · MessageHeartbeat | string

Custom heartbeat message. Defaults to MessageHeartbeat.Pong.

Return Value

app · H3

H3 application instance with WebSocket handler configured.

closeAllPeers · () => void

Function to close all connected peer connections.

Event Types

The server handles the following WebSocket event types:

• transport:connection:heartbeat - Connection health monitoring
• module:authenticate - Client authentication
• module:announce - Module registration and announcement
• registry:modules:sync - Module registry synchronization
• ui:configure - Module configuration from UI
• Custom events - Routed to appropriate peers based on routing rules

Environment Variables

The server runtime supports the following environment variables:

• SERVER_INSTANCE_ID - Server instance identifier
• AUTHENTICATION_TOKEN - Default authentication token
• LOG_LEVEL - Default log level
• LOG_FORMAT - Default log format

Architecture

The server runtime follows a peer-to-peer architecture where:

1. Clients connect via WebSocket to /ws
2. Authentication occurs if a token is configured
3. Module announcement registers the client in the module registry
4. Events are routed based on destinations and routing policies
5. Heartbeats maintain connection health

Next Steps

WebSocket Protocol

Learn about the WebSocket protocol and message format

Event System

Explore the event system and routing mechanisms