The protocol package

{
  "name": "@relay/protocol",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "exports": {
    ".": "./src/index.ts"
  },
  "scripts": {
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "zod": "^4.4.3"
  }
}

{
  "extends": "../../tsconfig.base.json",
  "include": ["src"]
}

mkdir -p packages/protocol/src

import { z } from "zod";
 
// The wire contract, one home (ADR-01). Every frame is a JSON object with a
// `type` discriminator and a `payload` (EIR-WS-02). Schemas are the single
// source of truth: every exported static type is inferred from its schema,
// so the types and the validation cannot drift — there is no second
// definition. Payloads are strict: unknown fields are rejected.
 
/** Per-channel resume cursor: { channel_id: highest seq seen } (ADR-03). */
export const cursorSchema = z.record(z.string(), z.number().int().positive());
 
/** The message on the wire — derived from the SAD §6.1 `messages` columns.
 * Wire spellings follow SAD §5.1's own frame line (`channel`, `seq`).
 * metadata/attachments/edit/tombstone fields arrive with Part 2/4. */
export const messageSchema = z.strictObject({
  id: z.string().min(1),
  channel: z.string().min(1),
  seq: z.number().int().positive(),
  user: z.string().min(1),
  text: z.string(),
  created_at: z.iso.datetime(), // UTC, RFC 3339 (constitution: timestamps)
});
 
/** Server → client on successful handshake (EIR-WS-03, SAD §5.2). Sent after
 * backfill is fetched, so it can also carry the per-channel truncation list
 * (FR-RTM-04) — channels where backfill exceeded 500 and the client must
 * refetch history instead. */
export const connectionAckSchema = z.strictObject({
  type: z.literal("connection.ack"),
  payload: z.strictObject({
    user: z.string().min(1),
    cursor: cursorSchema,
    resume_ok: z.boolean(),
    truncated: z.array(z.string().min(1)),
  }),
});
 
/** Client → server send (SAD §5.1: `message.send {idem_key, channel, text}`).
 * The idempotency key is client-supplied (FR-SDK-06), deduplicated
 * server-side within 24 h (FR-MSG-04). */
export const messageSendSchema = z.strictObject({
  type: z.literal("message.send"),
  payload: z.strictObject({
    idem_key: z.string().min(1).max(255),
    channel: z.string().min(1),
    text: z.string(),
  }),
});
 
/** Server → sender after commit — never before (SAD §5.1, FR-MSG-05). */
export const messageAckSchema = z.strictObject({
  type: z.literal("message.ack"),
  payload: z.strictObject({
    seq: z.number().int().positive(),
  }),
});
 
// The six real-time event kinds (FR-RTM-05). The kinds are the SRS's; the
// `noun.verb` spellings are this chapter's recorded decision, following the
// documents' own connection.ack / message.send naming.
 
export const messageCreatedSchema = z.strictObject({
  type: z.literal("message.created"),
  payload: messageSchema,
});
 
export const messageUpdatedSchema = z.strictObject({
  type: z.literal("message.updated"),
  payload: messageSchema,
});
 
export const messageDeletedSchema = z.strictObject({
  type: z.literal("message.deleted"),
  payload: messageSchema,
});
 
export const membershipChangedSchema = z.strictObject({
  type: z.literal("membership.changed"),
  payload: z.strictObject({
    channel: z.string().min(1),
    user: z.string().min(1),
    change: z.enum(["added", "removed"]),
  }),
});
 
/** Presence states per FR-RTM-06; delivery scope is FR-RTM-07's concern. */
export const presenceChangedSchema = z.strictObject({
  type: z.literal("presence.changed"),
  payload: z.strictObject({
    user: z.string().min(1),
    state: z.enum(["online", "offline"]),
  }),
});
 
/** Expires after 5 s without renewal and is never persisted (FR-RTM-08). */
export const typingSchema = z.strictObject({
  type: z.literal("typing"),
  payload: z.strictObject({
    channel: z.string().min(1),
    user: z.string().min(1),
  }),
});
 
