Line data Source code
1 : /**
2 : * Read-time schema-version gate (CRDT keep-alive invariant KA-11).
3 : *
4 : * KA-11: "Schema-version discipline, ENFORCED ON READ. Bump `SCHEMA_VERSION`
5 : * when an old reader would mis-project a new doc; fail-closed on an unreadable
6 : * schema."
7 : *
8 : * Before this file the follower had no read-side gate at all: the only mention
9 : * of the version anywhere was `expect(SCHEMA_VERSION).toBe(1)` in a test, which
10 : * pins the BUILD-TIME constant of the package the frontend compiled against and
11 : * says nothing about the version of the document that actually arrived over the
12 : * socket. A doc-host advancing to schema v2 would have been read with a v1
13 : * reader — whatever keys still parsed would render, silently and wrongly. That
14 : * is fail-OPEN, the exact failure KA-11 names.
15 : *
16 : * The version is read through the shared package's PUBLIC api
17 : * (`readSchemaVersion`, `SCHEMA_VERSION`) — never through a deep/internal
18 : * import — so the key name and the expected value cannot drift from the
19 : * writer: they are the same symbols the cloud doc-host uses. The package's own `migrate()` is deliberately
20 : * NOT called: it is host-only (it mutates the doc), and a follower must never
21 : * write the shared doc (KA-6 / FORECLOSE #5).
22 : */
23 : import { SCHEMA_VERSION, readSchemaVersion } from '@comfyorg/comfy-multi-player'
24 : import type * as Y from 'yjs'
25 :
26 : import { assert } from '@/base/assert'
27 :
28 : /** Thrown by {@link assertReadableSchema}; carries the version actually found. */
29 1 : export class FollowerSchemaError extends Error {
30 : constructor(
31 0 : readonly found: unknown,
32 : message: string
33 : ) {
34 0 : super(message)
35 0 : this.name = 'FollowerSchemaError'
36 : }
37 : }
38 :
39 : /**
40 : * Fail closed unless the merged doc declares exactly the schema version this
41 : * build was written against.
42 : *
43 : * A MISSING `meta.schema_version` fails too, and deliberately: every doc the
44 : * host produces is seeded by the shared package (`initDoc`/`mint` both write
45 : * the key), so an absent version means the bytes are not a document this
46 : * reader understands — which is precisely "unreadable schema".
47 : *
48 : * @throws FollowerSchemaError when the doc is not readable at this version.
49 : */
50 0 : export function assertReadableSchema(doc: Y.Doc): void {
51 0 : const found = readSchemaVersion(doc)
52 0 : if (found === SCHEMA_VERSION) return
53 :
54 0 : const message =
55 : `CRDT follower: doc meta.schema_version=${String(found)} is not the ` +
56 : `v${SCHEMA_VERSION} layout this build reads — refusing to project it ` +
57 : `(fail-closed, keep-alive invariant KA-11).`
58 :
59 0 : try {
60 : // Route through the repo's central invariant channel: console.error in
61 : // every environment, Sentry reporter in production.
62 0 : assert(
63 : false,
64 : 'CRDT follower: doc meta.schema_version is not the layout this build reads — refusing to project it (fail-closed, keep-alive invariant KA-11)',
65 : { found }
66 : )
67 : } catch {
68 : // Swallowed on purpose. `assert` throws only under DEV, so it is NOT a
69 : // fail-closed mechanism by itself — outside DEV it returns normally and
70 : // the caller would carry on projecting an unreadable doc. The typed throw
71 : // below is what actually closes the gate, in every environment.
72 : }
73 0 : throw new FollowerSchemaError(found, message)
74 : }
|