@irtio/protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 irtio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,336 @@
+import * as _irtio_schema from '@irtio/schema';
+import { ByteReader, RpcMap, ServerRpcs, AnySchema, RpcDesc, InstanceOf, Schema, SchemaDefs, SchemaRpc, SchemaRoles } from '@irtio/schema';
+
+/**
+ * Frame envelope: one type byte, then an opaque payload. `encodeFrame`/`decodeFrame` only
+ * handle the envelope — payload codecs live in `session.ts`, `rpc.ts`, `msg.ts`.
+ */
+/** Wire protocol version (u8), bumped on any breaking change to framing or payload shapes. */
+declare const PROTOCOL_VERSION = 1;
+declare const FrameType: {
+    readonly HELLO: 1;
+    readonly WELCOME: 2;
+    readonly ERROR: 3;
+    readonly PING: 4;
+    readonly PONG: 5;
+    readonly DELTA: 6;
+    readonly WRITE: 7;
+    readonly CORRECT: 8;
+    readonly CALL: 9;
+    readonly REPLY: 10;
+    readonly MSG: 11;
+    /**
+     * Client → server, no payload. Sent on `room.leave()`/graceful close, right
+     * before the socket closes: tells the supervisor this departure is deliberate, so it skips the
+     * reconnect grace window and the room's `onLeave` sees `reason: 'left'` instead of waiting for
+     * the close to time out into `'timeout'`. Additive — protocol version stays 1.
+     */
+    readonly LEAVE: 12;
+};
+type FrameType = (typeof FrameType)[keyof typeof FrameType];
+interface Frame {
+    readonly type: FrameType;
+    readonly payload: Uint8Array;
+}
+declare function isFrameType(v: number): v is FrameType;
+/** `[type byte][payload]`. */
+declare function encodeFrame(type: FrameType, payload: Uint8Array): Uint8Array;
+/** `payload` is a subarray view into `bytes` (no copy). Throws on an empty buffer or unknown type. */
+declare function decodeFrame(bytes: Uint8Array): Frame;
+
+/**
+ * Protocol error catalogue: stable numeric codes (1..n) with a `{placeholder}` message
+ * template per code. `ErrorPayload` (the wire shape) lives in `session.ts`.
+ */
+interface ErrorCodeDef {
+    readonly code: number;
+    readonly message: string;
+}
+/** Name -> `{ code, message template }`. Numeric codes are stable; never renumber. */
+declare const ErrorCode: {
+    readonly E_PROTOCOL_VERSION: {
+        readonly code: 1;
+        readonly message: "unsupported protocol version {version}";
+    };
+    readonly E_ORIGIN: {
+        readonly code: 2;
+        readonly message: "origin {origin} is not allowed";
+    };
+    readonly E_AUTH: {
+        readonly code: 3;
+        readonly message: "authentication failed";
+    };
+    readonly E_SCHEMA_MISMATCH: {
+        readonly code: 4;
+        readonly message: "schema hash mismatch";
+    };
+    readonly E_ROOM_NOT_FOUND: {
+        readonly code: 5;
+        readonly message: "room {roomId} not found — room ids are 1-32 of A-Z a-z 0-9 - _";
+    };
+    readonly E_ROOM_FULL: {
+        readonly code: 6;
+        readonly message: "room {roomId} is full";
+    };
+    readonly E_ROOM_CLOSED: {
+        readonly code: 7;
+        readonly message: "room {roomId} is closed";
+    };
+    readonly E_RESUME_EXPIRED: {
+        readonly code: 8;
+        readonly message: "resume token expired";
+    };
+    readonly E_RATE_LIMITED: {
+        readonly code: 9;
+        readonly message: "rate limited";
+    };
+    readonly E_NOT_OWNER: {
+        readonly code: 10;
+        readonly message: "not the owner of {entity} {id}";
+    };
+    readonly E_RPC_UNKNOWN: {
+        readonly code: 11;
+        readonly message: "unknown rpc {name}";
+    };
+    readonly E_RPC_REJECTED: {
+        readonly code: 12;
+        readonly message: "rpc {name} rejected: {reason}";
+    };
+    readonly E_RPC_TIMEOUT: {
+        readonly code: 13;
+        readonly message: "rpc {name} timed out";
+    };
+    readonly E_RPC_BAD_PARAMS: {
+        readonly code: 14;
+        readonly message: "bad params for rpc {name}: {reason}";
+    };
+    readonly E_WRITE_REJECTED: {
+        readonly code: 15;
+        readonly message: "write rejected: {reason}";
+    };
+    readonly E_KICKED: {
+        readonly code: 16;
+        readonly message: "kicked: {reason}";
+    };
+    readonly E_INTERNAL: {
+        readonly code: 17;
+        readonly message: "internal error";
+    };
+    readonly E_BAD_FRAME: {
+        readonly code: 18;
+        readonly message: "malformed or unexpected frame {frame}";
+    };
+    readonly E_STARTING: {
+        readonly code: 19;
+        readonly message: "your game server is starting";
+    };
+    readonly E_SLOW_CONSUMER: {
+        readonly code: 20;
+        readonly message: "client cannot keep up with the stream; reconnect for a fresh snapshot";
+    };
+};
+type ErrorCodeName = keyof typeof ErrorCode;
+interface ErrorCatalogueEntry {
+    readonly name: ErrorCodeName;
+    readonly code: number;
+    readonly message: string;
+}
+/** Flat catalogue (stable order = declaration order) for the CLI / docs generator. */
+declare const ERROR_CATALOGUE: readonly ErrorCatalogueEntry[];
+/** Fills `{placeholders}` in the named error's message template from `vars`. */
+declare function formatError(name: ErrorCodeName, vars?: Readonly<Record<string, string | number>>): string;
+/** Looks up a catalogue entry by numeric code. Throws if unknown. */
+declare function errorByCode(code: number): ErrorCatalogueEntry;
+
+/**
+ * Session-lifecycle payload codecs: HELLO, WELCOME, ERROR, PING, PONG, and the framing
+ * helpers for DELTA/WRITE/CORRECT (whose payload is opaque schema-codec bytes at this layer).
+ */
+
+type Credential = {
+    readonly kind: 'key';
+    readonly key: string;
+} | {
+    readonly kind: 'token';
+    readonly token: string;
+};
+interface Hello {
+    readonly protocolVersion: number;
+    readonly credential: Credential;
+    readonly roomId: string;
+    /** First 8 bytes of the schema hash (see `@irtio/schema` `Schema.hash8`). */
+    readonly schemaHash8: Uint8Array;
+    /** Present when resuming a prior session. */
+    readonly resumeToken?: string | undefined;
+    /** Role requested at join (server may override/reject). */
+    readonly role?: string | undefined;
+    /** Display name requested at join. */
+    readonly name?: string | undefined;
+}
+declare function encodeHello(h: Hello): Uint8Array;
+declare function decodeHello(bytes: Uint8Array): Hello;
+interface Welcome {
+    readonly clientId: string;
+    readonly role: string;
+    readonly tick: number;
+    /** Full-state snapshot, opaque schema-codec bytes. */
+    readonly snapshot: Uint8Array;
+    readonly resumeToken: string;
+    /**
+     * The room this session joined. A client that sent an empty `HELLO.roomId` (create-by-join)
+     * learns its room code here — it is what `room.id` / `room.link` / `?room=` are built
+     * from. Appended after `resumeToken`, so every byte before it is unchanged from the
+     * pre-`roomId` layout.
+     */
+    readonly roomId: string;
+    /**
+     * The room's tick interval in milliseconds (`round(1000 / tickRate)`), or `0` when the sender
+     * does not know it (a relay room, or a pre-week-8 server). The client's interpolation delay
+     * defaults to `max(50, 2 × tickIntervalMs)` (D20). Appended after `roomId` in week 8, same
+     * additive style as `roomId` itself.
+     */
+    readonly tickIntervalMs: number;
+}
+declare function encodeWelcome(w0: Welcome): Uint8Array;
+declare function decodeWelcome(bytes: Uint8Array): Welcome;
+interface ErrorPayload {
+    /** Numeric `ErrorCode.<NAME>.code` (see `errors.ts`). */
+    readonly code: number;
+    readonly message: string;
+    readonly fatal: boolean;
+}
+declare function encodeErrorPayload(e: ErrorPayload): Uint8Array;
+declare function decodeErrorPayload(bytes: Uint8Array): ErrorPayload;
+interface Ping {
+    readonly t: number;
+}
+declare function encodePing(p: Ping): Uint8Array;
+declare function decodePing(bytes: Uint8Array): Ping;
+interface Pong {
+    readonly t: number;
+    readonly serverTick: number;
+}
+declare function encodePong(p: Pong): Uint8Array;
+declare function decodePong(bytes: Uint8Array): Pong;
+/** Identity: the DELTA frame payload is schema-codec bytes, opaque at this layer. */
+declare function deltaPayload(codecBytes: Uint8Array): Uint8Array;
+/** Identity: the WRITE frame payload is schema-codec bytes, opaque at this layer. */
+declare function writePayload(codecBytes: Uint8Array): Uint8Array;
+/**
+ * The CORRECT frame payload: the schema-codec delta bytes with the judged client write tick
+ * (u32) appended (week 8, D19). Additive: the codec's delta decoder never reads past the delta
+ * body, so a decoder that does not know about the suffix ignores it; a reader that does
+ * (`decodeDeltaFrom`) is left positioned exactly at it.
+ */
+declare function correctPayload(codecBytes: Uint8Array, clientTick: number): Uint8Array;
+/**
+ * Reads the `clientTick` suffix a reader is positioned at after `decodeDeltaFrom`, or
+ * `undefined` for a pre-week-8 CORRECT payload with no suffix.
+ */
+declare function readCorrectClientTick(r: ByteReader): number | undefined;
+declare function encodeDeltaFrame(codecBytes: Uint8Array): Uint8Array;
+declare function encodeWriteFrame(codecBytes: Uint8Array): Uint8Array;
+declare function encodeCorrectFrame(codecBytes: Uint8Array, clientTick: number): Uint8Array;
+
+interface Call {
+    readonly reqId: number;
+    readonly rpcId: number;
+    /** Rest-of-buffer: opaque schema-codec-encoded params (not length-prefixed). */
+    readonly params: Uint8Array;
+}
+declare function encodeCall(c: Call): Uint8Array;
+declare function decodeCall(bytes: Uint8Array): Call;
+type Reply = {
+    readonly reqId: number;
+    readonly ok: true;
+    readonly result: Uint8Array;
+} | {
+    readonly reqId: number;
+    readonly ok: false;
+    readonly error: string;
+};
+declare function encodeReply(r: Reply): Uint8Array;
+declare function decodeReply(bytes: Uint8Array): Reply;
+/** `requestOwnership(entity, id) -> { granted }`: the only built-in RPC. */
+declare const requestOwnership: _irtio_schema.RpcDef<"server", {
+    entity: _irtio_schema.Type<string, false>;
+    id: _irtio_schema.Type<string, false>;
+}, {
+    granted: _irtio_schema.Type<boolean, false>;
+}>;
+/** Built-in RPCs every room gets for free, appended to the schema's RPC table. */
+declare const builtinRpcs: {
+    requestOwnership: _irtio_schema.RpcDef<"server", {
+        entity: _irtio_schema.Type<string, false>;
+        id: _irtio_schema.Type<string, false>;
+    }, {
+        granted: _irtio_schema.Type<boolean, false>;
+    }>;
+};
+declare function rpcTable(schema: AnySchema): RpcDesc[];
+declare function rpcIdOf(schema: AnySchema, name: string): number;
+declare function rpcByIdOf(schema: AnySchema, id: number): RpcDesc;
+/**
+ * The client's callable RPC set: every builder-declared server RPC plus irtio's built-ins
+ * (`requestOwnership`), which the schema builder never declares (`Implementations<ServerRpcs<R>>`
+ * stays builder-only — only the client call proxy needs the built-ins mixed in).
+ */
+type ClientCallable<R extends RpcMap> = ServerRpcs<R> & typeof builtinRpcs;
+
+/**
+ * MSG frame payload: an out-of-band message with an addressing discriminator. The same
+ * shape is reused in both directions — client→server as the send *target*, server→client as
+ * the *from* (sender) of a relayed message.
+ */
+type MsgTarget = {
+    readonly kind: 'all';
+} | {
+    readonly kind: 'client';
+    readonly clientId: string;
+} | {
+    readonly kind: 'role';
+    readonly role: string;
+} | {
+    readonly kind: 'server';
+};
+interface Msg {
+    readonly target: MsgTarget;
+    /** Rest-of-buffer: opaque application payload. */
+    readonly payload: Uint8Array;
+}
+declare function encodeMsg(m: Msg): Uint8Array;
+declare function decodeMsg(bytes: Uint8Array): Msg;
+
+declare const presenceEntity: _irtio_schema.EntityDef<{
+    clientId: _irtio_schema.Type<string, false>;
+    role: _irtio_schema.Type<string, false>;
+    name: _irtio_schema.Type<string, false>;
+    connected: _irtio_schema.Type<boolean, false>;
+}, {
+    readonly serverOwned: true;
+}>;
+/** Collection name the runtime merges `presenceEntity` in under. */
+declare const PRESENCE_COLLECTION = "clients";
+type PresenceRecord = InstanceOf<typeof presenceEntity>;
+/**
+ * The runtime-extended schema: the builder's schema plus the built-in `clients` presence
+ * collection. Both the runtime and the client SDK derive it, so snapshot/delta headers carry its
+ * `hash8` while `HELLO` carries the builder's. Pure and memoised per schema.
+ */
+declare function withBuiltins<S extends AnySchema>(schema: S): Schema<SchemaDefs<S> & {
+    clients: typeof presenceEntity;
+}, SchemaRpc<S>, SchemaRoles<S>>;
+/**
+ * The schema of a room with nothing deployed — no builder collections, just the
+ * built-in presence merged by `withBuiltins`. The supervisor's relay forwarder encodes presence
+ * snapshots/deltas with it so the client SDK has one `room.clients` path with or without a
+ * deployed schema.
+ */
+declare const relaySchema: Schema<{
+    clients: typeof presenceEntity;
+}, {}, readonly string[]>;
+/** The `schemaHash8` a relay HELLO carries: 8 zero bytes ("no schema"). */
+declare const RELAY_HASH8: Uint8Array;
+declare function isRelayHash8(hash8: Uint8Array): boolean;
+
+export { type Call, type ClientCallable, type Credential, ERROR_CATALOGUE, type ErrorCatalogueEntry, ErrorCode, type ErrorCodeDef, type ErrorCodeName, type ErrorPayload, type Frame, FrameType, type Hello, type Msg, type MsgTarget, PRESENCE_COLLECTION, PROTOCOL_VERSION, type Ping, type Pong, type PresenceRecord, RELAY_HASH8, type Reply, type Welcome, builtinRpcs, correctPayload, decodeCall, decodeErrorPayload, decodeFrame, decodeHello, decodeMsg, decodePing, decodePong, decodeReply, decodeWelcome, deltaPayload, encodeCall, encodeCorrectFrame, encodeDeltaFrame, encodeErrorPayload, encodeFrame, encodeHello, encodeMsg, encodePing, encodePong, encodeReply, encodeWelcome, encodeWriteFrame, errorByCode, formatError, isFrameType, isRelayHash8, presenceEntity, readCorrectClientTick, relaySchema, requestOwnership, rpcByIdOf, rpcIdOf, rpcTable, withBuiltins, writePayload };

