@softure-ai/backup 0.0.0-stage → 0.1.0

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.
Files changed (107) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/LICENSE +21 -0
  3. package/README.md +223 -2
  4. package/dist/cli/main.d.ts +3 -0
  5. package/dist/cli/main.d.ts.map +1 -0
  6. package/dist/cli/main.js +16 -0
  7. package/dist/cli/main.js.map +1 -0
  8. package/dist/cli/run.d.ts +12 -0
  9. package/dist/cli/run.d.ts.map +1 -0
  10. package/dist/cli/run.js +335 -0
  11. package/dist/cli/run.js.map +1 -0
  12. package/dist/contract.d.ts +41 -0
  13. package/dist/contract.d.ts.map +1 -0
  14. package/dist/contract.js +14 -0
  15. package/dist/contract.js.map +1 -0
  16. package/dist/index.d.ts +21 -0
  17. package/dist/index.d.ts.map +1 -0
  18. package/dist/index.js +30 -0
  19. package/dist/index.js.map +1 -0
  20. package/dist/messages/en.d.ts +16 -0
  21. package/dist/messages/en.d.ts.map +1 -0
  22. package/dist/messages/en.js +16 -0
  23. package/dist/messages/en.js.map +1 -0
  24. package/dist/messages/index.d.ts +21 -0
  25. package/dist/messages/index.d.ts.map +1 -0
  26. package/dist/messages/index.js +4 -0
  27. package/dist/messages/index.js.map +1 -0
  28. package/dist/offsite/config.d.ts +43 -0
  29. package/dist/offsite/config.d.ts.map +1 -0
  30. package/dist/offsite/config.js +130 -0
  31. package/dist/offsite/config.js.map +1 -0
  32. package/dist/offsite/crypto.d.ts +22 -0
  33. package/dist/offsite/crypto.d.ts.map +1 -0
  34. package/dist/offsite/crypto.js +48 -0
  35. package/dist/offsite/crypto.js.map +1 -0
  36. package/dist/offsite/index.d.ts +11 -0
  37. package/dist/offsite/index.d.ts.map +1 -0
  38. package/dist/offsite/index.js +13 -0
  39. package/dist/offsite/index.js.map +1 -0
  40. package/dist/offsite/lifecycle.d.ts +17 -0
  41. package/dist/offsite/lifecycle.d.ts.map +1 -0
  42. package/dist/offsite/lifecycle.js +45 -0
  43. package/dist/offsite/lifecycle.js.map +1 -0
  44. package/dist/offsite/objects.d.ts +19 -0
  45. package/dist/offsite/objects.d.ts.map +1 -0
  46. package/dist/offsite/objects.js +44 -0
  47. package/dist/offsite/objects.js.map +1 -0
  48. package/dist/offsite/postgres.d.ts +32 -0
  49. package/dist/offsite/postgres.d.ts.map +1 -0
  50. package/dist/offsite/postgres.js +97 -0
  51. package/dist/offsite/postgres.js.map +1 -0
  52. package/dist/offsite/restore.d.ts +54 -0
  53. package/dist/offsite/restore.d.ts.map +1 -0
  54. package/dist/offsite/restore.js +67 -0
  55. package/dist/offsite/restore.js.map +1 -0
  56. package/dist/offsite/s3.d.ts +34 -0
  57. package/dist/offsite/s3.d.ts.map +1 -0
  58. package/dist/offsite/s3.js +119 -0
  59. package/dist/offsite/s3.js.map +1 -0
  60. package/dist/offsite/sigv4.d.ts +19 -0
  61. package/dist/offsite/sigv4.d.ts.map +1 -0
  62. package/dist/offsite/sigv4.js +69 -0
  63. package/dist/offsite/sigv4.js.map +1 -0
  64. package/dist/offsite/status-sql.d.ts +10 -0
  65. package/dist/offsite/status-sql.d.ts.map +1 -0
  66. package/dist/offsite/status-sql.js +37 -0
  67. package/dist/offsite/status-sql.js.map +1 -0
  68. package/dist/offsite/upload.d.ts +33 -0
  69. package/dist/offsite/upload.d.ts.map +1 -0
  70. package/dist/offsite/upload.js +98 -0
  71. package/dist/offsite/upload.js.map +1 -0
  72. package/dist/offsite/verify.d.ts +32 -0
  73. package/dist/offsite/verify.d.ts.map +1 -0
  74. package/dist/offsite/verify.js +75 -0
  75. package/dist/offsite/verify.js.map +1 -0
  76. package/dist/schema.d.ts +150 -0
  77. package/dist/schema.d.ts.map +1 -0
  78. package/dist/schema.js +15 -0
  79. package/dist/schema.js.map +1 -0
  80. package/dist/server/index.d.ts +28 -0
  81. package/dist/server/index.d.ts.map +1 -0
  82. package/dist/server/index.js +98 -0
  83. package/dist/server/index.js.map +1 -0
  84. package/examples/backup-verify.yml +84 -0
  85. package/migrations/0001_create_runs.sql +21 -0
  86. package/module.json +12 -0
  87. package/package.json +67 -4
  88. package/src/cli/main.ts +16 -0
  89. package/src/cli/run.ts +338 -0
  90. package/src/contract.ts +46 -0
  91. package/src/index.ts +41 -0
  92. package/src/messages/en.ts +15 -0
  93. package/src/messages/index.ts +6 -0
  94. package/src/offsite/config.ts +157 -0
  95. package/src/offsite/crypto.ts +53 -0
  96. package/src/offsite/index.ts +31 -0
  97. package/src/offsite/lifecycle.ts +47 -0
  98. package/src/offsite/objects.ts +54 -0
  99. package/src/offsite/postgres.ts +115 -0
  100. package/src/offsite/restore.ts +108 -0
  101. package/src/offsite/s3.ts +144 -0
  102. package/src/offsite/sigv4.ts +84 -0
  103. package/src/offsite/status-sql.ts +45 -0
  104. package/src/offsite/upload.ts +116 -0
  105. package/src/offsite/verify.ts +97 -0
  106. package/src/schema.ts +17 -0
  107. package/src/server/index.ts +111 -0
