Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us