@defensestation/ysync-go 0.1.0 → 0.2.0-dev.13.f029dd9

package/README.md

@@ -96,6 +96,50 @@ documented in
 Generated protobuf descriptors are exported under `@defensestation/ysync-go/ysync/v1`
 if you need raw RPC access.
 
+## Compaction adapter (Node 18+)
+
+The server's update log grows until the host folds it - **compaction is
+required in production** (see the repository README). The snapshot must be
+built with real Yjs (Go-side merges corrupt nested-XML documents -
+BlockNote, ProseMirror, Tiptap), so this package ships the adapter:
+
+```ts
+import { compactDocuments } from "@defensestation/ysync-go/compaction";
+
+// AWS Lambda handler, Cloud Run job, or any Node 18+ process:
+export const handler = async () => {
+  const run = await compactDocuments(
+    {
+      baseUrl: "https://collab.internal.example.com",
+      headers: () => ({ authorization: `Bearer ${process.env.COMPACT_TOKEN}` }),
+      threshold: 200, // fold once a doc exceeds this many log records
+      keep: 50, //       newest records kept individually attributed
+    },
+    await listCandidateDocIds(), // doc discovery is the host app's job
+  );
+  if (run.errors.length > 0) {
+    throw new Error(`${run.errors.length} document(s) failed`);
+  }
+  return run; // { compacted, skipped, results, errors }
+};
+```
+
+`compactDocument(options, docId)` is the single-document primitive.
+Everything is idempotent - retries and concurrent runs converge - and one
+bad document never aborts a `compactDocuments` run.
+
+For cron-style schedulers there is a CLI:
+
+```bash
+npx ysync-compact --base-url http://localhost:8080 --docs doc-1,doc-2 \
+  --threshold 200 --keep 50 --header 'authorization: Bearer ...'
+# or stream doc IDs, one per line:
+psql -Atc 'select id from documents' | npx ysync-compact --base-url ... --docs -
+```
+
+Compaction rewrites stored history: gate the server's `Authz.CanCompact`
+so **only** this job's identity holds it.
+
 ## License
 
 MIT

package/dist/compaction/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/compaction/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/compaction/cli.ts"],"names":[],"mappings":""}

