edytor 0.1.0-next.23 → 0.1.0-next.25

package/README.md

@@ -15,7 +15,7 @@
 
 Edytor aims to be for Svelte what Slate.js is for React: a heavily customizable editor with an API to build any kind of collaborative rich text editor.
 
-> **Work in progress.** Edytor is a pre-release (`0.1.0-next.23`, `edytor@next` on npm) and not ready for production; the API changes between releases without a compatibility layer. The untagged `edytor@0.0.11` on npm predates the current API. Issues and PRs are welcome: when you report a bug, include the document's JSON value.
+> **Work in progress.** Edytor is a pre-release (`0.1.0-next.25`, `edytor@next` on npm) and not ready for production; the API changes between releases without a compatibility layer. The untagged `edytor@0.0.11` on npm predates the current API. Issues and PRs are welcome: when you report a bug, include the document's JSON value.
 
 ## Features
 

package/dist/cloudflare/DocumentRoom.d.ts

@@ -95,6 +95,8 @@
  */
 import { DurableObject } from 'cloudflare:workers';
 import * as E from '../crdt/index.js';
+import type { PurgeReport } from '../crdt/purge.js';
+import { type HistoryEntry, type HistoryOptions, type KVLike } from './history.js';
 import type { AwarenessEntry, DocumentSemanticsConfig, EdytorDoc, JSONBlock, JSONDoc, YDoc } from '../crdt/index.js';
 /** Under SQLite-backed Durable Objects' 2 MB row cap, with room for the other columns. */
 export declare const DEFAULT_MAX_ROW_BYTES: number;
@@ -135,6 +137,16 @@ export type ReplicaOwner = {
     replica: number;
     user: string;
 };
