@softure-ai/backup 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +30 -0
- package/LICENSE +21 -0
- package/README.md +243 -2
- package/dist/cli/main.d.ts +3 -0
- package/dist/cli/main.d.ts.map +1 -0
- package/dist/cli/main.js +16 -0
- package/dist/cli/main.js.map +1 -0
- package/dist/cli/run.d.ts +15 -0
- package/dist/cli/run.d.ts.map +1 -0
- package/dist/cli/run.js +442 -0
- package/dist/cli/run.js.map +1 -0
- package/dist/contract.d.ts +41 -0
- package/dist/contract.d.ts.map +1 -0
- package/dist/contract.js +15 -0
- package/dist/contract.js.map +1 -0
- package/dist/index.d.ts +22 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +30 -0
- package/dist/index.js.map +1 -0
- package/dist/messages/en.d.ts +17 -0
- package/dist/messages/en.d.ts.map +1 -0
- package/dist/messages/en.js +17 -0
- package/dist/messages/en.js.map +1 -0
- package/dist/messages/index.d.ts +22 -0
- package/dist/messages/index.d.ts.map +1 -0
- package/dist/messages/index.js +4 -0
- package/dist/messages/index.js.map +1 -0
- package/dist/offsite/config.d.ts +45 -0
- package/dist/offsite/config.d.ts.map +1 -0
- package/dist/offsite/config.js +147 -0
- package/dist/offsite/config.js.map +1 -0
- package/dist/offsite/crypto.d.ts +22 -0
- package/dist/offsite/crypto.d.ts.map +1 -0
- package/dist/offsite/crypto.js +48 -0
- package/dist/offsite/crypto.js.map +1 -0
- package/dist/offsite/dump.d.ts +23 -0
- package/dist/offsite/dump.d.ts.map +1 -0
- package/dist/offsite/dump.js +85 -0
- package/dist/offsite/dump.js.map +1 -0
- package/dist/offsite/index.d.ts +13 -0
- package/dist/offsite/index.d.ts.map +1 -0
- package/dist/offsite/index.js +15 -0
- package/dist/offsite/index.js.map +1 -0
- package/dist/offsite/lifecycle.d.ts +17 -0
- package/dist/offsite/lifecycle.d.ts.map +1 -0
- package/dist/offsite/lifecycle.js +45 -0
- package/dist/offsite/lifecycle.js.map +1 -0
- package/dist/offsite/objects.d.ts +19 -0
- package/dist/offsite/objects.d.ts.map +1 -0
- package/dist/offsite/objects.js +44 -0
- package/dist/offsite/objects.js.map +1 -0
- package/dist/offsite/postgres.d.ts +32 -0
- package/dist/offsite/postgres.d.ts.map +1 -0
- package/dist/offsite/postgres.js +97 -0
- package/dist/offsite/postgres.js.map +1 -0
- package/dist/offsite/record.d.ts +3 -0
- package/dist/offsite/record.d.ts.map +1 -0
- package/dist/offsite/record.js +10 -0
- package/dist/offsite/record.js.map +1 -0
- package/dist/offsite/restore.d.ts +54 -0
- package/dist/offsite/restore.d.ts.map +1 -0
- package/dist/offsite/restore.js +67 -0
- package/dist/offsite/restore.js.map +1 -0
- package/dist/offsite/s3.d.ts +34 -0
- package/dist/offsite/s3.d.ts.map +1 -0
- package/dist/offsite/s3.js +119 -0
- package/dist/offsite/s3.js.map +1 -0
- package/dist/offsite/sigv4.d.ts +19 -0
- package/dist/offsite/sigv4.d.ts.map +1 -0
- package/dist/offsite/sigv4.js +69 -0
- package/dist/offsite/sigv4.js.map +1 -0
- package/dist/offsite/status-sql.d.ts +10 -0
- package/dist/offsite/status-sql.d.ts.map +1 -0
- package/dist/offsite/status-sql.js +37 -0
- package/dist/offsite/status-sql.js.map +1 -0
- package/dist/offsite/upload.d.ts +33 -0
- package/dist/offsite/upload.d.ts.map +1 -0
- package/dist/offsite/upload.js +98 -0
- package/dist/offsite/upload.js.map +1 -0
- package/dist/offsite/verify.d.ts +32 -0
- package/dist/offsite/verify.d.ts.map +1 -0
- package/dist/offsite/verify.js +75 -0
- package/dist/offsite/verify.js.map +1 -0
- package/dist/schema.d.ts +150 -0
- package/dist/schema.d.ts.map +1 -0
- package/dist/schema.js +15 -0
- package/dist/schema.js.map +1 -0
- package/dist/server/index.d.ts +28 -0
- package/dist/server/index.d.ts.map +1 -0
- package/dist/server/index.js +98 -0
- package/dist/server/index.js.map +1 -0
- package/examples/backup-verify.yml +84 -0
- package/migrations/0001_create_runs.sql +21 -0
- package/module.json +12 -0
- package/package.json +73 -4
- package/src/cli/main.ts +16 -0
- package/src/cli/run.ts +441 -0
- package/src/contract.ts +47 -0
- package/src/index.ts +41 -0
- package/src/messages/en.ts +16 -0
- package/src/messages/index.ts +6 -0
- package/src/offsite/config.ts +173 -0
- package/src/offsite/crypto.ts +53 -0
- package/src/offsite/dump.ts +97 -0
- package/src/offsite/index.ts +33 -0
- package/src/offsite/lifecycle.ts +47 -0
- package/src/offsite/objects.ts +54 -0
- package/src/offsite/postgres.ts +115 -0
- package/src/offsite/record.ts +11 -0
- package/src/offsite/restore.ts +108 -0
- package/src/offsite/s3.ts +144 -0
- package/src/offsite/sigv4.ts +84 -0
- package/src/offsite/status-sql.ts +45 -0
- package/src/offsite/upload.ts +116 -0
- package/src/offsite/verify.ts +97 -0
- package/src/schema.ts +17 -0
- package/src/server/index.ts +111 -0
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
// What an app reads of the off-site backup: the newest run and the newest successful one for a settings screen, a
|
|
2
|
+
// short history, metrics for an alert ("off-site backup older than 26 h") and the module's health check. The rows
|
|
3
|
+
// are written on the host by `softure-backup upload` (deploy.sh maintain); no run recorded means not configured.
|
|
4
|
+
import { metrics } from "@opentelemetry/api";
|
|
5
|
+
import { ok } from "@softure-ai/core";
|
|
6
|
+
import { createLogger } from "@softure-ai/observability";
|
|
7
|
+
import { desc, eq, sql } from "drizzle-orm";
|
|
8
|
+
import { runs } from "../schema.js";
|
|
9
|
+
const MAX_HISTORY = 100;
|
|
10
|
+
const DEFAULT_HISTORY = 10;
|
|
11
|
+
/** Metrics read the table at most this often, however often the exporter collects. */
|
|
12
|
+
const METRICS_CACHE_MS = 60_000;
|
|
13
|
+
function toRun(row) {
|
|
14
|
+
return {
|
|
15
|
+
startedAt: row.startedAt,
|
|
16
|
+
finishedAt: row.finishedAt,
|
|
17
|
+
result: row.result,
|
|
18
|
+
objects: row.objects,
|
|
19
|
+
sizeBytes: Number(row.sizeBytes),
|
|
20
|
+
error: row.errorCode === null ? null : { code: row.errorCode, message: row.errorMessage ?? "" },
|
|
21
|
+
};
|
|
22
|
+
}
|
|
23
|
+
/** The newest runs, newest first: `limit` from 1 to 100 (default 10). */
|
|
24
|
+
export async function listBackupRuns(db, options = {}) {
|
|
25
|
+
const limit = Math.min(MAX_HISTORY, Math.max(1, Math.trunc(options.limit ?? DEFAULT_HISTORY)));
|
|
26
|
+
const rows = await db.select().from(runs).orderBy(desc(runs.startedAt), desc(runs.id)).limit(limit);
|
|
27
|
+
return rows.map(toRun);
|
|
28
|
+
}
|
|
29
|
+
/** The status for a settings screen: the newest run and the newest successful one. */
|
|
30
|
+
export async function getLastBackup(db) {
|
|
31
|
+
const [last] = await db.select().from(runs).orderBy(desc(runs.startedAt), desc(runs.id)).limit(1);
|
|
32
|
+
if (last === undefined)
|
|
33
|
+
return { result: "not_configured", lastRun: null, lastSuccess: null };
|
|
34
|
+
const lastRun = toRun(last);
|
|
35
|
+
if (lastRun.result === "ok")
|
|
36
|
+
return { result: "ok", lastRun, lastSuccess: lastRun };
|
|
37
|
+
const [success] = await db.select().from(runs).where(eq(runs.result, "ok")).orderBy(desc(runs.startedAt), desc(runs.id)).limit(1);
|
|
38
|
+
return { result: lastRun.result, lastRun, lastSuccess: success === undefined ? null : toRun(success) };
|
|
39
|
+
}
|
|
40
|
+
/** Seconds since the newest successful run finished; null when none ever succeeded. */
|
|
41
|
+
export function getLastSuccessAgeSeconds(status, now) {
|
|
42
|
+
if (status.lastSuccess === null)
|
|
43
|
+
return null;
|
|
44
|
+
return Math.max(0, Math.round((now.getTime() - status.lastSuccess.finishedAt.getTime()) / 1000));
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Observable gauges over the newest runs, exported with the app's metrics (`startObservability`):
|
|
48
|
+
* `softure.backup.last_success.age` (s, absent until a run succeeded; alert when above 93600, i.e. 26 h),
|
|
49
|
+
* `softure.backup.last_run.ok` (1 or 0), `softure.backup.last_run.size` (By), `softure.backup.last_run.duration` (s).
|
|
50
|
+
* Nothing is reported while no run is recorded. Returns a function that unregisters them.
|
|
51
|
+
*/
|
|
52
|
+
export function registerBackupMetrics(options) {
|
|
53
|
+
const meter = options.meter ?? metrics.getMeter("@softure-ai/backup");
|
|
54
|
+
const now = options.now ?? (() => new Date());
|
|
55
|
+
const logger = createLogger("@softure-ai/backup");
|
|
56
|
+
let cached = null;
|
|
57
|
+
const age = meter.createObservableGauge("softure.backup.last_success.age", { unit: "s", description: "Seconds since the newest successful off-site backup" });
|
|
58
|
+
const okGauge = meter.createObservableGauge("softure.backup.last_run.ok", { description: "1 when the newest off-site backup run succeeded, else 0" });
|
|
59
|
+
const size = meter.createObservableGauge("softure.backup.last_run.size", { unit: "By", description: "Encrypted bytes the newest off-site backup run uploaded" });
|
|
60
|
+
const duration = meter.createObservableGauge("softure.backup.last_run.duration", { unit: "s", description: "Duration of the newest off-site backup run" });
|
|
61
|
+
async function readStatus() {
|
|
62
|
+
const at = now().getTime();
|
|
63
|
+
if (cached !== null && at - cached.at < METRICS_CACHE_MS)
|
|
64
|
+
return cached.status;
|
|
65
|
+
try {
|
|
66
|
+
const status = await getLastBackup(options.db);
|
|
67
|
+
cached = { at, status };
|
|
68
|
+
return status;
|
|
69
|
+
}
|
|
70
|
+
catch (error) {
|
|
71
|
+
logger.warn("cannot read the off-site backup status", { error });
|
|
72
|
+
return null;
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
const callback = async (batch) => {
|
|
76
|
+
const status = await readStatus();
|
|
77
|
+
if (status?.lastRun == null)
|
|
78
|
+
return;
|
|
79
|
+
const ageSeconds = getLastSuccessAgeSeconds(status, now());
|
|
80
|
+
if (ageSeconds !== null)
|
|
81
|
+
batch.observe(age, ageSeconds);
|
|
82
|
+
batch.observe(okGauge, status.lastRun.result === "ok" ? 1 : 0);
|
|
83
|
+
batch.observe(size, status.lastRun.sizeBytes);
|
|
84
|
+
batch.observe(duration, (status.lastRun.finishedAt.getTime() - status.lastRun.startedAt.getTime()) / 1000);
|
|
85
|
+
};
|
|
86
|
+
meter.addBatchObservableCallback(callback, [age, okGauge, size, duration]);
|
|
87
|
+
return () => {
|
|
88
|
+
meter.removeBatchObservableCallback(callback, [age, okGauge, size, duration]);
|
|
89
|
+
};
|
|
90
|
+
}
|
|
91
|
+
/** For `GET /api/health` of `@softure-ai/ops`: the runs table exists and answers, i.e. `softure migrate` ran. */
|
|
92
|
+
export const checkRunsTable = async (context) => {
|
|
93
|
+
// Core types `db` as unknown; the health route passes the @softure-ai/db handle.
|
|
94
|
+
const db = context.db;
|
|
95
|
+
await db.execute(sql `select 1 from backup.runs limit 0`);
|
|
96
|
+
return ok();
|
|
97
|
+
};
|
|
98
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,kHAAkH;AAClH,kHAAkH;AAClH,iHAAiH;AACjH,OAAO,EAAE,OAAO,EAAc,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,EAAE,EAAoB,MAAM,kBAAkB,CAAC;AAExD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEpC,MAAM,WAAW,GAAG,GAAG,CAAC;AACxB,MAAM,eAAe,GAAG,EAAE,CAAC;AAC3B,sFAAsF;AACtF,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAIhC,SAAS,KAAK,CAAC,GAAW;IACxB,OAAO;QACL,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC;QAChC,KAAK,EAAE,GAAG,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,YAAY,IAAI,EAAE,EAAE;KAChG,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,EAAa,EAAE,OAAO,GAAuB,EAAE;IAClF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC;IAC/F,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACpG,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC;AAED,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAAa;IAC/C,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAClG,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAC9F,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;IACpF,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAClI,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;AACzG,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,wBAAwB,CAAC,MAAoB,EAAE,GAAS;IACtE,IAAI,MAAM,CAAC,WAAW,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AACnG,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAA6B;IACjE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC;IACtE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,YAAY,CAAC,oBAAoB,CAAC,CAAC;IAClD,IAAI,MAAM,GAAgD,IAAI,CAAC;IAC/D,MAAM,GAAG,GAAG,KAAK,CAAC,qBAAqB,CAAC,iCAAiC,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,qDAAqD,EAAE,CAAC,CAAC;IAC9J,MAAM,OAAO,GAAG,KAAK,CAAC,qBAAqB,CAAC,4BAA4B,EAAE,EAAE,WAAW,EAAE,yDAAyD,EAAE,CAAC,CAAC;IACtJ,MAAM,IAAI,GAAG,KAAK,CAAC,qBAAqB,CAAC,8BAA8B,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,yDAAyD,EAAE,CAAC,CAAC;IACjK,MAAM,QAAQ,GAAG,KAAK,CAAC,qBAAqB,CAAC,kCAAkC,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,4CAA4C,EAAE,CAAC,CAAC;IAE3J,KAAK,UAAU,UAAU;QACvB,MAAM,EAAE,GAAG,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;QAC3B,IAAI,MAAM,KAAK,IAAI,IAAI,EAAE,GAAG,MAAM,CAAC,EAAE,GAAG,gBAAgB;YAAE,OAAO,MAAM,CAAC,MAAM,CAAC;QAC/E,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAC/C,MAAM,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;YACxB,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,wCAAwC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YACjE,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,EAAE,KAA0D,EAAiB,EAAE;QACnG,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;QAClC,IAAI,MAAM,EAAE,OAAO,IAAI,IAAI;YAAE,OAAO;QACpC,MAAM,UAAU,GAAG,wBAAwB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QAC3D,IAAI,UAAU,KAAK,IAAI;YAAE,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QACxD,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/D,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC9C,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAC7G,CAAC,CAAC;IACF,KAAK,CAAC,0BAA0B,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC3E,OAAO,GAAG,EAAE;QACV,KAAK,CAAC,6BAA6B,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChF,CAAC,CAAC;AACJ,CAAC;AAED,iHAAiH;AACjH,MAAM,CAAC,MAAM,cAAc,GAAgB,KAAK,EAAE,OAAO,EAAE,EAAE;IAC3D,iFAAiF;IACjF,MAAM,EAAE,GAAG,OAAO,CAAC,EAAe,CAAC;IACnC,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAA,mCAAmC,CAAC,CAAC;IACzD,OAAO,EAAE,EAAE,CAAC;AACd,CAAC,CAAC"}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# The weekly check of the off-site backup (@softure-ai/backup), for an adopting app's repository: copy this file to
|
|
2
|
+
# .github/workflows/backup-verify.yml. It downloads the newest encrypted dump with the read-only token, restores it into
|
|
3
|
+
# a throwaway Postgres of the server's major version, runs the schema guard against the migrations of the live image
|
|
4
|
+
# and counts the rows of deploy.json's database.rowCountTables, then drops it. A copy older than 26 hours, one that
|
|
5
|
+
# does not decrypt or restore, a missing table or a failed guard fails the run, and GitHub mails the failure.
|
|
6
|
+
#
|
|
7
|
+
# Settings live in the GitHub Environment `backup-verify`, which only this workflow uses (never the deploy's):
|
|
8
|
+
# variables: BACKUP_S3_ENDPOINT, BACKUP_S3_REGION, BACKUP_S3_BUCKET, BACKUP_S3_PREFIX (the app's prefix)
|
|
9
|
+
# secrets: BACKUP_S3_READ_ACCESS_KEY_ID, BACKUP_S3_READ_SECRET_ACCESS_KEY (the read-only token)
|
|
10
|
+
# BACKUP_AGE_IDENTITY (the age private key, AGE-SECRET-KEY-1…)
|
|
11
|
+
# Keeping the private key here is a trade-off: it lets the check run every week without the owner, and it never reaches
|
|
12
|
+
# the server. An owner who keeps the key offline only runs the same `softure-backup verify` on their own machine
|
|
13
|
+
# instead (modules/backup/README.md, "Restore and verify").
|
|
14
|
+
#
|
|
15
|
+
# Adjust IMAGE (the app's image, with a tag the registry keeps for the live release) and the postgres image's major.
|
|
16
|
+
name: backup verify
|
|
17
|
+
|
|
18
|
+
on:
|
|
19
|
+
schedule:
|
|
20
|
+
# Monday 05:40 UTC, after the night's maintain (03:17 server time) has uploaded.
|
|
21
|
+
- cron: "40 5 * * 1"
|
|
22
|
+
workflow_dispatch:
|
|
23
|
+
|
|
24
|
+
permissions:
|
|
25
|
+
contents: read
|
|
26
|
+
packages: read
|
|
27
|
+
|
|
28
|
+
jobs:
|
|
29
|
+
verify:
|
|
30
|
+
runs-on: ubuntu-latest
|
|
31
|
+
environment: backup-verify
|
|
32
|
+
timeout-minutes: 60
|
|
33
|
+
services:
|
|
34
|
+
postgres:
|
|
35
|
+
# The server's major version: pg_restore must be at least as new as the pg_dump that wrote the copy.
|
|
36
|
+
image: postgres:17
|
|
37
|
+
env:
|
|
38
|
+
POSTGRES_PASSWORD: postgres
|
|
39
|
+
ports:
|
|
40
|
+
- 5432:5432
|
|
41
|
+
options: >-
|
|
42
|
+
--health-cmd "pg_isready -U postgres"
|
|
43
|
+
--health-interval 5s
|
|
44
|
+
--health-timeout 5s
|
|
45
|
+
--health-retries 10
|
|
46
|
+
env:
|
|
47
|
+
IMAGE: ghcr.io/acme/app:latest
|
|
48
|
+
steps:
|
|
49
|
+
- uses: actions/checkout@v7
|
|
50
|
+
- uses: actions/setup-node@v7
|
|
51
|
+
with:
|
|
52
|
+
node-version: 22
|
|
53
|
+
# The migrations the live image ships, for the schema guard.
|
|
54
|
+
- name: Read the migrations of the live image
|
|
55
|
+
env:
|
|
56
|
+
REGISTRY_TOKEN: ${{ github.token }}
|
|
57
|
+
run: |
|
|
58
|
+
printf '%s' "$REGISTRY_TOKEN" | docker login ghcr.io --username "$GITHUB_ACTOR" --password-stdin
|
|
59
|
+
container="$(docker create "$IMAGE")"
|
|
60
|
+
docker cp "$container:/app/softure-migrations" ./softure-migrations
|
|
61
|
+
docker rm "$container" > /dev/null
|
|
62
|
+
# pg_restore of the server's major, from the same image as the throwaway database.
|
|
63
|
+
- name: PostgreSQL tools
|
|
64
|
+
run: |
|
|
65
|
+
cat > "$RUNNER_TEMP/pg_restore" <<'WRAPPER'
|
|
66
|
+
#!/usr/bin/env bash
|
|
67
|
+
exec docker run --rm -i --network host -e PGHOST -e PGPORT -e PGUSER -e PGPASSWORD -e PGDATABASE postgres:17 pg_restore "$@"
|
|
68
|
+
WRAPPER
|
|
69
|
+
chmod +x "$RUNNER_TEMP/pg_restore"
|
|
70
|
+
echo "BACKUP_PG_RESTORE=$RUNNER_TEMP/pg_restore" >> "$GITHUB_ENV"
|
|
71
|
+
- name: Verify the newest off-site copy
|
|
72
|
+
env:
|
|
73
|
+
BACKUP_S3_ENDPOINT: ${{ vars.BACKUP_S3_ENDPOINT }}
|
|
74
|
+
BACKUP_S3_REGION: ${{ vars.BACKUP_S3_REGION }}
|
|
75
|
+
BACKUP_S3_BUCKET: ${{ vars.BACKUP_S3_BUCKET }}
|
|
76
|
+
BACKUP_S3_PREFIX: ${{ vars.BACKUP_S3_PREFIX }}
|
|
77
|
+
BACKUP_S3_READ_ACCESS_KEY_ID: ${{ secrets.BACKUP_S3_READ_ACCESS_KEY_ID }}
|
|
78
|
+
BACKUP_S3_READ_SECRET_ACCESS_KEY: ${{ secrets.BACKUP_S3_READ_SECRET_ACCESS_KEY }}
|
|
79
|
+
BACKUP_AGE_IDENTITY: ${{ secrets.BACKUP_AGE_IDENTITY }}
|
|
80
|
+
BACKUP_VERIFY_DATABASE_URL: postgresql://postgres:postgres@localhost:5432/postgres
|
|
81
|
+
# The key goes in on stdin, never as an argument.
|
|
82
|
+
run: |
|
|
83
|
+
printf '%s\n' "$BACKUP_AGE_IDENTITY" \
|
|
84
|
+
| npx --yes @softure-ai/backup@0.1.0 verify --identity=- --config=deploy.json --migrations-dir=softure-migrations
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
-- One row per off-site backup run of the host (`softure-backup upload`, called by deploy.sh maintain): when it ran,
|
|
2
|
+
-- how it ended, and the objects it uploaded. Written by the host run as the postgres superuser, read by the app
|
|
3
|
+
-- (`getLastBackup`, `listBackupRuns`, the backup metrics). Errors are safe codes and messages, never a secret.
|
|
4
|
+
-- Rollback: DROP TABLE backup.runs; then
|
|
5
|
+
-- DELETE FROM softure.migrations WHERE module = 'backup' AND version = 1;
|
|
6
|
+
CREATE TABLE runs (
|
|
7
|
+
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
|
|
8
|
+
started_at timestamptz NOT NULL,
|
|
9
|
+
finished_at timestamptz NOT NULL CHECK (finished_at >= started_at),
|
|
10
|
+
result text NOT NULL CHECK (result IN ('ok', 'failed', 'not_configured')),
|
|
11
|
+
-- [{ "kind": "database" | "data", "key", "bytes", "sha256" }], one per uploaded object.
|
|
12
|
+
objects jsonb NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(objects) = 'array'),
|
|
13
|
+
-- The encrypted bytes uploaded in this run.
|
|
14
|
+
size_bytes bigint NOT NULL DEFAULT 0 CHECK (size_bytes >= 0),
|
|
15
|
+
error_code text CHECK (char_length(error_code) <= 64),
|
|
16
|
+
error_message text CHECK (char_length(error_message) <= 500),
|
|
17
|
+
CHECK ((result = 'failed') = (error_code IS NOT NULL))
|
|
18
|
+
);
|
|
19
|
+
|
|
20
|
+
CREATE INDEX runs_started_at_idx ON runs (started_at DESC);
|
|
21
|
+
CREATE INDEX runs_ok_started_at_idx ON runs (started_at DESC) WHERE result = 'ok';
|
package/module.json
ADDED
package/package.json
CHANGED
|
@@ -1,6 +1,75 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@softure-ai/backup",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "SOFTURE AI off-site backup: encrypts each nightly dump of @softure-ai/deploy with age to a public key, uploads it to any S3-compatible store with a write-only token, records every run for the app (getLastBackup, OpenTelemetry metrics), and restores or verifies an off-site copy with a private key that never reaches the server.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"sideEffects": false,
|
|
8
|
+
"engines": {
|
|
9
|
+
"node": ">=22"
|
|
10
|
+
},
|
|
11
|
+
"repository": {
|
|
12
|
+
"type": "git",
|
|
13
|
+
"url": "git+https://github.com/SOFTURE/AI.git",
|
|
14
|
+
"directory": "modules/backup"
|
|
15
|
+
},
|
|
16
|
+
"files": [
|
|
17
|
+
"dist",
|
|
18
|
+
"CHANGELOG.md",
|
|
19
|
+
"src",
|
|
20
|
+
"!src/**/*.test.ts",
|
|
21
|
+
"!src/**/*.test.tsx",
|
|
22
|
+
"migrations",
|
|
23
|
+
"module.json",
|
|
24
|
+
"examples"
|
|
25
|
+
],
|
|
26
|
+
"publishConfig": {
|
|
27
|
+
"access": "public",
|
|
28
|
+
"provenance": true
|
|
29
|
+
},
|
|
30
|
+
"bin": {
|
|
31
|
+
"softure-backup": "./dist/cli/main.js"
|
|
32
|
+
},
|
|
33
|
+
"exports": {
|
|
34
|
+
".": {
|
|
35
|
+
"@softure-ai/source": "./src/index.ts",
|
|
36
|
+
"types": "./dist/index.d.ts",
|
|
37
|
+
"default": "./dist/index.js"
|
|
38
|
+
},
|
|
39
|
+
"./server": {
|
|
40
|
+
"@softure-ai/source": "./src/server/index.ts",
|
|
41
|
+
"types": "./dist/server/index.d.ts",
|
|
42
|
+
"default": "./dist/server/index.js"
|
|
43
|
+
},
|
|
44
|
+
"./offsite": {
|
|
45
|
+
"@softure-ai/source": "./src/offsite/index.ts",
|
|
46
|
+
"types": "./dist/offsite/index.d.ts",
|
|
47
|
+
"default": "./dist/offsite/index.js"
|
|
48
|
+
}
|
|
49
|
+
},
|
|
50
|
+
"softure": {
|
|
51
|
+
"workers": [
|
|
52
|
+
".",
|
|
53
|
+
"./server"
|
|
54
|
+
]
|
|
55
|
+
},
|
|
56
|
+
"scripts": {
|
|
57
|
+
"build": "tsc -p tsconfig.build.json"
|
|
58
|
+
},
|
|
59
|
+
"dependencies": {
|
|
60
|
+
"@opentelemetry/api": "^1.10.0",
|
|
61
|
+
"@softure-ai/core": "^0.2.7",
|
|
62
|
+
"@softure-ai/db": "^0.1.14",
|
|
63
|
+
"@softure-ai/deploy": "^0.6.0 || ^0.7.0",
|
|
64
|
+
"@softure-ai/observability": "^0.8.2",
|
|
65
|
+
"age-encryption": "^0.3.1",
|
|
66
|
+
"pg": "^8.23.1",
|
|
67
|
+
"zod": "^4.6.7"
|
|
68
|
+
},
|
|
69
|
+
"devDependencies": {
|
|
70
|
+
"@types/pg": "^8.23.1"
|
|
71
|
+
},
|
|
72
|
+
"peerDependencies": {
|
|
73
|
+
"drizzle-orm": "^0.45.2"
|
|
74
|
+
}
|
|
75
|
+
}
|
package/src/cli/main.ts
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { runCli } from "./run.js";
|
|
3
|
+
|
|
4
|
+
async function readStdin(): Promise<string> {
|
|
5
|
+
const chunks: Buffer[] = [];
|
|
6
|
+
for await (const chunk of process.stdin) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : (chunk as Buffer));
|
|
7
|
+
return Buffer.concat(chunks).toString("utf8");
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
process.exitCode = await runCli(process.argv.slice(2), {
|
|
11
|
+
cwd: process.cwd(),
|
|
12
|
+
env: process.env,
|
|
13
|
+
stdout: (text) => process.stdout.write(text),
|
|
14
|
+
stderr: (text) => process.stderr.write(text),
|
|
15
|
+
readStdin,
|
|
16
|
+
});
|