@hiyve/semantic-relay-client

Framework-agnostic browser client for the Hiyve Semantic Relay — built for high-frequency, fire-and-forget, room-scoped messaging.

Connects over WebTransport (HTTP/3 / QUIC datagrams, preferred) with automatic WebSocket fallback: when WebTransport is missing or cannot connect (e.g. networks that block UDP), the client transparently retries over WebSocket against the same relay endpoint. Consumers use one API either way; the active transport is reported via client.transportKind.

For React applications, use @hiyve/react-semantic-relay which wraps this client with a context provider and topic-scoped pub/sub hooks.

Installation

npm install @hiyve/semantic-relay-client
Copy

Quick start

import { SemanticRelayClient } from '@hiyve/semantic-relay-client';

const client = new SemanticRelayClient({
  url: 'https://semantic.hiyve.tv:4443/relay',
  roomId: 'lesson-abc',
  userId: 'alice@example.com',
  token: jwtFromBackend,
  serverCertificateHashes, // optional; required for self-signed dev/prod certs
});

const session = await client.connect();
console.log('session id', session.sessionId, 'peers', session.peers);

const unsubscribe = client.subscribe('instrument-notes', ({ payload, userId }) => {
  console.log(`${userId} played`, payload);
});

client.publish('instrument-notes', { midi: 60, on: true, velocity: 100 });

// Later:
unsubscribe();
client.dispose();
Copy

serverCertificateHashes is a RelayCertHash[] of SHA-256 fingerprints — see the WebTransport docs for derivation. Production deployments using a public CA can omit it.

Options

The client wraps relay messages in a small envelope; serialization, framing, and identity stamping are handled internally.

Staying connected

A relay connection can be lost long after it was established — a VPN or tunnel dropping, a Wi-Fi handover, a laptop waking, the relay restarting. By default the client re-establishes it on its own, with a delay that doubles from reconnectBaseDelayMs to reconnectMaxDelayMs, and it keeps trying even when the very first connect() never succeeded, so a room joined on a network that blocks the relay recovers as soon as that network changes. Retries fire immediately when the browser reports the network is back or the tab becomes visible, rather than waiting out the remaining delay.

Two things follow for consumers:

• Re-read sessionInfo after a reconnect. The relay assigns a new session ID on rejoin, so the snapshot connect() resolved with is stale from the first drop onwards. onConnectionChange firing 'connected' again is the signal.
• Subscriptions are not affected. They belong to the client, not the connection, so nothing needs re-registering.

connect() still rejects when the first attempt fails — reconnection runs alongside that rejection rather than replacing it. Pass reconnect: false to connect once and stop.

Tokens expire. If a lesson can outlive its token, supply getToken so each attempt presents a fresh one; without it, a reconnect rejected on authentication ends the loop, because retrying a token the relay has already refused achieves nothing. getToken is given the same 8s budget as a handshake — a token endpoint on the same broken network usually hangs rather than failing, and an unbounded wait there would stop the loop as surely as an error. Rejecting or timing out is not fatal: the next attempt asks again.

Limits

• One sender per connection (peer routing is server-side).
• Up to 100 participants per room (relay-enforced).
• Max envelope size ~1200 bytes (MAX_DATAGRAM_BYTES); larger messages should fragment at the application layer.

Browser support

Every current browser is supported. WebTransport (the preferred transport) is available in Chrome/Edge 97+, Firefox 114+, and Safari 26.4+; everywhere else — including older Safari/iOS and networks that block UDP — the client falls back to WebSocket automatically. No consumer-side capability gating is required.

Delivery semantics are fire-and-forget on both transports: messages may be dropped under network congestion (natively on WebTransport; via latest-wins coalescing on WebSocket), so protocols built on this client should tolerate loss — exactly as they must for datagrams.

Types & constants

License

MIT