@geekmidas/cli 10.0.0-alpha.12 → 10.0.0-alpha.121

package/dist/backups/runner.d.cts

@@ -0,0 +1,102 @@
+//#region src/backups/runner.d.ts
+/**
+ * The backups container's program: `pg_dump` each of the stack's databases
+ * on schedule and stream it, gzipped, to the stage's backups prefix.
+ *
+ * It ships alone — copied into an image built `FROM postgres:<major>-alpine`
+ * with Node added — so it imports nothing but Node's own modules: S3 is
+ * spoken to with a SigV4 signature made here, not the AWS SDK.
+ *
+ *   node backup.mjs serve    run on schedule, forever (the container's command)
+ *   node backup.mjs run      one backup now (`gkm backup:now`)
+ *   node backup.mjs health   exit 1 when the last good run is too old
+ *
+ * Its key may only put objects under the prefix: it never reads, lists or
+ * deletes, so nothing here does either. A dump is uploaded in parts as it is
+ * made, so no database is ever held on disk or in memory whole.
+ *
+ * Environment:
+ *
+ * - `BACKUPS_URL` — `s3://KEY:SECRET@bucket?region=…`, the stage's backups key
+ * - `BACKUPS_PREFIX` — `gkm/<project>/<stage>/backups`
+ * - `BACKUPS_DATABASES` — `[{"file":"auth-database","name":"auth_database_production"}]`
+ * - `BACKUPS_SCHEDULE` — `{"kind":"every","seconds":86400,"offset":7200}`, or
+ *   a cron expanded: `{"kind":"cron","minutes":[0],"hours":[0,6,12,18],…}`
+ * - `BACKUPS_MAX_GAP_SECONDS` — the longest the schedule goes between runs
+ * - `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD` — read by `pg_dump` itself
+ * - `OTEL_EXPORTER_OTLP_ENDPOINT`/`_HEADERS` — where each run's result is
+ *   also sent as an OTLP log, when the stage's telemetry is on
+ */
+export interface IntervalSchedule {
+  kind: 'every';
+  seconds: number;
+  offset: number;
+}
+export interface CronSchedule {
+  kind: 'cron';
+  minutes: number[];
+  hours: number[];
+  days: number[] | null;
+  months: number[] | null;
+  weekdays: number[] | null;
+}
+export type Schedule = IntervalSchedule | CronSchedule;
+/**
+ * The first time after `after`, to the minute, the schedule runs — the copy
+ * of `schedule.ts`'s `nextRun` this file carries, since it ships alone.
+ */
+export declare function nextRun(schedule: Schedule, after: Date): Date | null;
+/** One run's folder: `2026-10-10/02-00-00Z`. */
+export declare function runFolder(at: Date): string;
+/** Where and as whom the backups are put. */
+export interface Destination {
+  bucket: string;
+  region: string;
+  endpoint?: string;
+  forcePathStyle: boolean;
+  accessKeyId: string;
+  secretAccessKey: string;
+}
+/** `BACKUPS_URL`, read the way `@geekmidas/storage/s3-url` writes it. */
+export declare function destination(url: string): Destination;
+interface S3Request {
+  method: 'PUT' | 'POST';
+  key: string;
+  query?: Record<string, string>;
+  body?: Buffer;
+  headers?: Record<string, string>;
+}
+/** One request to S3, signed with SigV4; the response's status and body. */
+export declare function s3Send(to: Destination, request: S3Request, now?: Date): Promise<{
+  status: number;
+  body: string;
+  headers: Record<string, string>;
+}>;
+/**
+ * Upload a stream to `key`: one PUT when it fits in a part, else a multipart
+ * upload — every action of which is `s3:PutObject`, all the key may do. A
+ * failed upload is left for the bucket's lifecycle to abort.
+ */
+export declare function upload(to: Destination, key: string, stream: AsyncIterable<Buffer>,
+/**
+ * How what made the stream ended. Awaited before the last request: a dump
+ * that failed half way ends its stream early, and must never be put as
+ * though it were whole.
+ */
+finished?: Promise<void>): Promise<number>;
+export interface BackupDatabase {
+  file: string;
+  name: string;
+}
+/** Be handed each line the runner logs. Returns what stops it. */
+export declare function onReport(listener: (line: Record<string, unknown>) => void): () => void;
+/** One backup of every database, into one run folder. Resolves whether it all went. */
+export declare function backupOnce(at?: Date): Promise<boolean>;
+/** Whether the last good run — or, before one, the start — is recent enough. */
+export declare function healthy(now?: number): boolean;
+/** Run on schedule, forever. */
+export declare function serve(): Promise<void>;
+/** What `node backup.mjs <command>` runs; resolves with its exit code. */
+export declare function main(command: string | undefined): Promise<number>;
+//#endregion
+//# sourceMappingURL=runner.d.cts.map

