@everystack/server 0.4.2 → 0.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -151,9 +151,9 @@
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/pg-tools": "0.4.0",
     "@everystack/auth": "0.4.0",
-    "@everystack/cli": "0.4.8"
+    "@everystack/cli": "0.4.18",
+    "@everystack/pg-tools": "0.4.0"
   },
   "scripts": {
     "test": "jest",

package/src/backup-run.ts

@@ -19,6 +19,7 @@ import { randomBytes } from 'node:crypto';
 import type { Readable } from 'node:stream';
 import {
   backupPrefix, backupKey, metaKey, backupId, idForKey, keyForId, utcStamp,
+  artifactKey, artifactId, artifactPrefix, artifactIdForKey,
   pgEnvFromUrl, dbNameFromUrl, pgDumpArgs, pgRestoreArgs,
 } from './backup';
 
@@ -147,6 +148,77 @@ export async function runBackup(deps: BackupRunDeps, stage: string): Promise<Bac
   return { id, key, bytes };
 }
 
+export interface ExportRunResult {
+  id: string;
+  key: string;
+  bytes?: number;
+  /** The schema fingerprint the artifact was built against (the swap's gate compares it). */
+  fingerprint: string;
+}
+
+/**
+ * pg_dump ONE schema (`--schema=<schema>`) → gzip → S3 under the artifact prefix, with a
+ * `.meta.json` carrying the schema fingerprint — the canonical-sync export (docs/plans/
+ * canonical-sync-artifacts.md). The fingerprint is computed by the CLI from the same live schema
+ * (one formula both sides) and passed in; this stamps it into the artifact so db:swap can gate on
+ * it. Same streaming + child-exit guard as runBackup: a truncated dump never ships.
+ */
+export async function runExport(
+  deps: BackupRunDeps,
+  opts: { schema: string; stage: string; fingerprint: string },
+): Promise<ExportRunResult> {
+  const { bucket, region, adminUrl } = deps;
+  const { schema, stage, fingerprint } = opts;
+  const env = { ...process.env, ...pgEnvFromUrl(adminUrl) };
+  const stamp = utcStamp(new Date());
+  const shortId = randomBytes(3).toString('hex');
+  const key = artifactKey(schema, stage, stamp, shortId);
+  const mkey = metaKey(key);
+  const id = artifactId(schema, stage, stamp, shortId);
+
+  const s3 = await getS3(region);
+  const { Upload } = await importOptionalAws(() => import('@aws-sdk/lib-storage'), '@aws-sdk/lib-storage', 'db:export');
+  const { DeleteObjectCommand, PutObjectCommand, HeadObjectCommand } = await importOptionalAws(
+    () => import('@aws-sdk/client-s3'), '@aws-sdk/client-s3', 'db:export',
+  );
+
+  const child = spawn('pg_dump', pgDumpArgs({ schema }), { env, stdio: ['ignore', 'pipe', 'pipe'] });
+  let stderr = '';
+  child.stderr.on('data', (d) => { stderr += d.toString(); });
+  const childExit = new Promise<void>((resolve, reject) => {
+    child.on('error', reject);
+    child.on('close', (code) => code === 0 ? resolve() : reject(new Error(`pg_dump exited ${code}: ${stderr.trim()}`)));
+  });
+
+  const gzip = createGzip();
+  const upload = new Upload({
+    client: s3,
+    params: { Bucket: bucket, Key: key, Body: gzip, ContentType: 'application/gzip', ServerSideEncryption: 'AES256' },
+  });
+
+  try {
+    await Promise.all([pipeline(child.stdout!, gzip), upload.done(), childExit]);
+  } catch (err) {
+    try { await upload.abort(); } catch { /* may already have completed */ }
+    await s3.send(new DeleteObjectCommand({ Bucket: bucket, Key: key })).catch(() => {});
+    throw err;
+  }
+
+  let bytes: number | undefined;
+  try {
+    const head = await s3.send(new HeadObjectCommand({ Bucket: bucket, Key: key }));
+    bytes = head.ContentLength;
+  } catch { /* size is best-effort */ }
+
+  const meta = { id, schema, stage, createdAt: new Date().toISOString(), bytes, key, fingerprint };
+  await s3.send(new PutObjectCommand({
+    Bucket: bucket, Key: mkey, Body: JSON.stringify(meta),
+    ContentType: 'application/json', ServerSideEncryption: 'AES256',
+  }));
+
+  return { id, key, bytes, fingerprint };
+}
+
 /** List a stage's backups (newest first) from S3 object metadata — one list call, no per-item gets. */
 export async function listBackups(deps: BackupRunDeps, stage: string): Promise<BackupSummary[]> {
   const s3 = await getS3(deps.region);

package/src/backup.ts

@@ -72,6 +72,44 @@ export function idForKey(dumpKey: string): string | null {
   return m ? `${m[1]}/${m[2]}` : null;
 }
 
+// --- Artifact key scheme (schema-scoped exports for the canonical-sync hot-swap) ----------------
+// A backup is the whole database; an ARTIFACT is one schema, content-addressed, carrying the schema
+// fingerprint it was built against. Separate prefix so lifecycle rules and the swap resolver never
+// confuse the two. See docs/plans/canonical-sync-artifacts.md.
+
+/** The S3 prefix a schema's artifacts live under (admin-only, encrypted). */
+export function artifactPrefix(schema: string, stage: string): string {
+  return `artifacts/${schema}/${stage}`;
+}
+
+/** The object key for a new schema artifact. `stamp` is a UTC `YYYYMMDDTHHMMSSZ` string. */
+export function artifactKey(schema: string, stage: string, stamp: string, shortId: string): string {
+  return `${artifactPrefix(schema, stage)}/${stamp}-${shortId}.dump.gz`;
+}
+
+/** A schema-qualified artifact id — `stats/dev/20260716T120000Z-ab12cd`. */
+export function artifactId(schema: string, stage: string, stamp: string, shortId: string): string {
+  return `${schema}/${stage}/${stamp}-${shortId}`;
+}
+
+/** Parse an artifact id into schema/stage/name, or null when malformed. */
+export function parseArtifactRef(id: string): { schema: string; stage: string; name: string } | null {
+  const m = id.match(/^([A-Za-z0-9_]+)\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_.:-]+)$/);
+  return m ? { schema: m[1], stage: m[2], name: m[3] } : null;
+}
+
+/** The S3 dump key for an artifact id (inverse of artifactId), or null when malformed. */
+export function keyForArtifactId(id: string): string | null {
+  const ref = parseArtifactRef(id);
+  return ref ? `${artifactPrefix(ref.schema, ref.stage)}/${ref.name}.dump.gz` : null;
+}
+
+/** The artifact id from a dump key (inverse of artifactKey), or null when it isn't an artifact key. */
+export function artifactIdForKey(dumpKey: string): string | null {
+  const m = dumpKey.match(/^artifacts\/([A-Za-z0-9_]+)\/([A-Za-z0-9_-]+)\/(.+)\.dump\.gz$/);
+  return m ? `${m[1]}/${m[2]}/${m[3]}` : null;
+}
+
 /** Format a Date as the UTC `YYYYMMDDTHHMMSSZ` stamp (caller's clock; pure). */
 export function utcStamp(date: Date): string {
   const p = (n: number): string => String(n).padStart(2, '0');
@@ -115,8 +153,12 @@ export function dbNameFromUrl(url: string): string {
  * connection comes from PG* env, so no host/db on argv. --no-owner/--no-privileges/--no-comments
  * make the dump restore cleanly into a different stage (and dodge the RDS plpgsql-comment error).
  */
-export function pgDumpArgs(): string[] {
-  return ['-Fc', '--no-owner', '--no-privileges', '--no-comments'];
+export function pgDumpArgs(opts: { schema?: string } = {}): string[] {
+  const args = ['-Fc', '--no-owner', '--no-privileges', '--no-comments'];
+  // A schema-scoped artifact dumps ONE schema (the canonical-sync export). pg_dump's --schema
+  // takes a pattern; a plain identifier scopes to exactly that schema and its objects.
+  if (opts.schema) args.push(`--schema=${opts.schema}`);
+  return args;
 }
 
 /**

package/src/db.ts

@@ -96,6 +96,34 @@ export function getJwtSecret(): Uint8Array {
   throw new Error('JWT_SECRET not set — link an sst.Secret or set process.env.JWT_SECRET');
 }
 
+/**
+ * The ssl option for a connection URL: an explicit `sslmode` query param wins
+ * (return no override — postgres.js honors the URL natively), otherwise default
+ * to 'require' (RDS). This is what lets ONE handler serve both venues: local
+ * Postgres appends `?sslmode=disable` to its URL, deployed stages carry no
+ * param and keep TLS. An unparseable URL fails toward TLS and lets the connect
+ * report the real error.
+ */
+export function sslOptionForUrl(url: string): 'require' | undefined {
+  try {
+    return new URL(url).searchParams.has('sslmode') ? undefined : 'require';
+  } catch {
+    return 'require';
+  }
+}
+
+/** postgres.js options shared by every connection — ssl derived from the URL. */
+function connectionOptions(url: string, maxConnections?: number): Parameters<typeof postgres>[1] {
+  const ssl = sslOptionForUrl(url);
+  return {
+    max: maxConnections ?? 1,
+    idle_timeout: 60,
+    connect_timeout: 5,
+    max_lifetime: 60 * 5,
+    ...(ssl ? { ssl } : {}),
+  };
+}
+
 // Lazy singleton DB connection
 let dbInstance: ReturnType<typeof drizzle> | null = null;
 let sqlClient: ReturnType<typeof postgres> | null = null;
@@ -110,13 +138,7 @@ export function createDb<T extends Record<string, unknown>>(
   if (dbInstance) return { db: dbInstance, schema };
 
   const url = getDatabaseUrl();
-  sqlClient = postgres(url, {
-    max: options?.maxConnections ?? 1,
-    idle_timeout: 60,
-    connect_timeout: 5,
-    max_lifetime: 60 * 5,
-    ssl: 'require',
-  });
+  sqlClient = postgres(url, connectionOptions(url, options?.maxConnections));
   dbInstance = drizzle(sqlClient, { schema });
   return { db: dbInstance, schema };
 }
@@ -242,13 +264,7 @@ export function createAdminDb<T extends Record<string, unknown>>(
     return createDb(schema, options);
   }
 
-  adminSqlClient = postgres(adminUrl, {
-    max: options?.maxConnections ?? 1,
-    idle_timeout: 60,
-    connect_timeout: 5,
-    max_lifetime: 60 * 5,
-    ssl: 'require',
-  });
+  adminSqlClient = postgres(adminUrl, connectionOptions(adminUrl, options?.maxConnections));
   adminDbInstance = drizzle(adminSqlClient, { schema });
   return { db: adminDbInstance, schema };
 }
@@ -314,13 +330,7 @@ export function createReadDb<T extends Record<string, unknown>>(
   const url = getReadDatabaseUrl();
   if (!url) return createDb(schema, options);
 
-  readSqlClient = postgres(url, {
-    max: options?.maxConnections ?? 1,
-    idle_timeout: 60,
-    connect_timeout: 5,
-    max_lifetime: 60 * 5,
-    ssl: 'require',
-  });
+  readSqlClient = postgres(url, connectionOptions(url, options?.maxConnections));
   readDbInstance = drizzle(readSqlClient, { schema });
   return { db: readDbInstance, schema };
 }

package/src/plugin.ts

@@ -885,6 +885,24 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
           return { error: err?.message || String(err) };
         }
       };
+
+      // --- db:export — the schema-scoped, fingerprint-stamped artifact (canonical-sync gap B) ---
+      // pg_dump ONE schema → S3 artifact carrying the schema fingerprint the CLI computed from the
+      // same live schema (one formula both sides). db:swap gates on that fingerprint before it lands.
+      actions['db:export'] = async (payload, ctx) => {
+        const { schema, fingerprint } = (payload ?? {}) as { schema?: string; fingerprint?: string };
+        const stage = ((payload ?? {}) as { stage?: string }).stage ?? ctx.environment ?? 'default';
+        if (!schema) return { error: 'db:export requires { schema }' };
+        if (!fingerprint) return { error: 'db:export requires { fingerprint } — the CLI computes the scoped schema fingerprint so the artifact and the swap gate agree' };
+        const r = await resolveBackupDeps();
+        if ('error' in r) return { error: r.error };
+        const { runExport } = await import('./backup-run');
+        try {
+          return await runExport(r.deps, { schema, stage, fingerprint });
+        } catch (err: any) {
+          return { error: err?.message || String(err) };
+        }
+      };
     }
 
     // --- db:apply — the credential-free staged write (Phase 2) ---