@everystack/server 0.4.1 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -76,6 +76,10 @@
     "./pipeline": {
       "types": "./src/pipeline.ts",
       "default": "./src/pipeline.ts"
+    },
+    "./infra": {
+      "types": "./src/infra.ts",
+      "default": "./src/infra.ts"
     }
   },
   "peerDependencies": {
@@ -87,6 +91,7 @@
     "@aws-sdk/signature-v4a": ">=3.1048.0",
     "@everystack/auth": ">=0.1.0",
     "@everystack/cli": ">=0.1.0",
+    "@everystack/pg-tools": ">=0.4.0",
     "drizzle-orm": "0.41.0",
     "heic-decode": "2.1.0",
     "postgres": "3.4.9",
@@ -106,6 +111,9 @@
     "sst": {
       "optional": true
     },
+    "@everystack/pg-tools": {
+      "optional": true
+    },
     "@everystack/auth": {
       "optional": true
     },
@@ -143,8 +151,9 @@
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/cli": "0.4.7",
-    "@everystack/auth": "0.4.0"
+    "@everystack/pg-tools": "0.4.0",
+    "@everystack/auth": "0.4.0",
+    "@everystack/cli": "0.4.8"
   },
   "scripts": {
     "test": "jest",

package/src/db-doctor.ts

@@ -87,6 +87,20 @@ export interface DoctorProbe {
    * an older probe (the check is then skipped). B4.
    */
   darkRelations?: DarkRelation[];
+  /**
+   * pg_dump layer capability: whether @everystack/pg-tools is attached (pg_dump present) and its
+   * major can dump this server (client >= server). Drives the one-line "backups" lens — a missing
+   * layer blocks db:backup AND the snapshot-first destructive apply. Absent on an older probe (the
+   * check is then skipped). See docs/plans/pgdump-layer.md.
+   */
+  backup?: {
+    /** `pg_dump --version` output, or null when the layer is not attached. */
+    pgDump: string | null;
+    pgDumpMajor: number | null;
+    serverMajor: number | null;
+    /** pgDumpMajor >= serverMajor — a client can dump an older-or-equal server, never a newer one. */
+    compatible: boolean;
+  };
 }
 
 /** A function PUBLIC can EXECUTE, and whether it runs as its owner (the dangerous half). */
@@ -544,6 +558,33 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
     }
   }
 
+  // Backups lens — the pg_dump layer gates db:backup AND the snapshot-first destructive apply. A
+  // missing layer isn't a security hole (warn, not fail), but it silently blocks the ceremony.
+  if (probe.backup) {
+    const b = probe.backup;
+    if (b.pgDump && b.compatible) {
+      checks.push({
+        name: 'Logical backups available (pg_dump layer)',
+        status: 'pass',
+        detail: `pg_dump major ${b.pgDumpMajor} attached and compatible with server major ${b.serverMajor} — db:backup and the snapshot-first destructive apply are ready`,
+      });
+    } else if (b.pgDump && !b.compatible) {
+      checks.push({
+        name: 'Logical backups available (pg_dump layer)',
+        status: 'warn',
+        detail: `pg_dump major ${b.pgDumpMajor} is older than server major ${b.serverMajor} — it will refuse to dump (no bypass exists)`,
+        remediation: 'Upgrade @everystack/pg-tools to advance the client ceiling to >= the server major, then redeploy.',
+      });
+    } else {
+      checks.push({
+        name: 'Logical backups available (pg_dump layer)',
+        status: 'warn',
+        detail: 'pg_dump layer not attached — db:backup and the snapshot-first destructive apply are unavailable',
+        remediation: 'Install @everystack/pg-tools and redeploy (pgDumpLayer attaches it automatically), or pass a bring-your-own layerArn in sst.config.ts.',
+      });
+    }
+  }
+
   return {
     api,
     admin,

package/src/infra.ts

@@ -0,0 +1,96 @@
+/**
+ * @everystack/server/infra — deploy-time helpers for a consumer's `sst.config.ts`.
+ *
+ * `pgDumpLayer()` attaches the PostgreSQL client-tools Lambda layer that `db:backup`/`db:restore`
+ * (and the snapshot-first apply ceremony) need. It replaces the old `PGDUMP_LAYER_ARN` env-var line
+ * with a zero-config, declarative resource: the framework ships the binaries (@everystack/pg-tools),
+ * and this publishes them as a content-addressed LayerVersion into the CONSUMER's own account.
+ *
+ * Declarative, not imperative: it returns a Pulumi-managed resource's arn (or an escape-hatch
+ * string), so the SST/Pulumi engine owns the layer's lifecycle — no SDK side effects at config-eval,
+ * no untracked state, clean teardown. Same artifact sha => same layer name => redeploys are no-ops.
+ */
+
+import { manifest, layerZipPath } from '@everystack/pg-tools';
+
+/**
+ * SST's ambient config globals, injected so this package typechecks standalone (it must not depend on
+ * SST's per-app generated types). In `sst.config.ts` you already have both — pass `{ aws, $util }`.
+ * Typed loosely on purpose; the shapes are Pulumi's and not worth vendoring here.
+ */
+export interface PgDumpLayerContext {
+  /** SST's global `aws` (@pulumi/aws) — for `aws.lambda.LayerVersion`. */
+  aws: any;
+  /** SST's global `$util` (@pulumi/pulumi) — for `$util.asset.FileArchive`. */
+  $util: any;
+}
+
+export interface PgDumpLayerOptions {
+  /**
+   * The stage's PostgreSQL server major. The shipped client must be >= this (pg_dump/pg_restore are
+   * backward compatible; a client older than the server is refused). Read it from the engine you declare.
+   */
+  pgMajor: number;
+  /**
+   * Escape hatch: attach this exact layer ARN instead of the managed publish. For consumers who build
+   * their own (e.g. x86_64, an exotic major) via tools/pgdump-layer. Outranks everything else.
+   */
+  layerArn?: string;
+}
+
+let warnedEnv = false;
+
+/**
+ * Resolve and attach the pg_dump layer. Returns the ARN to spread into a Function's `layers: []`.
+ *
+ * Precedence: explicit `layerArn` > `PGDUMP_LAYER_ARN` (deprecated alias, warns once) > the managed
+ * content-addressed LayerVersion published into this account.
+ *
+ * @example
+ *   import { pgDumpLayer } from '@everystack/server/infra';
+ *   const ops = new sst.aws.Function('Ops', {
+ *     layers: [pgDumpLayer({ aws, $util }, 'PgDump', { pgMajor: 16 })],
+ *     // ...
+ *   });
+ */
+export function pgDumpLayer(
+  ctx: PgDumpLayerContext,
+  name: string,
+  opts: PgDumpLayerOptions,
+): any /* Input<string> — the layer arn; `any` at the Pulumi interop boundary so it spreads into layers:[] */ {
+  // 1) explicit escape hatch wins.
+  if (opts.layerArn) return opts.layerArn;
+
+  // 2) deprecated env alias — still honored for one minor line, but warned.
+  const envArn = process.env.PGDUMP_LAYER_ARN;
+  if (envArn) {
+    if (!warnedEnv) {
+      warnedEnv = true;
+      console.warn(
+        '[everystack] PGDUMP_LAYER_ARN is deprecated and will be removed in the next minor. ' +
+          'Install @everystack/pg-tools and drop the env var (the layer is published automatically), ' +
+          'or pass pgDumpLayer(ctx, name, { layerArn }) for a bring-your-own layer.',
+      );
+    }
+    return envArn;
+  }
+
+  // 3) the managed publish: a content-addressed LayerVersion in the consumer's own account.
+  if (manifest.major < opts.pgMajor) {
+    throw new Error(
+      `@everystack/pg-tools ships pg${manifest.major} client tools, but this stage's server is ` +
+        `pg${opts.pgMajor}. pg_dump/pg_restore must be >= the server. Upgrade @everystack/pg-tools ` +
+        `to advance the client ceiling, or pass a bring-your-own layerArn.`,
+    );
+  }
+  const sha8 = manifest.sha256.slice(0, 8);
+  const layer = new ctx.aws.lambda.LayerVersion(name, {
+    // content-addressed: same artifact => same name => Pulumi treats redeploys as no-ops.
+    layerName: `everystack-pgdump${manifest.major}-${sha8}`,
+    code: new ctx.$util.asset.FileArchive(layerZipPath()),
+    compatibleRuntimes: ['nodejs20.x'],
+    compatibleArchitectures: [manifest.arch],
+    description: `everystack pg_dump/pg_restore — pg${manifest.postgresql}, sha ${sha8}`,
+  });
+  return layer.arn;
+}

package/src/plugin.ts

@@ -725,8 +725,34 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
         }
       }
 