/** Protocol-level error — EIR-API-04's error shape, reused on the socket
 * (this chapter's recorded decision). `request_id` joins in Part 2, when a
 * gateway exists to mint one. */
export const errorFrameSchema = z.strictObject({
  type: z.literal("error"),
  payload: z.strictObject({
    code: z.string().min(1),
    message: z.string().min(1),
    docs_url: z.string().min(1),
    field: z.string().min(1).optional(),
  }),
});
 
/** Every frame either end may legally utter. */
export const frameSchema = z.discriminatedUnion("type", [
  connectionAckSchema,
  messageSendSchema,
  messageAckSchema,
  messageCreatedSchema,
  messageUpdatedSchema,
  messageDeletedSchema,
  membershipChangedSchema,
  presenceChangedSchema,
  typingSchema,
  errorFrameSchema,
]);
 
// The static types ARE the schemas — z.infer, never a hand-written twin.
export type Cursor = z.infer<typeof cursorSchema>;
export type Message = z.infer<typeof messageSchema>;
export type ConnectionAck = z.infer<typeof connectionAckSchema>;
export type MessageSend = z.infer<typeof messageSendSchema>;
export type MessageAck = z.infer<typeof messageAckSchema>;
export type Frame = z.infer<typeof frameSchema>;
 
/** Parse anything the wire delivers. Hostile input is an expected value, not
 * an exception: this returns zod's safeParse result and never throws. */
export function parseFrame(raw: unknown) {
  return frameSchema.safeParse(raw);
}

// Close codes and protocol error codes — the contract's failure vocabulary.
// EIR-WS-06 requires close codes to distinguish authentication failure,
// quota exhaustion, server shutdown, and protocol violation. Two numbers are
// document-fixed (4001: EIR-WS-05; 4009: SAD §7); the other two classes are
// numbered here — chapter 1.3's recorded decision.
 
export const CLOSE_CODES = {
  4001: "invalid or expired token",
  4002: "protocol violation",
  4008: "quota exhausted",
  4009: "server shutdown (drain)",
} as const;
 
export type CloseCode = keyof typeof CLOSE_CODES;
 
// Protocol-level error codes carried by the `error` frame (EIR-API-04's
// shape). A starter registry — endpoints and services add their own codes in
// their chapters; uniqueness is test-enforced from day one.
export const ERROR_CODES = {
  invalid_frame: "the frame failed schema validation",
  unknown_frame_type: "the type discriminator names no known frame",
  unauthorized: "the connection is not authorized for this action",
  rate_limited: "too many frames; slow down and retry",
} as const;
 
export type ErrorCode = keyof typeof ERROR_CODES;

// @relay/protocol — the shared wire contract (ADR-01's payoff, chapter 1.3).
// One home for frame schemas, their inferred types, and the failure
// vocabulary. Consumed by the gateway and API service from 1.4, and by the
// SDK in a later part.
 
export * from "./frames.js";
export * from "./codes.js";

import { describe, expect, it } from "vitest";
 
import { parseFrame } from "./frames.js";
 
// The contract must bite: for every frame, one specimen that parses and a
// table of malformed near-misses that MUST reject. A schema that accepts
// garbage is worse than no schema — it certifies garbage.
 
const message = {
  id: "m1",
  channel: "c1",
  seq: 42,
  user: "u1",
  text: "hello",
  created_at: "2026-08-01T09:00:00.000Z",
};
 
