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" }] | ||
| }, | ||
Loading a note
Not changed by this pull request.
- Added
- Rerouted, relabelled or moved
- Removed
Someone opens /#groceries. The page connects to the note's room and gets its text.
The flow load-note at the head of this pull request, numbered in its order, with the steps it adds, reroutes, relabels, moves and removes. A removed step has no number.
Steps
- Step 1: editor-a → api GET / (the editor page and its script, from static assets)
- Step 2: editor-a → api GET /notes/groceries/ws, Upgrade: websocket
- Step 3: api → note-room forward the upgrade to the room for idFromName("groceries")
- Step 4: note-room → editor-a 101 Switching Protocols, socket accepted for hibernation
- Step 5: note-room → editor-a snapshot: the note's text and version
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