@mmstack/mesh-protocol 0.1.0 → 0.1.1

package/README.md

@@ -139,8 +139,46 @@ export class MeshRoom {
 }
 ```
 
-Durable storage (journal persistence across restarts) rides the same seam and lands with a
-later release. In-memory rooms cover dev and single-process deployments today.
+## Persistence
+
+Rooms live in memory. That covers dev and single-process deployments, and when the relay
+restarts, the first client to rejoin seeds the room from its own local state, so nothing is
+lost as long as somebody was online. For durability beyond that, the relay exposes a seam
+rather than a storage engine, because the envelope already is the persistence record: an
+event-sourced journal is just `snapshot + envelopes`, compacted by re-snapshotting.
+
+`onCommit` fires after every envelope is sequenced and folded, with the envelope and the
+room's current `{ seq, epoch, root }`. Append the envelope to your journal, and checkpoint the
+root as often as you like. The relay never awaits it, so batching and backpressure belong to
+your adapter:
+
+```ts
+const relay = createRelay({
+  onCommit: (room, env, state) => {
+    journal.append(room, env); // your DB, KV, or DO storage
+    if (state.seq % 100 === 0) checkpoints.put(room, state);
+  },
+});
+```
+
+`relay.hydrate(room, snapshot)` restores a persisted room before clients join (relay boot, or
+inside a Durable Object's `blockConcurrencyWhile`). It refuses once the room has state or
+members, so your load can race a fast client without corrupting a live sequence space:
+
+```ts
+const saved = await checkpoints.get(roomName);
+if (saved) {
+  relay.hydrate(roomName, {
+    ...saved, // seq, epoch, root
+    journal: await journal.tail(roomName, saved.seq),
+  });
+}
+```
+
+Restoring the persisted `epoch` is what lets clients that were connected before the restart
+keep their sequence watermark and catch up with a cheap `delta` answer. Omit it and they fall
+back to a full snapshot, which is always safe. The optional journal tail is only there to make
+those delta answers possible; the room is complete without it.
 
 ## WebRTC signaling
 

package/index.d.ts

@@ -1,10 +1,4 @@
 //#region src/lib/wire.d.ts
-/**
- * Canonical wire types of the mmstack op protocol (op-protocol RFC §3/§6). Structurally
- * identical to the L0 types in `@mmstack/primitives` — deliberately NOT imported from there,
- * so this package stays zero-dependency and never drags Angular peers onto a server. The
- * client package asserts mutual assignability at compile time.
- */
 type Key = string | number;
 type StoreOp = {
   kind: 'set';
@@ -184,6 +178,30 @@ type RelayOptions = {
   readonly journalLimit?: number;
   readonly now?: () => number;
   readonly onViolation?: (room: string, violation: PolicyViolation) => void;
+  /**
+   * The persistence egress: fired after an envelope is sequenced, folded into the room
+   * snapshot, and broadcast. The envelope is the persistence record (append it to a journal);
+   * `state` carries the folded root for throttled checkpoints. Called synchronously and never
+   * awaited: batch, debounce, and store at the adapter layer. Pair with {@link Relay.hydrate}.
+   */
+  readonly onCommit?: (room: string, env: SeqEnvelope, state: RoomState) => void;
+};
+/** The room's durable state at a commit: what a checkpoint needs to capture. */
+type RoomState = {
+  readonly seq: number;
+  readonly epoch: string;
+  readonly root: unknown;
+};
+/** A persisted room to restore via {@link Relay.hydrate}. */
+type RoomSnapshot = {
+  readonly seq: number;
+  readonly root: unknown;
+  /**
+   * Restore the persisted epoch so clients reconnecting across the restart keep their seq
+   * watermark and get a `delta` answer; omit to mint a fresh one (they re-snapshot instead).
+   */
+  readonly epoch?: string; /** Journal tail (ascending seq, entries at or below `seq`) enabling those delta answers. */
+  readonly journal?: readonly SeqEnvelope[];
 };
 type RelayConnection = {
   receive(msg: ClientMsg): void;
@@ -197,6 +215,12 @@ type RoomInfo = {
 type Relay = {
   /** Attach an authenticated connection. `ctx.writer` is the trusted principal. */connect(socket: RelaySocket, ctx: PrincipalCtx): RelayConnection;
   room(name: string): RoomInfo | undefined;
+  /**
+   * Restore a persisted room before clients join (relay boot, Durable Object wake). Refused
+   * (`false`) once the room has state or members: hydrating a live seq space would corrupt
+   * it. Load asynchronously at the adapter layer, then hydrate synchronously.
+   */
+  hydrate(name: string, snapshot: RoomSnapshot): boolean;
 };
 /**
  * The reference relay core (op-protocol RFC §6/§7): room-scoped sequencing, journal +
@@ -213,4 +237,4 @@ type Relay = {
  */
 declare function createRelay(opt?: RelayOptions): Relay;
 //#endregion
-export { type ClientEnvMsg, type ClientMsg, type ClientPresenceMsg, type ClientSignalMsg, type EjectMsg, type HelloMsg, type Hlc, type Key, MESH_PROTO_VERSION, type MemberMsg, type OpEnvelope, type OpPolicy, type PathAclRule, type PolicyViolation, type PresenceState, type PrincipalCtx, type RejectMsg, type Relay, type RelayConnection, type RelayLimits, type RelayOptions, type RelaySocket, type RoomInfo, type SeqEnvelope, type ServerEnvMsg, type ServerMsg, type ServerPresenceMsg, type ServerSignalMsg, type StoreOp, type WelcomeMsg, applyWireOps, checkEnvelope, createRelay, pathPrefixAcl };
+export { type ClientEnvMsg, type ClientMsg, type ClientPresenceMsg, type ClientSignalMsg, type EjectMsg, type HelloMsg, type Hlc, type Key, MESH_PROTO_VERSION, type MemberMsg, type OpEnvelope, type OpPolicy, type PathAclRule, type PolicyViolation, type PresenceState, type PrincipalCtx, type RejectMsg, type Relay, type RelayConnection, type RelayLimits, type RelayOptions, type RelaySocket, type RoomInfo, type RoomSnapshot, type RoomState, type SeqEnvelope, type ServerEnvMsg, type ServerMsg, type ServerPresenceMsg, type ServerSignalMsg, type StoreOp, type WelcomeMsg, applyWireOps, checkEnvelope, createRelay, pathPrefixAcl };

package/index.js

@@ -158,6 +158,15 @@ function createRelay(opt = {}) {
 				journal: room.journal.length
 			} : void 0;
 		},
+		hydrate: (name, snapshot) => {
+			const room = roomOf(name);
+			if (room.seq !== 0 || room.members.size > 0 || room.journal.length > 0) return false;
+			room.seq = snapshot.seq;
+			room.root = snapshot.root;
+			if (snapshot.epoch !== void 0) room.epoch = snapshot.epoch;
+			if (snapshot.journal) room.journal = snapshot.journal.filter((e) => e.seq <= snapshot.seq).sort((a, b) => a.seq - b.seq).slice(-journalLimit);
+			return true;
+		},
 		connect: (socket, ctx) => {
 			const joined = /* @__PURE__ */ new Map();
 			const disconnect = () => {
@@ -309,6 +318,11 @@ function createRelay(opt = {}) {
 						room: msg.room,
 						env: seqEnv
 					});
+					opt.onCommit?.(msg.room, seqEnv, {
+						seq: room.seq,
+						epoch: room.epoch,
+						root: room.root
+					});
 				}
 			};
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/mesh-protocol",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",
@@ -33,4 +33,4 @@
   },
   "homepage": "https://github.com/mihajm/mmstack/blob/master/packages/mesh/protocol",
   "sideEffects": false
-}
+}