+      // Backups lens — is the pg_dump layer attached AND version-compatible? Reuse the
+      // db:backup:probe internals; a missing layer leaves pgDump null (the lens warns), never throws.
+      let backup: import('./db-doctor').DoctorProbe['backup'];
+      try {
+        const { pgClientVersion, parsePgDumpMajor, serverMajorFromNum, isDumpCompatible } = await import('./backup');
+        let pgDump: string | null = null;
+        let pgDumpMajor: number | null = null;
+        try {
+          pgDump = await pgClientVersion('pg_dump');
+          pgDumpMajor = parsePgDumpMajor(pgDump);
+        } catch {
+          // layer absent — pgDump stays null, the lens reports "not attached"
+        }
+        const svnRow = rowsOf(await opsDb.execute(sql.raw('SHOW server_version_num')))[0];
+        const svn = Number(svnRow?.server_version_num);
+        const serverMajor = Number.isFinite(svn) ? serverMajorFromNum(svn) : null;
+        backup = {
+          pgDump,
+          pgDumpMajor,
+          serverMajor,
+          compatible: pgDumpMajor != null && Number.isFinite(svn) ? isDumpCompatible(pgDumpMajor, svn) : false,
+        };
+      } catch {
+        // leave backup undefined → the lens is skipped, exactly like the other optional probes
+      }
+
       return buildDoctorReport(
-        { api, admin, forceRls, appGrantedRls, apiAmbientRead, secdefFunctions, publicExecutableFunctions, darkRelations },
+        { api, admin, forceRls, appGrantedRls, apiAmbientRead, secdefFunctions, publicExecutableFunctions, darkRelations, backup },
         { forceRlsCarveouts: options.forceRlsCarveouts, functionSchemas: options.functionSchemas },
       );
     };
@@ -794,7 +820,7 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       try {
         pgDump = await pgClientVersion('pg_dump');
       } catch (err: any) {
-        return { error: `pg_dump not available — is the pg_dump layer attached to this function? (${err?.message || String(err)})` };
+        return { error: `pg_dump not available — the pg_dump layer is not attached. Install @everystack/pg-tools and redeploy (pgDumpLayer() attaches it automatically), or pass a bring-your-own layerArn in sst.config.ts. (${err?.message || String(err)})` };
       }
       const pgDumpMajor = parsePgDumpMajor(pgDump);