Transports - HAIProtocol (HAIP)

New protocol version released: This page may contain outdated information.

The HAIP SDK supports multiple transport protocols for different environments and use cases. Each transport implements the same interface but uses different underlying communication mechanisms.

Transport Types

WebSocket Transport

The default and most feature-complete transport, supporting real-time bidirectional communication. Features:

Real-time bidirectional communication
Binary data support
Automatic reconnection
Flow control
Heartbeat monitoring

Usage:

import { createHAIPClient } from "haip-sdk";

const client = createHAIPClient({
  url: "ws://localhost:8080",
  token: "your-jwt-token",
  transport: "websocket",
});

Configuration Options:

url

string

required

WebSocket server URL (ws:// or wss://).

token

string

required

JWT authentication token.

options

WebSocketTransportOptions

Additional WebSocket-specific options.

interface WebSocketTransportOptions {
  maxReconnectAttempts?: number;
  reconnectDelay?: number;
  heartbeatInterval?: number;
  binaryType?: "arraybuffer" | "blob";
}

Server-Sent Events (SSE) Transport

Browser-only transport using Server-Sent Events for receiving data and HTTP POST for sending. Features:

Browser-native support
Automatic reconnection
HTTP POST for sending messages
Event stream parsing

Usage:

import { createHAIPClient } from "haip-sdk";

const client = createHAIPClient({
  url: "http://localhost:8080/sse",
  token: "your-jwt-token",
  transport: "sse",
});

Configuration Options:

url

string

required

SSE endpoint URL (http:// or https://).

token

string

required

JWT authentication token.

options

SSETransportOptions

Additional SSE-specific options.

interface SSETransportOptions {
  maxReconnectAttempts?: number;
  reconnectDelay?: number;
  withCredentials?: boolean;
  headers?: Record<string, string>;
}

Limitations:

Browser environment only
No binary data support
Unidirectional for receiving (uses HTTP POST for sending)

HTTP Streaming Transport

Universal transport using fetch streaming for both sending and receiving. Features:

Works in Node.js and browsers
Fetch-based streaming
Automatic reconnection
Universal compatibility

Usage:

import { createHAIPClient } from "haip-sdk";

const client = createHAIPClient({
  url: "http://localhost:8080/stream",
  token: "your-jwt-token",
  transport: "http-streaming",
});

Configuration Options:

url

string

required

HTTP streaming endpoint URL.

token

string

required

JWT authentication token.

options

HTTPStreamingTransportOptions

Additional HTTP streaming options.

interface HTTPStreamingTransportOptions {
  maxReconnectAttempts?: number;
  reconnectDelay?: number;
  timeout?: number;
  headers?: Record<string, string>;
}

Transport Comparison

Feature	WebSocket	SSE	HTTP Streaming
Environment	Node.js + Browser	Browser only	Node.js + Browser
Bidirectional	✅	❌ (POST for sending)	✅
Binary Support	✅	❌	✅
Real-time	✅	✅	✅
Reconnection	✅	✅	✅
Flow Control	✅	✅	✅
Heartbeat	✅	❌	❌
Performance	Excellent	Good	Good
Compatibility	High	Medium	High

Transport Selection

Choose WebSocket when:

You need full bidirectional communication
Binary data support is required
Maximum performance is needed
Both Node.js and browser environments

Choose SSE when:

Browser-only application
Server-sent events are preferred
Simpler server implementation
Real-time updates are the primary need

Choose HTTP Streaming when:

Universal compatibility is required
Fetch API is preferred
Both Node.js and browser support needed
Simpler deployment (no WebSocket server)

Transport Configuration

Global Configuration

const client = createHAIPClient({
  url: "ws://localhost:8080",
  token: "your-jwt-token",
  transport: "websocket",
  // Global transport options
  maxReconnectAttempts: 5,
  reconnectDelay: 1000,
  heartbeatInterval: 30000,
});

Transport-Specific Configuration

// WebSocket with custom options
const wsClient = createHAIPClient({
  url: "wss://secure-server.com",
  token: "your-jwt-token",
  transport: "websocket",
  options: {
    maxReconnectAttempts: 10,
    reconnectDelay: 2000,
    heartbeatInterval: 15000,
    binaryType: "arraybuffer",
  },
});

// SSE with custom headers
const sseClient = createHAIPClient({
  url: "https://api.example.com/sse",
  token: "your-jwt-token",
  transport: "sse",
  options: {
    withCredentials: true,
    headers: {
      "X-Custom-Header": "value",
    },
  },
});

// HTTP Streaming with timeout
const httpClient = createHAIPClient({
  url: "https://api.example.com/stream",
  token: "your-jwt-token",
  transport: "http-streaming",
  options: {
    timeout: 30000,
    headers: {
      "User-Agent": "HAIP-Client/1.0",
    },
  },
});

Connection Management

Automatic Reconnection

All transports support automatic reconnection with exponential backoff:

const client = createHAIPClient({
  url: "ws://localhost:8080",
  token: "your-jwt-token",
  transport: "websocket",
  maxReconnectAttempts: 5, // Maximum reconnection attempts
  reconnectDelay: 1000, // Initial delay (doubles each attempt)
});

Manual Reconnection

client.on("disconnect", (reason) => {
  console.log("Disconnected:", reason);

  // Manual reconnection
  setTimeout(async () => {
    try {
      await client.connect();
    } catch (error) {
      console.error("Reconnection failed:", error);
    }
  }, 5000);
});

Transport Events

All transports emit the same events:

client.on("connect", () => {
  console.log("Transport connected");
});

client.on("disconnect", (reason) => {
  console.log("Transport disconnected:", reason);
});

client.on("error", (error) => {
  console.error("Transport error:", error);
});

client.on("message", (message) => {
  console.log("Message received:", message);
});

client.on("binary", (data) => {
  console.log("Binary data received:", data.byteLength, "bytes");
});

Transport Health Monitoring

Connection State

const state = client.getConnectionState();
console.log("Connection state:", {
  connected: state.connected,
  handshakeCompleted: state.handshakeCompleted,
  sessionId: state.sessionId,
  reconnectAttempts: state.reconnectAttempts,
});

Performance Metrics

const metrics = client.getPerformanceMetrics();
console.log("Transport metrics:", {
  messagesSent: metrics.messagesSent,
  messagesReceived: metrics.messagesReceived,
  bytesSent: metrics.bytesSent,
  bytesReceived: metrics.bytesReceived,
  connectionTime: metrics.connectionTime,
});

Transport Switching

You can switch transports by creating a new client:

// Start with WebSocket
let client = createHAIPClient({
  url: "ws://localhost:8080",
  token: "your-jwt-token",
  transport: "websocket",
});

// Switch to HTTP streaming if WebSocket fails
client.on("error", async (error) => {
  if (error.message.includes("WebSocket connection failed")) {
    console.log("Switching to HTTP streaming...");

    await client.disconnect();

    client = createHAIPClient({
      url: "http://localhost:8080/stream",
      token: "your-jwt-token",
      transport: "http-streaming",
    });

    await client.connect();
  }
});

Transport Testing

Testing Different Transports

async function testTransport(transportType: string) {
  const client = createHAIPClient({
    url:
      transportType === "websocket"
        ? "ws://localhost:8080"
        : "http://localhost:8080/stream",
    token: "test-token",
    transport: transportType as any,
  });

  try {
    await client.connect();
    console.log(`${transportType} transport connected successfully`);

    const runId = await client.startRun("test-run");
    await client.sendTextMessage("USER", "Test message", "test", runId);

    await client.disconnect();
    console.log(`${transportType} transport test completed`);
  } catch (error) {
    console.error(`${transportType} transport test failed:`, error);
  }
}

// Test all transports
await testTransport("websocket");
await testTransport("http-streaming");
// SSE only works in browser
if (typeof window !== "undefined") {
  await testTransport("sse");
}

Next Steps

Client API

Learn about the client interface and methods.

Examples

See practical examples of transport usage.

Authentication

Understand authentication across different transports.

API Reference

Full API reference documentation.

​Transport Types

​WebSocket Transport

​Server-Sent Events (SSE) Transport

​HTTP Streaming Transport

​Transport Comparison

​Transport Selection

​Choose WebSocket when:

​Choose SSE when:

​Choose HTTP Streaming when:

​Transport Configuration

​Global Configuration

​Transport-Specific Configuration

​Connection Management

​Automatic Reconnection

​Manual Reconnection

​Transport Events

​Transport Health Monitoring

​Connection State

​Performance Metrics

​Transport Switching

​Transport Testing

​Testing Different Transports

​Next Steps

Client API

Examples

Authentication

API Reference

Transport Types

WebSocket Transport

Server-Sent Events (SSE) Transport

HTTP Streaming Transport

Transport Comparison

Transport Selection

Choose WebSocket when:

Choose SSE when:

Choose HTTP Streaming when:

Transport Configuration

Global Configuration

Transport-Specific Configuration

Connection Management

Automatic Reconnection

Manual Reconnection

Transport Events

Transport Health Monitoring

Connection State

Performance Metrics

Transport Switching

Transport Testing

Testing Different Transports

Next Steps