@velajs/live-protocol 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @velajs/live-protocol
+
+## 1.1.0
+
+### Minor Changes
+
+- 6e9d70a: Validate live frame schemas, JSON shape, protocol versions, cursor/epoch pairs, and secure default size limits for frames, deltas, and presence metadata. Outbound encoders now reject malformed or oversized frames before serialization.
+
+## 1.0.1
+
+### Patch Changes
+
+- 0fcf971: Modernize the package build, validation, and release toolchain.

package/README.md

@@ -13,7 +13,7 @@ Zero runtime dependencies. Ships three things:
 
 ## Versioning
 
-`LIVE_PROTOCOL` (currently `1`) bumps only on breaking wire changes. Receivers must ignore unknown frame types and unknown fields; additive changes do not bump the version. Any wire change releases in lockstep: live-protocol → `@velajs/vela` → `@velajs/cloudflare` → `@velajs/client`.
+`LIVE_PROTOCOL` is `2`. Every subscription must advertise `v: 2`; omitted or older versions are rejected. Receivers still ignore unknown frame types and unknown fields within the same version. Any wire change releases in lockstep: live-protocol → `@velajs/vela` → `@velajs/cloudflare` → `@velajs/client`.
 
 ## Delivery semantics (normative summary)
 
@@ -23,4 +23,13 @@ Zero runtime dependencies. Ships three things:
 - **`resume`** means nothing relevant changed while the client was away: keep the cached value, advance the cursor.
 - Optimistic updates gate on a subscription frame whose `cursor` passes the mutation's `Vela-Commit-Cursor` — never on HTTP response timing, which races the broadcast.
 
+## Validation and limits
+
+Both endpoints must run the exported frame guards before dispatch. They reject
+non-JSON/prototype-bearing payloads, unsafe or negative cursors, incomplete
+cursor/epoch pairs, unsupported advertised versions, oversized strings, and
+malformed row operations. Defaults are 64 KiB per envelope, 1,000 delta operations,
+and 4 KiB of presence metadata. Clients ignore regressive cursors and cold-resubscribe
+when an epoch or watermark cannot continue safely.
+
 See `vela/LIVE.md` in the main framework repo for the full feature documentation.

package/dist/index.d.ts

