exampleslive-notes Public
Save a snapshot of each note to R2 every 100 versions #2
Changed.rebasely/architecture/flows/edit-broadcast.yaml+4−1
| @@ -1,5 +1,7 @@ | ||
| title: An edit reaching other editors | ||
| -description: Editor A types while editor B has the same note open. The room puts the edit in order, saves it and passes it on. | ||
| +description: >- | ||
| + Editor A types while editor B has the same note open. The room puts the edit in order, saves it | ||
| + and passes it on. Every 100th version it also copies the note to R2. | ||
| actors: [editor-a, editor-b] | ||
| steps: | ||
| - { from: editor-a, to: note-room, label: "op: insert \"oat \" at 4, written against version 41" } | ||
| @@ -7,4 +9,5 @@ | ||
| - { from: ops, to: note-room, label: "the op as it applies now, which the room saves to SQLite" } | ||
| - { from: note-room, to: editor-a, label: "ack: version 44" } | ||
| - { from: note-room, to: editor-b, label: the transformed op at version 44 } | ||
| + - { from: note-room, to: snapshots, label: "every 100 versions: put the note's text, after the replies" } | ||
| - { from: editor-b, to: ops, label: "move the op past B's own unacknowledged edits, then apply it" } | ||
Added.rebasely/architecture/flows/reading-history.yaml+13−0
| @@ -0,0 +1,13 @@ | ||
| +title: Reading a note's history | ||
| +description: >- | ||
| + Someone wants to see what the groceries note said before today's edits. The Worker reads the | ||
| + snapshots from R2 under the room's object id, which it computes with idFromName, so the room | ||
| + is never woken. | ||
| +actors: [reader] | ||
| +steps: | ||
| + - { from: reader, to: api, label: "GET /notes/groceries/snapshots" } | ||
| + - { from: api, to: snapshots, label: "list snapshots/<idFromName(groceries)>/, 100 keys at a time" } | ||
| + - { from: api, to: reader, label: "versions 100, 200 and 300, when each was saved and its size" } | ||
| + - { from: reader, to: api, label: "GET /notes/groceries/snapshots/200" } | ||
| + - { from: api, to: snapshots, label: "get snapshots/<id>/000000000200.txt" } | ||
| + - { from: api, to: reader, label: "the text at version 200, as text/plain, cacheable for a year" } | ||
Changed.rebasely/architecture/system.yaml+16−3
| @@ -1,17 +1,30 @@ | ||
| components: | ||
| api: | ||
| kind: worker | ||
| - description: The Worker. Routes /notes/:id to that note's room and serves the editor page as static assets. | ||
| + description: >- | ||
| + The Worker. Routes /notes/:id to that note's room, serves the editor page as static assets, | ||
| + and reads a note's snapshots straight from R2 so history never wakes the room. | ||
| owns: [src/index.ts, src/routes.ts] | ||
| talks_to: | ||
| - { to: note-room, via: rpc } | ||
| + - { to: snapshots, via: r2 } | ||
| note-room: | ||
| kind: durable-object | ||
| - description: One per note, picked by name. Orders every edit, keeps the note and its op log in SQLite, and holds the editors' WebSockets. | ||
| + description: >- | ||
| + One per note, picked by name. Orders every edit, keeps the note and its op log in SQLite, | ||
| + holds the editors' WebSockets, and copies the note to R2 every 100 versions. | ||
| binding: NOTES | ||
| - owns: [src/note-room.ts, src/room.ts] | ||
| + owns: [src/note-room.ts, src/room.ts, src/snapshots.ts] | ||
| talks_to: | ||
| - { to: ops, via: import } | ||
| + - { to: snapshots, via: r2 } | ||
| + snapshots: | ||
| + kind: r2-bucket | ||
| + description: >- | ||
| + Bucket live-notes-snapshots. The note's text every 100 versions, at | ||
| + snapshots/<object id>/<version>.txt, kept after the op log has moved on. Written by the | ||
| + note's room, read by the Worker. | ||
| + binding: SNAPSHOTS | ||
| ops: | ||
| kind: library | ||
| description: Insert and delete operations, their transform, and the messages on the socket. The same code runs in the room and in the browser. | ||
Changed.rebasely/architecture/views/editing.yaml+2−2
| @@ -1,2 +1,2 @@ | ||
| -description: What takes part in an edit, from the browser to the room and back. | ||
| -components: [client, ops, note-room] | ||
| +description: What takes part in an edit, from the browser to the room and back, and where the room keeps copies. | ||
| +components: [client, ops, note-room, snapshots] | ||
Changed.rebasely/kb/concepts/conflict-strategy.md+5−1
| @@ -2,7 +2,7 @@ | ||
| id: conflict-strategy | ||
| type: concept | ||
| owner: justin | ||
| -reviewed: 2026-10-14 | ||
| +reviewed: 2026-10-16 | ||
| component: ops | ||
| describes: | ||
| - src/ops.ts | ||
| @@ -58,3 +58,7 @@ | ||
| take the note past 100,000 characters gets a snapshot back instead of an ack. The editor shows the snapshot and drops its pending edits. | ||
| In practice this happens after a long disconnect, and the page disables the textarea while it | ||
| is offline so nothing is typed into the void. | ||
| + | ||
| +Ops older than the log are gone, but the text is not: every 100th version of the note is kept in | ||
| +R2 ([[snapshots]]). Snapshots are not part of conflict handling; the room never transforms | ||
| +against them. | ||
Changed.rebasely/kb/concepts/note-room.md+13−2
| @@ -2,7 +2,7 @@ | ||
| id: note-room | ||
| type: concept | ||
| owner: justin | ||
| -reviewed: 2026-10-14 | ||
| +reviewed: 2026-10-16 | ||
| component: note-room | ||
| describes: | ||
| - src/note-room.ts | ||
| @@ -25,16 +25,24 @@ | ||
| ## Storage | ||
| -Two tables in the object's SQLite database: | ||
| +Three tables in the object's SQLite database: | ||
| - `note`: one row with the text and its version. `Room` caps the text at 100,000 UTF-16 code | ||
| units, so the row and every snapshot frame stay small. | ||
| - `ops`: the op log, keyed by the version each op produced, trimmed to the last 200. | ||
| +- `snapshot`: one row with the version of the last copy saved to R2. | ||
| `commit()` writes the new text, appends the op and trims the log inside one `transactionSync`, | ||
| so a note and its log never disagree. The room only updates its in-memory copy after the | ||
| write. | ||
| +## Snapshots | ||
| + | ||
| +Every 100 versions `Room` asks for the note to be copied to the `SNAPSHOTS` bucket. | ||
| +`webSocketMessage` sends the ack and the broadcast first, then writes the copy and records its | ||
| +version in `snapshot`. A failed write is logged and tried again on the next edit, and only one | ||
| +runs at a time. See [[snapshots]]. | ||
| + | ||
| ## Hibernation | ||
| Sockets are accepted with `ctx.acceptWebSocket`, the Hibernation API. When nobody has typed for | ||
| @@ -50,3 +58,6 @@ | ||
| `GET /notes/:id` calls the `read()` RPC method and returns `{ id, text, version }`. It reads the | ||
| room's in-memory copy, which is always the last committed state. | ||
| + | ||
| +`GET /notes/:id/snapshots` and `GET /notes/:id/snapshots/:version` do not reach the room at all: | ||
| +the Worker reads them from R2 under `idFromName(id)`, the same id the room saves them under. | ||
Added.rebasely/kb/concepts/snapshots.md+65−0
| @@ -0,0 +1,65 @@ | ||
| +--- | ||
| +id: snapshots | ||
| +type: concept | ||
| +owner: justin | ||
| +component: snapshots | ||
| +describes: | ||
| + - src/snapshots.ts | ||
| +reviewed: 2026-10-16 | ||
| +--- | ||
| +# Snapshots in R2 | ||
| + | ||
| +A room keeps only the latest text and its last 200 ops ([[note-room]]). Every 100 versions it | ||
| +also writes the note's text to the `SNAPSHOTS` bucket, so what a note said last week can still | ||
| +be read after the op log has moved on. [[0003-snapshots-in-r2]] has the reasoning. | ||
| + | ||
| +These are the same thing as the `snapshot` message on the socket ([[wire-protocol]]), the text | ||
| +at a version. The difference is that these are kept. | ||
| + | ||
| +## When the room saves one | ||
| + | ||
| +`Room.receive()` (`src/room.ts`) marks an outcome with `saveSnapshot` when the new version is at | ||
| +least `SNAPSHOT_EVERY` (100) past the last saved one. `NoteRoom` sends the ack and the broadcast | ||
| +first, then puts the text in R2, then records the version in its SQLite `snapshot` table. The | ||
| +editors never wait for R2. | ||
| + | ||
| +If the put fails, nothing is recorded, so the next edit is due again and tries once more. Only | ||
| +one save runs at a time per room; edits that arrive while one is in flight do not start another. | ||
| +A failed save is logged as `saving a snapshot failed` with the version. | ||
| + | ||
| +Edits that change nothing, and edits the room refuses, never trigger a save. | ||
| + | ||
| +## Keys | ||
| + | ||
| +``` | ||
| +snapshots/<object id>/<version, 12 digits>.txt | ||
| +snapshots/6f1c...e2/000000000300.txt | ||
| +``` | ||
| + | ||
| +The object id is `idFromName(noteId).toString()`. The room knows it as `ctx.id`, and the Worker | ||
| +can compute it from the URL, so both sides agree on the prefix without the room ever being told | ||
| +its name. The zero padding makes R2 list keys in version order. | ||
| + | ||
| +An object is never overwritten: a version is only saved once, and a note's text at a version | ||
| +never changes. | ||
| + | ||
| +## Reading them | ||
| + | ||
| +The Worker serves them from R2 without touching the room: | ||
| + | ||
| +``` | ||
| +GET /notes/groceries/snapshots | ||
| +{ "id": "groceries", "snapshots": [{ "version": 100, "saved_at": "2026-10-15T09:00:00.000Z", "size": 412 }], "next": null } | ||
| +GET /notes/groceries/snapshots?after=10000 | ||
| +GET /notes/groceries/snapshots/100 | ||
| +``` | ||
| + | ||
| +The list is oldest first, 100 at a time; pass `next` back as `after` for the following page. | ||
| +`saved_at` is when R2 stored the object. One snapshot comes back as `text/plain` with a year of | ||
| +`cache-control`, because it can never change. A version that was never saved is a 404. | ||
| + | ||
| +## Tests | ||
| + | ||
| +`test/snapshots.test.ts` covers when the room asks for a save, retries after a failed one, the | ||
| +recorded version surviving a wake from hibernation, and the key format, saving, reading and | ||
| +paging against an in-memory bucket (`test/helpers/memory-bucket.ts`). | ||
Added.rebasely/kb/decisions/0003-snapshots-in-r2.md+37−0
| @@ -0,0 +1,37 @@ | ||
| +--- | ||
| +id: 0003-snapshots-in-r2 | ||
| +type: decision | ||
| +owner: justin | ||
| +reviewed: 2026-10-16 | ||
| +status: accepted | ||
| +--- | ||
| +# 0003 Snapshots of every note in R2, every 100 versions | ||
| + | ||
| +## Context | ||
| + | ||
| +A room keeps one row with the current text and a log of the last 200 ops, which is all the | ||
| +sequencer needs ([[0001-single-sequencer-per-note]]). Anything older is gone. When someone | ||
| +deletes half a note by accident and notices an hour later, there is nothing to go back to. | ||
| + | ||
| +Keeping more in the Durable Object would work, but every note's history would then live inside | ||
| +its object: reading it means waking the room, and deleting the object deletes its history. | ||
| + | ||
| +## Decision | ||
| + | ||
| +Every 100 versions, the room writes the note's text to an R2 bucket, `live-notes-snapshots`, | ||
| +under `snapshots/<object id>/<version>.txt`. The write happens after the replies, and a failed | ||
| +write is retried on the next edit. The Worker reads the bucket directly for | ||
| +`GET /notes/:id/snapshots`. See [[snapshots]]. | ||
| + | ||
| +## Consequences | ||
| + | ||
| +- A note's history is readable without waking its room, and it is ordinary R2 objects that can | ||
| + be listed, copied or given a lifecycle rule. | ||
| +- History has 100 version steps. What happened between two snapshots is not kept once it leaves | ||
| + the op log. A version is roughly a word of typing, so a step is a sentence or two. | ||
| +- One R2 write per 100 edits per note. A note is at most 100,000 characters, so a thousand edits | ||
| + cost at most about a megabyte of storage, and a typical note far less. | ||
| +- Nothing deletes snapshots yet. When that matters, an R2 lifecycle rule on the `snapshots/` | ||
| + prefix is the place to do it, not the room. | ||
| +- Restoring from a snapshot is by hand for now: read the text, paste it into the editor. The | ||
| + paste is an ordinary edit, so everyone sees it and it is in the next snapshot. | ||
Changed.rebasely/kb/guides/local-dev.md+14−2
| @@ -2,7 +2,7 @@ | ||
| id: local-dev | ||
| type: guide | ||
| owner: justin | ||
| -reviewed: 2026-10-13 | ||
| +reviewed: 2026-10-16 | ||
| --- | ||
| # Running it locally | ||
| @@ -29,6 +29,18 @@ | ||
| curl http://localhost:8787/notes/groceries | ||
| ``` | ||
| +## Snapshots | ||
| + | ||
| +wrangler dev gives the Worker a local R2 bucket for `SNAPSHOTS`. Type a hundred edits into a | ||
| +note (pasting a word a hundred times works), then: | ||
| + | ||
| +```bash | ||
| +curl http://localhost:8787/notes/groceries/snapshots | ||
| +curl http://localhost:8787/notes/groceries/snapshots/100 | ||
| +``` | ||
| + | ||
| +See [[snapshots]] for what is saved and when. | ||
| + | ||
| ## Watching the protocol | ||
| The browser's developer tools show the frames on the socket under the Network tab, on the | ||
| @@ -37,4 +49,4 @@ | ||
| ## Starting over | ||
| -Delete `.wrangler/state` to forget every note. | ||
| +Delete `.wrangler/state` to forget every note and its snapshots. | ||
Changed.rebasely/kb/index.md+2−0
| @@ -8,11 +8,13 @@ | ||
| - [[conflict-strategy]]: how two people typing at once end up with the same text. | ||
| - [[note-room]]: the Durable Object behind a note, its storage, and hibernation. | ||
| - [[wire-protocol]]: the messages on the socket. | ||
| +- [[snapshots]]: the copy of every note in R2 every 100 versions, and how to read them. | ||
| ## Decisions | ||
| - [[0001-single-sequencer-per-note]]: the room is the only place edits are ordered. | ||
| - [[0002-drop-inserts-inside-concurrent-deletes]]: the one rule that keeps the transform small. | ||
| +- [[0003-snapshots-in-r2]]: history lives in R2, not in the room. | ||
| ## Guides | ||
ChangedREADME.md+10−6
| @@ -18,7 +18,8 @@ | ||
| stays where it was while others type. | ||
| The room keeps the note and its last 200 operations in the Durable Object's SQLite database | ||
| -and accepts sockets with the Hibernation API. A note nobody is typing in is evicted from | ||
| +and accepts sockets with the Hibernation API. Every 100 versions it also saves a copy of the | ||
| +text to R2, so older versions can still be read. A note nobody is typing in is evicted from | ||
| memory without closing anyone's connection, and wakes up on the next keystroke. | ||
| ## Running it locally | ||
| @@ -36,11 +37,13 @@ | ||
| ## API | ||
| -| Request | Response | | ||
| -| ---------------------- | --------------------------------------------------------------- | | ||
| -| `GET /` | the editor page; the part after `#` is the note id | | ||
| -| `GET /notes/:id` | the note as JSON: `{ "id", "text", "version" }` | | ||
| -| `GET /notes/:id/ws` | a WebSocket to the note's room | | ||
| +| Request | Response | | ||
| +| ----------------------------------- | -------------------------------------------------------- | | ||
| +| `GET /` | the editor page; the part after `#` is the note id | | ||
| +| `GET /notes/:id` | the note as JSON: `{ "id", "text", "version" }` | | ||
| +| `GET /notes/:id/ws` | a WebSocket to the note's room | | ||
| +| `GET /notes/:id/snapshots` | the note's saved versions, oldest first; `?after=` pages | | ||
| +| `GET /notes/:id/snapshots/:version` | the note's text at that version, as plain text | | ||
| Note ids are 1 to 64 letters, digits, dashes or underscores. On the socket, the editor sends | ||
| @@ -72,6 +75,7 @@ | ||
| routes.ts path matching for the Worker | ||
| note-room.ts the Durable Object: sockets, hibernation, SQLite | ||
| room.ts the sequencer, with storage behind an interface | ||
| + snapshots.ts copies of the note in R2: keys, saving, listing | ||
| ops.ts insert, delete, transform, compose, diff | ||
| protocol.ts the socket messages and their validation | ||
| client/ | ||
Changedsrc/index.ts+23−4
| @@ -1,25 +1,44 @@ | ||
| // The live-notes Worker. It routes each note to its own NoteRoom by name, so every editor of | ||
| // "groceries" reaches the same object wherever they are. | ||
| // | ||
| -// GET /notes/:id the note as JSON: { id, text, version } | ||
| -// GET /notes/:id/ws upgrade to a WebSocket and edit the note (protocol.ts) | ||
| +// GET /notes/:id the note as JSON: { id, text, version } | ||
| +// GET /notes/:id/ws upgrade to a WebSocket and edit the note (protocol.ts) | ||
| +// GET /notes/:id/snapshots?after=n the note's saved snapshots, oldest first (snapshots.ts) | ||
| +// GET /notes/:id/snapshots/:version the note's text at that version, as text/plain | ||
| +// | ||
| +// Snapshots are read straight from R2, so looking at a note's history never wakes its room. | ||
| import type { NoteRoom } from "./note-room.ts"; | ||
| import { route } from "./routes.ts"; | ||
| +import { listSnapshots, readSnapshot } from "./snapshots.ts"; | ||
| export { NoteRoom } from "./note-room.ts"; | ||
| export interface Env { | ||
| NOTES: DurableObjectNamespace<NoteRoom>; | ||
| + SNAPSHOTS: R2Bucket; | ||
| } | ||
| export default { | ||
| async fetch(request, env): Promise<Response> { | ||
| - const r = route(new URL(request.url).pathname); | ||
| + const url = new URL(request.url); | ||
| + const r = route(url.pathname); | ||
| if (!r) return new Response("not found", { status: 404 }); | ||
| if (request.method !== "GET") return new Response("method not allowed", { status: 405, headers: { allow: "GET" } }); | ||
| - const room = env.NOTES.get(env.NOTES.idFromName(r.id)); | ||
| + const objectId = env.NOTES.idFromName(r.id); | ||
| + if (r.kind === "snapshots") { | ||
| + const after = Number(url.searchParams.get("after") ?? 0); | ||
| + if (!Number.isSafeInteger(after) || after < 0) return new Response("after is a version number", { status: 400 }); | ||
| + return Response.json({ id: r.id, ...(await listSnapshots(env.SNAPSHOTS, objectId.toString(), after)) }); | ||
| + } | ||
| + if (r.kind === "snapshot") { | ||
| + const text = await readSnapshot(env.SNAPSHOTS, objectId.toString(), r.version); | ||
| + if (text === null) return new Response("no snapshot of that version", { status: 404 }); | ||
| + return new Response(text, { headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "public, max-age=31536000, immutable" } }); | ||
| + } | ||
| + | ||
| + const room = env.NOTES.get(objectId); | ||
| if (r.kind === "socket") { | ||
| if (request.headers.get("Upgrade") !== "websocket") return new Response("expected a WebSocket upgrade", { status: 426 }); | ||
| return room.fetch(request); | ||
Changedsrc/note-room.ts+43−10
| @@ -5,15 +5,22 @@ | ||
| // keeps the connections open while the object is evicted, and wakes it with webSocketMessage | ||
| // when a frame arrives. Everything the room needs lives in SQLite, so the constructor below is | ||
| // also the wake-up path. | ||
| +// | ||
| +// Every SNAPSHOT_EVERY versions the room also copies the note's text to the SNAPSHOTS bucket | ||
| +// (snapshots.ts), after the editors have their replies. | ||
| import { DurableObject } from "cloudflare:workers"; | ||
| +import type { Env } from "./index.ts"; | ||
| import type { Op } from "./ops.ts"; | ||
| import { LOG_SIZE, Room, type Note, type NoteStore } from "./room.ts"; | ||
| +import { saveSnapshot } from "./snapshots.ts"; | ||
| -export class NoteRoom extends DurableObject { | ||
| +export class NoteRoom extends DurableObject<Env> { | ||
| #room: Room; | ||
| + // A snapshot is being written. Edits that arrive meanwhile don't start another one. | ||
| + #saving = false; | ||
| - constructor(ctx: DurableObjectState, env: Cloudflare.Env) { | ||
| + constructor(ctx: DurableObjectState, env: Env) { | ||
| super(ctx, env); | ||
| this.#room = new Room(new SqlNoteStore(ctx.storage)); | ||
| } | ||
| @@ -39,18 +46,35 @@ | ||
| } | ||
| const out = this.#room.receive(data); | ||
| ws.send(JSON.stringify(out.reply)); | ||
| - if (!out.broadcast) return; | ||
| - const frame = JSON.stringify(out.broadcast); | ||
| - for (const other of this.ctx.getWebSockets()) { | ||
| - if (other === ws) continue; | ||
| - try { | ||
| - other.send(frame); | ||
| - } catch { | ||
| - // The socket is closing; webSocketClose will follow. | ||
| + if (out.broadcast) { | ||
| + const frame = JSON.stringify(out.broadcast); | ||
| + for (const other of this.ctx.getWebSockets()) { | ||
| + if (other === ws) continue; | ||
| + try { | ||
| + other.send(frame); | ||
| + } catch { | ||
| + // The socket is closing; webSocketClose will follow. | ||
| + } | ||
| } | ||
| } | ||
| + if (out.saveSnapshot) await this.#snapshot(out.saveSnapshot); | ||
| } | ||
| + // Copies the note to R2. A failure is logged and the snapshot stays due, so the next edit | ||
| + // tries again; editing never waits on R2. | ||
| + async #snapshot(note: Note): Promise<void> { | ||
| + if (this.#saving) return; | ||
| + this.#saving = true; | ||
| + try { | ||
| + await saveSnapshot(this.env.SNAPSHOTS, this.ctx.id.toString(), note); | ||
| + this.#room.snapshotSaved(note.version); | ||
| + } catch (e) { | ||
| + console.error(JSON.stringify({ msg: "saving a snapshot failed", version: note.version, error: String(e) })); | ||
| + } finally { | ||
| + this.#saving = false; | ||
| + } | ||
| + } | ||
| + | ||
| async webSocketClose(ws: WebSocket, code: number): Promise<void> { | ||
| // 1005 and 1006 report that no close code was sent; they can't be sent back. | ||
| ws.close(code === 1005 || code === 1006 ? 1000 : code); | ||
| @@ -66,7 +90,16 @@ | ||
| storage.sql.exec(` | ||
| CREATE TABLE IF NOT EXISTS note (id INTEGER PRIMARY KEY CHECK (id = 1), text TEXT NOT NULL, version INTEGER NOT NULL); | ||
| CREATE TABLE IF NOT EXISTS ops (version INTEGER PRIMARY KEY, op TEXT NOT NULL); | ||
| + CREATE TABLE IF NOT EXISTS snapshot (id INTEGER PRIMARY KEY CHECK (id = 1), version INTEGER NOT NULL); | ||
| `); | ||
| + } | ||
| + | ||
| + lastSnapshot(): number { | ||
| + return this.#storage.sql.exec<{ version: number }>("SELECT version FROM snapshot WHERE id = 1").toArray()[0]?.version ?? 0; | ||
| + } | ||
| + | ||
| + snapshotSaved(version: number): void { | ||
| + this.#storage.sql.exec("INSERT INTO snapshot (id, version) VALUES (1, ?) ON CONFLICT (id) DO UPDATE SET version = excluded.version", version); | ||
| } | ||
| load(): Note { | ||
Changedsrc/room.ts+21−4
| @@ -16,6 +16,10 @@ | ||
| // snapshot, so it stays well under what a socket frame and a row comfortably hold. | ||
| export const MAX_LENGTH = 100_000; | ||
| +// How often the room copies the note to R2 (snapshots.ts): whenever it is this many versions | ||
| +// past the last copy that was saved. | ||
| +export const SNAPSHOT_EVERY = 100; | ||
| + | ||
| export type Note = { text: string; version: number }; | ||
| export interface NoteStore { | ||
| @@ -26,11 +30,15 @@ | ||
| // Saves the note at its new version together with the op that produced it, and trims the | ||
| // log to the last LOG_SIZE ops. Must be atomic. | ||
| commit(note: Note, op: Op): void; | ||
| + // The version of the last snapshot saved to R2, or 0 if there is none. | ||
| + lastSnapshot(): number; | ||
| + // Records that the snapshot of `version` is saved. | ||
| + snapshotSaved(version: number): void; | ||
| } | ||
| -// What to send after a message: `reply` goes back to the sender, `broadcast` to every other | ||
| -// editor of the note. | ||
| -export type Outcome = { reply: ServerMessage; broadcast?: ServerMessage }; | ||
| +// What to do after a message: `reply` goes back to the sender, `broadcast` to every other | ||
| +// editor of the note, and `saveSnapshot`, when set, is the note to copy to R2. | ||
| +export type Outcome = { reply: ServerMessage; broadcast?: ServerMessage; saveSnapshot?: Note }; | ||
| export class Room { | ||
| #store: NoteStore; | ||
| @@ -73,6 +81,15 @@ | ||
| const note = { text: next, version: version + 1 }; | ||
| this.#store.commit(note, op); | ||
| this.#note = note; | ||
| - return { reply: { type: "ack", version: note.version }, broadcast: { type: "op", version: note.version, op } }; | ||
| + const out: Outcome = { reply: { type: "ack", version: note.version }, broadcast: { type: "op", version: note.version, op } }; | ||
| + // Due until a save is recorded, so a snapshot that failed to save is tried again on the next | ||
| + // edit rather than skipped. | ||
| + if (note.version - this.#store.lastSnapshot() >= SNAPSHOT_EVERY) out.saveSnapshot = note; | ||
src/room.ts line 87
| ||
| + return out; | ||
| + } | ||
| + | ||
| + // NoteRoom calls this once the snapshot of `version` is in R2. | ||
| + snapshotSaved(version: number): void { | ||
| + if (version > this.#store.lastSnapshot()) this.#store.snapshotSaved(version); | ||
| } | ||
| } | ||
Changedsrc/routes.ts+11−3
| @@ -1,12 +1,20 @@ | ||
| // The Worker's routes, kept apart from index.ts so they can be tested without the runtime. | ||
| -export type Route = { kind: "note"; id: string } | { kind: "socket"; id: string } | null; | ||
| +export type Route = | ||
| + | { kind: "note"; id: string } | ||
| + | { kind: "socket"; id: string } | ||
| + | { kind: "snapshots"; id: string } | ||
| + | { kind: "snapshot"; id: string; version: number } | ||
| + | null; | ||
| // Note ids are what people put in a link: letters, digits, dashes and underscores. | ||
| -const NOTE = /^\/notes\/([A-Za-z0-9_-]{1,64})(\/ws)?$/; | ||
| +const NOTE = /^\/notes\/([A-Za-z0-9_-]{1,64})(?:\/(ws|snapshots)(?:\/([1-9][0-9]{0,11}))?)?$/; | ||
| export function route(pathname: string): Route { | ||
| const m = NOTE.exec(pathname); | ||
| if (!m) return null; | ||
| - return m[2] ? { kind: "socket", id: m[1] } : { kind: "note", id: m[1] }; | ||
| + const [, id, part, version] = m; | ||
| + if (!part) return { kind: "note", id }; | ||
| + if (part === "ws") return version ? null : { kind: "socket", id }; | ||
| + return version ? { kind: "snapshot", id, version: Number(version) } : { kind: "snapshots", id }; | ||
| } | ||
Addedsrc/snapshots.ts+43−0
| @@ -0,0 +1,43 @@ | ||
| +// Copies of a note's text in R2, saved by its room every SNAPSHOT_EVERY versions (room.ts). The | ||
| +// room's own SQLite holds only the latest text and the last LOG_SIZE ops; these let anyone read | ||
| +// what the note said further back, without waking the room. | ||
| +// | ||
| +// Keys are snapshots/<object id>/<version>.txt. The object id is the room's | ||
| +// idFromName(note id), which the Worker computes the same way, so it can list and read a note's | ||
| +// snapshots straight from the bucket. Versions are zero-padded so keys list in version order. | ||
| + | ||
| +import type { Note } from "./room.ts"; | ||
| + | ||
| +export type SnapshotInfo = { version: number; saved_at: string; size: number }; | ||
| +export type SnapshotPage = { snapshots: SnapshotInfo[]; next: number | null }; | ||
| + | ||
| +export const PAGE = 100; | ||
| +const DIGITS = 12; | ||
| + | ||
| +export function snapshotKey(objectId: string, version: number): string { | ||
| + return `snapshots/${objectId}/${String(version).padStart(DIGITS, "0")}.txt`; | ||
| +} | ||
| + | ||
| +export async function saveSnapshot(bucket: R2Bucket, objectId: string, note: Note): Promise<void> { | ||
| + await bucket.put(snapshotKey(objectId, note.version), note.text, { | ||
| + httpMetadata: { contentType: "text/plain; charset=utf-8" }, | ||
| + }); | ||
| +} | ||
| + | ||
| +// A note's snapshots in version order, PAGE at a time, starting after version `after`. | ||
| +export async function listSnapshots(bucket: R2Bucket, objectId: string, after = 0): Promise<SnapshotPage> { | ||
| + const prefix = `snapshots/${objectId}/`; | ||
| + const page = await bucket.list({ prefix, startAfter: snapshotKey(objectId, after), limit: PAGE }); | ||
| + const snapshots = page.objects.map((o) => ({ | ||
| + version: Number(o.key.slice(prefix.length, -".txt".length)), | ||
| + saved_at: o.uploaded.toISOString(), | ||
| + size: o.size, | ||
| + })); | ||
| + return { snapshots, next: page.truncated ? (snapshots.at(-1)?.version ?? null) : null }; | ||
| +} | ||
| + | ||
| +// The note's text at `version`, or null when there is no snapshot of that version. | ||
| +export async function readSnapshot(bucket: R2Bucket, objectId: string, version: number): Promise<string | null> { | ||
| + const object = await bucket.get(snapshotKey(objectId, version)); | ||
| + return object ? object.text() : null; | ||
| +} | ||
Addedtest/helpers/memory-bucket.ts+37−0
| @@ -0,0 +1,37 @@ | ||
| +// The part of an R2 bucket snapshots.ts uses (put, get and list with prefix, startAfter and | ||
| +// limit), in memory. Keys list in byte order, as they do in R2. | ||
| + | ||
| +type Stored = { text: string; uploaded: Date }; | ||
| + | ||
| +export class MemoryBucket { | ||
| + objects = new Map<string, Stored>(); | ||
| + failNext = false; | ||
| + #clock: () => Date; | ||
| + | ||
| + constructor(clock: () => Date = () => new Date()) { | ||
| + this.#clock = clock; | ||
| + } | ||
| + | ||
| + async put(key: string, value: string): Promise<void> { | ||
| + if (this.failNext) { | ||
| + this.failNext = false; | ||
| + throw new Error("R2 put failed: 503 Service Unavailable"); | ||
| + } | ||
| + this.objects.set(key, { text: value, uploaded: this.#clock() }); | ||
| + } | ||
| + | ||
| + async get(key: string) { | ||
| + const o = this.objects.get(key); | ||
| + return o ? { text: async () => o.text } : null; | ||
| + } | ||
| + | ||
| + async list({ prefix = "", startAfter = "", limit = 1000 }: { prefix?: string; startAfter?: string; limit?: number }) { | ||
| + const keys = [...this.objects.keys()].filter((k) => k.startsWith(prefix) && k > startAfter).sort(); | ||
| + const objects = keys.slice(0, limit).map((key) => ({ key, size: new TextEncoder().encode(this.objects.get(key)!.text).length, uploaded: this.objects.get(key)!.uploaded })); | ||
| + return { objects, truncated: keys.length > limit }; | ||
| + } | ||
| +} | ||
| + | ||
| +export function memoryBucket(clock?: () => Date): MemoryBucket & R2Bucket { | ||
| + return new MemoryBucket(clock) as MemoryBucket & R2Bucket; | ||
| +} | ||
Changedtest/helpers/memory-store.ts+9−0
| @@ -5,6 +5,7 @@ | ||
| export class MemoryStore implements NoteStore { | ||
| note: Note; | ||
| log: { version: number; op: Op }[] = []; | ||
| + snapshot = 0; | ||
| constructor(note: Note = { text: "", version: 0 }) { | ||
| this.note = note; | ||
| @@ -22,5 +23,13 @@ | ||
| this.note = { ...note }; | ||
| this.log.push({ version: note.version, op }); | ||
| this.log = this.log.filter((e) => e.version > note.version - LOG_SIZE); | ||
| + } | ||
| + | ||
| + lastSnapshot(): number { | ||
| + return this.snapshot; | ||
| + } | ||
| + | ||
| + snapshotSaved(version: number): void { | ||
| + this.snapshot = version; | ||
| } | ||
| } | ||
Changedtest/routes.test.ts+9−1
| @@ -7,8 +7,16 @@ | ||
| assert.deepEqual(route("/notes/team_standup-42/ws"), { kind: "socket", id: "team_standup-42" }); | ||
| }); | ||
| +test("routes a note's snapshots and one snapshot by version", () => { | ||
| + assert.deepEqual(route("/notes/groceries/snapshots"), { kind: "snapshots", id: "groceries" }); | ||
| + assert.deepEqual(route("/notes/groceries/snapshots/300"), { kind: "snapshot", id: "groceries", version: 300 }); | ||
| +}); | ||
| + | ||
| test("refuses other paths and odd ids", () => { | ||
| - for (const p of ["/", "/notes", "/notes/", "/notes/a/b", "/notes/a%20b", "/notes/../x", `/notes/${"a".repeat(65)}`, "/notes/a/ws/x"]) { | ||
| + for (const p of [ | ||
| + "/", "/notes", "/notes/", "/notes/a/b", "/notes/a%20b", "/notes/../x", `/notes/${"a".repeat(65)}`, "/notes/a/ws/x", | ||
| + "/notes/a/ws/100", "/notes/a/snapshots/0", "/notes/a/snapshots/007", "/notes/a/snapshots/1e3", "/notes/a/snapshots/", `/notes/a/snapshots/${"9".repeat(13)}`, | ||
| + ]) { | ||
| assert.equal(route(p), null, p); | ||
| } | ||
| }); | ||
Addedtest/snapshots.test.ts+88−0
| @@ -0,0 +1,88 @@ | ||
| +import assert from "node:assert/strict"; | ||
| +import { describe, test } from "node:test"; | ||
| +import { insert, type Op } from "../src/ops.ts"; | ||
| +import { Room, SNAPSHOT_EVERY } from "../src/room.ts"; | ||
| +import { PAGE, listSnapshots, readSnapshot, saveSnapshot, snapshotKey } from "../src/snapshots.ts"; | ||
| +import { memoryBucket } from "./helpers/memory-bucket.ts"; | ||
| +import { MemoryStore } from "./helpers/memory-store.ts"; | ||
| + | ||
| +const send = (base: number, op: Op) => JSON.stringify({ type: "op", base, op }); | ||
| +const ID = "a1b2c3"; | ||
| + | ||
| +describe("when the room asks for a snapshot", () => { | ||
| + test("every SNAPSHOT_EVERY versions, with the note as it is at that version", () => { | ||
| + const room = new Room(new MemoryStore()); | ||
| + for (let v = 0; v < SNAPSHOT_EVERY - 1; v++) assert.equal(room.receive(send(v, insert(v, "x"))).saveSnapshot, undefined); | ||
| + const due = room.receive(send(SNAPSHOT_EVERY - 1, insert(0, "y"))); | ||
| + assert.deepEqual(due.saveSnapshot, { text: "y" + "x".repeat(SNAPSHOT_EVERY - 1), version: SNAPSHOT_EVERY }); | ||
| + // The reply and the broadcast are the same as for any other edit. | ||
| + assert.deepEqual(due.reply, { type: "ack", version: SNAPSHOT_EVERY }); | ||
| + assert.equal(due.broadcast?.type, "op"); | ||
| + }); | ||
| + | ||
| + test("not again until another SNAPSHOT_EVERY versions after a recorded save", () => { | ||
| + const store = new MemoryStore({ text: "", version: SNAPSHOT_EVERY - 1 }); | ||
| + const room = new Room(store); | ||
| + room.snapshotSaved(room.receive(send(SNAPSHOT_EVERY - 1, insert(0, "a"))).saveSnapshot!.version); | ||
| + assert.equal(store.snapshot, SNAPSHOT_EVERY); | ||
| + assert.equal(room.receive(send(SNAPSHOT_EVERY, insert(0, "b"))).saveSnapshot, undefined); | ||
| + }); | ||
| + | ||
| + test("on the next edit again when a save was never recorded", () => { | ||
| + const room = new Room(new MemoryStore({ text: "", version: SNAPSHOT_EVERY - 1 })); | ||
| + assert.equal(room.receive(send(SNAPSHOT_EVERY - 1, insert(0, "a"))).saveSnapshot?.version, SNAPSHOT_EVERY); | ||
| + assert.equal(room.receive(send(SNAPSHOT_EVERY, insert(0, "b"))).saveSnapshot?.version, SNAPSHOT_EVERY + 1); | ||
| + }); | ||
| + | ||
| + test("never for an edit that changed nothing or was refused", () => { | ||
| + const room = new Room(new MemoryStore({ text: "abc", version: 2 * SNAPSHOT_EVERY })); | ||
| + assert.equal(room.receive(send(2 * SNAPSHOT_EVERY, insert(0, ""))).saveSnapshot, undefined); | ||
| + assert.equal(room.receive(send(2 * SNAPSHOT_EVERY, insert(9, "x"))).saveSnapshot, undefined); | ||
| + }); | ||
| + | ||
| + test("a recorded save survives the room waking from hibernation", () => { | ||
| + const store = new MemoryStore({ text: "", version: SNAPSHOT_EVERY - 1 }); | ||
| + const room = new Room(store); | ||
| + room.snapshotSaved(room.receive(send(SNAPSHOT_EVERY - 1, insert(0, "a"))).saveSnapshot!.version); | ||
| + const woken = new Room(store); | ||
| + assert.equal(woken.receive(send(SNAPSHOT_EVERY, insert(0, "b"))).saveSnapshot, undefined); | ||
| + }); | ||
| + | ||
| + test("an older save never moves the recorded version back", () => { | ||
| + const store = new MemoryStore(); | ||
| + const room = new Room(store); | ||
| + room.snapshotSaved(300); | ||
| + room.snapshotSaved(200); | ||
| + assert.equal(store.snapshot, 300); | ||
| + }); | ||
| +}); | ||
| + | ||
| +describe("snapshots in R2", () => { | ||
| + test("keys sort in version order", () => { | ||
| + assert.equal(snapshotKey(ID, 100), "snapshots/a1b2c3/000000000100.txt"); | ||
| + assert.ok(snapshotKey(ID, 900) < snapshotKey(ID, 1000)); | ||
| + }); | ||
| + | ||
| + test("saves a note and reads it back by version", async () => { | ||
| + const bucket = memoryBucket(); | ||
| + await saveSnapshot(bucket, ID, { text: "milk\neggs\n", version: 100 }); | ||
| + assert.equal(await readSnapshot(bucket, ID, 100), "milk\neggs\n"); | ||
| + assert.equal(await readSnapshot(bucket, ID, 200), null); | ||
| + assert.equal(await readSnapshot(bucket, "another-note", 100), null); | ||
| + }); | ||
| + | ||
| + test("lists a note's snapshots oldest first, a page at a time", async () => { | ||
| + const bucket = memoryBucket(() => new Date("2026-10-15T09:00:00Z")); | ||
| + for (let v = 1; v <= PAGE + 2; v++) await saveSnapshot(bucket, ID, { text: "é".repeat(v), version: v * SNAPSHOT_EVERY }); | ||
| + await saveSnapshot(bucket, "another-note", { text: "", version: SNAPSHOT_EVERY }); | ||
| + | ||
| + const first = await listSnapshots(bucket, ID); | ||
| + assert.equal(first.snapshots.length, PAGE); | ||
| + assert.deepEqual(first.snapshots[0], { version: SNAPSHOT_EVERY, saved_at: "2026-10-15T09:00:00.000Z", size: 2 }); | ||
| + assert.equal(first.next, PAGE * SNAPSHOT_EVERY); | ||
| + | ||
| + const second = await listSnapshots(bucket, ID, first.next!); | ||
| + assert.deepEqual(second.snapshots.map((s) => s.version), [(PAGE + 1) * SNAPSHOT_EVERY, (PAGE + 2) * SNAPSHOT_EVERY]); | ||
| + assert.equal(second.next, null); | ||
| + }); | ||
| +}); | ||
Changedwrangler.jsonc+5−2
| @@ -1,5 +1,5 @@ | ||
| -// live-notes: one Worker, and one NoteRoom Durable Object per note. The editor page is a | ||
| -// static asset; `npm run build` compiles its script into public/js first. | ||
| +// live-notes: one Worker, one NoteRoom Durable Object per note, and an R2 bucket of snapshots. | ||
| +// The editor page is a static asset; `npm run build` compiles its script into public/js first. | ||
| { | ||
| "$schema": "node_modules/wrangler/config-schema.json", | ||
| "name": "live-notes", | ||
| @@ -8,6 +8,9 @@ | ||
| "observability": { "enabled": true }, | ||
| "build": { "command": "npm run build", "watch_dir": ["client", "src"] }, | ||
| "assets": { "directory": "public" }, | ||
| + // Copies of each note every 100 versions (src/snapshots.ts). Create it once with | ||
| + // `npx wrangler r2 bucket create live-notes-snapshots`. | ||
| + "r2_buckets": [{ "binding": "SNAPSHOTS", "bucket_name": "live-notes-snapshots" }], | ||
| "durable_objects": { | ||
| "bindings": [{ "name": "NOTES", "class_name": "NoteRoom" }] | ||
| }, | ||
View editing
1 component added, 1 changed, 1 connection added
- Added
- Changed
- Removed
What takes part in an edit, from the browser to the room and back, and where the room keeps copies.
The view editing at the head of this pull request, with what it adds, changes and removes from the merge base d21dfdd. Select a component for what changed in it.
ops
Insert and delete operations, their transform, and the messages on the socket. The same code runs in the room and in the browser.
Not changed by this pull request.
Takes part in An edit reaching other editors.
Changes
Knowledge base
- Conflict strategy Changedconcepts/conflict-strategy.md · concept
- The note room Changedconcepts/note-room.md · concept
- Snapshots in R2 Addedconcepts/snapshots.md · concept
- 0003 Snapshots of every note in R2, every 100 versions Addeddecisions/0003-snapshots-in-r2.md · decision
- Running it locally Changedguides/local-dev.md · guide
- live-notes Changedindex.md · index