@substrat-run/control-plane-api 0.49.0 → 0.51.0

package/dist/r2-backups.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The Cloudflare R2 implementation of the `ScopeBackupStore` seam (#493) — the platform's
+ * own backup bucket, bound on the control-plane worker.
+ *
+ * Structurally typed against the binding (`R2BucketLike`) rather than importing a
+ * Cloudflare SDK, the same way `adapter-cloudflare/src/r2.ts` wraps a tenant blob store:
+ * this package stays SDK-free and the fake in tests is an object literal.
+ *
+ * One bucket, held by the PLATFORM, not by the tenant. A tenant-held bucket would be
+ * deleted by the very teardown these copies exist to survive.
+ */
+import type { DirectoryBackupStore, ScopeBackupStore } from './backups.js';
+export declare function createR2BackupStore(bucket: unknown): ScopeBackupStore;
+/**
+ * The Cloudflare R2 implementation of `DirectoryBackupStore` (#40).
+ *
+ * Deliberately a separate factory over the SAME binding shape rather than a mode flag on
+ * `createR2BackupStore`: the two stores answer different questions and only this one can
+ * delete. A deployment may point them at one bucket or two — the prefixes keep them apart
+ * either way, and pointing THIS one at a bucket in another account is the upgrade path
+ * from "survives losing the directory" to "survives losing the account".
+ */
+export declare function createR2DirectoryBackupStore(bucket: unknown): DirectoryBackupStore;
+//# sourceMappingURL=r2-backups.d.ts.map

package/dist/r2-backups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2-backups.d.ts","sourceRoot":"","sources":["../src/r2-backups.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAsC3E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,CAsErE;AAcD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,OAAO,GAAG,oBAAoB,CAgElF"}

package/dist/r2-backups.js

@@ -0,0 +1,175 @@
+/**
+ * The Cloudflare R2 implementation of the `ScopeBackupStore` seam (#493) — the platform's
+ * own backup bucket, bound on the control-plane worker.
+ *
+ * Structurally typed against the binding (`R2BucketLike`) rather than importing a
+ * Cloudflare SDK, the same way `adapter-cloudflare/src/r2.ts` wraps a tenant blob store:
+ * this package stays SDK-free and the fake in tests is an object literal.
+ *
+ * One bucket, held by the PLATFORM, not by the tenant. A tenant-held bucket would be
+ * deleted by the very teardown these copies exist to survive.
+ */
+import { directoryDump, scopeDump, } from '@substrat-run/contracts';
+/**
+ * Keys are `scopes/<tenantId>/<scopeId>/<capturedAt>.json`, so a scope's copies are one
+ * prefix list and a tenant's are one level up. The scheme is private to this module —
+ * callers address a backup by (tenant, scope, capturedAt) and never build a path.
+ */
+function backupKey(tenantId, scopeId, capturedAt) {
+    return `scopes/${tenantId}/${scopeId}/${capturedAt}.json`;
+}
+function scopePrefix(tenantId, scopeId) {
+    return `scopes/${tenantId}/${scopeId}/`;
+}
+export function createR2BackupStore(bucket) {
+    const r2 = bucket;
+    return {
+        async put({ vertical, dump }) {
+            const body = JSON.stringify(dump);
+            // Byte length, not string length: the size is meant to be the stored object's,
+            // and a dump full of non-ASCII would otherwise under-report.
+            const size = new TextEncoder().encode(body).length;
+            const backup = {
+                tenantId: dump.tenantId,
+                scopeId: dump.scopeId,
+                vertical,
+                capturedAt: dump.capturedAt,
+                size,
+                tables: dump.tables.length,
+            };
+            await r2.put(backupKey(dump.tenantId, dump.scopeId, dump.capturedAt), body, {
+                httpMetadata: { contentType: 'application/json' },
+                // Mirrored into custom metadata so `list` can answer without fetching every
+                // dump — a scope's backups are megabytes, its listing is a table row.
+                customMetadata: {
+                    tenantId: backup.tenantId,
+                    scopeId: backup.scopeId,
+                    capturedAt: backup.capturedAt,
+                    tables: String(backup.tables),
+                    ...(vertical ? { vertical } : {}),
+                },
+            });
+            return backup;
+        },
+        async list({ tenantId, scopeId }) {
+            const prefix = scopePrefix(tenantId, scopeId);
+            const out = [];
+            let cursor;
+            do {
+                const page = await r2.list({
+                    prefix,
+                    include: ['customMetadata'],
+                    ...(cursor ? { cursor } : {}),
+                });
+                for (const o of page.objects) {
+                    const meta = o.customMetadata ?? {};
+                    // The key is the fallback address: an object written before the metadata
+                    // existed (or by a manual upload) still lists rather than vanishing.
+                    const capturedAt = meta.capturedAt ?? o.key.slice(prefix.length).replace(/\.json$/, '');
+                    out.push({
+                        tenantId,
+                        scopeId,
+                        vertical: meta.vertical ?? null,
+                        capturedAt,
+                        size: o.size,
+                        tables: meta.tables ? Number(meta.tables) : 0,
+                    });
+                }
+                cursor = page.truncated ? page.cursor : undefined;
+            } while (cursor);
+            // Newest first. ISO 8601 sorts lexicographically, which is why `capturedAt` is
+            // the key's last segment.
+            return out.sort((a, b) => (a.capturedAt < b.capturedAt ? 1 : -1));
+        },
+        async get({ tenantId, scopeId, capturedAt }) {
+            const obj = await r2.get(backupKey(tenantId, scopeId, capturedAt));
+            if (!obj)
+                return null;
+            // Parsed through the contract on the way out: a corrupted or hand-edited object
+            // fails HERE, loudly, rather than at the restore that trusted it.
+            return scopeDump.parse(JSON.parse(await obj.text()));
+        },
+    };
+}
+/**
+ * Keys are `directory/<capturedAt>.json` — one flat prefix, because there is exactly one
+ * directory per deployment and `capturedAt` is a copy's whole address. Sharing a bucket
+ * with the scope backups above is safe by construction: `scopes/` and `directory/` cannot
+ * collide, and neither prefix is ever built by a caller.
+ */
+function directoryKey(capturedAt) {
+    return `directory/${capturedAt}.json`;
+}
+const DIRECTORY_PREFIX = 'directory/';
+/**
+ * The Cloudflare R2 implementation of `DirectoryBackupStore` (#40).
+ *
+ * Deliberately a separate factory over the SAME binding shape rather than a mode flag on
+ * `createR2BackupStore`: the two stores answer different questions and only this one can
+ * delete. A deployment may point them at one bucket or two — the prefixes keep them apart
+ * either way, and pointing THIS one at a bucket in another account is the upgrade path
+ * from "survives losing the directory" to "survives losing the account".
+ */
+export function createR2DirectoryBackupStore(bucket) {
+    const r2 = bucket;
+    return {
+        async put({ dump }) {
+            const body = JSON.stringify(dump);
+            // Byte length, not string length — the size is the stored object's.
+            const size = new TextEncoder().encode(body).length;
+            const backup = {
+                capturedAt: dump.capturedAt,
+                size,
+                tables: dump.tables.length,
+            };
+            await r2.put(directoryKey(dump.capturedAt), body, {
+                httpMetadata: { contentType: 'application/json' },
+                // Mirrored into custom metadata so `list` answers without fetching every dump —
+                // a directory copy is megabytes, its listing is a table row.
+                customMetadata: {
+                    capturedAt: backup.capturedAt,
+                    tables: String(backup.tables),
+                },
+            });
+            return backup;
+        },
+        async list() {
+            const out = [];
+            let cursor;
+            do {
+                const page = await r2.list({
+                    prefix: DIRECTORY_PREFIX,
+                    include: ['customMetadata'],
+                    ...(cursor ? { cursor } : {}),
+                });
+                for (const o of page.objects) {
+                    const meta = o.customMetadata ?? {};
+                    // The key is the fallback address, as in the scope store: an object written
+                    // before the metadata existed still lists rather than vanishing.
+                    const capturedAt = meta.capturedAt ?? o.key.slice(DIRECTORY_PREFIX.length).replace(/\.json$/, '');
+                    out.push({
+                        capturedAt,
+                        size: o.size,
+                        tables: meta.tables ? Number(meta.tables) : 0,
+                    });
+                }
+                cursor = page.truncated ? page.cursor : undefined;
+            } while (cursor);
+            // Newest first — ISO 8601 sorts lexicographically, which is why `capturedAt` is
+            // the key's last segment. The daily-cadence guard reads element 0.
+            return out.sort((a, b) => (a.capturedAt < b.capturedAt ? 1 : -1));
+        },
+        async get({ capturedAt }) {
+            const obj = await r2.get(directoryKey(capturedAt));
+            if (!obj)
+                return null;
+            // Parsed through the contract on the way out, so a corrupted object fails HERE
+            // rather than half-way through the restore that trusted it.
+            return directoryDump.parse(JSON.parse(await obj.text()));
+        },
+        async delete({ capturedAt }) {
+            await r2.delete(directoryKey(capturedAt));
+        },
+    };
+}
+//# sourceMappingURL=r2-backups.js.map

package/dist/r2-backups.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@substrat-run/control-plane-api",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "HTTP surface over HostAdmin — the audited control-plane transport (control-plane.md §4.5)",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -23,20 +23,20 @@
   ],
   "dependencies": {
     "hono": "^4.6.0",
-    "@substrat-run/contracts": "^0.49.0",
-    "@substrat-run/kernel": "^0.49.0",
-    "@substrat-run/psl": "^0.2.0"
+    "@substrat-run/contracts": "^0.51.0",
+    "@substrat-run/psl": "^0.2.0",
+    "@substrat-run/kernel": "^0.51.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.13.0",
-    "@types/better-sqlite3": "^7.6.0",
+    "@types/better-sqlite3": "^9.6.0",
     "better-auth": "^1.6.23",
-    "better-sqlite3": "^12.0.0",
+    "better-sqlite3": "^13.0.3",
     "hono": "^4.6.0",
     "tsx": "^4.19.0",
     "typescript": "^7.0.0",
     "vitest": "^3.0.0",
-    "@substrat-run/adapter-sqlite": "^0.49.0"
+    "@substrat-run/adapter-sqlite": "^0.51.0"
   },
   "publishConfig": {
     "access": "public"