Rebasely Beta: data may be purged

exampleslive-notes Public

Save a snapshot of each note to R2 every 100 versions #2

Changed files

21 files changed470 additions41 deletionssince main at d21dfdd

  1. Changed.rebasely/architecture/flows/edit-broadcast.yaml+4−1
  2. Added.rebasely/architecture/flows/reading-history.yaml+13−0
  3. Changed.rebasely/architecture/system.yaml+16−3
  4. Changed.rebasely/architecture/views/editing.yaml+2−2
  5. Changed.rebasely/kb/concepts/conflict-strategy.md+5−1
  6. Changed.rebasely/kb/concepts/note-room.md+13−2
  7. Added.rebasely/kb/concepts/snapshots.md+65−0
  8. Added.rebasely/kb/decisions/0003-snapshots-in-r2.md+37−0
  9. Changed.rebasely/kb/guides/local-dev.md+14−2
  10. Changed.rebasely/kb/index.md+2−0
  11. ChangedREADME.md+10−6
  12. Changedsrc/index.ts+23−4
  13. Changedsrc/note-room.ts+43−10
  14. Changedsrc/room.ts+21−4
  15. Changedsrc/routes.ts+11−3
  16. Addedsrc/snapshots.ts+43−0
  17. Addedtest/helpers/memory-bucket.ts+37−0
  18. Changedtest/helpers/memory-store.ts+9−0
  19. Changedtest/routes.test.ts+9−1
  20. Addedtest/snapshots.test.ts+88−0
  21. Changedwrangler.jsonc+5−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" }
View file
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" }
View file
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.
View file
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]
View file
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.
View file
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.
View file
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`).
View file
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.
View file
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.
View file
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
View file
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/
View file
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);
View file
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 {
View file
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
  1. Justin Torre

    Thinking through an R2 outage: once a note is due, every edit tries a put until one works. The #saving flag in NoteRoom keeps that to one request at a time per room, so it is bounded by how fast people type. I am fine with that. If we ever see a long outage in the logs, a backoff on the recorded failure time would be a small change here.

+ 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);
}
}
View file
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 };
}
View file
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;
+}
View file
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;
+}
View file
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;
}
}
View file
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);
}
});
View file
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);
+ });
+});
View file
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 file

Back to the conversation