+/** What `restoreHistory` did (`room.history.restore`): `refused` when the room holds no such version. */
+export type RestoreResult = {
+    status: 'applied' | 'noop' | 'refused';
+    key: string;
+    revived?: number;
+    moved?: number;
+    rewritten?: number;
+    created?: number;
+    deleted?: number;
+};
 /** The document as `onSave` receives it. */
 export type SavedDocument = {
     /** The document as JSON. */
@@ -154,6 +166,14 @@ export type LoadedDocument = JSONDoc | Uint8Array | Pick<SavedDocument, 'update'
 export declare const PROBE_HEADER = "X-Edytor-Probe";
 /** The transaction origin of the room's own edits (`transact`, `onLoad` seeds). */
 export declare const ROOM_ORIGIN: unique symbol;
+/** The transaction origin of a history restore (H11): the room's restore history tracks it. */
+export declare const RESTORE_ORIGIN: unique symbol;
+/** The transaction origin of the room's purge (H7): tracked by no history. */
+export declare const PURGE_ORIGIN: unique symbol;
+/** The header `routeDocumentHistory` sets on an authorized history request (H11). */
+export declare const HISTORY_HEADER = "X-Edytor-History";
+/** The version key of a history `read` or `restore` request. */
+export declare const HISTORY_KEY_HEADER = "X-Edytor-History-Key";
 /**
  * Headers carrying the identity `routeDocumentSocket` verified — never the
  * client's. The user id is percent-encoded (`encodeURIComponent`): a header
@@ -179,6 +199,17 @@ export type DocumentRoomEnv = {
     EDYTOR_MAX_UPDATES_PER_SECOND?: string | number;
     /** `off`: the room logs nothing (default: one JSON line per compaction, quota hit, denial, fault). */
     EDYTOR_LOG?: string;
+    /**
+     * Days after which deleted content is purged (H7; default: the history
+     * retention, else 30); `off` never purges.
+     */
+    EDYTOR_PURGE_AFTER_DAYS?: string | number;
+    /** A KV namespace binding: the room keeps its version history there (H11, `history()`). */
+    EDYTOR_HISTORY?: KVLike;
+    /** Days a version is kept (default 30). */
+    EDYTOR_HISTORY_RETENTION_DAYS?: string | number;
+    /** The IANA time zone of the history's half-day slots (default `UTC`). */
+    EDYTOR_HISTORY_TIME_ZONE?: string;
 };
 /** What a socket is bound to: its verified user, its replica (Yjs client id), its access. */
 export type SocketIdentity = {
@@ -192,7 +223,7 @@ export type Attachment = SocketIdentity & {
     clock: number | null;
 };
 export type Refusal = {
-    reason: 'generation' | 'schema' | 'malformed' | 'container' | 'identity' | 'replica' | 'read-only' | 'waiting' | 'storage' | 'internal' | 'quota' | 'mark' | 'denied' | 'orphan' | 'relayed';
+    reason: 'generation' | 'schema' | 'malformed' | 'container' | 'identity' | 'replica' | 'read-only' | 'waiting' | 'storage' | 'internal' | 'quota' | 'mark' | 'denied' | 'orphan' | 'relayed' | 'history';
     detail: unknown;
 };
 /** A duration series: how many, their total and longest (ms; see {@link RoomMetrics}). */
@@ -239,6 +270,17 @@ export type RoomMetrics = {
     validationDenials: number;
     /** Every refusal, by reason (as `refusalCounts`). */
     refusals: Partial<Record<Refusal['reason'], number>>;
+    /** Versions written to the history (H11), skipped (`history` refusals), and the last key written. */
+    history: {
+        written: number;
+        skipped: number;
+        lastKey: string | null;
+    };
+    /** Purges run (H7) and what they wrote, summed; the last horizon purged (ms since the epoch). */
+    purge: PurgeReport & {
+        runs: number;
+        horizon: number | null;
+    };
     /** When this instance started (ms since the epoch). */
     since: number;
 };
@@ -250,6 +292,20 @@ export type RoomLogEntry = {
     records: number;
     rows: number;
 } | {
+    edytor: 'history';
+    key: string;
+    bytes: number;
+    editors: number;
+} | {
+    edytor: 'restore';
+    key: string;
+    user: string | null;
+    undo: boolean;
+} | ({
+    edytor: 'purge';
+    horizon: number;
+    bytes: number;
+} & PurgeReport) | {
     edytor: 'quota';
     user: string;
     quota: string;
@@ -261,6 +317,12 @@ export type RoomLogEntry = {
     edytor: 'fault';
     reason: 'storage' | 'internal';
     detail: string;
+} | {
+    edytor: 'convert';
+    from: number;
+    to: number;
+    blocks: number;
+    bytes: number;
 };
 /** `pending`: deletes of items the room does not hold yet (they wait for them). */
 type RowKind = 'generation' | 'update' | 'snapshot' | 'pending';
@@ -375,6 +437,22 @@ export type AttachDocumentOptions = {
      * {@link E.defaultSemantics} (the bundled rich-text, code and image kinds).
      */
     semantics?: DocumentSemanticsConfig;
+    /**
+     * Version history in KV (H11, `room.history.*`): the room writes its
+     * state twice a day — the morning's at local noon, the evening's at
+     * midnight, in `timeZone` — when it changed, for `retentionDays`; read
+     * and restore them with `listHistory`, `readHistory`, `restoreHistory`
+     * and `undoRestore` (or `routeDocumentHistory`). Without it, no history.
+     */
+    history?: HistoryOptions;
+    /**
+     * Days after which deleted content is purged from the room and every
+     * replica (H7, `room.purge.*`): default the history's `retentionDays`,
+     * else 30; `false` never purges.
+     */
+    purgeAfterDays?: number | false;
+    /** The room's clock, ms since the epoch (default `Date.now`): its slots, epochs and alarm read it. */
+    now?: () => number;
 };
 /** The tag of the document's sockets: other sockets of the object are left to you. */
 export declare const SOCKET_TAG = "edytor";
@@ -409,6 +487,10 @@ export declare class AttachedDocument {
     } | {
         kind: 'restored';
         records: number;
+    } | {
+        kind: 'converted';
+        from: number;
+        records: number;
     };
     private nextRecord;
     private updates;
@@ -442,14 +524,33 @@ export declare class AttachedDocument {
     private retryable;
     private readonly sql;
     private _facade;
-    private saveScheduled;
     /** Alarms in a row that found the rows unreadable: each re-arms later. */
     private saveRetries;
+    /** Each alarm task's due time (`room.alarm.tasks`), mirrored in the meta table (`due.<task>`). */
+    private dues;
+    /** The alarm this instance set, or found set at its start (`null`: none). */
+    private armed;
+    /** The room's clock (`now`). */
+    private readonly clock;
+    /** The verified users the open slot recorded (memory: a wake records them again, `OR IGNORE`). */
+    private readonly slotEditors;
+    /** Who the room writes for while a restore or its undo runs (the slot's editor). */
+    private writer;
+    /** The last restore's step (`room.history.undo`), read from the `restore` table at load. */
+    private restoreStep;
+    /** The history recording restores (`RESTORE_ORIGIN`), on the live facade. */
+    private restoreManager;
+    /** The version writes in flight (`historyWritten()`). */
+    private writing;
     private readonly options;
     private readonly rowsTable;
     private readonly replicasTable;
     private readonly metaTable;
+    private readonly epochsTable;
+    private readonly editorsTable;
+    private readonly restoreTable;
     private _lookups;
+    private _history;
     constructor(ctx: DurableObjectState, options?: AttachDocumentOptions);
     /**
      * Restore from storage, or seed from `onLoad`. Never throws: a throw
@@ -508,15 +609,33 @@ export declare class AttachedDocument {
     /** The document as JSON. */
     read(): JSONDoc;
     /**
-     * Runs `onSave` — the object's alarm, `saveAfter` ms after the first
-     * unsaved change. While the rows cannot be read (a retryable failure),
-     * it starts the room again; if that fails too, the save stays due: the
-     * alarm is set again, later at each failure (up to 5 minutes), so the
-     * mirror never silently lags what the room stored.
+     * The room's one alarm (`room.alarm.tasks`): every task due at its time
+     * runs — the history slot (`room.history.slots`), `onSave`, the purge
+     * (`room.purge.timing`) — each re-arming itself or clearing its due
+     * row; then the alarm is set to the earliest due time left. While the
+     * rows cannot be read (a retryable failure), it starts the room again;
+     * if that fails too, the save stays due, later at each failure (up to 5
+     * minutes), so the mirror never silently lags what the room stored. A
+     * throw from `onSave` keeps it due and is rethrown (the platform retries).
      */
     alarm(): Promise<void>;
-    /** The first unsaved change arms the save alarm; a wake keeps one already armed (`start`). */
+    /** The `save` task: `onSave` with the document, or the save kept due while the rows cannot be read. */
+    private save;
+    /** The first unsaved change arms the save alarm; a save already due keeps its time. */
     private scheduleSave;
+    /**
+     * Arm `task` at `at` (`room.alarm.tasks`): a task already due keeps its
+     * time (a wake or an edit never moves a pending save), unless `earlier`
+     * (an earlier time wins: the purge tick) or `replace`. The due time is
+     * stored (meta `due.<task>`) and the alarm set to the earliest one.
+     */
+    private schedule;
+    /** Clear `task`'s due time. */
+    private unschedule;
+    /** Set the alarm to the earliest due time (none due: the alarm set is left, and finds nothing). */
+    private arm;
+    /** The due times stored (`due.<task>`); an alarm armed by 0.1.0-next.23 (none stored) is a due save. */
+    private readDues;
     /**
      * Generation cutover: drop the stored document (both tables) of a room
      * whose storage belongs to another edytor generation, and start again
@@ -542,6 +661,18 @@ export declare class AttachedDocument {
      * engine refuses) is refused for good.
      */
     private load;
+    /**
+     * The generation cutover at load (`room.generation.convert`): the
+     * records of a generation-4 container are read as JSON
+     * (`crdt.generations.previousJSON`), which this generation seeds as
+     * `onLoad`'s JSON is (deterministic: every replica converting the same
+     * state writes the same update), and the container is replaced by it in
+     * one storage transaction: rows, replicas, purge epochs, slot editors
+     * and the stored restore go; the document data, the alarm's due tasks
+     * and `lastUpdated` stay. What a generation-4 client never sent is not
+     * in it; history, attribution and CRDT identity do not cross.
+     */
+    private convert;
     /** The bytes of the stored `pending` records (uncompressed, as every record but a snapshot). */
     private pendingBytes;
     /**
@@ -600,6 +731,93 @@ export declare class AttachedDocument {
      * (`GET <room>?lastUpdated`), also over RPC.
      */
     lastUpdated(): number | null;
+    /** The room's id: its name (`getByName`), else the object's id. */
+    private get roomId();
+    /** The history settings, resolved at first use (`null`: none; an unknown time zone is noted `history`). */
+    private get historyConfig();
+    /** Days after which deleted content is purged (`null`: never), `room.purge.timing`. */
+    private get purgeDays();
+    /** The last restore's deleted content, kept for its undo (`prepareRoomDoc`). */
+    private get restoreKeep();
+    /** The verified user a stored change is written for (a socket's, or the restorer's), or `null`. */
+    private editorOf;
+    /**
+     * A change was stored: arm the purge tick (`room.purge.timing`) and open
+     * the history slot it falls in (`room.history.slots`) — a purge opens
+     * none: it changes nothing a reader sees.
+     */
+    private noteChange;
+    /** Before a write: a slot past its end is captured as it is, and written (`room.history.slots`). */
+    private closeSlotIfPast;
+    /** Close the open slot: capture it now, write it (the alarm, a start past its end). */
+    private closeSlot;
+    /**
+     * The open slot's version, read now (synchronous: nothing writes
+     * between the read and the slot's close), and the slot closed.
+     */
+    private captureSlot;
+    /** Write a captured version (`room.history.value`); a failure is noted `history` and the slot skipped. */
+    private putSlot;
+    private skipVersion;
+    /** The history settings, or a throw: the room keeps no history. */
+    private requireHistory;
+    /**
+     * Resolves once the versions the room is writing are stored (a slot a
+     * write closed is written in the background).
+     */
+    historyWritten(): Promise<void>;
+    /**
+     * The room's versions, newest first (H11): one per half-day slot that
+     * changed, for the retention (`room.history.slots`). Throws when the
+     * room keeps no history.
+     */
+    listHistory(): Promise<HistoryEntry[]>;
+    /** Version `key` as JSON (a preview), or `null` when this room holds no such version. */
+    readHistory(key: string): Promise<JSONDoc | null>;
+    /**
+     * Restore version `key` as a forward edit (`room.history.restore`): one
+     * room transaction makes the visible document equal the version, keeping
+     * every id the registry holds and writing only what differs; stored,
+     * relayed to every socket, one step `undoRestore` undoes. `user` (the
+     * restorer) is recorded as the slot's editor and in the log. `refused`:
+     * this room holds no such version (expired, another room's key).
+     */
+    restoreHistory(key: string, options?: {
+        user?: string;
+    }): Promise<RestoreResult>;
+    /**
+     * Undo the last restore (`room.history.undo`): the history undo of
+     * exactly its transaction, edits made since kept. One level: `noop` when
+     * no restore stands (none, undone already, or past the purge horizon).
+     */
+    undoRestore(options?: {
+        user?: string;
+    }): Promise<{
+        status: 'applied' | 'noop';
+    }>;
+    /** The history recording restores, on the live facade (`RESTORE_ORIGIN` only, one step each). */
+    private restoreHistoryOf;
+    /** The last restore's step, from its table (`null`: none). */
+    private readRestore;
+    /**
+     * Forget the last restore's step: its table row goes, then what it kept
+     * is released and collected (the next compaction stores it collected).
+     */
+    private dropRestore;
+    /**
+     * The purge task, also over RPC (`room.purge.timing`): record an epoch
+     * (the state vector, now) when the document changed since the last one,
+     * purge what was deleted before the horizon — the newest epoch at least
+     * `purgeAfterDays` old — when it is newer than the last purged, and
+     * re-arm for the next epoch to pass it. Returns what the purge wrote, or
+     * `null` when nothing was past the horizon.
+     */
+    purge(): (PurgeReport & {
+        horizon: number;
+    }) | null;
+    private tick;
+    /** Purge what was deleted before `horizon`, as the room's own transaction, then compact. */
+    private purgeTo;
     /** The room's counters (H14), also over RPC — see {@link RoomMetrics}. */
     metrics(): RoomMetrics;
     /** What the rows take: bytes, logical records, rows. */
@@ -687,6 +905,13 @@ export declare class AttachedDocument {
      */
     private attribute;
     fetch(request: Request): Promise<Response>;
+    /**
+     * One history request (H11): `list`, `read` (a version as JSON), and,
+     * for a write identity, `restore` and `undo`. `404` when the room keeps
+     * no history or holds no such version, `403` for a read-only identity's
+     * write, `503` when the room cannot serve it.
+     */
+    private historyRequest;
     /** Is `ws` one of this document's sockets? */
     owns(ws: WebSocket): boolean;
     webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): boolean;
@@ -806,7 +1031,8 @@ export declare class AttachedDocument {
  * `edytor_replicas`) live beside yours and its sockets carry
  * {@link SOCKET_TAG}. Each handler your class does not define —
  * `fetch`, `webSocketMessage`, `webSocketClose`, `webSocketError`, and
- * `alarm` when `onSave` is set — is installed on the object; a class that
+ * `alarm` unless the document needs none (no `onSave`, no `history`,
+ * `purgeAfterDays: false`) — is installed on the object; a class that
  * defines one delegates to the returned document's method (which returns
  * `false` for a socket that is not the document's).
  */
@@ -840,12 +1066,40 @@ export declare class DocumentRoom<Env = DocumentRoomEnv> extends DurableObject<E
      * at first use (after construction: it may return a subclass field).
      */
     protected semantics(): DocumentSemanticsConfig;
+    /**
+     * Version history — see {@link AttachDocumentOptions.history}. Default:
+     * the `EDYTOR_HISTORY` KV binding, with `EDYTOR_HISTORY_RETENTION_DAYS`
+     * and `EDYTOR_HISTORY_TIME_ZONE`; none without it. Read once, at first use.
+     */
+    protected history(): HistoryOptions | undefined;
+    /** The room's clock — see {@link AttachDocumentOptions.now}. */
+    protected now(): number;
     fetch(request: Request): Promise<Response>;
     webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): void;
     webSocketClose(ws: WebSocket, code: number, reason: string): void;
     webSocketError(ws: WebSocket): void;
-    /** Runs `onSave`. Call `super.alarm()` if you override it. */
+    /** Runs the room's tasks: `onSave`, the history slots, the purge. Call `super.alarm()` if you override it. */
     alarm(): Promise<void>;
+    /** The versions, newest first, also over RPC — see {@link AttachedDocument.listHistory}. */
+    listHistory(): Promise<HistoryEntry[]>;
+    /** A version as JSON, also over RPC — see {@link AttachedDocument.readHistory}. */
+    readHistory(key: string): Promise<JSONDoc | null>;
+    /** Restore a version, also over RPC — see {@link AttachedDocument.restoreHistory}. */
+    restoreHistory(key: string, options?: {
+        user?: string;
+    }): Promise<RestoreResult>;
+    /** Undo the last restore, also over RPC — see {@link AttachedDocument.undoRestore}. */
+    undoRestore(options?: {
+        user?: string;
+    }): Promise<{
+        status: 'applied' | 'noop';
+    }>;
+    /** The version writes in flight, also over RPC — see {@link AttachedDocument.historyWritten}. */
+    historyWritten(): Promise<void>;
+    /** Run the purge task now, also over RPC — see {@link AttachedDocument.purge}. */
+    purge(): (PurgeReport & {
+        horizon: number;
+    }) | null;
     /** Compaction, also over RPC. */
     compact(): {
         rows: number;