Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

kernel: a relay snapshot strips large inline assets (photo-heavy decks share again) (#509)

nyblnet30a667c6c3bb
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 59a8886d..f35185a6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,13 @@ pre-1.0.
## [Unreleased]
+- **A deck full of photos can be shared live again.** A deck whose pictures
+ were each under the sharing limit but together came to more than about a
+ megabyte could not be shared at all — the copy a joining collaborator
+ receives was sent as one oversize frame the relay refused. Each picture
+ already travelled separately when it changed; that copy now does the same,
+ so the deck shares no matter how many photos it holds.
+
## [1.2.1] — 2026-09-17
- **Pasting into a table cell lands once.** Edit a cell, leave it unchanged,
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index 4a4c930c..2d25cdb1 100644
--- a/docs/DECISIONS.md
+++ b/docs/DECISIONS.md
@@ -7279,3 +7279,37 @@ generation (that would break the same-block RGA merge). Its gate is the full
convergence rig, `scripts/test-sync`. Where it is wanted: bento/spaces per-block
text under Markdown storage (working/design/spaces-pages.md follow-ups).
+## 2026-09-17 — A relay snapshot obeys the blob-offload rule: large inline assets are stripped
+
+`crdt.ts` diffDoc keeps inline assets over `BLOB_INLINE_MAX` (64 KB) out of ops
+— they travel as blobs (`offloadAssets`) and the receiver rebuilds them with
+`resolveBlobs`. The relay SNAPSHOT paths did not: `session.snapshot()`,
+`recoverFromDiffFailure`, and the fork snapshot in `hello()` all serialised the
+FULL `store.doc` with every inline asset. On a photo-heavy deck that inlines the
+whole asset table, and the wire frame — `base64(iv ‖ AES-GCM(JSON))`, ~4/3 the
+JSON — exceeds the relay's `MAX_FRAME` (1,900,000). Measured on the maintainer's
+real deck: 1.57 MB doc (1.43 MB inline photos, none over the per-image limit) →
+~2.1 MB frame → relay refuses `too-large`. Because a snapshot is never acked, no
+op matched the refusal (`matchRefused` → null → `refused('too-large', null)` →
+notice `ops:0`), so the editor showed the per-CHANGE wording with a per-image
+limit — wrong for a whole-deck snapshot.
+
+Fix: snapshots apply diffDoc's rule via `SyncSession.snapshotDoc()` — drop
+`assets.<k>` whose inline value is over `BLOB_INLINE_MAX`, keep `blobs` intact;
+the receiver materialises them with `resolveBlobs` exactly as it does for ops.
+`offloadAssets` already runs on every flush (and `snapshot()` flushes first), so
+the blob refs exist by the time a snapshot is uploaded on a shared deck. Residual,
+stated: a large asset whose offload has not yet completed (or a relay with no
+blob store — `unsupported`) has no ref, so the receiver shows it blank until the
+ref syncs — identical to the existing op path, and self-healing. Rig:
+`scripts/test-sync-session.ts` asserts the stripped snapshot frame is under
+`MAX_FRAME` while the full-doc frame is over (negative control), the blob ref
+survives, and the local store keeps the full asset.
+
+Message: after this fix a snapshot is essentially never refused for assets. If a
+snapshot is still refused `too-large` (many sub-64 KB assets, or huge text), the
+transport surfaces `refused('too-large', null)` → the session emits a notice with
+`ops: 0` and no `media` flag — the signal the editor can use to say "the whole
+deck is too large to share" rather than "that change is too large". (Wording is
+the slides zone's.)
+
diff --git a/kernel/src/sync/online.ts b/kernel/src/sync/online.ts
index 656b6262..94a24446 100644
--- a/kernel/src/sync/online.ts
+++ b/kernel/src/sync/online.ts
@@ -261,8 +261,9 @@ export class OnlineTransport implements Transport {
/** replay done: (actor,seq) pairs the room holds; return true to upload a snapshot */
onReady: (seen: Set<string>, seq: number) => boolean
/** the relay refused a frame; `ops` are the ones it will never accept
- * (null when the refusal couldn't be pinned to a frame we sent) */
- onRefused?: (code: RefusalCode, ops: Op[] | null) => void
+ * (null when the refusal couldn't be pinned to a frame we sent). `opts.snapshot`
+ * = the refused frame was a whole-deck snapshot (no op of ours matched it). */
+ onRefused?: (code: RefusalCode, ops: Op[] | null, opts?: { snapshot?: boolean }) => void
// ——— broadcast reception (audience side, and the presenter's own
// checkpoint/count signals). All optional: a session with no show wires
// none of them and nothing below fires. ———
@@ -522,7 +523,10 @@ export class OnlineTransport implements Transport {
const culprit = this.matchRefused(env)
if (culprit) this.awaitingAck = this.awaitingAck.filter((o) => o !== culprit)
console.warn(`[bento-sync] relay refused a frame (${env.code})`, env)
- this.hooks.onRefused?.(env.code, culprit?.ops ?? null)
+ // No matched op for a whole-frame refusal = the frame was a snapshot (ops
+ // are tracked and matched by id; snapshots are never acked). Lets the editor
+ // word it "the deck is too large" rather than "that change is too large".
+ this.hooks.onRefused?.(env.code, culprit?.ops ?? null, culprit ? undefined : { snapshot: true })
}
/**
@@ -973,11 +977,11 @@ export function joinFromDoc(session: SyncSession, store: Store): OnlineTransport
getSnapshot: () => session.snapshot(),
onOpen: () => session.hello(),
onReady: (seen) => session.onRelayReady(seen),
- onRefused: (code, ops) => {
+ onRefused: (code, ops, opts) => {
// show-full is a broadcast refusal: it means "checkpoint now", handled
// by the show path, not the collab resend log.
if ((code as string) === 'show-full') { session.showCheckpoint(); return }
- session.refused(code, ops)
+ session.refused(code, ops, opts)
},
onShowOps: (ops) => session.applyShowOps(ops),
onShowSnap: (doc, state) => session.applyShowSnap(doc, state),
diff --git a/kernel/src/sync/session.ts b/kernel/src/sync/session.ts
index 55ca48fe..6031ff81 100644
--- a/kernel/src/sync/session.ts
+++ b/kernel/src/sync/session.ts
@@ -268,6 +268,10 @@ export interface SyncNotice {
ops: number
/** the abandoned ops carried embedded media — lets the UI say "that image" */
media?: boolean
+ /** the refused frame was a whole-deck SNAPSHOT, not a single change (the relay
+ * could not attribute it to any op of ours). Lets the UI say "this deck is too
+ * large to share" rather than "that change is too large". `ops` is 0 here. */
+ snapshot?: boolean
}
/** Same-machine transport: every open tab/window of this document. */
@@ -603,7 +607,7 @@ export class SyncSession {
this.broadcast({
t: 'snap',
a: this.actor,
- doc: JSON.parse(JSON.stringify(this.store.doc)) as SyncDoc,
+ doc: this.snapshotDoc(),
state: JSON.parse(JSON.stringify(this.state.toJSON())),
})
} catch (e2) {
@@ -892,7 +896,7 @@ export class SyncSession {
* ONLY the exact ops the refused frame carried — never a range, never the
* rest of the log, and never anything when the frame couldn't be identified.
*/
- refused(code: RefusalCode, ops: Op[] | null) {
+ refused(code: RefusalCode, ops: Op[] | null, opts?: { snapshot?: boolean }) {
const doomed = ops ?? []
if (doomed.length) {
const keys = new Set(doomed.map((o) => `${o.a}:${o.s}`))
@@ -903,20 +907,55 @@ export class SyncSession {
permanent: code !== 'rate-limited',
ops: doomed.length,
...(this.host.carriesMedia(doomed) ? { media: true } : {}),
+ ...(opts?.snapshot ? { snapshot: true } : {}),
})
}
// --- snapshots (online catch-up + file-fork merge) ------------------------
+ /**
+ * A doc clone SAFE to put in a relay snapshot frame. Inline assets larger than
+ * BLOB_INLINE_MAX are DROPPED — exactly as crdt.ts diffDoc keeps them out of
+ * ops — because they travel as blobs (offloadAssets) and the receiver
+ * materialises them with resolveBlobs. Without this, a photo-heavy deck's
+ * snapshot inlines the whole asset table and the frame text (after JSON +
+ * AES-GCM + base64) exceeds the relay's MAX_FRAME, so the relay refuses it
+ * 'too-large'; since a snapshot is never acked no op matches the refusal and
+ * the editor showed the wrong per-change limit. `blobs` is left intact so the
+ * references survive. See docs/DECISIONS.md and docs/blob-offload.md.
+ */
+ private snapshotDoc(): SyncDoc {
+ const doc = JSON.parse(JSON.stringify(this.store.doc)) as SyncDoc
+ const assets = doc.assets
+ if (assets)
+ for (const [k, v] of Object.entries(assets))
+ if (typeof v === 'string' && v.length > BLOB_INLINE_MAX) delete assets[k]
+ return doc
+ }
+
/** current (doc, sync-state) pair for an encrypted relay snapshot */
snapshot(): { doc: SyncDoc; state: SyncStateJSON } {
this.flush()
return {
- doc: JSON.parse(JSON.stringify(this.store.doc)) as SyncDoc,
+ doc: this.snapshotDoc(),
state: JSON.parse(JSON.stringify(this.state.toJSON())),
}
}
+ /** How many inline assets are still awaiting blob offload — over
+ * BLOB_INLINE_MAX and without a published `blobs` reference yet. While this is
+ * > 0 a joining collaborator may see those pictures blank until the reference
+ * syncs, so the editor can surface "N pictures still uploading". Cheap: one
+ * pass over the asset table. */
+ pendingBlobUploads(): number {
+ const doc = this.store.doc
+ const assets = doc.assets ?? {}
+ let n = 0
+ for (const [k, v] of Object.entries(assets))
+ if (typeof v === 'string' && v.length > BLOB_INLINE_MAX && !doc.blobs?.[k]) n++
+ return n
+ }
+
/** merge a remote snapshot (relay replay for far-behind joiners) */
applySnapshot(rdoc: SyncDoc, rstate: SyncStateJSON) {
if (!rstate || rstate.v !== SYNC_V) return // pre-v2 room snapshot — unusable
diff --git a/scripts/test-sync-session.ts b/scripts/test-sync-session.ts
index 13987f8a..a4eec936 100644
--- a/scripts/test-sync-session.ts
+++ b/scripts/test-sync-session.ts
@@ -265,6 +265,60 @@ H('an emptied document heals with a paragraph, not a slide');
'and it is an empty paragraph — somewhere to put the caret');
}
+H('a photo-heavy deck snapshot fits under the relay frame ceiling (assets travel as blobs)');
+{
+ // A snapshot that inlined the whole asset table blew past the relay ceiling
+ // and was refused 'too-large' — on a deck where no single photo is over the
+ // per-image limit. snapshot() must apply diffDoc's rule: drop inline assets
+ // over BLOB_INLINE_MAX (they go as blobs), keep the blob refs.
+ const MAX_FRAME = 1_900_000; // server/sync-worker/src/worker.js
+ const BLOB_INLINE_MAX = 64 * 1024; // kernel/src/sync/crdt.ts
+ // The relay measures the WIRE frame, not the doc JSON: online.ts seals the
+ // payload as base64(iv ‖ AES-GCM(JSON)), which is ~4/3 the JSON size — the
+ // reason a 1.57 MB deck (under MAX_FRAME as JSON) produced a ~2.1 MB frame
+ // and was refused. Model that expansion so the ceiling comparison is real.
+ const frameBytes = (jsonLen: number) => Math.ceil((jsonLen + 12 + 16) / 3) * 4; // 12B iv + 16B GCM tag
+ const doc = newDoc();
+ doc.docId = `rig-photo-${Math.random().toString(36).slice(2, 8)}`;
+ const hero = 'data:image/jpeg;base64,' + 'A'.repeat(1_500_000); // one photo, over MAX_FRAME on its own
+ const small = 'data:image/png;base64,' + 'B'.repeat(1000); // under BLOB_INLINE_MAX, stays inline
+ (doc as unknown as { assets: Record<string, string> }).assets = { hero, small };
+ // offload has already run: the big asset carries a blob reference — what makes
+ // dropping its inline bytes safe (the receiver rebuilds it from the blob).
+ (doc as unknown as { blobs: Record<string, unknown> }).blobs =
+ { hero: { key: 'k-hero', mime: 'image/jpeg', size: 1_100_000 } };
+ const store = new Store(doc);
+ const s = new SyncSession(store);
+ const rawFrame = frameBytes(JSON.stringify(store.doc).length);
+ const snap = s.snapshot();
+ const leanFrame = frameBytes(JSON.stringify(snap.doc).length);
+ ok(rawFrame > MAX_FRAME, `negative control: the FULL doc's frame is over the ceiling (${rawFrame} B > ${MAX_FRAME})`);
+ ok(leanFrame < MAX_FRAME, `the stripped snapshot's frame fits under MAX_FRAME (${leanFrame} B)`);
+ const snapAssets = (snap.doc as unknown as { assets?: Record<string, string> }).assets ?? {};
+ ok(!('hero' in snapAssets), 'the large inline asset is dropped from the snapshot (it travels as a blob)');
+ ok(snapAssets.small === small, 'a small inline asset is kept inline');
+ const snapBlobs = (snap.doc as unknown as { blobs?: Record<string, { key: string }> }).blobs ?? {};
+ ok(snapBlobs.hero?.key === 'k-hero', 'the blob reference is kept, so the receiver materialises it via resolveBlobs');
+ ok((store.doc as unknown as { assets: Record<string, string> }).assets.hero === hero,
+ 'the local store keeps the full asset — only the snapshot copy is stripped');
+
+ // pending-upload count: what the editor shows as "N pictures still uploading"
+ ok(s.pendingBlobUploads() === 0, 'no pending uploads when every large asset already has a blob ref');
+ (store.doc as unknown as { assets: Record<string, string> }).assets.hero2 =
+ 'data:image/jpeg;base64,' + 'C'.repeat(200_000); // large, no ref yet
+ ok(s.pendingBlobUploads() === 1, 'a large asset without a blob ref counts as pending');
+
+ // the snapshot discriminator: a refused snapshot carries snapshot:true, ops:0,
+ // so the editor words it "the deck is too large" not "that change is too large"
+ let last: { code: string; ops: number; permanent: boolean; snapshot?: boolean } | null = null;
+ const un = s.onNotice((n) => { last = n as never; });
+ s.refused('too-large', null, { snapshot: true });
+ ok(last?.snapshot === true && last?.ops === 0 && last?.permanent === true,
+ 'a snapshot refusal emits { snapshot:true, ops:0, permanent:true }');
+ un();
+ s.stop?.();
+}
+
console.log(`\n${checks - failures}/${checks} checks passed`);
// BroadcastChannel and the heartbeat keep node's event loop alive
process.exit(failures ? 1 : 0);