@irtio/schema 3.1.1 → 4.0.0

package/dist/index.d.ts

@@ -361,6 +361,17 @@ interface EntityOptions {
      * Server behaviour, so it is part of the canonical form and the hash — unlike `predicted`.
      */
     readonly perPlayer?: boolean;
+    /**
+     * M8 proposal 13: the fields of this per-player record that outlive the room.
+     *
+     * On a relay-with-state project a client that joins with a verified identity assertion has these
+     * fields hydrated from a per-(project, subject) blob, and they are written back when the player
+     * leaves. Anonymous joins get schema defaults and write nothing. Requires `perPlayer: true`, the
+     * named fields must exist, and their worst-case encoded size must fit `PERSIST_BLOB_BYTES`.
+     *
+     * Server behaviour — hydration shape — so it is part of the canonical form and the hash.
+     */
+    readonly persist?: readonly string[];
     /**
      * D77: clients may `add` records to this collection (the adder becomes the owner, with the id
      * it chose) and the owner may `remove` one. Off by default, which is what every collection
@@ -413,6 +424,21 @@ declare function entity<F extends Fields, const O extends EntityOptions>(fields:
 /** Exactly one instance; same `serverOwned`/`visibility` options. */
 declare function singleton<F extends Fields>(fields: F): SingletonDef<F, {}>;
 declare function singleton<F extends Fields, const O extends EntityOptions>(fields: F, options: O): SingletonDef<F, O>;
+/**
+ * The hard cap on one player's persistence blob, in encoded bytes.
+ *
+ * A compile that could exceed it is refused here rather than at the first leave that would have
+ * written an oversize blob: a cap discovered in production is a cap nobody can act on.
+ */
+declare const PERSIST_BLOB_BYTES: number;
+/**
+ * The worst-case encoded size of `names` out of `fields`, in bytes.
+ *
+ * Static and deliberately pessimistic: every bound is the largest value the declared type can
+ * hold, so a schema that compiles can never write a blob over the cap. Mirrors `codec.ts`'s
+ * writers — LEB128 varints for list and string lengths, one presence byte for `.opt`.
+ */
+declare function maxEncodedBytes(fields: readonly FieldDesc[], names: readonly string[]): number;
 type RpcDirection = 'server' | 'client';
 interface RpcDef<Dir extends RpcDirection = RpcDirection, P extends Fields = Fields, R extends Fields | undefined = Fields | undefined> {
     readonly kind: 'rpc';
@@ -484,6 +510,11 @@ interface CollectionDesc {
     readonly physics: PhysicsDesc | undefined;
     /** D77: one record per joined client, owned by them. In the hash. */
     readonly perPlayer: boolean;
+    /**
+     * M8 proposal 13: the per-player fields that outlive the room, sorted, or `undefined` when none
+     * were declared. In the hash when present.
+     */
+    readonly persist: readonly string[] | undefined;
     /** D77: clients may add records here and their owner may remove them. In the hash. */
     readonly clientCreate: boolean;
     /** D77: the compiled transfer and leave rules. `undefined` when none were declared. In the hash. */
@@ -1258,4 +1289,4 @@ declare function diffSchemas(oldSchema: AnySchema, newSchema: AnySchema): Schema
  */
 declare function breakingIsWireOnly(changes: readonly SchemaChange[]): boolean;
 
-export { type AddOptions, type AnyDef, type AnyMessageMap, type AnyRpc, type AnySchema, type AnyType, type Body2dState, type BodyFieldsOf, type BroadcastProxy, ByteReader, ByteWriter, CANONICAL_VERSION, type ClientCallProxy, type ClientImplementations, type ClientRpcs, type ClientState, type Collection, type CollectionDesc, type CollectionDirty, type DecodeSnapshotOptions, type DecodedSnapshot, type DeepReadonly, type DeepWritable, type DefMap, type Delta, type DeltaCollection, type DeltaOp, type DirtySet, EntityCollection, type EntityDef, type EntityOptions, type EntityPhysics, type FieldDesc, type FieldMask, type Fields, type FromCanonicalOptions, type GridDesc, type GridOptions, type Header, ID_MAX_BYTES, type Implementations, type Infer, type InferFields, type InitFields, type InitOf, type InstanceOf, type Kind, MAX_MESSAGES, MAX_USER_RPCS, type MessageChannels, type MessageDesc, type MessageMap, type MessageNames, type MessageValue, type MessagesOf, type OwnableKeys, type Owned, type OwnershipDesc, type OwnershipLeave, type OwnershipLeaveAction, type OwnershipOptions, type OwnershipPosition, type OwnershipTransfer, PHYSICS_BODY_CHANNELS, type PhysicsBodyChannel, type PhysicsBodyMap, type PhysicsDesc, type PhysicsKeys, type PlainState, RESERVED_COLLECTION_NAMES, RESERVED_RPC_NAMES, RESERVED_RPC_PREFIX, type ReadOptions, type ReadonlyBodyFields, type ReadonlyCollection, type RecordDirty, type RoleOf, type RpcDef, type RpcDesc, type RpcDirection, type RpcMap, type RpcParams, type RpcReturns, type RpcSpec, SERVER_OWNER, SINGLETON_ID, type Schema, type SchemaChange, type SchemaDefs, type SchemaIssue, type SchemaMessages, type SchemaOptions, type SchemaRoles, type SchemaRpc, type ServerCallProxy, type ServerMessageChannels, type ServerOwnedKeys, type ServerRpcs, type SingletonDef, type SnapshotOptions, type State, type Tracked, type Type, type TypeDesc, type ValueSink, type Visibility, type VisibleKeys, type WalkEvents, angleFrom2d, applyChannel2d, applyDelta, bool, breakingIsWireOnly, bytesEqual, canonicalOwnership, canonicalPhysics, canonicalType, channelOf2d, client, cloneValue, collectionDirty, compileOwnership, compilePhysics, computeDirty, createDirtySet, createFieldMask, createState, decodeDelta, decodeDeltaFrom, decodeFields, decodeSnapshot, defaultRecord, defaultValue, defineSchema, describeType, diffSchemas, encodeDelta, encodeFields, encodeSnapshot, entity, enumOf, estimateSize, f32, f64, filterDirty, frozenProxy, i32, isDirtyEmpty, isWhole, list, markAdd, markField, markOwner, markPath, markRemove, mergeDirty, mergeMask, normalizeRecord, normalizeValue, ownershipFromCanonical, parseHold, physicsFromCanonical, readValue, reconcileCollection, ref, schemaFromCanonical, server, sha256, sha256Hex, singleton, stableStringify, str, struct, toHex, track, u16, u32, u8, utf8Length, validateForDeploy, validateValue, walkDelta, walkSnapshot, writeValue };
+export { type AddOptions, type AnyDef, type AnyMessageMap, type AnyRpc, type AnySchema, type AnyType, type Body2dState, type BodyFieldsOf, type BroadcastProxy, ByteReader, ByteWriter, CANONICAL_VERSION, type ClientCallProxy, type ClientImplementations, type ClientRpcs, type ClientState, type Collection, type CollectionDesc, type CollectionDirty, type DecodeSnapshotOptions, type DecodedSnapshot, type DeepReadonly, type DeepWritable, type DefMap, type Delta, type DeltaCollection, type DeltaOp, type DirtySet, EntityCollection, type EntityDef, type EntityOptions, type EntityPhysics, type FieldDesc, type FieldMask, type Fields, type FromCanonicalOptions, type GridDesc, type GridOptions, type Header, ID_MAX_BYTES, type Implementations, type Infer, type InferFields, type InitFields, type InitOf, type InstanceOf, type Kind, MAX_MESSAGES, MAX_USER_RPCS, type MessageChannels, type MessageDesc, type MessageMap, type MessageNames, type MessageValue, type MessagesOf, type OwnableKeys, type Owned, type OwnershipDesc, type OwnershipLeave, type OwnershipLeaveAction, type OwnershipOptions, type OwnershipPosition, type OwnershipTransfer, PERSIST_BLOB_BYTES, PHYSICS_BODY_CHANNELS, type PhysicsBodyChannel, type PhysicsBodyMap, type PhysicsDesc, type PhysicsKeys, type PlainState, RESERVED_COLLECTION_NAMES, RESERVED_RPC_NAMES, RESERVED_RPC_PREFIX, type ReadOptions, type ReadonlyBodyFields, type ReadonlyCollection, type RecordDirty, type RoleOf, type RpcDef, type RpcDesc, type RpcDirection, type RpcMap, type RpcParams, type RpcReturns, type RpcSpec, SERVER_OWNER, SINGLETON_ID, type Schema, type SchemaChange, type SchemaDefs, type SchemaIssue, type SchemaMessages, type SchemaOptions, type SchemaRoles, type SchemaRpc, type ServerCallProxy, type ServerMessageChannels, type ServerOwnedKeys, type ServerRpcs, type SingletonDef, type SnapshotOptions, type State, type Tracked, type Type, type TypeDesc, type ValueSink, type Visibility, type VisibleKeys, type WalkEvents, angleFrom2d, applyChannel2d, applyDelta, bool, breakingIsWireOnly, bytesEqual, canonicalOwnership, canonicalPhysics, canonicalType, channelOf2d, client, cloneValue, collectionDirty, compileOwnership, compilePhysics, computeDirty, createDirtySet, createFieldMask, createState, decodeDelta, decodeDeltaFrom, decodeFields, decodeSnapshot, defaultRecord, defaultValue, defineSchema, describeType, diffSchemas, encodeDelta, encodeFields, encodeSnapshot, entity, enumOf, estimateSize, f32, f64, filterDirty, frozenProxy, i32, isDirtyEmpty, isWhole, list, markAdd, markField, markOwner, markPath, markRemove, maxEncodedBytes, mergeDirty, mergeMask, normalizeRecord, normalizeValue, ownershipFromCanonical, parseHold, physicsFromCanonical, readValue, reconcileCollection, ref, schemaFromCanonical, server, sha256, sha256Hex, singleton, stableStringify, str, struct, toHex, track, u16, u32, u8, utf8Length, validateForDeploy, validateValue, walkDelta, walkSnapshot, writeValue };

package/dist/index.js

@@ -704,6 +704,90 @@ function compileServerFields(name, kind, fields, o) {
   }
   return new Set([...out].sort());
 }
+var PERSIST_BLOB_BYTES = 4 * 1024;
+function maxEncodedBytes(fields, names) {
+  const byName = new Map(fields.map((f) => [f.name, f]));
+  let total = 0;
+  for (const n of names) {
+    const f = byName.get(n);
+    if (f) total += worstCase(f.type);
+  }
+  return total;
+}
+function varintBytes(max) {
+  let bytes = 1;
+  let v = Math.max(0, Math.floor(max));
+  while (v > 127) {
+    v = Math.floor(v / 128);
+    bytes++;
+  }
+  return bytes;
+}
+function worstCase(d) {
+  const presence = d.opt ? 1 : 0;
+  switch (d.kind) {
+    case "bool":
+    case "u8":
+    case "enum":
+      return presence + 1;
+    case "u16":
+      return presence + 2;
+    case "u32":
+    case "i32":
+    case "f32":
+      return presence + 4;
+    case "f64":
+      return presence + 8;
+    case "str":
+      return presence + varintBytes(d.max) + d.max;
+    case "ref":
+      return presence + varintBytes(ID_MAX_BYTES) + ID_MAX_BYTES;
+    case "list":
+      return presence + varintBytes(d.max) + d.max * worstCase(d.item);
+    case "struct": {
+      let n = presence;
+      for (const fd of Object.values(d.fields)) n += worstCase(fd);
+      return n;
+    }
+  }
+}
+function compilePersist(name, fields, perPlayer, declared) {
+  if (declared === void 0) return void 0;
+  if (!Array.isArray(declared)) {
+    throw new Error(`${name}: persist must be an array of field names`);
+  }
+  if (!perPlayer) {
+    throw new Error(
+      `${name}: persist requires perPlayer \u2014 only a per-player record has a player to follow`
+    );
+  }
+  if (declared.length === 0) {
+    throw new Error(`${name}: persist is empty; leave it off instead`);
+  }
+  const known = new Map(fields.map((f) => [f.name, f]));
+  const out = [];
+  for (const field of declared) {
+    if (typeof field !== "string" || !known.has(field)) {
+      throw new Error(
+        `${name}: persist names ${JSON.stringify(field)}, which is not a field of ${name}`
+      );
+    }
+    if (out.includes(field)) throw new Error(`${name}: persist names ${field} twice`);
+    if (known.get(field).type.kind === "ref") {
+      throw new Error(
+        `${name}: persist names ${field}, an entity ref \u2014 a ref is an id inside one room and means nothing in the next one`
+      );
+    }
+    out.push(field);
+  }
+  const bytes = maxEncodedBytes(fields, out);
+  if (bytes > PERSIST_BLOB_BYTES) {
+    throw new Error(
+      `${name}: persist fields can encode up to ${bytes} bytes, over the 4 KB persistence cap`
+    );
+  }
+  return out.sort();
+}
 function checkFields(fields) {
   const names = Object.keys(fields);
   if (names.length === 0) throw new Error("entity/singleton needs at least one field");
@@ -762,6 +846,7 @@ function defineSchema(defs, options = {}) {
       );
     }
     const ownership = o.ownership || perPlayer ? compileOwnership(name, def.kind, fields, o.ownership ?? {}, perPlayer) : void 0;
+    const persist = compilePersist(name, fields, perPlayer, o.persist);
     const serverFields = compileServerFields(name, def.kind, fields, o);
     return {
       name,
@@ -772,6 +857,7 @@ function defineSchema(defs, options = {}) {
       serverOwned: o.serverOwned === true,
       serverFields,
       perPlayer,
+      persist,
       clientCreate: o.clientCreate === true,
       ownership,
       visibility: o.visibility ?? "all",
@@ -982,6 +1068,10 @@ function canonicalize(s) {
       // writes `upgrades` disagree about the world.
       serverFields: c.serverFields ? [...c.serverFields] : void 0,
       perPlayer: c.perPlayer ? true : void 0,
+      // M8 proposal 13: the same only-when-declared rule again. In the hash when present because
+      // it is hydration shape: a room that fills a field from a blob and a client that does not
+      // expect it to be filled disagree about the world.
+      persist: c.persist ? [...c.persist] : void 0,
       clientCreate: c.clientCreate ? true : void 0,
       ownership: c.ownership ? canonicalOwnership(c.ownership) : void 0
       // ---- end M6 lane K ----
@@ -1250,6 +1340,11 @@ function entityOptions(e, name) {
   const physics = e.physics === void 0 || e.physics === null ? void 0 : physicsFromCanonical(`schemaFromCanonical: ${name}`, e.physics);
   const grid = e.grid === void 0 || e.grid === null ? void 0 : gridFromCanonical(name, objectAt(e, "grid"));
   const ownership = e.ownership === void 0 || e.ownership === null ? void 0 : ownershipFromCanonical(`schemaFromCanonical: ${name}`, e.ownership);
+  const persist = e.persist === void 0 || e.persist === null ? void 0 : arrayAtRaw(e, "persist").map((f) => {
+    if (typeof f !== "string")
+      throw new Error(`schemaFromCanonical: ${name}: persist must be strings`);
+    return f;
+  });
   const serverFields = e.serverFields === void 0 || e.serverFields === null ? void 0 : arrayAtRaw(e, "serverFields").map((f) => {
     if (typeof f !== "string")
       throw new Error(`schemaFromCanonical: ${name}: serverFields must be strings`);
@@ -1263,6 +1358,7 @@ function entityOptions(e, name) {
     ...physics !== void 0 ? { physics } : {},
     // ---- M6 lane K: stateful relay ----
     ...e.perPlayer === true ? { perPlayer: true } : {},
+    ...persist !== void 0 ? { persist } : {},
     ...e.clientCreate === true ? { clientCreate: true } : {},
     ...ownership !== void 0 ? { ownership } : {},
     // ---- end M6 lane K ----
@@ -3348,6 +3444,7 @@ export {
   ID_MAX_BYTES,
   MAX_MESSAGES,
   MAX_USER_RPCS,
+  PERSIST_BLOB_BYTES,
   PHYSICS_BODY_CHANNELS,
   RESERVED_COLLECTION_NAMES,
   RESERVED_RPC_NAMES,
@@ -3401,6 +3498,7 @@ export {
   markOwner,
   markPath,
   markRemove,
+  maxEncodedBytes,
   mergeDirty,
   mergeMask,
   normalizeRecord,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/schema",
-  "version": "3.1.1",
+  "version": "4.0.0",
   "description": "irtio schema DSL, type inference, canonical hash, codec, change tracking, and schema diff",
   "license": "MIT",
   "repository": {