package/dist/backups/runner.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.cts","names":[],"sources":["../../src/backups/runner.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiDiB;EAChB;EACA;EACA;;iBAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;;YAGW,WAAW,mBAAmB;;;;;wBAqB1B,QAAQ,UAAU,UAAU,OAAO,OAAO;;wBA2B1C,UAAU,IAAI;;iBAUb;EAChB;EACA;EACA;EACA;EACA;EACA;;;wBAIe,YAAY,cAAc;UAgChC;EACT;EACA;EACA,QAAQ;EACR,OAAO;EACP,UAAU;;;wBAIW,OACrB,IAAI,aACJ,SAAS,WACT,MAAK,OACH;EAAU;EAAgB;EAAc,SAAS;;;;;;;wBAoK9B,OACrB,IAAI,aACJ,aACA,QAAQ,cAAc,SAMtB;;;;;;AAAA,WAAU,gBACR;iBA0Ec;EAChB;EACA;;;wBAOe,SACf,WAAW,MAAM;;wBA2JI,WAAW,KAAI,OAAoB;;wBA6DzC,QAAQ;;wBAeF,SAAS;;wBAiCT,KAAK,8BAA8B"}

package/dist/backups/runner.d.mts

@@ -0,0 +1,102 @@
+//#region src/backups/runner.d.ts
+/**
+ * The backups container's program: `pg_dump` each of the stack's databases
+ * on schedule and stream it, gzipped, to the stage's backups prefix.
+ *
+ * It ships alone — copied into an image built `FROM postgres:<major>-alpine`
+ * with Node added — so it imports nothing but Node's own modules: S3 is
+ * spoken to with a SigV4 signature made here, not the AWS SDK.
+ *
+ *   node backup.mjs serve    run on schedule, forever (the container's command)
+ *   node backup.mjs run      one backup now (`gkm backup:now`)
+ *   node backup.mjs health   exit 1 when the last good run is too old
+ *
+ * Its key may only put objects under the prefix: it never reads, lists or
+ * deletes, so nothing here does either. A dump is uploaded in parts as it is
+ * made, so no database is ever held on disk or in memory whole.
+ *
+ * Environment:
+ *
+ * - `BACKUPS_URL` — `s3://KEY:SECRET@bucket?region=…`, the stage's backups key
+ * - `BACKUPS_PREFIX` — `gkm/<project>/<stage>/backups`
+ * - `BACKUPS_DATABASES` — `[{"file":"auth-database","name":"auth_database_production"}]`
+ * - `BACKUPS_SCHEDULE` — `{"kind":"every","seconds":86400,"offset":7200}`, or
+ *   a cron expanded: `{"kind":"cron","minutes":[0],"hours":[0,6,12,18],…}`
+ * - `BACKUPS_MAX_GAP_SECONDS` — the longest the schedule goes between runs
+ * - `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD` — read by `pg_dump` itself
+ * - `OTEL_EXPORTER_OTLP_ENDPOINT`/`_HEADERS` — where each run's result is
+ *   also sent as an OTLP log, when the stage's telemetry is on
+ */
+export interface IntervalSchedule {
+  kind: 'every';
+  seconds: number;
+  offset: number;
+}
+export interface CronSchedule {
+  kind: 'cron';
+  minutes: number[];
+  hours: number[];
+  days: number[] | null;
+  months: number[] | null;
+  weekdays: number[] | null;
+}
+export type Schedule = IntervalSchedule | CronSchedule;
+/**
+ * The first time after `after`, to the minute, the schedule runs — the copy
+ * of `schedule.ts`'s `nextRun` this file carries, since it ships alone.
+ */
+export declare function nextRun(schedule: Schedule, after: Date): Date | null;
+/** One run's folder: `2026-10-10/02-00-00Z`. */
+export declare function runFolder(at: Date): string;
+/** Where and as whom the backups are put. */
+export interface Destination {
+  bucket: string;
+  region: string;
+  endpoint?: string;
+  forcePathStyle: boolean;
+  accessKeyId: string;
+  secretAccessKey: string;
+}
+/** `BACKUPS_URL`, read the way `@geekmidas/storage/s3-url` writes it. */
+export declare function destination(url: string): Destination;
+interface S3Request {
+  method: 'PUT' | 'POST';
+  key: string;
+  query?: Record<string, string>;
+  body?: Buffer;
+  headers?: Record<string, string>;
+}
+/** One request to S3, signed with SigV4; the response's status and body. */
+export declare function s3Send(to: Destination, request: S3Request, now?: Date): Promise<{
+  status: number;
+  body: string;
+  headers: Record<string, string>;
+}>;
+/**
+ * Upload a stream to `key`: one PUT when it fits in a part, else a multipart
+ * upload — every action of which is `s3:PutObject`, all the key may do. A
+ * failed upload is left for the bucket's lifecycle to abort.
+ */
+export declare function upload(to: Destination, key: string, stream: AsyncIterable<Buffer>,
+/**
+ * How what made the stream ended. Awaited before the last request: a dump
+ * that failed half way ends its stream early, and must never be put as
+ * though it were whole.
+ */
+finished?: Promise<void>): Promise<number>;
+export interface BackupDatabase {
+  file: string;
+  name: string;
+}
+/** Be handed each line the runner logs. Returns what stops it. */
+export declare function onReport(listener: (line: Record<string, unknown>) => void): () => void;
+/** One backup of every database, into one run folder. Resolves whether it all went. */
+export declare function backupOnce(at?: Date): Promise<boolean>;
+/** Whether the last good run — or, before one, the start — is recent enough. */
+export declare function healthy(now?: number): boolean;
+/** Run on schedule, forever. */
+export declare function serve(): Promise<void>;
+/** What `node backup.mjs <command>` runs; resolves with its exit code. */
+export declare function main(command: string | undefined): Promise<number>;
+//#endregion
+//# sourceMappingURL=runner.d.mts.map

package/dist/backups/runner.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.mts","names":[],"sources":["../../src/backups/runner.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiDiB;EAChB;EACA;EACA;;iBAGgB;EAChB;EACA;EACA;EACA;EACA;EACA;;YAGW,WAAW,mBAAmB;;;;;wBAqB1B,QAAQ,UAAU,UAAU,OAAO,OAAO;;wBA2B1C,UAAU,IAAI;;iBAUb;EAChB;EACA;EACA;EACA;EACA;EACA;;;wBAIe,YAAY,cAAc;UAgChC;EACT;EACA;EACA,QAAQ;EACR,OAAO;EACP,UAAU;;;wBAIW,OACrB,IAAI,aACJ,SAAS,WACT,MAAK,OACH;EAAU;EAAgB;EAAc,SAAS;;;;;;;wBAoK9B,OACrB,IAAI,aACJ,aACA,QAAQ,cAAc,SAMtB;;;;;;AAAA,WAAU,gBACR;iBA0Ec;EAChB;EACA;;;wBAOe,SACf,WAAW,MAAM;;wBA2JI,WAAW,KAAI,OAAoB;;wBA6DzC,QAAQ;;wBAeF,SAAS;;wBAiCT,KAAK,8BAA8B"}