Listeners

Transport listeners are pluggable components that handle network-level ingress connections for nodes. They manage server lifecycle tied to node lifecycle—starting when a node starts and stopping when it stops.

What Listeners Do

Listeners serve as the entry points for external connections to a node:

• Accept inbound connections over various transports (HTTP, WebSocket, browser channels)
• Route incoming messages to the node for processing
• Manage server lifecycle automatically with the node
• Provide callback grants for reverse connections (allowing parents to connect back to children)

A useful mental model: if a node is like a service, listeners are like the network interfaces that service binds to.

Available Listener Types

Server-Side Listeners (Node.js / Python)

Browser-Only Listeners (TypeScript)

Configuration

Listeners are configured in the listeners array within a node configuration:

const config = {
  node: {
    type: 'Sentinel',
    listeners: [
      {
        type: 'HttpListener',
        port: 8000,
        enabled: true,
      },
      {
        type: 'WebSocketListener',
        port: 8000,
        enabled: true,
      },
    ],
    // ... other config
  },
};

config = {
    "node": {
        "type": "Sentinel",
        "listeners": [
            {
                "type": "HttpListener",
                "port": 8000,
                "enabled": True,
            },
            {
                "type": "WebSocketListener",
                "port": 8000,
                "enabled": True,
            },
        ],
        # ... other config
    },
}

Common Configuration Options

The enabled Flag

The enabled property allows you to selectively enable or disable listeners without modifying the configuration structure. This is particularly useful when using pre-built configurations like SENTINEL_CONFIG:

import { SENTINEL_CONFIG } from '@naylence/agent-sdk';
 
// SENTINEL_CONFIG includes HttpListener, WebSocketListener, and AgentHttpGatewayListener
// Each can be enabled/disabled via environment variables:
// - FAME_LISTENER_HTTP_ENABLED (default: true)
// - FAME_LISTENER_WEBSOCKET_ENABLED (default: true)
// - FAME_LISTENER_AGENT_HTTP_GATEWAY_ENABLED (default: false)
 
const sentinel = new Sentinel(SENTINEL_CONFIG);

from naylence.agent import SENTINEL_CONFIG
 
# SENTINEL_CONFIG includes HttpListener, WebSocketListener, and AgentHttpGatewayListener
# Each can be enabled/disabled via environment variables:
# - FAME_LISTENER_HTTP_ENABLED (default: true)
# - FAME_LISTENER_WEBSOCKET_ENABLED (default: true)
# - FAME_LISTENER_AGENT_HTTP_GATEWAY_ENABLED (default: false)
 
sentinel = Sentinel(SENTINEL_CONFIG)

Disabled listeners are skipped during node initialization—they consume no resources and open no ports.

Listener Details

HttpListener

The HTTP listener provides a stateless REST-like interface for envelope delivery. It’s useful for:

• Fire-and-forget message delivery
• Request-response patterns over HTTP
• Integration with load balancers and HTTP proxies
• Environments where WebSocket connections aren’t practical

Endpoints:

• POST /fame/v1/ingress/upstream — Deliver envelopes to the node

WebSocketListener

The WebSocket listener handles persistent connections for the fabric protocol. It’s the primary transport for:

• Node attachment (downstream nodes connecting to sentinels)
• Peer connections between sentinels
• Long-lived bidirectional communication

Endpoints:

• GET /fame/v1/attach/ws/downstream — Downstream node attachment
• GET /fame/v1/attach/ws/peer — Peer sentinel attachment
• GET /fame/v1/attach/ws/upstream — Upstream (callback) connections

AgentHttpGatewayListener

The Agent HTTP Gateway provides a simplified HTTP API for interacting with agents. It’s designed for external clients that want to invoke agent methods without implementing the full fabric protocol.

Endpoints:

• POST /fame/v1/gateway/rpc — Synchronous RPC invocations
• POST /fame/v1/gateway/messages — Asynchronous message delivery
• GET /fame/v1/gateway/health — Health checks

export FAME_LISTENER_AGENT_HTTP_GATEWAY_ENABLED=true

Additional configuration options:

InPageListener (Browser)

The in-page listener uses a shared EventTarget for communication between components in the same page. All listeners and connectors with the same channel name share messages.

Configuration:

BroadcastChannelListener (Browser)

The broadcast channel listener enables communication across browser tabs and windows using the BroadcastChannel API.

Configuration:

How Listeners Work

Lifecycle

1. Node initialization — Listeners register their routes with the HTTP server (or initialize browser channels)
2. Node started — Listeners begin accepting connections
3. Node stopped — Listeners stop accepting new connections and clean up

Pluggable Factory System

Listeners use Naylence’s pluggable factory system. Each listener type has a corresponding factory:

• HttpListenerFactory → creates HttpListener
• WebSocketListenerFactory → creates WebSocketListener
• AgentHttpGatewayListenerFactory → creates AgentHttpGatewayListener
• etc.

When you specify a listener configuration with a type field, the factory system:

1. Looks up the registered factory for that type
2. Calls the factory’s create() method with the configuration
3. Returns the listener instance

This allows third-party packages to register custom listener types that integrate seamlessly with the configuration system.

Shared HTTP Server

Multiple listeners can share the same HTTP server. When you configure HttpListener and WebSocketListener on the same port, they share a single underlying server with different route prefixes:

listeners:
  - type: HttpListener
    port: 8000      # Routes: /fame/v1/ingress/*
  - type: WebSocketListener
    port: 8000      # Routes: /fame/v1/attach/*
  - type: AgentHttpGatewayListener
    port: 8000      # Routes: /fame/v1/gateway/*

Environment Variables

Control listener behavior via environment variables:

These variables work with the pre-built SENTINEL_CONFIG from @naylence/agent-sdk.

When to Use Which Listener

See Also

• Configuration Reference — Full configuration options and environment variables
• Sentinels — How sentinels use listeners to accept connections