@forcewire/webtransport

High-performance, type-safe WebTransport (QUIC/HTTP3) client wrapper for the ForceWire realtime communication framework.

📦 Features

• Reliable QUIC Streams: Send framed, ordered messages over bidirectional QUIC streams without Head-of-Line blocking.
• Unreliable Datagrams: Send ultra low-latency raw UDP/QUIC datagrams for high-frequency telemetry, gaming, or audio/video packets.
• Auto Reconnect: Robust state machine with configurable exponential backoff and randomized full jitter.
• Automatic Message Framing: Seamlessly integrates with @forcewire/protocol for transparent envelope encoding and stream deframing.
• Zero External Dependencies: Clean, small bundle footprint (< 4KB minified).

🚀 Installation

pnpm add @forcewire/webtransport @forcewire/protocol

🛠️ Usage

Connecting & Listening to Events

import { ForceWireWebTransport } from '@forcewire/webtransport';
import { createMessage } from '@forcewire/protocol';

const client = new ForceWireWebTransport({
  url: 'https://api.example.com/live',
  reconnect: {
    maxRetries: 5,
    initialDelayMs: 1000,
    maxDelayMs: 10000,
  }
});

// Lifecycle events
client.on('connect', () => {
  console.log('Connected to WebTransport server via QUIC/HTTP3');
});

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

client.on('stateChange', (newState, oldState) => {
  console.log(`State transition: ${oldState} -> ${newState}`);
});

// Incoming stream messages
client.onStreamMessage((message) => {
  console.log(`Received stream message [${message.type}]:`, message.payload);
});

// Incoming datagrams
client.onDatagram((buffer, message) => {
  if (message) {
    console.log(`Parsed datagram [${message.type}]:`, message.payload);
  } else {
    console.log(`Raw datagram bytes:`, buffer.byteLength);
  }
});

// Connect
await client.connect();

// 1. Send reliable stream message
const chatMsg = createMessage('chat.say', { text: 'Hello over QUIC stream!' });
await client.sendStream(chatMsg);

// 2. Send low-latency datagram (unreliable)
const telemetry = createMessage('agent.pos', { x: 100, y: 200 });
await client.sendDatagram(telemetry);

// Clean disconnect
// await client.close();