@everystack/server 0.1.0

package/src/ssr.ts

@@ -0,0 +1,425 @@
+/**
+ * @everystack/server/ssr — Web SSR handler for Lambda.
+ *
+ * Downloads a brotli-compressed tar archive from S3, extracts it to /tmp,
+ * and serves requests via expo-server. Caches the handler across warm
+ * Lambda invocations with a TTL-based re-check for new releases.
+ *
+ * Two modes:
+ *   V1 (no DB): reads from convention path {channel}/web/bundle.tar.br
+ *   V2 (with DB): resolves channel → branch → latest release → storagePrefix
+ *
+ * Per-channel caching: each channel maintains its own cached handler and
+ * build directory, allowing one Lambda to serve multiple channels.
+ */
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { StorageAdapter } from '@everystack/cli';
+
+// expo-server internals — accessed via package exports
+import { createRequestHandler } from 'expo-server/adapter/abstract';
+import { createNodeEnv, createNodeRequestScope } from 'expo-server/vendor/environment/node';
+
+const BUILD_DIR_BASE = '/tmp/web-build';
+const TTL_MS = 60_000; // Re-check storage every 60s
+
+/** Metadata from the channel's web manifest, used for diagnostics headers. */
+export interface ReleaseMetadata {
+  updateId?: string;
+  runtimeVersion?: string;
+  createdAt?: string;
+  storagePrefix?: string;
+}
+
+/** Resolved bundle key with optional manifest metadata. */
+export interface WebRelease {
+  bundleKey: string;
+  metadata?: ReleaseMetadata;
+}
+
+interface CachedHandler {
+  bundleKey: string;
+  etag: string;
+  metadata?: ReleaseMetadata;
+  handler: (request: Request) => Promise<Response>;
+  run: (fn: (request: Request) => Promise<Response>, request: Request) => Promise<Response>;
+  checkedAt: number;
+}
+
+const cachedHandlers = new Map<string, CachedHandler>();
+
+/** Return type for postProcessHtml — string replaces HTML, object also overrides status. */
+export type PostProcessResult = string | { html: string; status?: number };
+
+export interface WebHandlerOptions {
+  /** Channel name (default: 'production') */
+  channel?: string;
+  /** Hook called after bundle extraction, before handler creation. */
+  afterExtract?: (buildDir: string) => Promise<void> | void;
+  /** Drizzle database instance. When provided, resolves bundle via DB (V2). */
+  db?: any;
+
+  /** Query params to strip before SSR. Default: ['_v']. Set [] to disable. */
+  stripQueryParams?: string[];
+
+  /** Inject __EXPO_ROUTER_HYDRATE__ flag before </head>. Default: true. */
+  injectHydrateFlag?: boolean;
+
+  /**
+   * App-specific HTML post-processing. Called after built-in processing
+   * (param stripping, hydrate flag). Receives the processed HTML and the
+   * ORIGINAL request (pre-stripping). Return string to replace HTML, or
+   * { html, status } to also override the response status code.
+   */
+  postProcessHtml?: (html: string, request: Request) =>
+    PostProcessResult | Promise<PostProcessResult>;
+}
+
+const DEFAULT_STRIP_PARAMS = ['_v'];
+const HYDRATE_SCRIPT = '<script>globalThis.__EXPO_ROUTER_HYDRATE__=true;</script>\n';
+
+/**
+ * Wraps an SSR request handler with framework-level fixes:
+ *
+ *   1. Strips CFF query params (_v) so expo-router loader data keys
+ *      match the client-side route path (which has no CFF params).
+ *   2. Injects `__EXPO_ROUTER_HYDRATE__=true` before `</head>` so React
+ *      Native Web uses `hydrateRoot()` instead of `createRoot()`.
+ *      (React 19 suppresses <script> tags from SSR output, so this must
+ *      be done via string replacement after rendering.)
+ *   3. Calls an optional `postProcessHtml` hook for app-specific transforms
+ *      (e.g., JSON-LD injection, status code override from meta tags).
+ *
+ * @param innerHandler - The expo-server request handler
+ * @param bundleKey - Bundle identifier, set as X-Bundle-Key header
+ * @param options - SSR processing options
+ */
+export function wrapSsrHandler(
+  innerHandler: (request: Request) => Promise<Response>,
+  bundleKey: string,
+  options?: Pick<WebHandlerOptions, 'stripQueryParams' | 'injectHydrateFlag' | 'postProcessHtml'>,
+  metadata?: ReleaseMetadata,
+): (request: Request) => Promise<Response> {
+  const stripParams = options?.stripQueryParams ?? DEFAULT_STRIP_PARAMS;
+  const injectHydrate = options?.injectHydrateFlag !== false;
+  const postProcess = options?.postProcessHtml;
+
+  return async (request: Request): Promise<Response> => {
+    // 1. Strip CFF query params from request URL
+    let cleanRequest = request;
+    if (stripParams.length > 0) {
+      const url = new URL(request.url);
+      let modified = false;
+      for (const param of stripParams) {
+        if (url.searchParams.has(param)) {
+          url.searchParams.delete(param);
+          modified = true;
+        }
+      }
+      if (modified) {
+        cleanRequest = new Request(url.toString(), request);
+      }
+    }
+
+    // Delegate to inner handler
+    const response = await innerHandler(cleanRequest);
+
+    // Set bundle key and release metadata on all responses
+    const headers = new Headers(response.headers);
+    headers.set('X-Bundle-Key', bundleKey);
+    if (metadata?.updateId) headers.set('X-Update-Id', metadata.updateId);
+    if (metadata?.runtimeVersion) headers.set('X-Runtime-Version', metadata.runtimeVersion);
+    if (metadata?.createdAt) headers.set('X-Release-Created', metadata.createdAt);
+
+    // Non-HTML responses pass through untouched
+    const ct = headers.get('content-type') || '';
+    if (!ct.includes('text/html')) {
+      return new Response(response.body, {
+        status: response.status,
+        headers,
+      });
+    }
+
+    // 2. HTML post-processing
+    let html = await response.text();
+    let status = response.status;
+
+    // Inject hydration flag (idempotent — only if not already present)
+    if (injectHydrate && !html.includes('__EXPO_ROUTER_HYDRATE__')) {
+      html = html.replace('</head>', `${HYDRATE_SCRIPT}</head>`);
+    }
+
+    // 3. App-specific post-processing
+    if (postProcess) {
+      const result = await postProcess(html, request);
+      if (typeof result === 'string') {
+        html = result;
+      } else {
+        html = result.html;
+        if (result.status !== undefined) {
+          status = result.status;
+        }
+      }
+    }
+
+    // Update content-length to match modified HTML
+    headers.set('content-length', String(Buffer.byteLength(html)));
+
+    return new Response(html, { status, headers });
+  };
+}
+
+/**
+ * Resolve the S3 bundle key and release metadata for a channel.
+ *
+ * Resolution order:
+ *   1. S3 channel pointer: {channel}/web/manifest.json → storagePrefix + metadata → bundle key
+ *   2. DB resolution: channel → branchRef → latest web release → storagePrefix
+ *   3. Convention fallback: {channel}/web/bundle.tar.br
+ */
+export async function resolveWebRelease(channel: string, storage?: StorageAdapter, db?: any): Promise<WebRelease> {
+  const fallback = `${channel}/web/bundle.tar.br`;
+
+  // Priority 1: S3 channel pointer manifest
+  if (storage) {
+    try {
+      const pointerKey = `${channel}/web/manifest.json`;
+      const result = await storage.get(pointerKey);
+      if (result) {
+        const pointer = JSON.parse(result.data.toString('utf8'));
+        if (pointer.storagePrefix) {
+          return {
+            bundleKey: `${pointer.storagePrefix}/bundle.tar.br`,
+            metadata: {
+              updateId: pointer.updateId,
+              runtimeVersion: pointer.runtimeVersion,
+              createdAt: pointer.createdAt,
+              storagePrefix: pointer.storagePrefix,
+            },
+          };
+        }
+      }
+    } catch {
+      // Pointer doesn't exist or is malformed — fall through
+    }
+  }
+
+  // Priority 2: DB resolution
+  if (!db) return { bundleKey: fallback };
+
+  try {
+    // Dynamic import — only loaded when DB is used (keeps V1 zero-dep)
+    const { opsItems, buildArtifacts, runs } = await import('@everystack/cli/schema');
+    const { eq, and, desc, sql } = await import('drizzle-orm');
+
+    // Look up channel (opsItems type='release_channel')
+    const [ch] = await db
+      .select()
+      .from(opsItems)
+      .where(and(
+        eq(opsItems.type, 'release_channel'),
+        eq(opsItems.name, channel),
+      ))
+      .limit(1);
+
+    if (!ch) return { bundleKey: fallback };
+
+    const branchRef = (ch.data as Record<string, unknown>)?.branchRef as string;
+    if (!branchRef) return { bundleKey: fallback };
+
+    // Look up latest web release (buildArtifact type='ota') via run branchRef
+    const releaseResults = await db
+      .select({ release: buildArtifacts })
+      .from(buildArtifacts)
+      .innerJoin(runs, eq(buildArtifacts.runId, runs.id))
+      .where(and(
+        eq(buildArtifacts.type, 'ota'),
+        eq(buildArtifacts.platform, 'web'),
+        eq(runs.type, 'release'),
+        sql`${runs.data}->>'branchRef' = ${branchRef}`,
+      ))
+      .orderBy(desc(buildArtifacts.indexedAt))
+      .limit(1);
+
+    const rel = releaseResults[0]?.release;
+    if (!rel?.s3Key) return { bundleKey: fallback };
+
+    return { bundleKey: `${rel.s3Key}/bundle.tar.br` };
+  } catch {
+    // DB query failed — fall back to convention path
+    return { bundleKey: fallback };
+  }
+}
+
+/**
+ * Resolve the S3 bundle key for a channel.
+ * Delegates to resolveWebRelease — preserves existing API contract.
+ */
+export async function resolveBundleKey(channel: string, storage?: StorageAdapter, db?: any): Promise<string> {
+  return (await resolveWebRelease(channel, storage, db)).bundleKey;
+}
+
+/**
+ * Returns a Request→Response handler for the current web release,
+ * or null if no web release exists yet.
+ *
+ * V1: reads from convention path {channel}/web/bundle.tar.br (no DB required)
+ * V2: resolves channel → branch → latest release → storagePrefix (DB required)
+ *
+ * Per-channel caching: each channel has its own handler and build directory.
+ * Re-checks storage every TTL_MS to pick up new releases.
+ */
+export async function getWebHandler(
+  storage: StorageAdapter,
+  options?: WebHandlerOptions,
+): Promise<((request: Request) => Promise<Response>) | null> {
+  const now = Date.now();
+  const channel = options?.channel || 'production';
+  const buildDir = `${BUILD_DIR_BASE}/${channel}`;
+
+  const cached = cachedHandlers.get(channel);
+
+  // If cached and within TTL, return existing handler (no DB/S3 check)
+  if (cached && (now - cached.checkedAt) < TTL_MS) {
+    const rawHandler = async (req: Request) => cached.run(cached.handler, req);
+    return wrapSsrHandler(rawHandler, cached.bundleKey, options, cached.metadata);
+  }
+
+  // TTL expired or no cache — resolve bundle key and metadata
+  const { bundleKey, metadata } = await resolveWebRelease(channel, storage, options?.db);
+
+  // Check if bundle exists and get its ETag
+  let meta: { etag: string } | null = null;
+  try {
+    meta = await storage.head(bundleKey);
+  } catch {
+    // Storage unavailable — graceful fallback
+    return null;
+  }
+
+  if (!meta) {
+    return null;
+  }
+
+  // If already cached with same key and ETag, just update TTL
+  if (cached && cached.bundleKey === bundleKey && cached.etag === meta.etag) {
+    cached.checkedAt = now;
+    const rawHandler = async (req: Request) => cached.run(cached.handler, req);
+    return wrapSsrHandler(rawHandler, bundleKey, options, cached.metadata);
+  }
+
+  // New or updated release — download and extract server bundle archive
+  try {
+    await downloadAndExtract(storage, bundleKey, buildDir);
+  } catch {
+    // Download/extraction failed — no release available
+    return null;
+  }
+
+  if (options?.afterExtract) {
+    await options.afterExtract(buildDir);
+  }
+
+  // Create expo-server handler from the extracted bundle
+  const store = new AsyncLocalStorage();
+  const params = { build: buildDir };
+  const run = createNodeRequestScope(store, params);
+  const env = createNodeEnv(params);
+  const handler = createRequestHandler(env);
+
+  const entry: CachedHandler = {
+    bundleKey,
+    metadata,
+    etag: meta.etag,
+    handler,
+    run,
+    checkedAt: now,
+  };
+  cachedHandlers.set(channel, entry);
+
+  const rawHandler = async (req: Request) => entry.run(entry.handler, req);
+  return wrapSsrHandler(rawHandler, bundleKey, options, metadata);
+}
+
+/**
+ * Downloads a bundle.tar.br from storage and extracts to a build directory.
+ * Pure JS — no external tar binary required (Lambda doesn't have it).
+ */
+export async function downloadAndExtract(storage: StorageAdapter, bundleKey: string, buildDir: string = BUILD_DIR_BASE): Promise<void> {
+  // Clean previous build
+  if (fs.existsSync(buildDir)) {
+    await fsp.rm(buildDir, { recursive: true, force: true });
+  }
+  await fsp.mkdir(buildDir, { recursive: true });
+
+  // Download the archive as a single blob
+  const result = await storage.get(bundleKey);
+  if (!result) {
+    throw new Error(`Server bundle not found at ${bundleKey}`);
+  }
+
+  // Brotli decompress → tar extract (pure JS)
+  const decompressed = zlib.brotliDecompressSync(result.data);
+  await extractTar(decompressed, buildDir);
+}
+
+/**
+ * Minimal tar extractor — handles POSIX ustar format.
+ * Tar is a sequence of 512-byte header blocks followed by file data blocks.
+ */
+export async function extractTar(data: Buffer, destDir: string): Promise<void> {
+  const BLOCK = 512;
+  let offset = 0;
+
+  while (offset + BLOCK <= data.length) {
+    const header = data.subarray(offset, offset + BLOCK);
+
+    // Two consecutive zero blocks = end of archive
+    if (header.every(b => b === 0)) break;
+
+    // Parse file name (bytes 0-99, may continue in prefix bytes 345-499)
+    const prefix = readString(header, 345, 155);
+    const name = readString(header, 0, 100);
+    const fullName = prefix ? `${prefix}/${name}` : name;
+
+    // Parse size (octal, bytes 124-135)
+    const sizeStr = readString(header, 124, 12);
+    const fileSize = parseInt(sizeStr, 8) || 0;
+
+    // Parse type flag (byte 156): '0' or '\0' = regular file, '5' = directory
+    const typeFlag = header[156];
+
+    offset += BLOCK;
+
+    // Strip leading './' from tar paths
+    const cleanName = fullName.replace(/^\.\//, '');
+    if (!cleanName) {
+      offset += Math.ceil(fileSize / BLOCK) * BLOCK;
+      continue;
+    }
+
+    const destPath = path.join(destDir, cleanName);
+
+    if (typeFlag === 53) { // '5' = directory
+      await fsp.mkdir(destPath, { recursive: true });
+    } else if (typeFlag === 48 || typeFlag === 0) { // '0' or '\0' = regular file
+      await fsp.mkdir(path.dirname(destPath), { recursive: true });
+      const fileData = data.subarray(offset, offset + fileSize);
+      await fsp.writeFile(destPath, fileData);
+    }
+    // Skip other types (symlinks, etc.)
+
+    // Advance past file data (padded to 512-byte boundary)
+    offset += Math.ceil(fileSize / BLOCK) * BLOCK;
+  }
+}
+
+function readString(buf: Buffer, offset: number, length: number): string {
+  const end = buf.indexOf(0, offset);
+  const slice = buf.subarray(offset, Math.min(end >= offset ? end : offset + length, offset + length));
+  return slice.toString('utf8').trim();
+}

package/src/sst-env.d.ts

@@ -0,0 +1,27 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * SST Resource type declarations for @everystack/server/db.
+ *
+ * Augments the `sst` module's Resource interface with the shapes
+ * expected by db.ts. Consumers must link matching SST resources
+ * (e.g., sst.aws.Postgres named "Database", sst.Secret named "JwtSecret").
+ */
+declare module 'sst' {
+  export interface Resource {
+    Database: {
+      username: string;
+      password: string;
+      host: string;
+      port: number;
+      database: string;
+    };
+    JwtSecret: {
+      value: string;
+    };
+  }
+}
+
+import 'sst';
+export {};

package/src/stubs.ts

@@ -0,0 +1,39 @@
+/**
+ * @everystack/server/stubs — Client stub configuration for Lambda bundling.
+ *
+ * Lambda bundles use esbuild with `external` to skip client-side packages.
+ * These stubs provide no-op modules so runtime imports don't crash.
+ *
+ * Usage in sst.config.ts:
+ *   import { clientStubs, stubsDir } from '@everystack/server/stubs';
+ *   // esbuild: { external: clientStubs }
+ *   // copyFiles: [{ from: stubsDir, to: 'node_modules' }]
+ */
+
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+/** Client-side packages that must be stubbed in Lambda bundles. */
+export const clientStubs = [
+  'react',
+  'react-dom',
+  'react-native',
+  'react-native-web',
+  '@tanstack/react-query',
+  'expo',
+  'expo-router',
+  'expo-status-bar',
+  'react-native-safe-area-context',
+  'react-native-screens',
+  'd3-shape',
+  'd3-scale',
+  'd3-array',
+  'd3-time',
+  'd3-time-format',
+];
+
+/** Absolute path to the stubs directory for use with SST copyFiles. */
+export const stubsDir = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../stubs'
+);

