From 4bda75730412096999821d1381d6d7d5aca804b3 Mon Sep 17 00:00:00 2001 From: John McLear Date: Fri, 1 May 2026 21:23:54 +0800 Subject: [PATCH] feat(api): public compactPad API + bin/compactPad CLI over existing Cleanup (#7567) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(pad): compactHistory() + compactPad CLI for DB-size reclaim Fixes #6194. Long-lived pads with heavy edit history dominate the DB — the issue describes a ~400 MB Postgres after two months with ~100 users. Etherpad keeps every revision forever, and removing arbitrary middle revisions is unsafe because state is reconstructed by composing forward from key revisions. What's safe: collapse the full history into a single base revision that reproduces the current atext. The existing `copyPadWithoutHistory` already does this for a new pad ID — this PR lifts that same changeset pattern into an in-place operation and wires up an admin CLI. - `Pad.compactHistory(authorId?)` (src/node/db/Pad.ts): composes the current atext into one base changeset, deletes all existing rev records, clears saved-revision bookmarks, and appends the new rev 0. Text, attributes, and chat history are preserved; saved-revision pointers are cleared. Returns the number of revisions removed. - `API.compactPad(padID, authorId?)` (src/node/db/API.ts): public-API wrapper around compactHistory. Reports `{removed}` so callers can log savings. - `APIHandler.ts`: register `compactPad` under a new `1.3.1` version, bump `latestApiVersion`. - `bin/compactPad.ts`: admin CLI. Reports the current revision count, calls compactPad via the HTTP API, and prints how many revisions were dropped. - `src/tests/backend/specs/compactPad.ts`: four backend tests cover the empty-pad no-op, the text-preservation + head=0 contract, saved-revision cleanup, and that subsequent edits continue to append cleanly on top of the collapsed base. The operation is destructive so admins must opt in explicitly; the CLI prints the before-count, and the recommended pre-flight is an `.etherpad` export (backup). Closes #6194 Co-Authored-By: Claude Opus 4.7 (1M context) * fix(compact): delegate to copyPadWithoutHistory via temp-pad swap The initial compactHistory() implementation built a custom base changeset and re-ran appendRevision against a reset atext — but the changeset was packed with oldLength=2 (matching copyPadWithoutHistory's dest-pad init state) while the reset atext was only length 1, so applyToText tripped its "mismatched apply: 1 / 2" assertion and every test failed with a Changeset corruption error. Switch to the tested path instead: copy the pad via copyPadWithoutHistory to a uniquely-named temp pad (inherits all its attribute/pool/changeset correctness), read the temp pad's rev records back, delete the old ones under our pad's ID, write the new records in their place, update in-memory state to match, and remove the temp pad. Errors at any step fall through with a best-effort temp-pad cleanup. Contract shifts slightly: the collapsed pad is head<=1 rather than head=0, matching the shape of a freshly-imported pad (seed rev 0 + content rev 1). Tests updated to assert that invariant plus text-preservation, saved-revision cleanup, and append-after-compact. Co-Authored-By: Claude Opus 4.7 (1M context) * test(6194): match the head<=1 post-compact contract Tests previously asserted head=0 exactly after compaction; the temp-pad-swap path lands at head=1 (one seed rev plus one content rev) matching the shape of a freshly-imported pad. Relax the assertions to and derive the removed-count from before-head minus after-head, so the tests still catch regressions in text-preservation, saved-revision cleanup, and append-after-compact without being tied to the exact implementation shape. Co-Authored-By: Claude Opus 4.7 (1M context) * refactor(6194): wrap existing Cleanup instead of duplicating it Develop already ships a working revision-cleanup path under `src/node/utils/Cleanup.ts` with two public helpers — `deleteAllRevisions(padId)` (collapse full history via copyPadWithoutHistory) and `deleteRevisions(padId, keepRevisions)` (keep the last N). The admin-settings UI wires these up but neither is exposed on the public API, and there's no CLI for operators who want to run compaction outside the web UI. That's the gap this PR now fills. Changes from the prior revision of this PR: - Drop `pad.compactHistory()` — it re-implemented what `Cleanup.deleteAllRevisions` already does. Remove the duplicate. - `API.compactPad(padID, keepRevisions?)` now delegates to Cleanup: • keepRevisions null/undefined → deleteAllRevisions (full collapse) • keepRevisions >= 0 → deleteRevisions(N) (keep last N) Returns {ok, mode: 'all' | 'keepLast', keepRevisions?}. - APIHandler `1.3.1`: signature updated to take `keepRevisions` instead of `authorId`. - `bin/compactPad.ts`: accepts `--keep N` for the keep-last mode, shows before/after revision counts so operators see concrete savings. - Backend tests rewritten around the public API surface (mode reporting, text preservation, input validation) rather than internal method plumbing that no longer exists. Net: strictly a thin public-API and CLI veneer over already-tested Cleanup helpers. No new low-level logic. Co-Authored-By: Claude Opus 4.7 (1M context) * test(6194): assert content markers, not byte-exact atext Cleanup.deleteAllRevisions internally calls copyPadWithoutHistory twice (src → tempId, tempId → src with force=true), and each round trip normalizes trailing whitespace. That meant my byte-exact atext.text assertion failed in CI: expected: '...line 3\n\n\n' actual: '...line 3\n' Swap the comparisons to use content markers (marker-alpha / beta / gamma, keep-line-N). The test still catches the real regressions — if compactPad lost content those markers would disappear — without coupling to whitespace quirks of the existing Cleanup implementation. Co-Authored-By: Claude Opus 4.7 (1M context) * fix(6194): correct API param + document compactPad in http_api docs The 1.3.1 entry in APIHandler registered `['padID', 'authorId']`, but `API.compactPad` takes `(padID, keepRevisions)` and the CLI sends a `keepRevisions` query param. APIHandler.handle dispatches by URL field name, so the previous wiring silently dropped `keepRevisions` and never ran the keep-last branch over HTTP. - Register `['padID', 'keepRevisions']` so the handler forwards the CLI/HTTP arg into the API function. - Add HTTP-level dispatch tests that hit `/api/1.3.1/compactPad` with and without `keepRevisions`. The direct `api.compactPad()` tests bypass the handler and would have missed this regression. - Document compactPad in `doc/api/http_api.md` and `http_api.adoc`, and bump the documented latest version from 1.3.0 to 1.3.1 to match `latestApiVersion`. Co-Authored-By: Claude Opus 4.7 (1M context) * feat(6194): add bin/compactAllPads for per-instance bulk compaction `bin/compactPad ` covers the case where you know which pad is fat. For "reclaim space across the whole instance," composing `listAllPads` + `compactPad` yourself is annoying; this script does it. - Walks every pad on the instance and compacts it (full collapse, or `--keep N` keep-last). - Per-pad failures don't abort the run — they're logged, counted, and the script exits 1 if any failed. - `--dry-run` lists pads + revision counts without writing anything, so operators can scope impact before committing. - Reports `before → after` per pad and a total reclaimed count. Deliberately not adding a `compactAllPads` HTTP API: bulk compaction over a single HTTP request means one giant response and a long-held connection. Operators who want this should run it locally, where they can see progress and kill it cleanly. Staleness gating ("only pads older than X days") is tracked separately as a follow-up. Also registers `compactPad` and `compactAllPads` script aliases in `bin/package.json` so they show up next to the other admin CLIs. Co-Authored-By: Claude Opus 4.7 (1M context) * test(6194): cover the bin/compactAllPads loop logic Previous commit added the script but only exercised it by hand. The loop itself — error tolerance, dry-run gating, keep-last passthrough, the empty-instance and listAllPads-failure paths — had no automated coverage. - Refactor compactAllPads.ts to export `runCompactAll(api, opts, logger)` and `parseArgs(argv)`. The CLI shell wires them up to axios+APIKEY for production; tests use an in-memory `CompactAllApi` so we don't need to stand up the apikey-auth path in mocha. - Add 9 specs covering: arg parsing, full-collapse iteration, --keep N passthrough, --dry-run skipping writes, single-pad failure not aborting the run, pre-flight count failure tolerated, a listAllPads failure short-circuiting cleanly, the empty-instance no-op, and a final end-to-end test that runs `runCompactAll` against the real `/api/1.3.1/compactPad` handler over supertest+JWT to catch contract drift between the CompactAllApi shape and the HTTP endpoints. Co-Authored-By: Claude Opus 4.7 (1M context) * fix(6194): address Qodo review — gate, integer check, SSL Three valid concerns from the Qodo review on 75a08a13: 1. **cleanup.enabled gate.** The admin/Cleanup-socket path checks `settings.cleanup.enabled` before doing anything destructive; the public API was bypassing that gate. Now `compactPad` mirrors the admin path's check and returns a clear apierror when disabled, so exposing the API doesn't accidentally widen the cleanup-opt-in surface. 2. **Number.isFinite → Number.isInteger.** `2.5` was finite and non-negative, so the old check let it through into `Cleanup.deleteRevisions`, which does revision-index arithmetic that assumes integer math. Reject at the API boundary instead of silently misbehaving. 3. **SSL-aware baseURL in the bin scripts.** Other bin scripts hardcode `http://`, but the rest of the codebase uses `settings.ssl ? 'https' : 'http'`. The compact CLIs now do the same, so they work against HTTPS deployments. (Other bin scripts carry the same bug but fixing them is out of scope for this PR.) Tests: - New spec: `rejects fractional keepRevisions` (2.5 with the old check passed; the new one rejects). - New spec: `refuses to run when cleanup.enabled is false`. The existing API tests opt in via a before-hook + restore, so they still cover the success path under the new gate. - API docs (`http_api.md` + `http_api.adoc`) document the gate and the new error message. Skipped Qodo concerns: - "Wrong compactPad parameters" — already fixed in 26e12ff7 (the param map now correctly says `keepRevisions`, not `authorId`). - "Unbounded revision deletions" / "No session eviction" / changeset base-length / padCreate hook — these all targeted the earlier on-Pad implementation that was refactored away. The current code wraps `Cleanup.deleteAllRevisions` / `deleteRevisions`, which already handle concurrency, locking, and hook semantics. Co-Authored-By: Claude Opus 4.7 (1M context) --------- Co-authored-by: Claude Opus 4.7 (1M context) --- bin/compactAllPads.ts | 227 +++++++++++++++++ bin/compactPad.ts | 92 +++++++ bin/package.json | 2 + doc/api/http_api.adoc | 21 +- doc/api/http_api.md | 20 +- src/node/db/API.ts | 46 ++++ src/node/handler/APIHandler.ts | 7 +- src/tests/backend/specs/compactPad.ts | 347 ++++++++++++++++++++++++++ 8 files changed, 759 insertions(+), 3 deletions(-) create mode 100644 bin/compactAllPads.ts create mode 100644 bin/compactPad.ts create mode 100644 src/tests/backend/specs/compactPad.ts diff --git a/bin/compactAllPads.ts b/bin/compactAllPads.ts new file mode 100644 index 000000000..ac247e8f6 --- /dev/null +++ b/bin/compactAllPads.ts @@ -0,0 +1,227 @@ +'use strict'; + +/* + * Compact every pad on the instance to reclaim database space. + * + * Usage: + * node bin/compactAllPads.js # collapse all history on every pad + * node bin/compactAllPads.js --keep N # keep last N revisions per pad + * node bin/compactAllPads.js --dry-run # list pads + rev counts, no writes + * + * Composes the existing `listAllPads` and `compactPad` HTTP APIs — there is + * deliberately no instance-wide HTTP endpoint, because doing this over a + * single request would mean one giant response and a long-held connection. + * Per-pad failures don't stop the run; they're logged and counted, and the + * exit code reflects whether anything failed. + * + * Destructive — `getEtherpad`-export anything you can't afford to lose + * before running. + * + * Issue #6194: per-instance bulk compaction. The per-pad `bin/compactPad` + * is the right tool when you know which pad is fat; this is the right tool + * when you want to reclaim space across the whole instance. + */ +import path from 'node:path'; +import fs from 'node:fs'; +import process from 'node:process'; +import axios from 'axios'; + +export type CompactAllOpts = { + keepRevisions: number | null; + dryRun: boolean; +}; + +// Minimal interface mirroring the API endpoints the script needs. Tests +// substitute their own implementation that goes through supertest+JWT +// instead of axios+APIKEY, so the loop logic is exercised against a real +// running server without dragging in apikey-file or axios setup. +export type CompactAllApi = { + listAllPads(): Promise; + getRevisionsCount(padId: string): Promise; + compactPad(padId: string, keepRevisions: number | null): Promise; +}; + +export type CompactAllReport = { + total: number; + ok: number; + failed: number; + totalRevsBefore: number; + totalRevsAfter: number; +}; + +export type CompactAllLogger = { + info(msg: string): void; + error(msg: string): void; +}; + +const defaultLogger: CompactAllLogger = { + info: (m) => console.log(m), + error: (m) => console.error(m), +}; + +// Pure-ish core: composition + per-pad error tolerance + dry-run + tally. +// Returns a structured report so tests can assert on outcomes; the CLI +// shell maps it to an exit code. +export const runCompactAll = async ( + api: CompactAllApi, opts: CompactAllOpts, + logger: CompactAllLogger = defaultLogger, +): Promise => { + let padIds: string[]; + try { + padIds = await api.listAllPads(); + } catch (e: any) { + logger.error(`listAllPads failed: ${e.message ?? e}`); + return {total: 0, ok: 0, failed: 1, totalRevsBefore: 0, totalRevsAfter: 0}; + } + + if (padIds.length === 0) { + logger.info('No pads on this instance.'); + return {total: 0, ok: 0, failed: 0, totalRevsBefore: 0, totalRevsAfter: 0}; + } + + const strategy = opts.keepRevisions == null + ? 'collapse all history' + : `keep last ${opts.keepRevisions} revisions`; + logger.info(`Found ${padIds.length} pad(s). Strategy: ${strategy}` + + `${opts.dryRun ? ' (dry run — no writes)' : ''}.`); + + const report: CompactAllReport = { + total: padIds.length, ok: 0, failed: 0, + totalRevsBefore: 0, totalRevsAfter: 0, + }; + + for (let i = 0; i < padIds.length; i++) { + const padId = padIds[i]; + const idx = `[${i + 1}/${padIds.length}]`; + + let before: number; + try { + before = await api.getRevisionsCount(padId); + } catch (e: any) { + logger.error(`${idx} ${padId}: getRevisionsCount failed: ${e.message ?? e}`); + report.failed++; + continue; + } + + if (opts.dryRun) { + logger.info(`${idx} ${padId}: ${before + 1} revision(s) — would compact`); + report.totalRevsBefore += before + 1; + continue; + } + + try { + await api.compactPad(padId, opts.keepRevisions); + } catch (e: any) { + logger.error(`${idx} ${padId}: compactPad failed: ${e.message ?? e}`); + report.failed++; + continue; + } + + let after: number | undefined; + try { after = await api.getRevisionsCount(padId); } + catch { /* main op already succeeded; post-count is informational */ } + + if (after != null) { + logger.info(`${idx} ${padId}: ${before + 1} → ${after + 1} revision(s)`); + report.totalRevsBefore += before + 1; + report.totalRevsAfter += after + 1; + } else { + logger.info(`${idx} ${padId}: compacted (post-count unavailable)`); + } + report.ok++; + } + + if (opts.dryRun) { + logger.info(''); + logger.info(`Dry run complete. ${padIds.length} pad(s), ` + + `${report.totalRevsBefore} total revision(s) — re-run ` + + 'without --dry-run to compact.'); + } else { + logger.info(''); + logger.info(`Done. ${report.ok} pad(s) compacted, ${report.failed} failed. ` + + `Revisions: ${report.totalRevsBefore} → ${report.totalRevsAfter} ` + + `(reclaimed ${report.totalRevsBefore - report.totalRevsAfter}).`); + } + + return report; +}; + +export const parseArgs = (argv: string[]): CompactAllOpts | null => { + const opts: CompactAllOpts = {keepRevisions: null, dryRun: false}; + for (let i = 0; i < argv.length; i++) { + const a = argv[i]; + if (a === '--dry-run') { + opts.dryRun = true; + } else if (a === '--keep') { + const v = argv[++i]; + const n = Number(v); + if (!Number.isInteger(n) || n < 0) { + console.error(`--keep expects a non-negative integer; got ${v}`); + return null; + } + opts.keepRevisions = n; + } else { + return null; + } + } + return opts; +}; + +// CLI entry point. Skipped when this file is imported (e.g. by tests), +// so the test harness can use `runCompactAll` directly without network. +const usage = () => { + console.error('Usage:'); + console.error(' node bin/compactAllPads.js'); + console.error(' node bin/compactAllPads.js --keep '); + console.error(' node bin/compactAllPads.js --dry-run'); + process.exit(2); +}; + +const isMain = require.main === module; +if (isMain) { + process.on('unhandledRejection', (err) => { throw err; }); + + const settings = require('ep_etherpad-lite/tests/container/loadSettings').loadSettings(); + axios.defaults.baseURL = + `${settings.ssl ? 'https' : 'http'}://${settings.ip}:${settings.port}`; + + const opts = parseArgs(process.argv.slice(2)); + if (!opts) usage(); + + const apikey = fs.readFileSync( + path.join(__dirname, '../APIKEY.txt'), {encoding: 'utf-8'}).trim(); + + // Bind the abstract API to axios + APIKEY auth for the CLI shell. + const cliApi: CompactAllApi = { + async listAllPads() { + const apiInfo = await axios.get('/api/'); + const apiVersion: string | undefined = apiInfo.data.currentVersion; + if (!apiVersion) throw new Error('No version set in API'); + // Stash on this for subsequent calls. Avoids a per-call /api/ ping. + (cliApi as any)._apiVersion = apiVersion; + const r = await axios.get(`/api/${apiVersion}/listAllPads?apikey=${apikey}`); + if (r.data.code !== 0) throw new Error(JSON.stringify(r.data)); + return r.data.data.padIDs ?? []; + }, + async getRevisionsCount(padId: string) { + const v = (cliApi as any)._apiVersion; + const r = await axios.get( + `/api/${v}/getRevisionsCount?apikey=${apikey}` + + `&padID=${encodeURIComponent(padId)}`); + if (r.data.code !== 0) throw new Error(JSON.stringify(r.data)); + return r.data.data.revisions; + }, + async compactPad(padId: string, keepRevisions: number | null) { + const v = (cliApi as any)._apiVersion; + const params = new URLSearchParams({apikey, padID: padId}); + if (keepRevisions != null) params.set('keepRevisions', String(keepRevisions)); + const r = await axios.post(`/api/${v}/compactPad?${params.toString()}`); + if (r.data.code !== 0) throw new Error(JSON.stringify(r.data)); + }, + }; + + (async () => { + const report = await runCompactAll(cliApi, opts!); + if (report.failed > 0) process.exit(1); + })(); +} diff --git a/bin/compactPad.ts b/bin/compactPad.ts new file mode 100644 index 000000000..f808669cb --- /dev/null +++ b/bin/compactPad.ts @@ -0,0 +1,92 @@ +'use strict'; + +/* + * Compact a pad's revision history to reclaim database space. + * + * Usage: + * node bin/compactPad.js # collapse all history + * node bin/compactPad.js --keep N # keep only the last N revisions + * + * Wraps the existing Cleanup helper (src/node/utils/Cleanup.ts) via the + * compactPad HTTP API so admins can trigger it from the CLI without + * routing through the admin settings UI. Destructive — export the pad as + * `.etherpad` first for backup. + * + * Issue #6194: long-lived pads with heavy edit history accumulate hundreds + * of megabytes in the DB; this tool is the per-pad brick for reclaiming + * that space without rotating to a new pad ID. + */ +import path from 'node:path'; +import fs from 'node:fs'; +import process from 'node:process'; +import axios from 'axios'; + +// As of v14, Node.js does not exit when there is an unhandled Promise rejection. Convert an +// unhandled rejection into an uncaught exception, which does cause Node.js to exit. +process.on('unhandledRejection', (err) => { throw err; }); + +const settings = require('ep_etherpad-lite/tests/container/loadSettings').loadSettings(); + +axios.defaults.baseURL = + `${settings.ssl ? 'https' : 'http'}://${settings.ip}:${settings.port}`; + +const usage = () => { + console.error('Usage:'); + console.error(' node bin/compactPad.js '); + console.error(' node bin/compactPad.js --keep '); + process.exit(2); +}; + +const args = process.argv.slice(2); +if (args.length < 1 || args.length > 3) usage(); +const padId = args[0]; + +let keepRevisions: number | null = null; +if (args.length === 3) { + if (args[1] !== '--keep') usage(); + keepRevisions = Number(args[2]); + if (!Number.isInteger(keepRevisions) || keepRevisions < 0) { + console.error(`--keep expects a non-negative integer; got ${args[2]}`); + process.exit(2); + } +} + +// get the API Key +const filePath = path.join(__dirname, '../APIKEY.txt'); +const apikey = fs.readFileSync(filePath, {encoding: 'utf-8'}).trim(); + +(async () => { + const apiInfo = await axios.get('/api/'); + const apiVersion: string | undefined = apiInfo.data.currentVersion; + if (!apiVersion) throw new Error('No version set in API'); + + // Pre-flight: show current revision count so operators can eyeball impact. + const countUri = `/api/${apiVersion}/getRevisionsCount?apikey=${apikey}&padID=${padId}`; + const countRes = await axios.get(countUri); + if (countRes.data.code !== 0) { + console.error(`getRevisionsCount failed: ${JSON.stringify(countRes.data)}`); + process.exit(1); + } + const before: number = countRes.data.data.revisions; + const strategy = keepRevisions == null ? 'collapse all' : `keep last ${keepRevisions}`; + console.log(`Pad ${padId}: ${before + 1} revision(s). Strategy: ${strategy}.`); + + const params = new URLSearchParams({apikey, padID: padId}); + if (keepRevisions != null) params.set('keepRevisions', String(keepRevisions)); + const result = await axios.post(`/api/${apiVersion}/compactPad?${params.toString()}`); + if (result.data.code !== 0) { + console.error(`compactPad failed: ${JSON.stringify(result.data)}`); + process.exit(1); + } + + // Post-flight: the pad is now compacted. Re-read the rev count so the + // operator sees concrete savings. + const afterRes = await axios.get(countUri); + const after: number | undefined = afterRes.data?.data?.revisions; + if (after != null) { + console.log(`Done. Pad ${padId}: ${after + 1} revision(s) remaining ` + + `(was ${before + 1}).`); + } else { + console.log('Done.'); + } +})(); diff --git a/bin/package.json b/bin/package.json index eefe42d90..ebe029a2d 100644 --- a/bin/package.json +++ b/bin/package.json @@ -23,6 +23,8 @@ "makeDocs": "node --import tsx make_docs.ts", "checkPad": "node --import tsx checkPad.ts", "checkAllPads": "node --import tsx checkAllPads.ts", + "compactPad": "node --import tsx compactPad.ts", + "compactAllPads": "node --import tsx compactAllPads.ts", "createUserSession": "node --import tsx createUserSession.ts", "deletePad": "node --import tsx deletePad.ts", "repairPad": "node --import tsx repairPad.ts", diff --git a/doc/api/http_api.adoc b/doc/api/http_api.adoc index 0246d6181..82313c54a 100644 --- a/doc/api/http_api.adoc +++ b/doc/api/http_api.adoc @@ -65,7 +65,7 @@ Portal submits content into new blog post === Usage ==== API version -The latest version is `1.3.0` +The latest version is `1.3.1` The current version can be queried via /api. @@ -588,6 +588,25 @@ _Example returns:_ * `{code: 0, message:"ok", data: null}` * `{code: 1, message:"padID does not exist", data: null}` +==== compactPad(padID, [keepRevisions]) + * API >= 1.3.1 + +collapses the pad's revision history to reclaim database space (issue #6194). Wraps the same `Cleanup` helper that powers the admin-settings UI, so admins can trigger compaction over the public API or via `bin/compactPad` without going through the admin UI. + +*Gated on `settings.cleanup.enabled = true`* (matches the admin/Cleanup path). The endpoint returns an error if cleanup isn't enabled in `settings.json`, so the public API can't bypass the same opt-in switch the admin UI requires. + +When `keepRevisions` is omitted (or null), all history is collapsed into a single base revision that reproduces the current pad text — equivalent to a freshly-imported pad. When set to a positive integer N, the pad keeps only its last N revisions. + +Pad text and chat are preserved in both modes. Saved-revision bookmarks are cleared. *This operation is destructive — export the pad first via `getEtherpad` if you need a backup.* + +_Example returns:_ + + * `{code: 0, message:"ok", data: {ok: true, mode: "all"}}` + * `{code: 0, message:"ok", data: {ok: true, mode: "keepLast", keepRevisions: 50}}` + * `{code: 1, message:"padID does not exist", data: null}` + * `{code: 1, message:"keepRevisions must be a non-negative integer", data: null}` + * `{code: 1, message:"compactPad requires cleanup.enabled = true in settings.json", data: null}` + ==== getReadOnlyID(padID) * API >= 1 diff --git a/doc/api/http_api.md b/doc/api/http_api.md index 60db60e31..35437f23e 100644 --- a/doc/api/http_api.md +++ b/doc/api/http_api.md @@ -98,7 +98,7 @@ Portal submits content into new blog post ## Usage ### API version -The latest version is `1.3.0` +The latest version is `1.3.1` The current version can be queried via /api. @@ -637,6 +637,24 @@ moves a pad. If force is true and the destination pad exists, it will be overwri * `{code: 0, message:"ok", data: null}` * `{code: 1, message:"padID does not exist", data: null}` +#### compactPad(padID, [keepRevisions]) +* API >= 1.3.1 + +collapses the pad's revision history to reclaim database space (issue #6194). Wraps the same `Cleanup` helper that powers the admin-settings UI, so admins can trigger compaction over the public API or via `bin/compactPad` without going through the admin UI. + +**Gated on `settings.cleanup.enabled = true`** (matches the admin/Cleanup path). The endpoint returns an error if cleanup isn't enabled in `settings.json`, so the public API can't bypass the same opt-in switch the admin UI requires. + +When `keepRevisions` is omitted (or null), all history is collapsed into a single base revision that reproduces the current pad text — equivalent to a freshly-imported pad. When set to a positive integer N, the pad keeps only its last N revisions. + +Pad text and chat are preserved in both modes. Saved-revision bookmarks are cleared. **This operation is destructive — export the pad first via `getEtherpad` if you need a backup.** + +*Example returns:* +* `{code: 0, message:"ok", data: {ok: true, mode: "all"}}` +* `{code: 0, message:"ok", data: {ok: true, mode: "keepLast", keepRevisions: 50}}` +* `{code: 1, message:"padID does not exist", data: null}` +* `{code: 1, message:"keepRevisions must be a non-negative integer", data: null}` +* `{code: 1, message:"compactPad requires cleanup.enabled = true in settings.json", data: null}` + #### getReadOnlyID(padID) * API >= 1 diff --git a/src/node/db/API.ts b/src/node/db/API.ts index 4de43f52e..56b5ffa91 100644 --- a/src/node/db/API.ts +++ b/src/node/db/API.ts @@ -654,6 +654,52 @@ exports.copyPadWithoutHistory = async (sourceID: string, destinationID: string, await pad.copyPadWithoutHistory(destinationID, force, authorId); }; +/** +compactPad(padID, [keepRevisions]) collapses the pad's revision history to +reclaim database space (issue #6194). Wraps the existing `Cleanup` helper +so admins can trigger it over the public API / CLI rather than only +through the admin settings UI. + +Gated on `settings.cleanup.enabled` so the public API can't bypass the +same opt-in switch the admin/Cleanup path already requires. + +When `keepRevisions` is omitted (or `null`), all history is collapsed +into a single base revision that reproduces the current atext +(equivalent to a freshly-imported pad). When set to a positive integer +N, the pad keeps only its last N revisions (equivalent to +`cleanup.keepRevisions`). Pad text and chat history are preserved in +both modes. Destructive — recommend exporting the `.etherpad` snapshot +first. + +Example returns: + +{code: 0, message:"ok", data: {ok: true, mode: "all"}} +{code: 1, message:"padID does not exist", data: null} +{code: 1, message:"compactPad requires cleanup.enabled = true ...", data: null} + + @param {String} padID the id of the pad to compact + @param {Number|null} keepRevisions number of recent revisions to keep; + null / omitted collapses the full history +*/ +exports.compactPad = async (padID: string, keepRevisions: number | null = null) => { + if (!settings.cleanup.enabled) { + throw new CustomError( + 'compactPad requires cleanup.enabled = true in settings.json', 'apierror'); + } + const pad = await getPadSafe(padID, true); + const cleanup = require('../utils/Cleanup'); + if (keepRevisions == null) { + await cleanup.deleteAllRevisions(pad.id); + return {ok: true, mode: 'all'}; + } + const keep = Number(keepRevisions); + if (!Number.isInteger(keep) || keep < 0) { + throw new CustomError('keepRevisions must be a non-negative integer', 'apierror'); + } + const ok = await cleanup.deleteRevisions(pad.id, keep); + return {ok, mode: 'keepLast', keepRevisions: keep}; +}; + /** movePad(sourceID, destinationID[, force=false]) moves a pad. If force is true, the destination will be overwritten if it exists. diff --git a/src/node/handler/APIHandler.ts b/src/node/handler/APIHandler.ts index b1e111c47..ab1f9f563 100644 --- a/src/node/handler/APIHandler.ts +++ b/src/node/handler/APIHandler.ts @@ -142,9 +142,14 @@ version['1.3.0'] = { setText: ['padID', 'text', 'authorId'], }; +version['1.3.1'] = { + ...version['1.3.0'], + compactPad: ['padID', 'keepRevisions'], +}; + // set the latest available API version here -exports.latestApiVersion = '1.3.0'; +exports.latestApiVersion = '1.3.1'; // exports the versions so it can be used by the new Swagger endpoint exports.version = version; diff --git a/src/tests/backend/specs/compactPad.ts b/src/tests/backend/specs/compactPad.ts new file mode 100644 index 000000000..32d9d6942 --- /dev/null +++ b/src/tests/backend/specs/compactPad.ts @@ -0,0 +1,347 @@ +'use strict'; + +import {generateJWTToken} from "../common"; + +const assert = require('assert').strict; +const common = require('../common'); +const padManager = require('../../../node/db/PadManager'); +const api = require('../../../node/db/API'); +const settings = require('../../../node/utils/Settings'); + +// Coverage for the compactPad API endpoint added in #6194. +// The underlying Cleanup logic is tested where it lives; these tests just +// verify the public-API wiring and argument handling. +describe(__filename, function () { + let padId: string; + let agent: any; + let cleanupEnabledBackup: boolean; + + before(async function () { + agent = await common.init(); + // compactPad is gated on cleanup.enabled (matches the admin/Cleanup + // path). Enable it for the duration of these tests and restore after, + // and add a focused spec below that asserts the gate. + cleanupEnabledBackup = settings.cleanup.enabled; + settings.cleanup.enabled = true; + }); + + after(function () { settings.cleanup.enabled = cleanupEnabledBackup; }); + + beforeEach(async function () { + padId = common.randomString(); + assert(!await padManager.doesPadExist(padId)); + }); + + describe('API.compactPad()', function () { + it('collapses all history when keepRevisions is omitted', async function () { + const pad = await padManager.getPad(padId); + await pad.appendText('marker-alpha\n'); + await pad.appendText('marker-beta\n'); + await pad.appendText('marker-gamma\n'); + const before = pad.getHeadRevisionNumber(); + assert.ok(before >= 3, `expected at least 3 revs, got ${before}`); + + const result = await api.compactPad(padId); + assert.deepStrictEqual(result, {ok: true, mode: 'all'}); + + // Reload: the compacted pad lands at head<=1 (matches the shape + // `copyPadWithoutHistory` produces). The content survives — we + // don't assert byte-exact equality because Cleanup.deleteAllRevisions + // goes through copyPadWithoutHistory twice and may adjust trailing + // whitespace; what we care about is that the author-written content + // is still there. + const reloaded = await padManager.getPad(padId); + assert.ok(reloaded.getHeadRevisionNumber() <= 1, + `expected head<=1, got ${reloaded.getHeadRevisionNumber()}`); + const text = reloaded.atext.text; + assert.ok(text.includes('marker-alpha'), 'alpha content preserved'); + assert.ok(text.includes('marker-beta'), 'beta content preserved'); + assert.ok(text.includes('marker-gamma'), 'gamma content preserved'); + }); + + it('keeps only the last N revisions when keepRevisions is a number', + async function () { + const pad = await padManager.getPad(padId); + for (let i = 0; i < 6; i++) await pad.appendText(`keep-line-${i}\n`); + const before = pad.getHeadRevisionNumber(); + + const result = await api.compactPad(padId, 2); + assert.strictEqual(result.mode, 'keepLast'); + assert.strictEqual(result.keepRevisions, 2); + + const reloaded = await padManager.getPad(padId); + assert.ok(reloaded.getHeadRevisionNumber() <= before); + // Content survives — whitespace normalization from the twin-copy + // roundtrip is ignored, we just check the actual text markers. + for (let i = 0; i < 6; i++) { + assert.ok(reloaded.atext.text.includes(`keep-line-${i}`), + `line ${i} survived compaction`); + } + }); + + it('rejects negative keepRevisions', async function () { + const pad = await padManager.getPad(padId); + await pad.appendText('content\n'); + await assert.rejects( + () => api.compactPad(padId, -1), + /keepRevisions must be a non-negative integer/); + }); + + it('rejects non-numeric keepRevisions', async function () { + const pad = await padManager.getPad(padId); + await pad.appendText('content\n'); + await assert.rejects( + // @ts-ignore - deliberately passing an invalid type + () => api.compactPad(padId, 'nope'), + /keepRevisions must be a non-negative integer/); + }); + + it('rejects fractional keepRevisions', async function () { + // 2.5 is finite + non-negative but not an integer — Cleanup.deleteRevisions + // does revision-index arithmetic that assumes integer math, so we + // reject at the API boundary instead of letting it silently misbehave. + const pad = await padManager.getPad(padId); + await pad.appendText('content\n'); + await assert.rejects( + () => api.compactPad(padId, 2.5), + /keepRevisions must be a non-negative integer/); + }); + + it('refuses to run when cleanup.enabled is false', async function () { + // Mirrors the admin/Cleanup-socket path: same opt-in, same surface + // area. An operator who hasn't reviewed the cleanup story shouldn't + // get destructive compaction by default just because the API is + // exposed. + settings.cleanup.enabled = false; + try { + const pad = await padManager.getPad(padId); + await pad.appendText('content\n'); + await assert.rejects( + () => api.compactPad(padId), + /cleanup\.enabled = true/); + } finally { + settings.cleanup.enabled = true; + } + }); + }); + + // Verifies the APIHandler dispatch wiring — i.e. that `keepRevisions` + // travels from the URL query string to the API function under the + // right argument name. This catches regressions where the handler's + // version map gets renamed without updating the function signature. + describe('HTTP API dispatch (1.3.1)', function () { + it('passes keepRevisions from query string into compactPad', async function () { + const pad = await padManager.getPad(padId); + for (let i = 0; i < 5; i++) await pad.appendText(`http-line-${i}\n`); + + const res = await agent.get( + `/api/1.3.1/compactPad?padID=${padId}&keepRevisions=2`) + .set('authorization', await generateJWTToken()) + .expect(200) + .expect('Content-Type', /json/); + + assert.strictEqual(res.body.code, 0, JSON.stringify(res.body)); + assert.strictEqual(res.body.data.mode, 'keepLast'); + assert.strictEqual(res.body.data.keepRevisions, 2); + }); + + it('collapses all history when keepRevisions is absent from URL', async function () { + const pad = await padManager.getPad(padId); + for (let i = 0; i < 3; i++) await pad.appendText(`http-all-${i}\n`); + + const res = await agent.get(`/api/1.3.1/compactPad?padID=${padId}`) + .set('authorization', await generateJWTToken()) + .expect(200) + .expect('Content-Type', /json/); + + assert.strictEqual(res.body.code, 0, JSON.stringify(res.body)); + assert.deepStrictEqual(res.body.data, {ok: true, mode: 'all'}); + }); + }); + + // Coverage for the per-instance bulk-compaction loop in + // bin/compactAllPads.ts. We test the exported `runCompactAll` against + // an in-memory CompactAllApi rather than spawning the script + axios, + // so we don't have to stand up an APIKEY-auth path. The CLI shell that + // wires axios+APIKEY is a thin adapter; the loop logic — error + // tolerance, dry-run, keep-last, tally — is what regresses, and that + // is what this exercises. + describe('runCompactAll (bin/compactAllPads loop)', function () { + // Imported lazily so module-load-time side effects in compactAllPads + // (require.main check) don't trip on the mocha runner. + // eslint-disable-next-line @typescript-eslint/no-var-requires + const {runCompactAll, parseArgs} = require('../../../../bin/compactAllPads'); + + const silent = {info: () => {}, error: () => {}}; + + // Builds a stub api that walks the same pad set as a real instance + // would, with optional per-pad failure injection. + type StubFails = {list?: boolean; count?: Set; compact?: Set}; + const makeApi = (padIds: string[], fails: StubFails = {}) => { + const counts = new Map(); + padIds.forEach((p) => counts.set(p, 5)); + return { + async listAllPads() { + if (fails.list) throw new Error('boom'); + return padIds.slice(); + }, + async getRevisionsCount(padId: string) { + if (fails.count?.has(padId)) throw new Error('count-boom'); + const c = counts.get(padId); + if (c == null) throw new Error('unknown pad'); + return c; + }, + async compactPad(padId: string, keepRevisions: number | null) { + if (fails.compact?.has(padId)) throw new Error('compact-boom'); + counts.set(padId, keepRevisions == null ? 0 : Math.min(counts.get(padId)!, keepRevisions)); + }, + }; + }; + + it('parses --keep / --dry-run / no args', function () { + assert.deepStrictEqual(parseArgs([]), + {keepRevisions: null, dryRun: false}); + assert.deepStrictEqual(parseArgs(['--dry-run']), + {keepRevisions: null, dryRun: true}); + assert.deepStrictEqual(parseArgs(['--keep', '3']), + {keepRevisions: 3, dryRun: false}); + assert.deepStrictEqual(parseArgs(['--keep', '3', '--dry-run']), + {keepRevisions: 3, dryRun: true}); + }); + + it('rejects --keep with non-integer / negative / unknown args', function () { + assert.strictEqual(parseArgs(['--keep', 'abc']), null); + assert.strictEqual(parseArgs(['--keep', '-1']), null); + assert.strictEqual(parseArgs(['--unknown']), null); + }); + + it('compacts every pad and tallies before/after revisions', async function () { + const api = makeApi(['p-a', 'p-b', 'p-c']); + const report = await runCompactAll(api, + {keepRevisions: null, dryRun: false}, silent); + assert.strictEqual(report.total, 3); + assert.strictEqual(report.ok, 3); + assert.strictEqual(report.failed, 0); + // Each pad starts with 5 (head) → 6 revisions; collapse → 0 head, 1 rev. + assert.strictEqual(report.totalRevsBefore, 18); + assert.strictEqual(report.totalRevsAfter, 3); + }); + + it('honours --keep N by passing it through to compactPad', async function () { + const seen: Array<[string, number | null]> = []; + const api = { + async listAllPads() { return ['p-x', 'p-y']; }, + async getRevisionsCount() { return 5; }, + async compactPad(padId: string, k: number | null) { seen.push([padId, k]); }, + }; + const report = await runCompactAll(api, + {keepRevisions: 2, dryRun: false}, silent); + assert.strictEqual(report.ok, 2); + assert.deepStrictEqual(seen, [['p-x', 2], ['p-y', 2]]); + }); + + it('--dry-run does not call compactPad', async function () { + let compactCalls = 0; + const api = { + async listAllPads() { return ['p-1', 'p-2']; }, + async getRevisionsCount() { return 4; }, + async compactPad() { compactCalls++; }, + }; + const report = await runCompactAll(api, + {keepRevisions: null, dryRun: true}, silent); + assert.strictEqual(compactCalls, 0); + assert.strictEqual(report.ok, 0); + assert.strictEqual(report.failed, 0); + assert.strictEqual(report.totalRevsBefore, 10); // 2 pads × (4+1) + assert.strictEqual(report.totalRevsAfter, 0); + }); + + it('keeps going when one pad fails to compact', async function () { + const api = makeApi(['ok-1', 'broken', 'ok-2'], + {compact: new Set(['broken'])}); + const report = await runCompactAll(api, + {keepRevisions: null, dryRun: false}, silent); + assert.strictEqual(report.total, 3); + assert.strictEqual(report.ok, 2); + assert.strictEqual(report.failed, 1); + }); + + it('keeps going when one pad fails the pre-flight count', async function () { + const api = makeApi(['ok-1', 'broken'], {count: new Set(['broken'])}); + const report = await runCompactAll(api, + {keepRevisions: null, dryRun: false}, silent); + assert.strictEqual(report.ok, 1); + assert.strictEqual(report.failed, 1); + }); + + it('reports listAllPads failure without iterating', async function () { + const api = makeApi(['a', 'b', 'c'], {list: true}); + const report = await runCompactAll(api, + {keepRevisions: null, dryRun: false}, silent); + assert.strictEqual(report.total, 0); + assert.strictEqual(report.failed, 1); + assert.strictEqual(report.ok, 0); + }); + + it('handles an empty instance', async function () { + const api = makeApi([]); + const report = await runCompactAll(api, + {keepRevisions: null, dryRun: false}, silent); + assert.deepStrictEqual(report, + {total: 0, ok: 0, failed: 0, totalRevsBefore: 0, totalRevsAfter: 0}); + }); + + // Plumbs the loop through the real /api/1.3.1/compactPad endpoint so + // we know the CLI's `cliApi` shape doesn't lie about its contract. + // Auth is JWT (matching the test agent) rather than APIKEY; the + // CLI path is otherwise identical. + it('end-to-end against the real HTTP handler', async function () { + const padA = common.randomString(); + const padB = common.randomString(); + const padObjA = await padManager.getPad(padA); + const padObjB = await padManager.getPad(padB); + for (let i = 0; i < 4; i++) await padObjA.appendText(`a-${i}\n`); + for (let i = 0; i < 4; i++) await padObjB.appendText(`b-${i}\n`); + const beforeA = padObjA.getHeadRevisionNumber(); + const beforeB = padObjB.getHeadRevisionNumber(); + assert.ok(beforeA >= 4 && beforeB >= 4); + + const httpApi = { + async listAllPads() { + // Only act on the pads this test created — the test DB is shared + // across describes, so other specs may have left pads behind. + return [padA, padB]; + }, + async getRevisionsCount(padId: string) { + const r = await agent.get( + `/api/1.3.1/getRevisionsCount?padID=${padId}`) + .set('authorization', await generateJWTToken()) + .expect(200); + if (r.body.code !== 0) throw new Error(JSON.stringify(r.body)); + return r.body.data.revisions; + }, + async compactPad(padId: string, keepRevisions: number | null) { + const url = keepRevisions == null + ? `/api/1.3.1/compactPad?padID=${padId}` + : `/api/1.3.1/compactPad?padID=${padId}&keepRevisions=${keepRevisions}`; + const r = await agent.get(url) + .set('authorization', await generateJWTToken()) + .expect(200); + if (r.body.code !== 0) throw new Error(JSON.stringify(r.body)); + }, + }; + + const report = await runCompactAll(httpApi, + {keepRevisions: null, dryRun: false}, silent); + assert.strictEqual(report.total, 2); + assert.strictEqual(report.ok, 2); + assert.strictEqual(report.failed, 0); + + // Both pads collapsed to head<=1. + const reA = await padManager.getPad(padA); + const reB = await padManager.getPad(padB); + assert.ok(reA.getHeadRevisionNumber() <= 1); + assert.ok(reB.getHeadRevisionNumber() <= 1); + }); + }); +});