Line data Source code
1 : /**
2 : * The transport boundary of the human write leg (plan 3.3): mints wire
3 : * identity onto semantic {@link GraphOperation}s and chunks batches to the
4 : * wire caps clients respect (contract layer, verified against comfy-cli's
5 : * vocabulary): 256 ops and 4 MiB per batch, under the package's own library
6 : * budgets. `clear` is catastrophic-by-nature and never rides inside a batch
7 : * (plan D4): it always ships as a batch of exactly one.
8 : */
9 : import { BATCHABLE_OPS } from '@comfyorg/comfy-multi-player'
10 : import type { Actor, Op, Stamp } from '@comfyorg/comfy-multi-player'
11 :
12 : import { createUuidv4 } from '@/utils/uuid'
13 :
14 : import type { DocOp } from './docFrameClient'
15 : import type { GraphOperation } from './graphOperations'
16 :
17 : export const WIRE_MAX_OPS_PER_BATCH = 256
18 : export const WIRE_MAX_BATCH_BYTES = 4 * 1024 * 1024
19 : const STAMP_LIFT_HEADROOM = WIRE_MAX_OPS_PER_BATCH * 2 * 16
20 :
21 : export interface MintContext {
22 : actor: Actor
23 : /** Doc version the ops are minted against (`base_version` on every op). */
24 : baseVersion: number
25 : }
26 :
27 : /** uuid4 hex: 32 lowercase `[0-9a-f]` chars (vocabulary §8.2). */
28 0 : export function mintOpId(): string {
29 0 : return createUuidv4().replaceAll('-', '')
30 : }
31 :
32 0 : function withEnvelope<T extends GraphOperation>(
33 : operation: T,
34 : { actor, baseVersion }: MintContext
35 : ): T & { op_id: string; actor: Actor; base_version: number; stamp: Stamp } {
36 0 : return {
37 : ...operation,
38 : op_id: mintOpId(),
39 : actor,
40 : base_version: baseVersion,
41 : stamp: [baseVersion, actor]
42 : }
43 : }
44 :
45 : /**
46 : * Attach wire identity to every operation. `op_id` is minted exactly once
47 : * here — a retry re-sends the SAME minted ops (the sender never re-mints;
48 : * changed-payload reuse rejects host-side).
49 : */
50 0 : export function mintWireOps(
51 : operations: GraphOperation[],
52 : context: MintContext
53 : ): Op[] {
54 0 : return operations.map((operation) => withEnvelope(operation, context))
55 : }
56 :
57 0 : function isBatchable(op: Op): boolean {
58 0 : return (BATCHABLE_OPS as readonly string[]).includes(op.op)
59 : }
60 :
61 : /**
62 : * A minted op as admitted: the semantic `op` callers get back at settlement,
63 : * the `wire` object the transport sends, and its UTF-8 size. `wire` is the
64 : * parsed result of the one serialization performed at admission: plain JSON
65 : * data with no `toJSON` and no cycles, so encoding the frame later yields
66 : * exactly the measured bytes however the original op's values behave.
67 : */
68 : export interface SizedOp {
69 : readonly op: Op
70 : readonly wire: DocOp
71 : readonly bytes: number
72 : }
73 :
74 : /**
75 : * The sequencing envelope: the fields the chunker classifies by (`op`), the
76 : * sender settles by (`op_id`), and the applier orders by (`base_version`,
77 : * `stamp`, `actor`). The wire must carry exactly the values minted onto the
78 : * semantic op.
79 : */
80 : interface Envelope {
81 : readonly op: string
82 : readonly op_id: string
83 : readonly actor: Actor
84 : readonly base_version: number
85 : readonly stamp: Stamp
86 : }
87 :
88 : type WireOp = DocOp & Envelope
89 :
90 1 : const WIRE_SCALAR_FIELDS = {
91 : op: 'string',
92 : op_id: 'string',
93 : actor: 'string',
94 : base_version: 'number'
95 : } as const
96 :
97 0 : function isStamp(value: unknown): value is Stamp {
98 0 : return (
99 : Array.isArray(value) &&
100 : value.length === 2 &&
101 : typeof value[0] === 'number' &&
102 : typeof value[1] === 'string'
103 : )
104 : }
105 :
106 0 : function isRecord(value: unknown): value is Record<string, unknown> {
107 0 : return typeof value === 'object' && value !== null && !Array.isArray(value)
108 : }
109 :
110 0 : function isWireOp(value: unknown): value is WireOp {
111 0 : if (!isRecord(value)) return false
112 : const scalarsTyped = Object.entries(WIRE_SCALAR_FIELDS).every(
113 : ([field, type]) => typeof value[field] === type
114 : )
115 0 : return scalarsTyped && isStamp(value.stamp)
116 : }
117 :
118 0 : function envelopeOf({
119 : op,
120 : op_id,
121 : actor,
122 : base_version,
123 : stamp
124 : }: Envelope): Envelope {
125 0 : return { op, op_id, actor, base_version, stamp: [stamp[0], stamp[1]] }
126 : }
127 :
128 0 : function sameEnvelope(a: Envelope, b: Envelope): boolean {
129 0 : return (
130 : a.op === b.op &&
131 : a.op_id === b.op_id &&
132 : a.actor === b.actor &&
133 : a.base_version === b.base_version &&
134 : a.stamp[0] === b.stamp[0] &&
135 : a.stamp[1] === b.stamp[1]
136 : )
137 : }
138 :
139 : export type WireMeasurement =
140 : | { readonly admitted: true; readonly sized: SizedOp }
141 : | { readonly admitted: false; readonly op: Op; readonly cause: unknown }
142 :
143 0 : function stringifyOp(op: Op): { json: string } | { cause: unknown } {
144 0 : try {
145 0 : const json: unknown = JSON.stringify(op)
146 0 : return typeof json === 'string'
147 : ? { json }
148 : : { cause: new TypeError('Operation did not serialize to JSON') }
149 : } catch (cause) {
150 0 : return { cause }
151 : }
152 : }
153 :
154 0 : function rejected(op: Op, message: string): WireMeasurement {
155 0 : return { admitted: false, op, cause: new TypeError(message) }
156 : }
157 :
158 : /**
159 : * Serialize an op once to prove it can ride a `doc_ops` frame and learn its
160 : * wire form and size. Never throws: anything `JSON.stringify` cannot turn
161 : * into a wire object (a cycle in a custom-node value, a `toJSON` that throws
162 : * or yields a non-object) comes back as a rejection carrying the cause, and
163 : * so does any serializer that leaves the wire's {@link Envelope} different
164 : * from the one minted before serialization, or rewrites the semantic op's
165 : * own envelope while running. The envelope is captured before `toJSON` runs
166 : * and compared against both results afterwards, so a stateful serializer
167 : * cannot settle one sequence position while transmitting another. Callers
168 : * settle a rejected op at admission; the original op is never serialized
169 : * again.
170 : */
171 0 : export function measureWireOp(op: Op): WireMeasurement {
172 0 : const minted = envelopeOf(op)
173 0 : const serialized = stringifyOp(op)
174 0 : if ('cause' in serialized)
175 0 : return { admitted: false, op, cause: serialized.cause }
176 0 : const wire: unknown = JSON.parse(serialized.json)
177 0 : if (!isWireOp(wire))
178 0 : return rejected(op, 'Operation did not serialize to a wire object')
179 0 : if (!sameEnvelope(wire, minted))
180 0 : return rejected(op, 'Operation serialized with a different envelope')
181 0 : if (!sameEnvelope(op, minted))
182 0 : return rejected(op, 'Operation changed its envelope while serializing')
183 0 : return {
184 : admitted: true,
185 : sized: { op, wire, bytes: new TextEncoder().encode(serialized.json).length }
186 : }
187 : }
188 :
189 : /**
190 : * Split measured ops into wire batches: order-preserving, at most
191 : * {@link WIRE_MAX_OPS_PER_BATCH} ops and {@link WIRE_MAX_BATCH_BYTES} bytes
192 : * per batch; every non-batchable op (`clear`) is a batch of one. A single op
193 : * larger than the byte cap still ships alone — the host, not the chunker,
194 : * owns rejecting it. Pure arithmetic over sizes measured at admission: it
195 : * cannot throw.
196 : */
197 0 : export function chunkWireOps(ops: readonly SizedOp[]): SizedOp[][] {
198 0 : const batches: SizedOp[][] = []
199 0 : let current: SizedOp[] = []
200 0 : let currentBytes = 0
201 :
202 0 : const flush = (): void => {
203 0 : if (current.length > 0) batches.push(current)
204 0 : current = []
205 0 : currentBytes = 0
206 : }
207 :
208 0 : for (const sized of ops) {
209 0 : if (!isBatchable(sized.op)) {
210 0 : flush()
211 0 : batches.push([sized])
212 0 : continue
213 : }
214 0 : const overOps = current.length + 1 > WIRE_MAX_OPS_PER_BATCH
215 0 : const overBytes =
216 : current.length > 0 &&
217 : currentBytes + sized.bytes > WIRE_MAX_BATCH_BYTES - STAMP_LIFT_HEADROOM
218 0 : if (overOps || overBytes) flush()
219 0 : current.push(sized)
220 0 : currentBytes += sized.bytes
221 : }
222 0 : flush()
223 0 : return batches
224 : }
|