const valid: Record<string, unknown> = {
  "connection.ack": {
    type: "connection.ack",
    payload: { user: "u1", cursor: { c1: 42 }, resume_ok: true, truncated: [] },
  },
  "message.send": {
    type: "message.send",
    payload: { idem_key: "k-1", channel: "c1", text: "hi" },
  },
  "message.ack": { type: "message.ack", payload: { seq: 43 } },
  "message.created": { type: "message.created", payload: message },
  "message.updated": { type: "message.updated", payload: message },
  "message.deleted": { type: "message.deleted", payload: message },
  "membership.changed": {
    type: "membership.changed",
    payload: { channel: "c1", user: "u2", change: "added" },
  },
  "presence.changed": {
    type: "presence.changed",
    payload: { user: "u1", state: "online" },
  },
  typing: { type: "typing", payload: { channel: "c1", user: "u1" } },
  error: {
    type: "error",
    payload: {
      code: "invalid_frame",
      message: "no",
      docs_url: "https://docs.example/errors/invalid_frame",
    },
  },
};
 
describe("every frame parses its valid specimen and round-trips", () => {
  for (const [name, frame] of Object.entries(valid)) {
    it(name, () => {
      const result = parseFrame(frame);
      expect(result.success).toBe(true);
      if (result.success) expect(result.data).toEqual(frame);
    });
  }
});
 
describe("malformed frames reject", () => {
  const rejects: Array<[string, unknown]> = [
    ["not an object", "message.send"],
    ["unknown type discriminator", { type: "message.destroy", payload: {} }],
    ["missing payload", { type: "message.ack" }],
    [
      "missing payload field",
      { type: "message.send", payload: { channel: "c1", text: "hi" } },
    ],
    [
      "wrong primitive (seq as string)",
      { type: "message.ack", payload: { seq: "43" } },
    ],
    ["zero seq", { type: "message.ack", payload: { seq: 0 } }],
    ["negative seq", { type: "message.ack", payload: { seq: -1 } }],
    [
      "empty idem_key",
      { type: "message.send", payload: { idem_key: "", channel: "c1", text: "hi" } },
    ],
    [
      "oversized idem_key",
      {
        type: "message.send",
        payload: { idem_key: "k".repeat(256), channel: "c1", text: "hi" },
      },
    ],
    [
      "unknown extra payload field",
      {
        type: "message.send",
        payload: { idem_key: "k-1", channel: "c1", text: "hi", admin: true },
      },
    ],
    [
      "invalid presence state",
      { type: "presence.changed", payload: { user: "u1", state: "away" } },
    ],
    [
      "non-RFC3339 timestamp",
      { type: "message.created", payload: { ...message, created_at: "yesterday" } },
    ],
  ];
 
  for (const [name, frame] of rejects) {
    it(name, () => {
      expect(parseFrame(frame).success).toBe(false);
    });
  }
});

import { describe, expect, it } from "vitest";
 
import { CLOSE_CODES, ERROR_CODES } from "./codes.js";
 
// The failure vocabulary stays coherent: EIR-WS-06's four classes are all
// present, exactly once, with distinct meanings — and error codes never
// collide or go blank as chapters add to the registry.
 
describe("close codes cover EIR-WS-06's four classes", () => {
  it("contains exactly 4001, 4002, 4008, 4009", () => {
    expect(Object.keys(CLOSE_CODES).map(Number).sort()).toEqual([
      4001, 4002, 4008, 4009,
    ]);
  });
 
  it("gives every code a distinct, non-empty meaning", () => {
    const meanings = Object.values(CLOSE_CODES);
    expect(new Set(meanings).size).toBe(meanings.length);
    for (const meaning of meanings) expect(meaning.length).toBeGreaterThan(0);
  });
});
 
describe("error codes stay unique and described", () => {
  it("has no duplicate or empty descriptions", () => {
    const descriptions = Object.values(ERROR_CODES);
    expect(new Set(descriptions).size).toBe(descriptions.length);
    for (const d of descriptions) expect(d.length).toBeGreaterThan(0);
  });
 
  it("uses snake_case machine-readable keys (EIR-API-04)", () => {
    for (const code of Object.keys(ERROR_CODES)) {
      expect(code).toMatch(/^[a-z][a-z_]*$/);
    }
  });
});

pnpm install
pnpm lint
pnpm typecheck
pnpm test