package/dist/index.js

@@ -0,0 +1,432 @@
+// src/frame.ts
+var PROTOCOL_VERSION = 1;
+var FrameType = {
+  HELLO: 1,
+  WELCOME: 2,
+  ERROR: 3,
+  PING: 4,
+  PONG: 5,
+  DELTA: 6,
+  WRITE: 7,
+  CORRECT: 8,
+  CALL: 9,
+  REPLY: 10,
+  MSG: 11,
+  /**
+   * Client → server, no payload. Sent on `room.leave()`/graceful close, right
+   * before the socket closes: tells the supervisor this departure is deliberate, so it skips the
+   * reconnect grace window and the room's `onLeave` sees `reason: 'left'` instead of waiting for
+   * the close to time out into `'timeout'`. Additive — protocol version stays 1.
+   */
+  LEAVE: 12
+};
+var FRAME_TYPE_VALUES = new Set(Object.values(FrameType));
+function isFrameType(v) {
+  return FRAME_TYPE_VALUES.has(v);
+}
+function encodeFrame(type, payload) {
+  const out = new Uint8Array(1 + payload.length);
+  out[0] = type;
+  out.set(payload, 1);
+  return out;
+}
+function decodeFrame(bytes) {
+  if (bytes.length === 0) throw new Error("decodeFrame: empty buffer");
+  const type = bytes[0];
+  if (!isFrameType(type)) throw new Error(`decodeFrame: unknown frame type ${type}`);
+  return { type, payload: bytes.subarray(1) };
+}
+
+// src/errors.ts
+var ErrorCode = {
+  E_PROTOCOL_VERSION: { code: 1, message: "unsupported protocol version {version}" },
+  E_ORIGIN: { code: 2, message: "origin {origin} is not allowed" },
+  E_AUTH: { code: 3, message: "authentication failed" },
+  E_SCHEMA_MISMATCH: { code: 4, message: "schema hash mismatch" },
+  E_ROOM_NOT_FOUND: {
+    code: 5,
+    message: "room {roomId} not found \u2014 room ids are 1-32 of A-Z a-z 0-9 - _"
+  },
+  E_ROOM_FULL: { code: 6, message: "room {roomId} is full" },
+  E_ROOM_CLOSED: { code: 7, message: "room {roomId} is closed" },
+  E_RESUME_EXPIRED: { code: 8, message: "resume token expired" },
+  E_RATE_LIMITED: { code: 9, message: "rate limited" },
+  E_NOT_OWNER: { code: 10, message: "not the owner of {entity} {id}" },
+  E_RPC_UNKNOWN: { code: 11, message: "unknown rpc {name}" },
+  E_RPC_REJECTED: { code: 12, message: "rpc {name} rejected: {reason}" },
+  E_RPC_TIMEOUT: { code: 13, message: "rpc {name} timed out" },
+  E_RPC_BAD_PARAMS: { code: 14, message: "bad params for rpc {name}: {reason}" },
+  E_WRITE_REJECTED: { code: 15, message: "write rejected: {reason}" },
+  E_KICKED: { code: 16, message: "kicked: {reason}" },
+  E_INTERNAL: { code: 17, message: "internal error" },
+  E_BAD_FRAME: { code: 18, message: "malformed or unexpected frame {frame}" },
+  E_STARTING: { code: 19, message: "your game server is starting" },
+  E_SLOW_CONSUMER: {
+    code: 20,
+    message: "client cannot keep up with the stream; reconnect for a fresh snapshot"
+  }
+};
+var ERROR_CATALOGUE = Object.keys(ErrorCode).map((name) => ({ name, code: ErrorCode[name].code, message: ErrorCode[name].message }));
+var BY_CODE = new Map(
+  ERROR_CATALOGUE.map((e) => [e.code, e])
+);
+function formatError(name, vars = {}) {
+  const def = ErrorCode[name];
+  return def.message.replace(
+    /\{(\w+)\}/g,
+    (m, key) => Object.prototype.hasOwnProperty.call(vars, key) ? String(vars[key]) : m
+  );
+}
+function errorByCode(code) {
+  const found = BY_CODE.get(code);
+  if (!found) throw new Error(`errorByCode: unknown error code ${code}`);
+  return found;
+}
+
+// src/session.ts
+import { ByteReader, ByteWriter } from "@irtio/schema";
+function assertEof(r, what) {
+  if (!r.eof) throw new Error(`${what}: trailing bytes`);
+}
+var HELLO_RESUME_BIT = 1 << 0;
+var HELLO_ROLE_BIT = 1 << 1;
+var HELLO_NAME_BIT = 1 << 2;
+function encodeHello(h) {
+  if (h.schemaHash8.length !== 8) {
+    throw new Error(`encodeHello: schemaHash8 must be 8 bytes, got ${h.schemaHash8.length}`);
+  }
+  const w = new ByteWriter();
+  w.u8(h.protocolVersion);
+  if (h.credential.kind === "key") {
+    w.u8(0);
+    w.str(h.credential.key);
+  } else {
+    w.u8(1);
+    w.str(h.credential.token);
+  }
+  w.str(h.roomId);
+  w.bytes(h.schemaHash8);
+  let mask = 0;
+  if (h.resumeToken !== void 0) mask |= HELLO_RESUME_BIT;
+  if (h.role !== void 0) mask |= HELLO_ROLE_BIT;
+  if (h.name !== void 0) mask |= HELLO_NAME_BIT;
+  w.u8(mask);
+  if (h.resumeToken !== void 0) w.str(h.resumeToken);
+  if (h.role !== void 0) w.str(h.role);
+  if (h.name !== void 0) w.str(h.name);
+  return w.finish();
+}
+function decodeHello(bytes) {
+  const r = new ByteReader(bytes);
+  const protocolVersion = r.u8();
+  const credKind = r.u8();
+  let credential;
+  if (credKind === 0) credential = { kind: "key", key: r.str() };
+  else if (credKind === 1) credential = { kind: "token", token: r.str() };
+  else throw new Error(`decodeHello: unknown credential kind ${credKind}`);
+  const roomId = r.str();
+  const schemaHash8 = r.bytes(8);
+  const mask = r.u8();
+  const resumeToken = (mask & HELLO_RESUME_BIT) !== 0 ? r.str() : void 0;
+  const role = (mask & HELLO_ROLE_BIT) !== 0 ? r.str() : void 0;
+  const name = (mask & HELLO_NAME_BIT) !== 0 ? r.str() : void 0;
+  assertEof(r, "decodeHello");
+  const hello = { protocolVersion, credential, roomId, schemaHash8 };
+  return {
+    ...hello,
+    ...resumeToken !== void 0 ? { resumeToken } : {},
+    ...role !== void 0 ? { role } : {},
+    ...name !== void 0 ? { name } : {}
+  };
+}
+function encodeWelcome(w0) {
+  const w = new ByteWriter();
+  w.str(w0.clientId);
+  w.str(w0.role);
+  w.u32(w0.tick);
+  w.blob(w0.snapshot);
+  w.str(w0.resumeToken);
+  w.str(w0.roomId);
+  w.u16(w0.tickIntervalMs);
+  return w.finish();
+}
+function decodeWelcome(bytes) {
+  const r = new ByteReader(bytes);
+  const clientId = r.str();
+  const role = r.str();
+  const tick = r.u32();
+  const snapshot = r.blob();
+  const resumeToken = r.str();
+  const roomId = r.str();
+  const tickIntervalMs = r.eof ? 0 : r.u16();
+  assertEof(r, "decodeWelcome");
+  return { clientId, role, tick, snapshot, resumeToken, roomId, tickIntervalMs };
+}
+function encodeErrorPayload(e) {
+  const w = new ByteWriter();
+  w.u16(e.code);
+  w.str(e.message);
+  w.bool(e.fatal);
+  return w.finish();
+}
+function decodeErrorPayload(bytes) {
+  const r = new ByteReader(bytes);
+  const code = r.u16();
+  const message = r.str();
+  const fatal = r.bool();
+  assertEof(r, "decodeErrorPayload");
+  return { code, message, fatal };
+}
+function encodePing(p) {
+  const w = new ByteWriter();
+  w.u32(p.t);
+  return w.finish();
+}
+function decodePing(bytes) {
+  const r = new ByteReader(bytes);
+  const t = r.u32();
+  assertEof(r, "decodePing");
+  return { t };
+}
+function encodePong(p) {
+  const w = new ByteWriter();
+  w.u32(p.t);
+  w.u32(p.serverTick);
+  return w.finish();
+}
+function decodePong(bytes) {
+  const r = new ByteReader(bytes);
+  const t = r.u32();
+  const serverTick = r.u32();
+  assertEof(r, "decodePong");
+  return { t, serverTick };
+}
+function deltaPayload(codecBytes) {
+  return codecBytes;
+}
+function writePayload(codecBytes) {
+  return codecBytes;
+}
+function correctPayload(codecBytes, clientTick) {
+  const w = new ByteWriter(codecBytes.length + 4);
+  w.bytes(codecBytes);
+  w.u32(clientTick);
+  return w.finish();
+}
+function readCorrectClientTick(r) {
+  return r.remaining >= 4 ? r.u32() : void 0;
+}
+function encodeDeltaFrame(codecBytes) {
+  return encodeFrame(FrameType.DELTA, deltaPayload(codecBytes));
+}
+function encodeWriteFrame(codecBytes) {
+  return encodeFrame(FrameType.WRITE, writePayload(codecBytes));
+}
+function encodeCorrectFrame(codecBytes, clientTick) {
+  return encodeFrame(FrameType.CORRECT, correctPayload(codecBytes, clientTick));
+}
+
+// src/rpc.ts
+import { ByteReader as ByteReader2, ByteWriter as ByteWriter2, bool, server, str } from "@irtio/schema";
+function assertEof2(r, what) {
+  if (!r.eof) throw new Error(`${what}: trailing bytes`);
+}
+function encodeCall(c) {
+  const w = new ByteWriter2();
+  w.u32(c.reqId);
+  w.u16(c.rpcId);
+  w.bytes(c.params);
+  return w.finish();
+}
+function decodeCall(bytes) {
+  const r = new ByteReader2(bytes);
+  const reqId = r.u32();
+  const rpcId = r.u16();
+  const params = r.rest();
+  return { reqId, rpcId, params };
+}
+function encodeReply(r) {
+  const w = new ByteWriter2();
+  w.u32(r.reqId);
+  w.bool(r.ok);
+  if (r.ok) w.bytes(r.result);
+  else w.str(r.error);
+  return w.finish();
+}
+function decodeReply(bytes) {
+  const r = new ByteReader2(bytes);
+  const reqId = r.u32();
+  const ok = r.bool();
+  if (ok) {
+    const result = r.rest();
+    return { reqId, ok: true, result };
+  }
+  const error = r.str();
+  assertEof2(r, "decodeReply");
+  return { reqId, ok: false, error };
+}
+var requestOwnership = server({
+  params: { entity: str(64), id: str(32) },
+  returns: { granted: bool }
+});
+var builtinRpcs = { requestOwnership };
+function fieldDescsOf(fields) {
+  return Object.entries(fields).map(([name, t], index) => ({ name, index, type: t.desc }));
+}
+var builtinRpcDescs = Object.keys(builtinRpcs).sort().map((name, index) => {
+  const r = builtinRpcs[name];
+  return {
+    name,
+    index,
+    direction: r.direction,
+    params: fieldDescsOf(r.params),
+    returns: r.returns ? fieldDescsOf(r.returns) : void 0
+  };
+});
+var rpcTables = /* @__PURE__ */ new WeakMap();
+function rpcTable(schema) {
+  let t = rpcTables.get(schema);
+  if (!t) {
+    t = [...schema.rpcs, ...builtinRpcDescs].map((r, index) => ({ ...r, index }));
+    rpcTables.set(schema, t);
+  }
+  return t;
+}
+function rpcIdOf(schema, name) {
+  const found = rpcTable(schema).find((r) => r.name === name);
+  if (!found) throw new Error(`rpcIdOf: unknown rpc ${JSON.stringify(name)}`);
+  return found.index;
+}
+function rpcByIdOf(schema, id) {
+  const found = rpcTable(schema).find((r) => r.index === id);
+  if (!found) throw new Error(`rpcByIdOf: unknown rpc id ${id}`);
+  return found;
+}
+
+// src/msg.ts
+import { ByteReader as ByteReader3, ByteWriter as ByteWriter3 } from "@irtio/schema";
+var MSG_KIND_ALL = 0;
+var MSG_KIND_CLIENT = 1;
+var MSG_KIND_ROLE = 2;
+var MSG_KIND_SERVER = 3;
+function encodeMsg(m) {
+  const w = new ByteWriter3();
+  switch (m.target.kind) {
+    case "all":
+      w.u8(MSG_KIND_ALL);
+      break;
+    case "client":
+      w.u8(MSG_KIND_CLIENT);
+      w.str(m.target.clientId);
+      break;
+    case "role":
+      w.u8(MSG_KIND_ROLE);
+      w.str(m.target.role);
+      break;
+    case "server":
+      w.u8(MSG_KIND_SERVER);
+      break;
+  }
+  w.bytes(m.payload);
+  return w.finish();
+}
+function decodeMsg(bytes) {
+  const r = new ByteReader3(bytes);
+  const kind = r.u8();
+  let target;
+  switch (kind) {
+    case MSG_KIND_ALL:
+      target = { kind: "all" };
+      break;
+    case MSG_KIND_CLIENT:
+      target = { kind: "client", clientId: r.str() };
+      break;
+    case MSG_KIND_ROLE:
+      target = { kind: "role", role: r.str() };
+      break;
+    case MSG_KIND_SERVER:
+      target = { kind: "server" };
+      break;
+    default:
+      throw new Error(`decodeMsg: unknown target discriminator ${kind}`);
+  }
+  const payload = r.rest();
+  return { target, payload };
+}
+
+// src/presence.ts
+import { bool as bool2, defineSchema, entity, str as str2 } from "@irtio/schema";
+var presenceEntity = entity(
+  { clientId: str2(32), role: str2(32), name: str2(32), connected: bool2 },
+  { serverOwned: true }
+);
+var PRESENCE_COLLECTION = "clients";
+var extended = /* @__PURE__ */ new WeakMap();
+function withBuiltins(schema) {
+  let ext = extended.get(schema);
+  if (!ext) {
+    ext = defineSchema(
+      { ...schema.defs, [PRESENCE_COLLECTION]: presenceEntity },
+      {
+        rpc: schema.rpc,
+        roles: schema.roles,
+        ...schema.project !== void 0 ? { project: schema.project } : {},
+        allowReservedNames: true
+      }
+    );
+    extended.set(schema, ext);
+  }
+  return ext;
+}
+var relaySchema = withBuiltins(defineSchema({}));
+var RELAY_HASH8 = new Uint8Array(8);
+function isRelayHash8(hash8) {
+  if (hash8.length !== 8) return false;
+  for (const b of hash8) if (b !== 0) return false;
+  return true;
+}
+export {
+  ERROR_CATALOGUE,
+  ErrorCode,
+  FrameType,
+  PRESENCE_COLLECTION,
+  PROTOCOL_VERSION,
+  RELAY_HASH8,
+  builtinRpcs,
+  correctPayload,
+  decodeCall,
+  decodeErrorPayload,
+  decodeFrame,
+  decodeHello,
+  decodeMsg,
+  decodePing,
+  decodePong,
+  decodeReply,
+  decodeWelcome,
+  deltaPayload,
+  encodeCall,
+  encodeCorrectFrame,
+  encodeDeltaFrame,
+  encodeErrorPayload,
+  encodeFrame,
+  encodeHello,
+  encodeMsg,
+  encodePing,
+  encodePong,
+  encodeReply,
+  encodeWelcome,
+  encodeWriteFrame,
+  errorByCode,
+  formatError,
+  isFrameType,
+  isRelayHash8,
+  presenceEntity,
+  readCorrectClientTick,
+  relaySchema,
+  requestOwnership,
+  rpcByIdOf,
+  rpcIdOf,
+  rpcTable,
+  withBuiltins,
+  writePayload
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@irtio/protocol",
+  "version": "0.1.0",
+  "description": "irtio wire protocol: frames, framing, session payloads, error codes, built-in presence",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@irtio/schema": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}