@everystack/server 0.1.0

package/README.md

@@ -0,0 +1,248 @@
+# @everystack/server
+
+Lambda runtime primitives for building serverless applications with SST. Provides event adapters, routing, database connection, SSR, image processing, migrations, and background job handling.
+
+## Install
+
+```bash
+pnpm add @everystack/server
+```
+
+## Entry Points
+
+| Export | Purpose |
+|--------|---------|
+| `@everystack/server` | Lambda handler, router, event adapters, logging |
+| `@everystack/server/db` | SST Resource-linked database connection |
+| `@everystack/server/ssr` | Expo web SSR bundle serving |
+| `@everystack/server/image` | On-demand image resizing via Sharp |
+| `@everystack/server/migrate` | Drizzle migration runner |
+| `@everystack/server/worker` | SQS job queue consumer |
+| `@everystack/server/stubs` | esbuild bundling helpers for client packages |
+
+## Quick Start
+
+```typescript
+import { createLambdaHandler } from '@everystack/server';
+import { createDb, getJwtSecret } from '@everystack/server/db';
+import { runMigrations } from '@everystack/server/migrate';
+import { createWorkerHandler } from '@everystack/server/worker';
+import * as schema from '../db/schema';
+
+const { db } = createDb(schema);
+
+// API Lambda
+export const handler = createLambdaHandler({
+  init: async () => ({
+    api: createApiHandler(db),
+  }),
+  routes: (h) => [
+    { path: '/api', handler: h.api },
+  ],
+  onAction: async (action, payload) => {
+    // CLI invocations via IAM-authed Lambda invoke
+    if (action === 'migrate') return runMigrations(db, './drizzle');
+    if (action === 'seed') return runSeed(db);
+  },
+});
+
+// Worker Lambda
+export const worker = createWorkerHandler(async () => ({
+  'email:send': async (payload) => { /* ... */ },
+  'image:process': async (payload) => { /* ... */ },
+}));
+```
+
+## Main Export (`@everystack/server`)
+
+### `createLambdaHandler(options)`
+
+The primary entry point. Wraps initialization, routing, and error handling into a Lambda handler.
+
+```typescript
+interface LambdaHandlerOptions {
+  init: () => Promise<Record<string, Handler>>;
+  routes: (handlers: Record<string, Handler>) => Route[];
+  fallback?: (handlers: Record<string, Handler>) => Handler;
+  onAction?: (action: string, payload: unknown, handlers: Record<string, Handler>) => Promise<unknown>;
+}
+```
+
+**Behavior:**
+- Lazy-initializes handlers once, caches across warm invocations
+- Detects CLI invocations (events with `_action` field) and dispatches to `onAction`
+- Sets Cache-Control: `private, no-store` (authenticated) or `public, s-maxage=300` (public GET)
+- Guards response size (5MB max for Function URLs)
+- Adds `x-request-id` from Lambda trace or UUID
+
+### `createRouter(routes, fallback?)`
+
+Path/method dispatcher.
+
+```typescript
+interface Route {
+  path: string;        // URL prefix match
+  method?: string;     // HTTP method filter (optional)
+  exact?: boolean;     // Exact path match (default: prefix)
+  handler: Handler;
+}
+```
+
+Routes match by prefix unless `exact: true`. First match wins.
+
+### `eventToRequest(event)`
+
+Converts AWS API Gateway V2 events to Web Standard `Request` objects.
+
+### `responseToResult(response)`
+
+Converts Web Standard `Response` to API Gateway V2 results. Auto-detects and base64-encodes binary content.
+
+### `log(level, message, meta?)`
+
+Structured JSON logging to stdout with ISO timestamp.
+
+## Database (`@everystack/server/db`)
+
+SST Resource-linked database helpers. All credentials come from SST's Resource linking — no env vars needed.
+
+### `createDb(schema, options?)`
+
+Lazy singleton Drizzle connection via postgres.js.
+
+```typescript
+const { db } = createDb(schema, { maxConnections: 1 });
+```
+
+Pool defaults: max 1, idle timeout 60s, connect timeout 5s, max lifetime 5min, SSL required.
+
+### `getDatabaseUrl()`
+
+Returns PostgreSQL connection URL from SST Resources.
+
+### `getJwtSecret()`
+
+Returns JWT secret as `Uint8Array` from `Resource.JwtSecret.value`.
+
+## Web SSR (`@everystack/server/ssr`)
+
+Serves Expo web builds deployed via `@everystack/cli`.
+
+### `getWebHandler(db, storage)`
+
+Returns a Request→Response handler for the latest web release.
+
+- Queries database for latest `platform='web'` release
+- Downloads and extracts brotli-compressed tar archive to `/tmp/web-build/`
+- Caches handler with 60s TTL (re-queries for new releases)
+- Returns `null` if no web release exists
+
+### `downloadAndExtract(storage, storagePrefix)`
+
+Downloads `{prefix}/bundle.tar.br` from storage, decompresses with brotli, extracts to `/tmp/web-build/`.
+
+### `extractTar(data, destDir)`
+
+Pure JavaScript POSIX tar extractor. Required because Lambda doesn't include the `tar` binary.
+
+## Image Processing (`@everystack/server/image`)
+
+On-demand image resizing via Sharp (provided as Lambda layer).
+
+### `createImageHandler(config)`
+
+```typescript
+interface ImageHandlerConfig {
+  bucket: string;          // S3 bucket name
+  region?: string;         // AWS region (default: AWS_REGION env)
+  pathPrefix?: string;     // URL prefix (default: '/media/')
+}
+```
+
+URL format: `/media/{key}?w=400&h=300&fit=cover&fm=webp&q=80&dpr=2`
+
+**Behavior:**
+- No transforms → 302 redirect to presigned S3 URL (avoids 6MB Lambda limit)
+- With transforms → fetch from S3, process with Sharp, return with immutable cache headers
+
+### `parseParams(query)`
+
+Validates URL query params into transform options:
+
+| Param | Range | Description |
+|-------|-------|-------------|
+| `w` | 1–4096 | Width |
+| `h` | 1–4096 | Height |
+| `fit` | cover, contain, fill, inside, outside | Resize fit |
+| `fm` | webp, jpeg, png, avif | Output format |
+| `q` | 1–100 | Quality |
+| `dpr` | 1–3 | Device pixel ratio (multiplies w/h) |
+
+## Migrations (`@everystack/server/migrate`)
+
+### `runMigrations(db, migrationsFolder)`
+
+Runs Drizzle migrations from the specified folder. Called via `onAction` handler (CLI → IAM → Lambda invoke).
+
+- Returns `{ success: true, message: 'Migrations applied' }`
+- Throws on error (caller handles response)
+
+## Worker (`@everystack/server/worker`)
+
+### `createWorkerHandler(init)`
+
+SQS Lambda handler with type-based job dispatch.
+
+```typescript
+type JobHandler = (payload: any, job: { id: string; type: string }) => Promise<void>;
+
+const worker = createWorkerHandler(async () => ({
+  'email:send': async (payload) => { /* ... */ },
+  'image:process': async (payload) => { /* ... */ },
+}));
+```
+
+- Lazy-initializes handlers, caches across warm invocations
+- Parses SQS message body as `{ jobId, type, payload }`
+- Returns `batchItemFailures` for partial failure handling (failed messages retry)
+
+## Stubs (`@everystack/server/stubs`)
+
+### `clientStubs`
+
+Array of client-side package names to exclude from Lambda bundles via esbuild `external`.
+
+### `stubsDir`
+
+Path to no-op module stubs. Used with SST `copyFiles` to prevent "module not found" errors when server code transitively imports client packages.
+
+```typescript
+// sst.config.ts
+import { clientStubs, stubsDir } from '@everystack/server/stubs';
+
+new sst.aws.Function('Api', {
+  handler: 'server/api.handler',
+  nodejs: {
+    esbuild: { external: clientStubs },
+  },
+  copyFiles: [{ from: stubsDir, to: 'stubs' }],
+});
+```
+
+## Peer Dependencies
+
+- `sst` — Resource linking for credentials
+- `drizzle-orm` — Database ORM
+- `postgres` — PostgreSQL driver
+- `sharp` — Image processing (optional, Lambda layer)
+- `@aws-sdk/client-s3` — S3 operations (image handler)
+- `@aws-sdk/s3-request-presigner` — Presigned URLs (image handler)
+- `@everystack/cli` — Storage adapter (SSR handler)
+
+---
+
+Part of [everystack](https://github.com/scalable-technology/everystack) — a self-hosted application stack for Expo apps on AWS.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@everystack/server",
+  "version": "0.1.0",
+  "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./db": {
+      "types": "./src/db.ts",
+      "default": "./src/db.ts"
+    },
+    "./ssr": {
+      "types": "./src/ssr.ts",
+      "default": "./src/ssr.ts"
+    },
+    "./image": {
+      "types": "./src/image.ts",
+      "default": "./src/image.ts"
+    },
+    "./migrate": {
+      "types": "./src/migrate.ts",
+      "default": "./src/migrate.ts"
+    },
+    "./worker": {
+      "types": "./src/worker.ts",
+      "default": "./src/worker.ts"
+    },
+    "./stubs": {
+      "types": "./src/stubs.ts",
+      "default": "./src/stubs.ts"
+    },
+    "./cdn": {
+      "types": "./src/cdn/index.ts",
+      "default": "./src/cdn/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": ">=3.0.0",
+    "@aws-sdk/s3-request-presigner": ">=3.0.0",
+    "@everystack/auth": ">=0.1.0",
+    "@everystack/cli": ">=0.1.0",
+    "drizzle-orm": ">=0.30.0",
+    "postgres": ">=3.0.0",
+    "sharp": ">=0.33.0",
+    "sst": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "sst": {
+      "optional": true
+    },
+    "@everystack/auth": {
+      "optional": true
+    },
+    "@everystack/cli": {
+      "optional": true
+    },
+    "sharp": {
+      "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/aws-lambda": "^8.10.145",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.0.0",
+    "drizzle-orm": "^0.41.0",
+    "jest": "^29.7.0",
+    "postgres": "^3.4.0",
+    "sst": "^4.13.1",
+    "ts-jest": "^29.3.0",
+    "typescript": "^5.7.0",
+    "@everystack/auth": "0.1.0",
+    "@everystack/cli": "0.1.0"
+  },
+  "scripts": {
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "build": "tsc --build",
+    "lint": "tsc --noEmit"
+  }
+}

package/src/cdn/compose.ts

@@ -0,0 +1,235 @@
+/**
+ * composeViewerRequest — multi-feature CloudFront Functions composer.
+ *
+ * Turns a list of `Feature` records into a single CFF runtime 2.0 source
+ * string, deduping shared helpers, namespacing per-feature state, ordering
+ * per-request bodies, wrapping everything in a fail-closed try/catch, and
+ * (by default) running a safe minifier with a 10 KB size budget.
+ *
+ * Output is the BODY for an SST `injection` (i.e. it goes inside an existing
+ * `function handler(event) { ... return event.request; }`), so helpers and
+ * state are nested function/var declarations rather than top-level.
+ */
+
+export interface Feature {
+  /** Unique feature name. Used to namespace state vars as `__<name>_<key>`. */
+  name: string;
+  /**
+   * Helper functions/vars shared with other features. Keys are dedupe IDs;
+   * values are full source ('function foo(){...}' or 'var T = ...;'). When
+   * two features register the same key, sources MUST be byte-identical or
+   * the composer throws.
+   */
+  helpers?: Record<string, string>;
+  /**
+   * JSON-serializable constants emitted as `var __<feature>_<key> = JSON;`.
+   */
+  state?: Record<string, unknown>;
+  /**
+   * Per-request code. Runs inside the wrapping try{}, in `order`. May
+   * `return <response>` to short-circuit downstream features.
+   */
+  body: string;
+  /** Smaller runs first. Default 100. Stable for ties. */
+  order?: number;
+}
+
+export interface ComposeOptions {
+  features: Feature[];
+  /** Default true. */
+  minify?: boolean;
+  /** CFF runtime 2.0 source-size hard limit. Default 10240. */
+  maxBytes?: number;
+}
+
+export interface ComposeResult {
+  code: string;
+  bytes: number;
+}
+
+const DEFAULT_MAX_BYTES = 10 * 1024;
+const DEFAULT_ORDER = 100;
+
+export function composeViewerRequest(opts: ComposeOptions): ComposeResult {
+  const features = opts.features;
+  const minify = opts.minify !== false;
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+
+  // 1. Dedupe helpers across features. Conflict (same key, different source)
+  //    is a hard error — silently picking one would mask a real bug.
+  const helpers = new Map<string, string>();
+  for (const f of features) {
+    if (!f.helpers) continue;
+    for (const [k, src] of Object.entries(f.helpers)) {
+      const existing = helpers.get(k);
+      if (existing !== undefined && existing !== src) {
+        throw new Error(
+          `composeViewerRequest: conflicting helper '${k}' between features (one of: ${f.name})`
+        );
+      }
+      helpers.set(k, src);
+    }
+  }
+
+  // 2. Emit state as namespaced vars.
+  const stateLines: string[] = [];
+  for (const f of features) {
+    if (!f.state) continue;
+    for (const [k, v] of Object.entries(f.state)) {
+      stateLines.push(`var __${f.name}_${k} = ${JSON.stringify(v)};`);
+    }
+  }
+
+  // 3. Stable-sort bodies by `order`.
+  const ordered = features
+    .map((f, i) => ({ f, i, order: f.order ?? DEFAULT_ORDER }))
+    .sort((a, b) => (a.order - b.order) || (a.i - b.i))
+    .map((x) => x.f);
+
+  const bodyParts = ordered.map((f) => `// --- ${f.name} ---\n${f.body}`).join('\n');
+
+  // 4. Wrap in fail-closed try/catch.
+  //    Any uncaught throw becomes a 401 — fail closed at the edge.
+  const composed = [
+    ...Array.from(helpers.values()),
+    ...stateLines,
+    'try {',
+    bodyParts,
+    '} catch (__e) {',
+    '  return { statusCode: 401, statusDescription: "Unauthorized", headers: { "content-type": { value: "application/json" }, "cache-control": { value: "no-store" } }, body: { encoding: "text", data: JSON.stringify({ message: "Edge auth error" }) } };',
+    '}',
+  ].join('\n');
+
+  const code = minify ? minifyCff(composed) : composed;
+  const bytes = Buffer.byteLength(code, 'utf8');
+
+  if (bytes > maxBytes) {
+    throw new Error(
+      `composeViewerRequest: output (${bytes} bytes) exceeds max (${maxBytes} bytes). ` +
+        `CloudFront Functions runtime 2.0 hard limit is 10 KB compiled.`
+    );
+  }
+
+  return { code, bytes };
+}
+
+/**
+ * Safe minifier for CFF source.
+ *
+ * Strips // and /* *\/ comments and collapses runs of whitespace, while
+ * preserving the contents of string literals (', ", `) and regex literals.
+ * Does NOT mangle identifiers (CFF runtime API surface like
+ * `event.request.headers.authorization.value` must survive intact).
+ *
+ * Hand-rolled tokenizer rather than terser so we ship zero new runtime deps
+ * and keep deploy-time evaluation fast.
+ */
+export function minifyCff(src: string): string {
+  let out = '';
+  let i = 0;
+  const n = src.length;
+
+  // Track previous non-whitespace char to disambiguate `/` (regex vs divide).
+  let prevSig = '';
+
+  while (i < n) {
+    const c = src[i];
+    const c2 = src[i + 1];
+
+    // Line comment.
+    if (c === '/' && c2 === '/') {
+      while (i < n && src[i] !== '\n') i++;
+      continue;
+    }
+
+    // Block comment.
+    if (c === '/' && c2 === '*') {
+      i += 2;
+      while (i < n && !(src[i] === '*' && src[i + 1] === '/')) i++;
+      i += 2;
+      continue;
+    }
+
+    // String literal — copy verbatim, handle escapes.
+    if (c === '"' || c === "'" || c === '`') {
+      const quote = c;
+      out += c;
+      i++;
+      while (i < n) {
+        const ch = src[i];
+        out += ch;
+        if (ch === '\\' && i + 1 < n) {
+          out += src[i + 1];
+          i += 2;
+          continue;
+        }
+        i++;
+        if (ch === quote) break;
+      }
+      prevSig = quote;
+      continue;
+    }
+
+    // Regex literal — only after operators / keywords where regex is valid.
+    if (c === '/' && isRegexContext(prevSig)) {
+      out += c;
+      i++;
+      while (i < n) {
+        const ch = src[i];
+        out += ch;
+        if (ch === '\\' && i + 1 < n) {
+          out += src[i + 1];
+          i += 2;
+          continue;
+        }
+        i++;
+        if (ch === '/') break;
+      }
+      // Flags.
+      while (i < n && /[a-z]/i.test(src[i])) {
+        out += src[i];
+        i++;
+      }
+      prevSig = '/';
+      continue;
+    }
+
+    // Whitespace collapse.
+    if (c === ' ' || c === '\t' || c === '\n' || c === '\r') {
+      // Look ahead for the next non-whitespace char.
+      let j = i + 1;
+      while (j < n && (src[j] === ' ' || src[j] === '\t' || src[j] === '\n' || src[j] === '\r')) j++;
+      const nextCh = j < n ? src[j] : '';
+      // Keep a single space only if removing it would fuse two identifier/number chars.
+      if (nextCh && needsSeparator(prevSig, nextCh)) {
+        out += ' ';
+      }
+      i = j;
+      continue;
+    }
+
+    out += c;
+    prevSig = c;
+    i++;
+  }
+
+  return out;
+}
+
+// Identifier-like = [A-Za-z0-9_$]
+function needsSeparator(a: string, b: string): boolean {
+  if (!a || !b) return false;
+  return isIdentChar(a) && isIdentChar(b);
+}
+
+function isIdentChar(c: string): boolean {
+  return /[A-Za-z0-9_$]/.test(c);
+}
+
+// Heuristic: a `/` is a regex literal start when the previous non-whitespace
+// token is an operator, opening bracket/brace/paren, comma, semicolon, or
+// the empty string (start of body). Otherwise it's division.
+function isRegexContext(prev: string): boolean {
+  if (prev === '') return true;
+  return /[=([{,;!&|?:+\-*%^~<>]/.test(prev);
+}