Skip to main content
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

FeatureWebSocketSSEHTTP Streaming
EnvironmentNode.js + BrowserBrowser onlyNode.js + Browser
Bidirectional✅❌ (POST for sending)✅
Binary Support✅❌✅
Real-time✅✅✅
Reconnection✅✅✅
Flow Control✅✅✅
Heartbeat✅❌❌
PerformanceExcellentGoodGood
CompatibilityHighMediumHigh

​
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.