项目同步与补丁安全 深度解析

121/* ==================== incremental save wire format ==================== */
122/*
123 * The PUT body is a DIFF, two levels:
124 *  1. Sectioning: the full payload splits into five sections (comp/chat/context/coverThumb/meta);
125 *     unchanged sections aren't sent, all-unchanged = zero request; on the server, ABSENT = unchanged,
126 *     keeping the current stored value.
127 *  2. Intra-section JSON Patch (RFC 6902, fast-json-patch): the client keeps a copy of the
128 *     "last successfully saved value"; the changed big sections (comp/chat/context) compare against
129 *     it into an op list, and if that's smaller than the whole section (<60%) it sends the patch —
130 *     dragging one block = one replace of a few hundred bytes, no more re-sending the whole 246KB.
131 * Correctness anchor: comp/chat patches carry a target canonical hash; the server verifies after
132 * applying, and on mismatch (base drifted / patch corrupt) → 422 need_full, the client clears the
133 * baseline and re-sends the whole section — worst case degrades to full, never silently wrong.
134 * context patches aren't verified (the server may have merged in keys from elsewhere, legitimately
135 * more than the client), and apply itself preserves unknown keys. The patch precondition =
136 * baseVersion optimistic concurrency: on 409 the client re-seeds the baseline (ackedFromDto) from
137 * the returned server full, so the retry diff is computed against server truth, converging per section.
138 */
139
140/** Diff wire format from client to server (serverSaveProject builds it from the full payload).
141 *  Each big section is one of three: full value / patch+target hash / absent (unchanged). */
142export interface ProjectSaveWire {
143  baseVersion: number | null;
144  comp?: Composition;
145  compPatch?: Operation[];
146  compHash?: string;
147  chat?: unknown[];
148  chatPatch?: Operation[];
149  chatHash?: string;
150  context?: StudioProjectContext;
151  contextPatch?: Operation[];
152  coverThumb?: string | null;
153  title?: string;
154  videoSig?: string | null;
155  videoDurationSec?: number | null;
156}
157
158/** Canonical serialization (object keys sorted): the hash must match on both ends, but jsonb
159 *  storage reorders keys, so plain JSON.stringify yields different strings for the same data.
160 *  undefined handled per JSON semantics (object keys dropped / array elements → null). */

267export function buildSaveWire(
268  p: ProjectSavePayload,
269  baseVersion: number | null,
270  acked: AckedSections | null,
271): { wire: ProjectSaveWire; acked: AckedSections } | null {
272  const compCanon = canonicalJson({ ...p.comp, video: null });
273  const chatCanon = canonicalJson(p.chat ?? []);
274  const ctxCanon = canonicalJson(p.context ?? {});
275  const hashes: SectionHashes = {
276    comp: hashSection(compCanon),
277    chat: hashSection(chatCanon),
278    context: hashSection(ctxCanon),
279    coverThumb: hashSection(p.coverThumb ?? ''),
280    meta: metaHashOf(p.title, p.videoSig, p.videoDurationSec),
281  };
282  // JSON-clean current values (parsed from the canonical string: incidentally drops undefined, so diff is structurally comparable to the baseline)
283  const values: AckedSections['values'] = {
284    comp: JSON.parse(compCanon) as Composition,
285    chat: JSON.parse(chatCanon) as unknown[],
286    context: JSON.parse(ctxCanon) as StudioProjectContext,
287  };
288  const wire: ProjectSaveWire = { baseVersion };
289  const w = wire as unknown as Record<string, unknown>;
290  let changed = false;
291
292  /** Big-section tri-state: unchanged → absent / has baseline and patch is smaller → send patch / else whole section. */
293  const emitBig = (key: 'comp' | 'chat' | 'context', canon: string, withHash: boolean) => {
294    if (acked && acked.hashes[key] === hashes[key]) return;
295    changed = true;
296    if (acked) {
297      try {
298        const ops = diffOps(acked.values[key], values[key]);
299        if (JSON.stringify(ops).length < canon.length * PATCH_WORTH_RATIO) {
300          w[`${key}Patch`] = ops;
301          if (withHash) w[`${key}Hash`] = hashes[key];
302          return;
303        }
304      } catch {
305        /* diff failed → fall back to whole section */
306      }
307    }
308    w[key] = values[key];
309  };
310  emitBig('comp', compCanon, true);
311  emitBig('chat', chatCanon, true);
312  emitBig('context', ctxCanon, false);
313
314  if (!acked || acked.hashes.coverThumb !== hashes.coverThumb) {
315    wire.coverThumb = p.coverThumb;
316    changed = true;
317  }
318  if (!acked || acked.hashes.meta !== hashes.meta) {
319    if (p.title !== undefined) wire.title = p.title;
320    wire.videoSig = p.videoSig;
321    wire.videoDurationSec = p.videoDurationSec;
322    changed = true;
323  }
324  return changed ? { wire, acked: { values, hashes } } : null;

391export function mergeSaveIntoRow(
392  existing: {
393    title: string;
394    comp: unknown;
395    chat: unknown;
396    context?: unknown;
397    videoSig: string | null;
398    videoDurationSec: string | number | null;
399    coverThumb: string | null;
400  },
401  p: NonNullable<ReturnType<typeof sanitizeSavePayload>>,
402): {
403  title: string;
404  comp: unknown;
405  chat: unknown;
406  context: Record<string, unknown>;
407  videoSig: string | null;
408  videoDurationSec: string | null;
409  coverThumb: string | null;
410} | null {
411  // comp: full > patch (with hash verify, strip video once more after apply as a safety net) > keep
412  let comp = existing.comp;
413  if (p.comp) comp = p.comp;
414  else if (p.compPatch) {
415    if (!p.compHash) return null; // patch must carry a target hash; missing = client broken
416    const patched = applySectionPatch(existing.comp, p.compPatch, p.compHash);
417    if (patched === null) return null;
418    comp = { ...(patched as Composition), video: null };
419  }
420
421  let chat = existing.chat;
422  if (p.chat) chat = p.chat;
423  else if (p.chatPatch) {
424    if (!p.chatHash) return null;
425    const patched = applySectionPatch(Array.isArray(existing.chat) ? existing.chat : [], p.chatPatch, p.chatHash);
426    if (patched === null) return null;
427    chat = patched;
428  }
429
430  // context: full = merge by key (guards partial state against erasure: missing key = don't know ≠ delete);
431  // patch = applied on the server's current value, naturally preserving keys the client doesn't know,
432  // no hash verify (the server may have merged in keys from elsewhere, legitimately more than the client, so verify would always false-positive).
433  const exCtx = (existing.context && typeof existing.context === 'object' ? existing.context : {}) as Record<string, unknown>;
434  let context = exCtx;
435  if (p.context) context = { ...exCtx, ...(p.context as Record<string, unknown>) };
436  else if (p.contextPatch) {
437    const patched = applySectionPatch(exCtx, p.contextPatch);
438    if (patched === null || typeof patched !== 'object' || Array.isArray(patched)) return null;
439    context = patched as Record<string, unknown>;
440  }
441
442  const exDur = existing.videoDurationSec;
443  return {
444    title: p.title ?? existing.title,
445    comp,
446    chat,
447    context,
448    // null doesn't overwrite non-empty: the saving tab may not have hydrated yet (its "absent" ≠ "user deleted")
449    videoSig: p.videoSig ?? existing.videoSig,
450    videoDurationSec: p.videoDurationSec != null ? String(p.videoDurationSec) : exDur == null ? null : String(exDur),
451    coverThumb: p.coverThumb ?? existing.coverThumb,
452  };