package/dist/compaction/cli.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// ysync-compact: compaction CLI over the programmatic adapter in
+// compaction.ts, for cron-style schedulers (Kubernetes CronJob, systemd
+// timers). Lambda/Cloud Run users should import `compactDocuments` directly.
+//
+// Usage:
+//   ysync-compact --base-url http://localhost:8080 --docs doc-1,doc-2
+//   ysync-compact --base-url ... --docs -            # doc IDs from stdin, one per line
+//   ysync-compact --base-url ... --docs ... \
+//     [--threshold 200] [--keep 50] \
+//     [--header 'authorization: Bearer ...']... [--user-id compact-sidecar]
+//
+// Exits 0 when every document succeeded, 1 when any document failed, 2 on
+// usage errors. Gate the server's Authz.CanCompact to this job's identity.
+import { compactDocuments } from "./compaction.js";
+async function main() {
+    let args;
+    try {
+        args = parseArgs(process.argv.slice(2));
+    }
+    catch (error) {
+        console.error(String(error instanceof Error ? error.message : error));
+        return 2;
+    }
+    if (!args.baseUrl || !args.docs) {
+        console.error("usage: ysync-compact --base-url URL --docs id1,id2|- [--threshold N] " +
+            "[--keep N] [--header 'name: value']... [--user-id ID]");
+        return 2;
+    }
+    const docIds = args.docs === "-"
+        ? (await readStdin()).split("\n").map((line) => line.trim())
+        : args.docs.split(",").map((docId) => docId.trim());
+    const filtered = docIds.filter((docId) => docId.length > 0);
+    if (filtered.length === 0) {
+        console.error("no document IDs given");
+        return 2;
+    }
+    const headers = { ...args.headers };
+    if (args.userId) {
+        // Demo identity hint; real deployments attach identity via auth
+        // middleware and pass the credential with --header instead.
+        headers["x-user-id"] = args.userId;
+    }
+    const run = await compactDocuments({
+        baseUrl: args.baseUrl,
+        headers,
+        threshold: args.threshold === undefined ? undefined : parseCount("--threshold", args.threshold),
+        keep: args.keep === undefined ? undefined : parseCount("--keep", args.keep),
+    }, filtered);
+    for (const result of run.results) {
+        if (result.compacted) {
+            console.log(`${result.docId}: folded ${result.foldedRecords}/${result.records} records ` +
+                `through sequence ${result.foldedThroughSequence} into a ` +
+                `${result.snapshotBytes}-byte snapshot`);
+        }
+        else {
+            console.log(`${result.docId}: ${result.records} records, nothing to do`);
+        }
+    }
+    for (const failure of run.errors) {
+        console.error(`${failure.docId}: ${String(failure.error)}`);
+    }
+    return run.errors.length > 0 ? 1 : 0;
+}
+function parseArgs(argv) {
+    const args = { headers: {} };
+    for (let i = 0; i < argv.length; i++) {
+        const flag = argv[i];
+        const value = argv[i + 1];
+        if (!flag.startsWith("--") || value === undefined) {
+            throw new Error(`unexpected argument: ${flag}`);
+        }
+        i++;
+        switch (flag) {
+            case "--base-url":
+                args.baseUrl = value;
+                break;
+            case "--docs":
+                args.docs = value;
+                break;
+            case "--threshold":
+                args.threshold = value;
+                break;
+            case "--keep":
+                args.keep = value;
+                break;
+            case "--user-id":
+                args.userId = value;
+                break;
+            case "--header": {
+                const colon = value.indexOf(":");
+                if (colon < 1) {
+                    throw new Error(`--header expects 'name: value', got ${JSON.stringify(value)}`);
+                }
+                args.headers[value.slice(0, colon).trim()] = value.slice(colon + 1).trim();
+                break;
+            }
+            default:
+                throw new Error(`unknown flag: ${flag}`);
+        }
+    }
+    return args;
+}
+function parseCount(flag, value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new Error(`${flag} expects a non-negative integer, got ${JSON.stringify(value)}`);
+    }
+    return parsed;
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => (data += chunk));
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", reject);
+    });
+}
+main().then((code) => process.exit(code), (error) => {
+    console.error(String(error));
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/compaction/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/compaction/cli.ts"],"names":[],"mappings":"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"}

package/dist/compaction/compaction.d.ts

@@ -0,0 +1,67 @@
+/** How to reach the ysync server and authenticate against it. */
+export interface CompactionClientOptions {
+    /** Server base URL, e.g. "http://localhost:8080". */
+    baseUrl: string;
+    /**
+     * Extra request headers (an authenticated identity that passes
+     * `Authz.CanCompact`). A function is awaited per request, so short-lived
+     * tokens can be refreshed.
+     */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /** Override the fetch implementation (tests, custom agents). */
+    fetch?: typeof globalThis.fetch;
+}
+/** When and how much to fold. Zero-config defaults match examples/compact-docs. */
+export interface CompactionPolicy {
+    /**
+     * Compact only when the document has more than this many log records
+     * (snapshot record included). Default 200.
+     */
+    threshold?: number;
+    /**
+     * Newest records to keep individually attributed for change history.
+     * Default 50.
+     */
+    keep?: number;
+}
+export interface CompactDocumentOptions extends CompactionClientOptions, CompactionPolicy {
+}
+export interface CompactDocumentResult {
+    docId: string;
+    /** False when the log was at or below the threshold (nothing folded). */
+    compacted: boolean;
+    /** Log records before compaction. */
+    records: number;
+    /** Records folded into the snapshot (set when compacted). */
+    foldedRecords?: number;
+    /** Sequence the log was folded through (set when compacted). */
+    foldedThroughSequence?: string;
+    /** Encoded snapshot size in bytes (set when compacted). */
+    snapshotBytes?: number;
+}
+export interface CompactionRunResult {
+    results: CompactDocumentResult[];
+    /** Per-document failures; one bad document never aborts the run. */
+    errors: {
+        docId: string;
+        error: unknown;
+    }[];
+    compacted: number;
+    skipped: number;
+}
+/**
+ * Compacts one document if its update log exceeds the policy threshold:
+ * lists the stored log, replays all but the newest `keep` records into a
+ * fresh Y.Doc, encodes the state with `Y.encodeStateAsUpdate`, and calls
+ * `CompactDocument` for the covered sequence. Idempotent — re-running
+ * converges to the same folded log, and updates pushed concurrently are
+ * unaffected (they sort after `compactThroughSequence`).
+ */
+export declare function compactDocument(options: CompactDocumentOptions, docId: string): Promise<CompactDocumentResult>;
+/**
+ * Compacts many documents sequentially (compaction is background work;
+ * predictable server load beats speed here). Per-document failures are
+ * collected in `errors` instead of aborting the run.
+ */
+export declare function compactDocuments(options: CompactDocumentOptions, docIds: Iterable<string>): Promise<CompactionRunResult>;
+//# sourceMappingURL=compaction.d.ts.map

package/dist/compaction/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/compaction/compaction.ts"],"names":[],"mappings":"AAmBA,iEAAiE;AACjE,MAAM,WAAW,uBAAuB;IACtC,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EACJ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACrE,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,sBACf,SAAQ,uBAAuB,EAC7B,gBAAgB;CAAG;AAEvB,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,SAAS,EAAE,OAAO,CAAC;IACnB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,oEAAoE;IACpE,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAWD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,qBAAqB,CAAC,CAuDhC;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GACvB,OAAO,CAAC,mBAAmB,CAAC,CAqB9B"}

package/dist/compaction/compaction.js

@@ -0,0 +1,153 @@
+// Compaction adapter for ysync-go servers.
+//
+// The server's update log grows until the host folds it (see the repository
+// README's Compaction section). This module implements the recommended
+// policy — once a document exceeds `threshold` log records, fold everything
+// except the newest `keep` records into one snapshot — using **real Yjs** to
+// build the snapshot. That matters: Go-side merges corrupt documents with
+// nested XML content (BlockNote, ProseMirror, Tiptap); see
+// adapters/yjs/ygo/README.md and its xmlrepro/ cross-implementation check.
+//
+// The functions are runtime-agnostic on purpose: call `compactDocuments`
+// from an AWS Lambda handler, a Cloud Run job, a Kubernetes CronJob (the
+// bundled `ysync-compact` CLI), or any Node 18+ process with `fetch`.
+//
+// Security: `CompactDocument` rewrites stored history, so gate it with
+// `Authz.CanCompact` on the server and give **only** this job's identity
+// that permission. Pass the credential via `headers`.
+import * as Y from "yjs";
+const DEFAULT_THRESHOLD = 200;
+const DEFAULT_KEEP = 50;
+/**
+ * Compacts one document if its update log exceeds the policy threshold:
+ * lists the stored log, replays all but the newest `keep` records into a
+ * fresh Y.Doc, encodes the state with `Y.encodeStateAsUpdate`, and calls
+ * `CompactDocument` for the covered sequence. Idempotent — re-running
+ * converges to the same folded log, and updates pushed concurrently are
+ * unaffected (they sort after `compactThroughSequence`).
+ */
+export async function compactDocument(options, docId) {
+    if (!docId) {
+        throw new Error("docId is required");
+    }
+    const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+    const keep = options.keep ?? DEFAULT_KEEP;
+    if (threshold < 1 || keep < 0) {
+        throw new Error(`invalid policy: threshold ${threshold}, keep ${keep}`);
+    }
+    const listed = (await rpc(options, "ListDocumentUpdates", { docId }));
+    const updates = listed.updates ?? [];
+    const skip = {
+        docId,
+        compacted: false,
+        records: updates.length,
+    };
+    if (updates.length <= threshold) {
+        return skip;
+    }
+    // Records arrive in sequence order; the first may already be a snapshot
+    // from a prior run. Folding only that snapshot again would be a no-op.
+    const cutoff = updates.length - keep;
+    if (cutoff < 1 || (cutoff === 1 && updates[0]?.isSnapshot)) {
+        return skip;
+    }
+    const target = updates[cutoff - 1];
+    if (target?.sequence === undefined) {
+        throw new Error(`${docId}: log record ${cutoff - 1} has no sequence`);
+    }
+    const doc = new Y.Doc();
+    for (const record of updates.slice(0, cutoff)) {
+        if (record.yjsUpdate) {
+            Y.applyUpdate(doc, fromBase64(record.yjsUpdate));
+        }
+    }
+    const snapshot = Y.encodeStateAsUpdate(doc);
+    doc.destroy();
+    await rpc(options, "CompactDocument", {
+        docId,
+        compactUpdate: toBase64(snapshot),
+        compactThroughSequence: target.sequence,
+    });
+    return {
+        docId,
+        compacted: true,
+        records: updates.length,
+        foldedRecords: cutoff,
+        foldedThroughSequence: String(target.sequence),
+        snapshotBytes: snapshot.byteLength,
+    };
+}
+/**
+ * Compacts many documents sequentially (compaction is background work;
+ * predictable server load beats speed here). Per-document failures are
+ * collected in `errors` instead of aborting the run.
+ */
+export async function compactDocuments(options, docIds) {
+    const run = {
+        results: [],
+        errors: [],
+        compacted: 0,
+        skipped: 0,
+    };
+    for (const docId of docIds) {
+        try {
+            const result = await compactDocument(options, docId);
+            run.results.push(result);
+            if (result.compacted) {
+                run.compacted++;
+            }
+            else {
+                run.skipped++;
+            }
+        }
+        catch (error) {
+            run.errors.push({ docId, error });
+        }
+    }
+    return run;
+}
+/** Plain Connect JSON: POST /<service>/<method> with a JSON body. */
+async function rpc(options, method, body) {
+    const headers = typeof options.headers === "function"
+        ? await options.headers()
+        : (options.headers ?? {});
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const base = options.baseUrl.replace(/\/+$/, "");
+    const response = await doFetch(`${base}/ysync.v1.YjsSyncService/${method}`, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...headers },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const detail = await response.text().catch(() => "");
+        throw new Error(`${method}: HTTP ${response.status}${detail ? `: ${detail}` : ""}`);
+    }
+    return response.json();
+}
+function nodeBuffer() {
+    return globalThis.Buffer;
+}
+function toBase64(bytes) {
+    const buffer = nodeBuffer();
+    if (buffer) {
+        return buffer.from(bytes).toString("base64");
+    }
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+function fromBase64(encoded) {
+    const buffer = nodeBuffer();
+    if (buffer) {
+        return Uint8Array.from(buffer.from(encoded, "base64"));
+    }
+    const binary = atob(encoded);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        out[i] = binary.charCodeAt(i);
+    }
+    return out;
+}
+//# sourceMappingURL=compaction.js.map

package/dist/compaction/compaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.js","sourceRoot":"","sources":["../../src/compaction/compaction.ts"],"names":[],"mappings":"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"}

package/dist/compaction/index.d.ts

@@ -0,0 +1,3 @@
+export { compactDocument, compactDocuments } from "./compaction.js";
+export type { CompactionClientOptions, CompactionPolicy, CompactDocumentOptions, CompactDocumentResult, CompactionRunResult, } from "./compaction.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/compaction/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/compaction/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EACV,uBAAuB,EACvB,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC"}

package/dist/compaction/index.js

@@ -0,0 +1,2 @@
+export { compactDocument, compactDocuments } from "./compaction.js";
+//# sourceMappingURL=index.js.map

package/dist/compaction/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/compaction/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defensestation/ysync-go",
-  "version": "0.1.0",
+  "version": "0.2.0-dev.13.f029dd9",
   "description": "Browser Yjs providers (Connect RPC and WebSocket) for the ysync-go collaboration backend",
   "license": "MIT",
   "repository": {
@@ -30,14 +30,20 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./compaction": {
+      "types": "./dist/compaction/index.d.ts",
+      "import": "./dist/compaction/index.js"
+    },
     "./ysync/v1": {
       "types": "./dist/gen/ysync/v1/sync_pb.d.ts",
       "import": "./dist/gen/ysync/v1/sync_pb.js"
     }
   },
+  "bin": {
+    "ysync-compact": "dist/compaction/cli.js"
+  },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "scripts": {
     "generate": "cd .. && PATH=\"./npm/node_modules/.bin:$PATH\" buf generate --template npm/buf.gen.yaml",