@@ -1,8 +1,218 @@
-export { LIVE_PROTOCOL } from './version';
-export { COMMIT_CURSOR_HEADER, COMMIT_EPOCH_HEADER, LIVE_ERROR_CODES, LIVE_EVENT, RESERVED_EVENT_PREFIX, canonicalLiveFrame, encodeLiveEnvelope, encodeLiveFrame, isClientLiveFrame, isRowOp, isRowOps, isServerLiveFrame, liveEnvelope, readLiveEnvelope, } from './frames';
-export type { ClientLiveFrame, LiveErrorCode, LiveFrame, RowOp, ServerLiveFrame } from './frames';
-export { DEFAULT_KEY_FIELD, applyListDelta, encodeListDelta } from './delta';
-export { runProtocolConformance } from './conformance';
-export type { ConformanceReport, DeltaCodec } from './conformance';
-export { DELTA_FIXTURES, FRAME_FIXTURES } from './fixtures';
-export type { DeltaFixture, FrameFixture } from './fixtures';
+//#region src/version.d.ts
+/**
+ * Live-protocol wire version. Bumped ONLY on a breaking wire change (renaming
+ * or removing a field, changing a delivery guarantee). Additive changes — new
+ * optional fields, new frame types — do NOT bump it: receivers MUST ignore
+ * unknown frame `t` values and unknown object fields.
+ *
+ * A client advertises the version it speaks via the `v` field on its `sub`
+ * frame; a server that cannot serve that version replies
+ * `{ t: 'error', code: 'unsupported_protocol', fatal: true }`.
+ */
+declare const LIVE_PROTOCOL = 2;
+//#endregion
+//#region src/frames.d.ts
+/** The reserved envelope event every live frame rides under. */
+declare const LIVE_EVENT = "$live";
+/**
+ * The reserved event-name prefix. The WS dispatcher rejects app gateways that
+ * register a `$…` event at bootstrap so live (and future framework) frames can
+ * never collide with app events.
+ */
+declare const RESERVED_EVENT_PREFIX = "$";
+/**
+ * HTTP response headers carrying the commit cursor/epoch of the log scope a
+ * mutation's invalidations landed in. The client gates optimistic-layer drops
+ * on a subscription frame whose `cursor` passes this value (and whose `epoch`
+ * matches) — never on HTTP response timing, which races the broadcast.
+ */
+declare const COMMIT_CURSOR_HEADER = "Vela-Commit-Cursor";
+declare const COMMIT_EPOCH_HEADER = "Vela-Commit-Epoch";
+/** Default hard limits shared by every live-protocol endpoint. */
+declare const MAX_LIVE_FRAME_BYTES: number;
+declare const MAX_PRESENCE_METADATA_BYTES: number;
+declare const MAX_DELTA_OPS = 1000;
+/** Well-known `error` frame codes. The code space is open — receivers must tolerate unknown codes. */
+declare const LIVE_ERROR_CODES: {
+  readonly UNSUPPORTED_PROTOCOL: 'unsupported_protocol';
+  readonly DUPLICATE_SUB: 'duplicate_sub';
+  readonly UNKNOWN_QUERY: 'unknown_query';
+  readonly FORBIDDEN: 'forbidden';
+  readonly BAD_ARGS: 'bad_args';
+  readonly LIMIT_EXCEEDED: 'limit_exceeded';
+  readonly INTERNAL: 'internal';
+};
+type LiveErrorCode = (typeof LIVE_ERROR_CODES)[keyof typeof LIVE_ERROR_CODES] | (string & {});
+/**
+ * One row change inside a `delta` frame. Ops are keyed by the query's key
+ * field (default `'id'`); `insert`/`update` carry the full new row, `delete`
+ * omits it. An `insert` carries `before` — the key of the row it precedes in
+ * the authoritative result (`null` = append) — so the client reconstructs the
+ * server's ordering exactly. Application is idempotent: `insert` on an
+ * existing key replaces in place, `delete` of an absent key is a no-op.
+ */
+type RowOp = {
+  op: 'insert';
+  key: string;
+  row: Record<string, unknown>;
+  before: string | null;
+} | {
+  op: 'update';
+  key: string;
+  row: Record<string, unknown>;
+} | {
+  op: 'delete';
+  key: string;
+};
+/** Client → server frames (the `data` of a `{ event: '$live' }` envelope). */
+type ClientLiveFrame = {
+  t: 'sub';
+  /** Client-chosen subscription id, unique per socket. */
+  sub: string;
+  /** The live-query identifier declared by `@LiveQuery(name)`. */
+  query: string;
+  args?: unknown;
+  /** Resume watermark: last observed cursor/epoch. Omitted = cold subscribe. */
+  sinceCursor?: number;
+  sinceEpoch?: string;
+  /** Key-field override for list deltas (default `'id'`). */
+  key?: string;
+  /** Protocol version the client speaks (see LIVE_PROTOCOL). */
+  v: number;
+} | {
+  t: 'unsub';
+  sub: string;
+} | {
+  t: 'presence';
+  room: string;
+  meta?: unknown;
+};
+/** Server → client frames. `ack` precedes any `data`/`resume` for a sub. */
+type ServerLiveFrame = {
+  t: 'ack';
+  sub: string;
+} | {
+  t: 'data';
+  sub: string;
+  snapshot: unknown;
+  cursor?: number;
+  epoch?: string;
+} | {
+  t: 'delta';
+  sub: string;
+  ops: RowOp[];
+  cursor?: number;
+  epoch?: string;
+} |
+/** Re-run result was byte-identical — no payload, but the cursor still advances (drops optimistic layers). */
+{
+  t: 'settled';
+  sub: string;
+  cursor?: number;
+  epoch?: string;
+} |
+/** Resume verdict: nothing relevant changed while away — keep the cached value, advance the cursor. */
+{
+  t: 'resume';
+  sub: string;
+  cursor: number;
+  epoch: string;
+} | {
+  t: 'error';
+  sub?: string;
+  code: LiveErrorCode;
+  message: string;
+  fatal: boolean;
+};
+type LiveFrame = ClientLiveFrame | ServerLiveFrame;
+/** Structural guard for a single {@link RowOp}. Unknown extra fields are tolerated. */
+declare const isRowOp: (value: unknown) => value is RowOp;
+declare const isRowOps: (value: unknown) => value is RowOp[];
+/**
+ * Structural guard for a client frame. Frames with an unknown `t` return
+ * false — per the forward-compat rule the receiver then ignores the frame.
+ */
+declare const isClientLiveFrame: (value: unknown) => value is ClientLiveFrame;
+/** Structural guard for a server frame. Unknown `t` → false (receiver ignores). */
+declare const isServerLiveFrame: (value: unknown) => value is ServerLiveFrame;
+/**
+ * Extract the live frame from a parsed WS envelope, or `undefined` when the
+ * envelope is not a live envelope. Does NOT validate the frame — pair with
+ * {@link isClientLiveFrame} / {@link isServerLiveFrame} on the receiving side.
+ */
+declare const readLiveEnvelope: (envelope: unknown) => unknown;
+/** Wrap a frame in the `$live` envelope object. */
+declare const liveEnvelope: (frame: LiveFrame) => {
+  event: typeof LIVE_EVENT;
+  data: LiveFrame;
+};
+/**
+ * Rebuild a frame with the canonical key order, dropping absent optionals.
+ * `JSON.stringify` of the result is the frame's canonical wire form — the one
+ * the golden fixtures pin byte-for-byte.
+ */
+declare const canonicalLiveFrame: (frame: LiveFrame) => Record<string, unknown>;
+/** Canonical JSON encoding of a bare frame (no envelope). */
+declare const encodeLiveFrame: (frame: LiveFrame) => string;
+/** Canonical JSON encoding of the full `$live` envelope — what actually goes on the socket. */
+declare const encodeLiveEnvelope: (frame: LiveFrame) => string;
+//#endregion
+//#region src/delta.d.ts
+/** Default row-identity field. Per-query override rides the `sub` frame's `key`. */
+declare const DEFAULT_KEY_FIELD = "id";
+/**
+ * Diff `previous` vs `next` into row ops, or `undefined` when any bail rule
+ * holds and the caller must send a full snapshot instead.
+ *
+ * An empty array is a valid result (no row-level change — typically the server
+ * catches byte-identical results earlier and sends `settled` instead).
+ */
+declare const encodeListDelta: (previous: unknown, next: unknown, keyField?: string) => RowOp[] | undefined;
+/**
+ * Merge row ops into a cached array result, returning a NEW array (the input
+ * is never mutated), or `undefined` when the ops cannot be applied cleanly —
+ * the caller then falls back to full replacement and lets the next snapshot
+ * reconcile.
+ *
+ * Idempotent by construction: replaying an op after a snapshot already
+ * delivered its effect changes nothing.
+ */
+declare const applyListDelta: (current: unknown, ops: readonly RowOp[], keyField?: string) => unknown[] | undefined;
+//#endregion
+//#region src/conformance.d.ts
+/** The two halves a wire endpoint must implement compatibly. */
+interface DeltaCodec {
+  encodeListDelta: (previous: unknown, next: unknown, keyField?: string) => RowOp[] | undefined;
+  applyListDelta: (current: unknown, ops: readonly RowOp[], keyField?: string) => unknown[] | undefined;
+}
+interface ConformanceReport {
+  /** Human-readable failure descriptions; empty = conformant. */
+  failures: string[];
+  checks: number;
+}
+/**
+ * Run the full conformance suite against a codec (defaults to the reference
+ * codec in this package — the package's own tests run exactly this).
+ */
+declare const runProtocolConformance: (codec?: DeltaCodec) => ConformanceReport;
+//#endregion
+//#region src/fixtures.d.ts
+interface FrameFixture {
+  name: string;
+  frame: LiveFrame;
+  /** Exact canonical envelope bytes: `encodeLiveEnvelope(frame)` must equal this. */
+  wire: string;
+}
+declare const FRAME_FIXTURES: FrameFixture[];
+interface DeltaFixture {
+  name: string;
+  previous: unknown;
+  next: unknown;
+  keyField?: string;
+  /** Expected ops, or `null` when the encoder MUST bail to snapshot. */
+  expected: RowOp[] | null;
+}
+declare const DELTA_FIXTURES: DeltaFixture[];
+//#endregion
+export { COMMIT_CURSOR_HEADER, COMMIT_EPOCH_HEADER, type ClientLiveFrame, type ConformanceReport, DEFAULT_KEY_FIELD, DELTA_FIXTURES, type DeltaCodec, type DeltaFixture, FRAME_FIXTURES, type FrameFixture, LIVE_ERROR_CODES, LIVE_EVENT, LIVE_PROTOCOL, type LiveErrorCode, type LiveFrame, MAX_DELTA_OPS, MAX_LIVE_FRAME_BYTES, MAX_PRESENCE_METADATA_BYTES, RESERVED_EVENT_PREFIX, type RowOp, type ServerLiveFrame, applyListDelta, canonicalLiveFrame, encodeListDelta, encodeLiveEnvelope, encodeLiveFrame, isClientLiveFrame, isRowOp, isRowOps, isServerLiveFrame, liveEnvelope, readLiveEnvelope, runProtocolConformance };
+//# sourceMappingURL=index.d.ts.map