@@ -0,0 +1,111 @@
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, type Meter } from "@opentelemetry/api";
5
+ import { ok, type HealthCheck } from "@softure-ai/core";
6
+ import type { Queryable } from "@softure-ai/db";
7
+ import { createLogger } from "@softure-ai/observability";
8
+ import { desc, eq, sql } from "drizzle-orm";
9
+ import type { BackupRun, BackupStatus } from "../contract.js";
10
+ import { runs } from "../schema.js";
11
+
12
+ const MAX_HISTORY = 100;
13
+ const DEFAULT_HISTORY = 10;
14
+ /** Metrics read the table at most this often, however often the exporter collects. */
15
+ const METRICS_CACHE_MS = 60_000;
16
+
17
+ type RunRow = typeof runs.$inferSelect;
18
+
19
+ function toRun(row: RunRow): BackupRun {
20
+ return {
21
+ startedAt: row.startedAt,
22
+ finishedAt: row.finishedAt,
23
+ result: row.result,
24
+ objects: row.objects,
25
+ sizeBytes: Number(row.sizeBytes),
26
+ error: row.errorCode === null ? null : { code: row.errorCode, message: row.errorMessage ?? "" },
27
+ };
28
+ }
29
+
30
+ /** The newest runs, newest first: `limit` from 1 to 100 (default 10). */
31
+ export async function listBackupRuns(db: Queryable, options: { limit?: number } = {}): Promise<BackupRun[]> {
32
+ const limit = Math.min(MAX_HISTORY, Math.max(1, Math.trunc(options.limit ?? DEFAULT_HISTORY)));
33
+ const rows = await db.select().from(runs).orderBy(desc(runs.startedAt), desc(runs.id)).limit(limit);
34
+ return rows.map(toRun);
35
+ }
36
+
37
+ /** The status for a settings screen: the newest run and the newest successful one. */
38
+ export async function getLastBackup(db: Queryable): Promise<BackupStatus> {
39
+ const [last] = await db.select().from(runs).orderBy(desc(runs.startedAt), desc(runs.id)).limit(1);
40
+ if (last === undefined) return { result: "not_configured", lastRun: null, lastSuccess: null };
41
+ const lastRun = toRun(last);
42
+ if (lastRun.result === "ok") return { result: "ok", lastRun, lastSuccess: lastRun };
43
+ const [success] = await db.select().from(runs).where(eq(runs.result, "ok")).orderBy(desc(runs.startedAt), desc(runs.id)).limit(1);
44
+ return { result: lastRun.result, lastRun, lastSuccess: success === undefined ? null : toRun(success) };
45
+ }
46
+
47
+ /** Seconds since the newest successful run finished; null when none ever succeeded. */
48
+ export function getLastSuccessAgeSeconds(status: BackupStatus, now: Date): number | null {
49
+ if (status.lastSuccess === null) return null;
50
+ return Math.max(0, Math.round((now.getTime() - status.lastSuccess.finishedAt.getTime()) / 1000));
51
+ }
52
+
53
+ export interface BackupMetricsOptions {
54
+ readonly db: Queryable;
55
+ /** The meter to register on; `metrics.getMeter("@softure-ai/backup")` by default. */
56
+ readonly meter?: Meter;
57
+ readonly now?: () => Date;
58
+ }
59
+
60
+ /**
61
+ * Observable gauges over the newest runs, exported with the app's metrics (`startObservability`):
62
+ * `softure.backup.last_success.age` (s, absent until a run succeeded; alert when above 93600, i.e. 26 h),
63
+ * `softure.backup.last_run.ok` (1 or 0), `softure.backup.last_run.size` (By), `softure.backup.last_run.duration` (s).
64
+ * Nothing is reported while no run is recorded. Returns a function that unregisters them.
65
+ */
66
+ export function registerBackupMetrics(options: BackupMetricsOptions): () => void {
67
+ const meter = options.meter ?? metrics.getMeter("@softure-ai/backup");
68
+ const now = options.now ?? (() => new Date());
69
+ const logger = createLogger("@softure-ai/backup");
70
+ let cached: { at: number; status: BackupStatus } | null = null;
71
+ const age = meter.createObservableGauge("softure.backup.last_success.age", { unit: "s", description: "Seconds since the newest successful off-site backup" });
72
+ const okGauge = meter.createObservableGauge("softure.backup.last_run.ok", { description: "1 when the newest off-site backup run succeeded, else 0" });
73
+ const size = meter.createObservableGauge("softure.backup.last_run.size", { unit: "By", description: "Encrypted bytes the newest off-site backup run uploaded" });
74
+ const duration = meter.createObservableGauge("softure.backup.last_run.duration", { unit: "s", description: "Duration of the newest off-site backup run" });
75
+
76
+ async function readStatus(): Promise<BackupStatus | null> {
77
+ const at = now().getTime();
78
+ if (cached !== null && at - cached.at < METRICS_CACHE_MS) return cached.status;
79
+ try {
80
+ const status = await getLastBackup(options.db);
81
+ cached = { at, status };
82
+ return status;
83
+ } catch (error) {
84
+ logger.warn("cannot read the off-site backup status", { error });
85
+ return null;
86
+ }
87
+ }
88
+
89
+ const callback = async (batch: { observe(gauge: typeof age, value: number): void }): Promise<void> => {
90
+ const status = await readStatus();
91
+ if (status?.lastRun == null) return;
92
+ const ageSeconds = getLastSuccessAgeSeconds(status, now());
93
+ if (ageSeconds !== null) batch.observe(age, ageSeconds);
94
+ batch.observe(okGauge, status.lastRun.result === "ok" ? 1 : 0);
95
+ batch.observe(size, status.lastRun.sizeBytes);
96
+ batch.observe(duration, (status.lastRun.finishedAt.getTime() - status.lastRun.startedAt.getTime()) / 1000);
97
+ };
98
+ meter.addBatchObservableCallback(callback, [age, okGauge, size, duration]);
99
+ return () => {
100
+ meter.removeBatchObservableCallback(callback, [age, okGauge, size, duration]);
101
+ };
102
+ }
103
+
104
+ /** For `GET /api/health` of `@softure-ai/ops`: the runs table exists and answers, i.e. `softure migrate` ran. */
105
+ export const checkRunsTable: HealthCheck = async (context) => {
106
+ // Core types `db` as unknown; the health route passes the @softure-ai/db handle.
107
+ const db = context.db as Queryable;
108
+ await db.execute(sql`select 1 from backup.runs limit 0`);
109
+ return ok();
110
+ };
111
+