package/src/worker.ts

@@ -0,0 +1,63 @@
+/**
+ * @everystack/server/worker — SQS consumer pattern for Lambda.
+ *
+ * Provides the dispatch/error-handling/batch-failure shell.
+ * The app provides the job handler registry via the init function.
+ */
+
+import { log } from './index.js';
+
+export interface SQSEvent {
+  Records: Array<{
+    messageId: string;
+    body: string;
+    attributes: Record<string, string>;
+    messageAttributes: Record<string, unknown>;
+  }>;
+}
+
+export interface SQSBatchResponse {
+  batchItemFailures: Array<{ itemIdentifier: string }>;
+}
+
+export type JobHandler = (payload: any, job: { id: string; type: string }) => Promise<void>;
+
+export function createWorkerHandler(
+  init: () => Promise<Record<string, JobHandler>>
+): (event: SQSEvent) => Promise<SQSBatchResponse> {
+  let jobHandlers: Record<string, JobHandler> | null = null;
+
+  async function ensureInitialized(): Promise<Record<string, JobHandler>> {
+    if (jobHandlers) return jobHandlers;
+    jobHandlers = await init();
+    log('info', 'Worker initialized', { jobTypes: Object.keys(jobHandlers) });
+    return jobHandlers;
+  }
+
+  return async (event: SQSEvent): Promise<SQSBatchResponse> => {
+    const handlers = await ensureInitialized();
+    const batchItemFailures: Array<{ itemIdentifier: string }> = [];
+
+    for (const record of event.Records) {
+      try {
+        const body = JSON.parse(record.body);
+        const { jobId, type, payload } = body;
+
+        const handlerFn = handlers[type];
+        if (!handlerFn) {
+          log('warn', 'No handler for job type', { type, jobId });
+          batchItemFailures.push({ itemIdentifier: record.messageId });
+          continue;
+        }
+
+        await handlerFn(payload, { id: jobId, type });
+        log('info', 'Job completed', { type, jobId });
+      } catch (error) {
+        log('error', 'Job failed', { messageId: record.messageId, error: String(error) });
+        batchItemFailures.push({ itemIdentifier: record.messageId });
+      }
+    }
+
+    return { batchItemFailures };
+  };
+}