Transport Layer

Transport Abstraction

A core design goal of ANCP is that message producers and consumers are isolated from the transport mechanism. The ITransport interface in EdgeStream defines the contract that all transports implement:

interface ITransport {
  readonly id: string;
  readonly type: 'signalr' | 'http-polling' | 'sse' | 'websocket';
  readonly status: 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';

  connect(): Promise<void>;
  disconnect(): Promise<void>;
  send(data: string | ArrayBuffer): Promise<void>;
  onMessage(handler: (raw: string | ArrayBuffer) => void): () => void;
  onStatusChange(handler: (status: TransportStatus) => void): () => void;
  onError(handler: (error: Error) => void): () => void;
}

The ANCP router serializes the envelope to JSON (or another protocol format), hands it to the active transport's send() method, and receives raw bytes from onMessage() — it never knows or cares which physical transport is being used.

Available Transports

SignalR (Primary)

SignalR is the default and recommended transport for ANCP in BizFirstGO. It provides full-duplex WebSocket communication with automatic fallback to HTTP long-polling when WebSockets are unavailable. The ASP.NET Core SignalR hub acts as the ANCP message broker for browser clients and server-side node hosts.

Connection Flow

HTTP (Synchronous)

For server-to-server communication where real-time push is not required, ANCP messages can be sent as HTTP POST requests. This is common for inter-service calls within the backend, webhook delivery, and integrations with external APIs.

POST /api/ancp/messages HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

{
  "id":              "cmd-http-001",
  "type":            "Command",
  "source":          "service://tenant-acme/payroll-service",
  "destination":     "node://tenant-acme/flow-55/notify",
  "tenantId":        "tenant-acme",
  "timestamp":       "2026-05-25T09:10:00.000Z",
  "protocolVersion": "1.0",
  "payload": { "action": "sendPayslip", "employeeId": "E-100" }
}

SSE (Server-Sent Events)

SSE provides a one-way server-to-client push channel. It is a good fit for browser clients that only need to receive ANCP Events (notifications, status updates) without sending messages back. SSE connections survive HTTP/1.1 proxies that would block WebSocket upgrades.

EdgeStream Pub/Sub

EdgeStream's topic-based pub/sub is the transport for ANCP Events that need to fan out to multiple subscribers. The EdgeStream subscription manager handles wildcard matching, subscriber lifecycle, and message replay from the LRU cache. This is the preferred transport for Event-type ANCP messages.

Choosing the Right Transport

Transport Configuration

// TypeScript — configuring a SignalR transport
const transportConfig: TransportConfig = {
  type: 'signalr',
  url: 'https://api.bizfirst.io/hub',
  reconnect: {
    maxAttempts: 10,          // 0 = infinite
    initialDelayMs: 1000,     // 1 second before first retry
    maxDelayMs: 30000,        // cap at 30 seconds
    backoffMultiplier: 2.0    // exponential backoff
  },
  timeoutMs: 10000,
  accessToken: getJwtToken()  // called on each reconnect
};