Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

4.0 KB
Raw Blame

WebSocket

Shared, type-safe WebSocket abstraction with reconnect, buffering, heartbeat, serialization, and Solid lifecycle helpers. Import its public API through the @macro-inc/collaboration/websocket export.

Basic Usage

import { JsonSerializer, WebsocketBuilder, WebsocketEvent } from '@macro-inc/collaboration/websocket';

const ws = new WebsocketBuilder('ws://localhost:5000')
  .withSerializer(new JsonSerializer<SendType, ReceiveType>())
  .build();

ws.addEventListener(WebsocketEvent.Message, (_socket, event) => {
  console.log('Received:', event.data);
});

ws.send({ type: 'hello' });

Builder Pattern

import { ExponentialBackoff, WebsocketBuilder } from '@macro-inc/collaboration/websocket';

const ws = new WebsocketBuilder('ws://localhost:5000')
  .withBackoff(new ExponentialBackoff(1_000, 5))
  .withHeartbeat({
    interval: 30_000,
    timeout: 5_000,
    pingMessage: 'ping',
    pongMessage: 'pong',
    maxMissedHeartbeats: 2,
  })
  .build();

Reconnection

Configure retries with the builder:

The Tauri transport converts native read errors (string payloads, including connection resets after iOS suspension) into one error followed by an abnormal close (1006). The same handling applies to recovered replay messages. Consumers can reconnect normally; a transport error must never escape as a pattern-match exception or leave the wrapper reporting OPEN. Read/send failures emit one websocket.transport.failure span with the native socket ID when assigned, operation, and closed outcome. URLs, message payloads, and raw provider errors are excluded.

const ws = new WebsocketBuilder(url)
  .withMaxRetries(10)
  .withBackoff(new ExponentialBackoff(1_000, 5))
  .build();

Serialization

Built-in serializers for common formats:

import { BebopSerializer, JsonSerializer } from '@macro-inc/collaboration/websocket';

// JSON
new WebsocketBuilder(url)
  .withSerializer(new JsonSerializer())
  .build();

// Bebop (binary)
new WebsocketBuilder(url)
  .withSerializer(new BebopSerializer(encoder, decoder))
  .build();

SolidJS Integration

Reactive effects for message handling:

import { createSocketEffect, createWebsocketEventEffect } from '@macro-inc/collaboration/websocket';

// Listen to all messages
createSocketEffect(ws, (data) => {
  console.log('Received:', data);
});

// Type-based filtering
createWebsocketEventEffect(ws, 'chat', (msg: ChatMessage) => {
  addToChat(msg);
});

Connection State

Track connection lifecycle:

import { WebsocketEvent } from '@macro-inc/collaboration/websocket';

ws.addEventListener(WebsocketEvent.Open, () => console.log('Connected'));
ws.addEventListener(WebsocketEvent.Close, () => console.log('Disconnected'));
ws.addEventListener(WebsocketEvent.retry, (_socket, event) =>
  console.log('Retrying:', event.detail)
);
ws.addEventListener(WebsocketEvent.Reconnect, () =>
  console.log('Reconnected')
);

// Or use reactive state
import { createWebsocketStateSignal } from '@macro-inc/collaboration/websocket';
const state = createWebsocketStateSignal(ws);

API Reference

Core

  • Websocket<Send, Receive> - Main WebSocket wrapper
  • WebsocketBuilder - Fluent builder interface

Backoff Strategies

  • ExponentialBackoff(base, maxExponent?) - Exponential growth
  • LinearBackoff(initial, increment, max?) - Linear growth
  • ConstantBackoff(delay) - Fixed delay

Serializers

  • JsonSerializer<Send, Receive>() - JSON serialization
  • BebopSerializer<Send, Receive>(encoder, decoder) - Binary serialization

Queues (for message buffering)

  • ArrayQueue<T>() - Unbounded array-based queue
  • RingQueue<T>(capacity) - Fixed-size circular buffer

SolidJS Effects

  • createSocketEffect(ws, handler) - Listen to all messages
  • createWebsocketEventEffect(ws, type, handler) - Filter by message type
  • createWebsocketStateSignal(ws) - Reactive connection state

Utils

  • untilMessage<T>(ws, predicate) - Promise that resolves on matching message