@rtcsvc/client

Front-line SDK (Node + browser) for rtcsvc: connect to the gateway, negotiate a peer-to-peer WebRTC DataChannel with the matched service-server, then send requests and exchange pub/sub events — all peer-to-peer, encoded with datapack.

The gateway only authenticates and relays WebRTC signalling. The server is the WebRTC offerer; this client answers and receives the channel.

Install

npm install @rtcsvc/client

In the browser, the global WebSocket and RTCPeerConnection are used — no extra dependencies. In Node, install the optional peers:

npm install @rtcsvc/client node-rtc-connection ws

Usage

import { ServiceClient } from "@rtcsvc/client";
import { pack, unpack, STRING } from "datapack";

const client = new ServiceClient({
  gatewayUrl: "wss://gateway.example.com/ws",
  serviceId: "svc_...", // from the admin console
});

await client.connect();

// Request/reply — payloads are opaque bytes; pick your own datapack schema.
const res = await client.request("echo", pack({ text: "hi" }, { text: STRING }));
console.log(res.status, unpack(res.data, { text: STRING }).text);

// Pub/sub:
client.subscribe("chat", (payload, event) => {
  console.log(event.from, unpack(payload, { text: STRING }).text);
});
client.publish("chat", pack({ text: "hello" }, { text: STRING }));

// Broadcast and topic events arrive on the 'event' listener too:
client.on("event", (payload, event) => {
  /* ... */
});

API

• new ServiceClient(options) — { gatewayUrl, serviceId, serverId?, requestTimeoutMs?, debug? }.
• .connect() / .close() — open / close the gateway connection.
• .request(type, payload) — round-trip a request; resolves to { status, data }.
• .subscribe(topic, cb?) / .unsubscribe(topic, cb?) — topic pub/sub.
• .publish(topic, payload) — publish bytes to a topic.
• .sendTo(connId, payload) — directed message to a single connection.
• .getSchema() — fetch the service's reflected schema (the registered request routes and event types with their datapack schemas). Asks the server directly over the data channel (the reserved #schema request); the gateway is not involved. Requires a live connection.
• .on(event, cb) — lifecycle events: open, event, message, peergone, error, close.

Payloads (request, publish) and event payloads are opaque Uint8Arrays — the application chooses its own datapack schema for each.

Codegen — typed client from a service's schema

Because a server reflects its routes/events via #schema, you can generate a fully-typed wrapper class for any running service — no hand-written types:

npx rtcsvc-codegen \
  --gateway ws://localhost:8787/ws \
  --service svc_... \
  --name Chat \
  --out chat-client.ts

It connects as a client, fetches the schema, and writes a ChatClient with a typed async method per request route and on<Event> / publish<Event> helpers per event type (interfaces derived from the datapack schemas):

import { ChatClient } from "./chat-client";

const chat = new ChatClient({ gatewayUrl, serviceId });
await chat.connect();
const { data } = await chat.say({ text: "hi" }); // typed in and out
chat.onRoom((msg) => console.log(msg.from, msg.text));

Flags: --out <file> (default stdout), --name <ClassName> (default the service id), --client-module <specifier> (the import the generated file uses, default @rtcsvc/client), --server <connId>, --timeout <ms>, --print. --gateway/--service may also come from GATEWAY_URL/SERVICE_ID.

License

MIT