@everystack/server 0.1.0 → 0.2.0

package/src/plugin.ts

@@ -0,0 +1,517 @@
+/**
+ * @everystack/server/plugin — Plugin system for composable Lambda handlers.
+ *
+ * Plugins are factory functions that receive a shared context and return
+ * route/action/handler contributions. The framework composes them into a
+ * single Lambda handler with lazy initialization.
+ */
+
+import type { Handler, Route, LogSink, ServerCacheConfig } from './index';
+import type {
+  APIGatewayProxyEventV2,
+  APIGatewayProxyStructuredResultV2,
+} from 'aws-lambda';
+import {
+  createRouter,
+  eventToRequest,
+  responseToResult,
+  log,
+} from './index';
+
+// --- Plugin Types ---
+
+/**
+ * Shared context provided to all plugins during initialization.
+ * Apps extend this with additional resources (auth handlers, job adapters, etc.).
+ */
+export interface PluginContext {
+  /** Drizzle database connection */
+  db: any;
+  /** App schema (all tables) */
+  schema: Record<string, any>;
+  /** Shared JWT verification — one function, used by all plugins */
+  verifyToken: (token: string) => Promise<Record<string, unknown> | null>;
+  /** Runtime environment */
+  environment: string;
+  /** Publish a background job */
+  publishJob: (type: string, payload: unknown) => Promise<string>;
+  /** Extensible — apps add whatever their plugins need */
+  [key: string]: unknown;
+}
+
+/**
+ * What a plugin contributes to the application.
+ */
+export interface PluginContribution {
+  /** Routes this plugin handles (matched in plugin array order) */
+  routes?: Route[];
+  /** Named handlers for cross-plugin reference (e.g., SSR as fallback) */
+  handlers?: Record<string, Handler>;
+  /** CLI actions this plugin handles (invoked via Lambda direct invoke) */
+  actions?: Record<string, ActionHandler>;
+  /** Log sink — at most one plugin should provide this */
+  logSink?: LogSink;
+}
+
+/**
+ * An action handler receives the payload and the shared context.
+ * No module-level globals needed — context is injected.
+ */
+export type ActionHandler = (
+  payload: unknown,
+  ctx: PluginContext
+) => Promise<unknown>;
+
+/**
+ * A plugin is a factory function.
+ * It receives the shared context and returns its contributions.
+ * Called lazily during init — dynamic imports go inside the factory body.
+ */
+export type Plugin = (ctx: PluginContext) => Promise<PluginContribution>;
+
+// --- Plugin Lambda Handler Options ---
+
+export interface PluginLambdaHandlerOptions {
+  /**
+   * Creates the shared context that all plugins receive.
+   * Called once on first request (lazy init for cold starts).
+   */
+  context: () => Promise<PluginContext>;
+  /**
+   * Plugins to compose. Order matters for route priority —
+   * earlier plugins' routes match first.
+   */
+  plugins: Plugin[];
+  /**
+   * App-level routes that don't belong to any plugin.
+   * Evaluated after plugin routes.
+   */
+  routes?: (ctx: PluginContext) => Route[];
+  /**
+   * Fallback handler when no route matches (e.g., SSR).
+   * Can be async if the handler requires initialization.
+   */
+  fallback?: (ctx: PluginContext) => Handler | Promise<Handler>;
+  /**
+   * App-level actions merged with plugin-contributed actions.
+   * App actions take precedence over plugin actions on name collision.
+   */
+  actions?: Record<string, ActionHandler>;
+  /** Override default Cache-Control headers */
+  cache?: ServerCacheConfig;
+}
+
+// --- Plugin Lambda Handler Implementation ---
+
+export function createPluginLambdaHandler(
+  options: PluginLambdaHandlerOptions
+): (event: APIGatewayProxyEventV2 | Record<string, unknown>) => Promise<APIGatewayProxyStructuredResultV2 | unknown> {
+  let cached: {
+    ctx: PluginContext;
+    router: (path: string, method: string) => Handler;
+    actions: Record<string, ActionHandler>;
+    logSink?: LogSink;
+  } | null = null;
+
+  async function ensureInitialized() {
+    if (cached) return cached;
+
+    const ctx = await options.context();
+
+    // Initialize all plugins (sequential to allow import ordering)
+    const contributions: PluginContribution[] = [];
+    for (const plugin of options.plugins) {
+      contributions.push(await plugin(ctx));
+    }
+
+    // Collect routes (plugin order = priority)
+    const pluginRoutes = contributions.flatMap(c => c.routes ?? []);
+    const appRoutes = options.routes?.(ctx) ?? [];
+    const allRoutes = [...pluginRoutes, ...appRoutes];
+
+    // Collect actions (app-level takes precedence on collision)
+    const pluginActions: Record<string, ActionHandler> = {};
+    for (const contribution of contributions) {
+      if (contribution.actions) {
+        Object.assign(pluginActions, contribution.actions);
+      }
+    }
+    const allActions = { ...pluginActions, ...(options.actions ?? {}) };
+
+    // Collect log sink (first one wins)
+    const logSink = contributions.find(c => c.logSink)?.logSink;
+
+    // Build router
+    const fallback = await options.fallback?.(ctx);
+    const router = createRouter(allRoutes, fallback);
+
+    cached = { ctx, router, actions: allActions, logSink };
+    log('info', 'Plugin handlers initialized', { plugins: options.plugins.length });
+    return cached;
+  }
+
+  return async (
+    event: APIGatewayProxyEventV2 | Record<string, unknown>
+  ): Promise<APIGatewayProxyStructuredResultV2 | unknown> => {
+    // Direct CLI invoke via Lambda Invoke — IAM is the auth layer.
+    if ('_action' in event && typeof event._action === 'string') {
+      const { ctx, actions } = await ensureInitialized();
+      const actionName = event._action;
+      const actionHandler = actions[actionName];
+      if (!actionHandler) {
+        return { error: `Unknown action: ${actionName}` };
+      }
+      log('info', 'CLI action invoked', { action: actionName });
+      try {
+        return await actionHandler(event._payload, ctx);
+      } catch (error) {
+        log('error', 'CLI action error', { action: actionName, error: String(error) });
+        return { error: String(error) };
+      }
+    }
+
+    // HTTP event — Function URL or API Gateway
+    const httpEvent = event as APIGatewayProxyEventV2;
+    const requestId =
+      httpEvent.headers?.['x-amzn-trace-id'] ||
+      httpEvent.headers?.['x-request-id'] ||
+      crypto.randomUUID();
+
+    try {
+      const { router, logSink } = await ensureInitialized();
+      const request = eventToRequest(httpEvent);
+      const path = httpEvent.rawPath;
+      const method = httpEvent.requestContext.http.method;
+      const handlerFn = router(path, method);
+      const response = await handlerFn(request);
+      const result = await responseToResult(response);
+
+      // Propagate request ID
+      result.headers = { ...result.headers, 'x-request-id': requestId };
+
+      // Set Cache-Control if not already set by the handler
+      if (!result.headers['cache-control']) {
+        if (method === 'GET' || method === 'HEAD') {
+          const isAuthenticated = !!httpEvent.headers?.authorization;
+          result.headers['cache-control'] = isAuthenticated
+            ? (options.cache?.private ?? 'private, no-store')
+            : (options.cache?.public ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5');
+        } else {
+          result.headers['cache-control'] = options.cache?.mutation ?? 'no-store';
+        }
+      }
+
+      // Response size guard — Lambda Function URLs have a 6MB limit
+      if (result.body && result.body.length > 5 * 1024 * 1024) {
+        return {
+          statusCode: 413,
+          headers: {
+            'Content-Type': 'application/json',
+            'cache-control': 'no-store',
+            'x-request-id': requestId,
+          },
+          body: JSON.stringify({ error: 'Response too large' }),
+        };
+      }
+
+      log('info', 'Request completed', {
+        requestId,
+        path,
+        method,
+        status: result.statusCode,
+      });
+
+      // Write to log sink (non-blocking)
+      if (logSink) {
+        logSink.ingest([{
+          id: requestId,
+          timestamp: Date.now(),
+          level: (result.statusCode ?? 200) >= 500 ? 'error' : 'info',
+          message: `${method} ${path} ${result.statusCode ?? 200}`,
+          source: 'lambda',
+          traceId: requestId,
+          data: { path, method, status: result.statusCode ?? 200, platform: 'server' },
+        }]).catch(() => {});
+      }
+
+      return result;
+    } catch (error) {
+      log('error', 'Lambda handler error', {
+        requestId,
+        error: String(error),
+      });
+      return {
+        statusCode: 500,
+        headers: {
+          'Content-Type': 'application/json',
+          'cache-control': 'no-store',
+          'x-request-id': requestId,
+        },
+        body: JSON.stringify({
+          error: 'Internal Server Error',
+          ...(process.env.ENVIRONMENT === 'dev'
+            ? { details: String(error) }
+            : {}),
+        }),
+      };
+    }
+  };
+}
+
+// --- SSR Fallback Plugin ---
+
+import type { PostProcessResult, WebHandlerOptions } from './ssr';
+
+export interface SsrPluginOptions {
+  /** App-specific HTML post-processing (e.g., JSON-LD injection, meta status codes) */
+  postProcessHtml?: (html: string, request: Request) => PostProcessResult | Promise<PostProcessResult>;
+  /** Channel name for bundle resolution (default: from ENVIRONMENT env var) */
+  channel?: string;
+  /** Query params to strip before SSR (default: ['_v']) */
+  stripQueryParams?: string[];
+  /** Inject __EXPO_ROUTER_HYDRATE__ flag (default: true) */
+  injectHydrateFlag?: boolean;
+}
+
+interface SsrContext extends PluginContext {
+  updatesStorage: any;
+}
+
+/**
+ * Creates an SSR fallback handler from plugin context.
+ * Resolves the web handler from S3/storage, extracts auth from cookies,
+ * and runs each request with auth context for SSR loaders.
+ *
+ * Usage:
+ *   fallback: ssrPlugin(),
+ *   fallback: ssrPlugin({ postProcessHtml: injectJsonLd }),
+ */
+export function ssrPlugin(options: SsrPluginOptions = {}): (ctx: PluginContext) => Promise<Handler> {
+  return async (ctx: PluginContext): Promise<Handler> => {
+    const { getWebHandler } = await import('./ssr');
+
+    // Auth helpers are optional — SSR works without auth (just no user context)
+    let getTokenFromCookies: ((cookieHeader: string | null) => string | null) | null = null;
+    let runWithAuthContext: (<T>(user: any, fn: () => T | Promise<T>) => T | Promise<T>) | null = null;
+    try {
+      const cookies = await import('@everystack/auth/cookies');
+      const context = await import('@everystack/auth/context');
+      getTokenFromCookies = cookies.getTokenFromCookies;
+      runWithAuthContext = context.runWithAuthContext;
+    } catch {
+      // @everystack/auth not installed — SSR works without auth context
+    }
+
+    const ssrOptions: Partial<WebHandlerOptions> = {};
+    if (options.postProcessHtml) ssrOptions.postProcessHtml = options.postProcessHtml;
+    if (options.channel) ssrOptions.channel = options.channel;
+    if (options.stripQueryParams) ssrOptions.stripQueryParams = options.stripQueryParams;
+    if (options.injectHydrateFlag !== undefined) ssrOptions.injectHydrateFlag = options.injectHydrateFlag;
+
+    return async (request: Request): Promise<Response> => {
+      const webHandler = await getWebHandler(
+        (ctx as SsrContext).updatesStorage,
+        { db: ctx.db, ...ssrOptions },
+      );
+      if (!webHandler) return new Response('Not Found', { status: 404 });
+
+      // Extract auth context from cookie for SSR loaders
+      let user: Record<string, unknown> | null = null;
+      if (getTokenFromCookies && runWithAuthContext) {
+        const cookieHeader = request.headers.get('cookie');
+        if (cookieHeader) {
+          const token = getTokenFromCookies(cookieHeader);
+          if (token) {
+            const claims = await ctx.verifyToken(token);
+            if (claims && typeof claims.sub === 'string') {
+              user = claims;
+            }
+          }
+        }
+        return runWithAuthContext(user, () => webHandler(request));
+      }
+
+      return webHandler(request);
+    };
+  };
+}
+
+// --- Database Actions Plugin ---
+
+export interface DbPluginOptions {
+  /** Absolute path to drizzle migrations folder */
+  migrationsFolder: string;
+  /** App-provided seed function — action only registered if provided */
+  seed?: (db: any, schema: any) => Promise<any>;
+  /** PostgreSQL schemas to drop during db:reset (default: ['public', 'drizzle']) */
+  schemas?: string[];
+  /** Connection info callback for db:psql (falls back to SST Resource.Database) */
+  connectionInfo?: () => Promise<Record<string, string>>;
+  /** Enable console action (default: true) */
+  allowConsole?: boolean;
+  /** Read replica URL for db:query (default: process.env.READ_DATABASE_URL) */
+  readDatabaseUrl?: string;
+}
+
+/**
+ * Database administration actions as a plugin.
+ * Contributes: migrate, seed, db:reset, db:psql, db:query, console.
+ *
+ * Usage:
+ *   dbPlugin({ migrationsFolder: join(__dirname, '..', 'drizzle'), seed: runSeed })
+ */
+export function dbPlugin(options: DbPluginOptions): Plugin {
+  return async (ctx: PluginContext): Promise<PluginContribution> => {
+    const actions: Record<string, ActionHandler> = {};
+
+    // --- migrate ---
+    actions.migrate = async (_payload, ctx) => {
+      const { runMigrations } = await import('./migrate');
+      return await runMigrations(ctx.db, options.migrationsFolder);
+    };
+
+    // --- seed (only when app provides a seed function) ---
+    if (options.seed) {
+      const seedFn = options.seed;
+      actions.seed = async (_payload, ctx) => {
+        if (ctx.environment !== 'dev') {
+          return { error: 'Seed is only available in dev environment' };
+        }
+        return await seedFn(ctx.db, ctx.schema);
+      };
+    }
+
+    // --- db:reset ---
+    actions['db:reset'] = async (_payload, ctx) => {
+      if (ctx.environment !== 'dev') {
+        return { error: 'db:reset is only available in dev environment' };
+      }
+      const { sql } = await import('drizzle-orm');
+      const schemas = options.schemas ?? ['public', 'drizzle'];
+      const dropStatements = schemas
+        .map(s => `DROP SCHEMA IF EXISTS ${s} CASCADE;`)
+        .join('\n    ');
+      await ctx.db.execute(sql.raw(`
+    ${dropStatements}
+    CREATE SCHEMA public;
+    GRANT ALL ON SCHEMA public TO postgres;
+    GRANT ALL ON SCHEMA public TO public;
+  `));
+      const { runMigrations } = await import('./migrate');
+      const result = await runMigrations(ctx.db, options.migrationsFolder);
+      return { reset: true, ...result };
+    };
+
+    // --- db:psql ---
+    actions['db:psql'] = async () => {
+      if (options.connectionInfo) {
+        return await options.connectionInfo();
+      }
+      try {
+        const { Resource } = await import('sst');
+        return {
+          host: (Resource as any).Database.host,
+          port: (Resource as any).Database.port,
+          database: (Resource as any).Database.database,
+          username: (Resource as any).Database.username,
+          password: (Resource as any).Database.password,
+        };
+      } catch {
+        return { error: 'No connectionInfo callback provided and SST Resource.Database not available' };
+      }
+    };
+
+    // --- db:query ---
+    actions['db:query'] = async (payload, ctx) => {
+      const { sql: querySql } = payload as { sql: string };
+      if (!querySql) {
+        return { error: 'SQL query is required' };
+      }
+      const writePatterns = [
+        /^INSERT\s/i, /^UPDATE\s/i, /^DELETE\s/i, /^DROP\s/i,
+        /^CREATE\s/i, /^ALTER\s/i, /^TRUNCATE\s/i, /^GRANT\s/i, /^REVOKE\s/i,
+      ];
+      if (writePatterns.some(p => p.test(querySql.trim()))) {
+        return {
+          error: 'Write operations are not allowed via db:query. Use db:migrate, seed, or console for write operations.',
+        };
+      }
+      try {
+        const { sql } = await import('drizzle-orm');
+        let queryDb = ctx.db;
+        const readUrl = options.readDatabaseUrl ?? process.env.READ_DATABASE_URL;
+        if (readUrl && readUrl !== process.env.DATABASE_URL) {
+          const { drizzle } = await import('drizzle-orm/postgres-js');
+          const postgres = (await import('postgres')).default;
+          queryDb = drizzle(postgres(readUrl, { max: 1, idle_timeout: 20, connect_timeout: 10 }));
+        }
+        const result: any = await queryDb.execute(sql.raw(querySql));
+        const rows = Array.isArray(result) ? result : result.rows || [];
+        return { rows };
+      } catch (err: any) {
+        return { error: err.message || String(err) };
+      }
+    };
+
+    // --- console ---
+    if (options.allowConsole !== false) {
+      actions.console = async (payload, ctx) => {
+        const { expression } = payload as { expression: string };
+        if (!expression) return { error: 'No expression provided' };
+        try {
+          const { eq, and, or, gt, lt, gte, lte, ne, count, sum, avg, sql, desc, asc } =
+            await import('drizzle-orm');
+          const evalContext: Record<string, unknown> = {
+            db: ctx.db, schema: ctx.schema,
+            eq, and, or, gt, lt, gte, lte, ne, count, sum, avg, sql, desc, asc,
+          };
+          const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
+          const fn = new AsyncFunction(
+            ...Object.keys(evalContext),
+            `return (${expression})`,
+          );
+          const result = await fn(...Object.values(evalContext));
+          return { result };
+        } catch (err: any) {
+          return { error: err.message || String(err) };
+        }
+      };
+    }
+
+    return { actions };
+  };
+}
+
+// --- Plugin Handler for Non-Lambda Runtimes (Expo Router, Bun, Deno) ---
+
+/**
+ * Creates a Web Standard handler from plugins — no Lambda, no event adaptation.
+ * For use with Expo Router API routes, Bun.serve, Deno.serve, etc.
+ */
+export function createPluginHandler(options: {
+  context: () => Promise<PluginContext>;
+  plugins: Plugin[];
+  routes?: (ctx: PluginContext) => Route[];
+  fallback?: (ctx: PluginContext) => Handler | Promise<Handler>;
+}): Handler {
+  let cached: { router: (path: string, method: string) => Handler } | null = null;
+
+  return async (request: Request): Promise<Response> => {
+    if (!cached) {
+      const ctx = await options.context();
+      const contributions: PluginContribution[] = [];
+      for (const plugin of options.plugins) {
+        contributions.push(await plugin(ctx));
+      }
+      const pluginRoutes = contributions.flatMap(c => c.routes ?? []);
+      const appRoutes = options.routes?.(ctx) ?? [];
+      const allRoutes = [...pluginRoutes, ...appRoutes];
+      const fallback = await options.fallback?.(ctx);
+      cached = { router: createRouter(allRoutes, fallback) };
+    }
+
+    const url = new URL(request.url);
+    const handler = cached.router(url.pathname, request.method);
+    return handler(request);
+  };
+}

package/src/ssr.ts

@@ -278,7 +278,7 @@ export async function getWebHandler(
   options?: WebHandlerOptions,
 ): Promise<((request: Request) => Promise<Response>) | null> {
   const now = Date.now();
-  const channel = options?.channel || 'production';
+  const channel = options?.channel || process.env.ENVIRONMENT || 'production';
   const buildDir = `${BUILD_DIR_BASE}/${channel}`;
 
   const cached = cachedHandlers.get(channel);

package/src/worker.ts

@@ -7,6 +7,26 @@
 
 import { log } from './index.js';
 
+/** Job shape — mirrors @everystack/jobs Job interface (type-compatible, no circular dep). */
+export interface WorkerJob<T = unknown> {
+  id: string;
+  type: string;
+  payload: T;
+  status: 'pending' | 'active' | 'completed' | 'failed' | 'dead';
+  attempts: number;
+  maxAttempts: number;
+  priority: number;
+  runAt: Date;
+  lockedAt: Date | null;
+  lockedBy: string | null;
+  completedAt: Date | null;
+  failedAt: Date | null;
+  error: string | null;
+  createdAt: Date;
+}
+
+export type JobHandler<T = unknown> = (payload: T, job: WorkerJob<T>) => Promise<void>;
+
 export interface SQSEvent {
   Records: Array<{
     messageId: string;
@@ -20,7 +40,30 @@ export interface SQSBatchResponse {
   batchItemFailures: Array<{ itemIdentifier: string }>;
 }
 
-export type JobHandler = (payload: any, job: { id: string; type: string }) => Promise<void>;
+/**
+ * Build a Job object from SQS message fields.
+ * Fills required Job properties with sensible defaults — the handler
+ * receives a complete Job even without a database.
+ */
+function jobFromSqsMessage(jobId: string, type: string, payload: unknown): WorkerJob {
+  const now = new Date();
+  return {
+    id: jobId,
+    type,
+    payload,
+    status: 'active',
+    attempts: 1,
+    maxAttempts: 3,
+    priority: 0,
+    runAt: now,
+    lockedAt: now,
+    lockedBy: null,
+    completedAt: null,
+    failedAt: null,
+    error: null,
+    createdAt: now,
+  };
+}
 
 export function createWorkerHandler(
   init: () => Promise<Record<string, JobHandler>>
@@ -50,7 +93,8 @@ export function createWorkerHandler(
           continue;
         }
 
-        await handlerFn(payload, { id: jobId, type });
+        const job = jobFromSqsMessage(jobId, type, payload);
+        await handlerFn(payload, job);
         log('info', 'Job completed', { type, jobId });
       } catch (error) {
         log('error', 'Job failed', { messageId: record.messageId, error: String(error) });

package/stubs/@tanstack/react-query/index.mjs

@@ -0,0 +1,13 @@
+// Auto-generated stub — these exports are never called at runtime.
+const _ = new Proxy(function(){}, {
+  get: () => _,
+  apply: () => _,
+  construct: () => _,
+});
+export default _;
+export const useQuery = _;
+export const useMutation = _;
+export const useQueryClient = _;
+export const QueryClient = _;
+export const QueryClientProvider = _;
+export const useInfiniteQuery = _;

package/stubs/@tanstack/react-query/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@tanstack/react-query",
+  "version": "0.0.0-stub",
+  "type": "module",
+  "main": "index.mjs",
+  "exports": {
+    ".": "./index.mjs",
+    "./*": "./index.mjs"
+  }
+}

package/stubs/@tanstack/react-query/sst-env.d.ts

@@ -0,0 +1,10 @@
+/* This file is auto-generated by SST. Do not edit. */
+/* tslint:disable */
+/* eslint-disable */
+/* deno-fmt-ignore-file */
+/* biome-ignore-all lint: auto-generated */
+
+/// <reference path="../../../../sst-env.d.ts" />
+
+import "sst"
+export {}

package/stubs/d3-array/index.mjs

@@ -0,0 +1,15 @@
+// Auto-generated stub — these exports are never called at runtime.
+const _ = new Proxy(function(){}, {
+  get: () => _,
+  apply: () => _,
+  construct: () => _,
+});
+export default _;
+export const extent = _;
+export const max = _;
+export const min = _;
+export const bisector = _;
+export const group = _;
+export const rollup = _;
+export const range = _;
+export const bin = _;

package/stubs/d3-array/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "d3-array",
+  "version": "0.0.0-stub",
+  "type": "module",
+  "main": "index.mjs",
+  "exports": {
+    ".": "./index.mjs",
+    "./*": "./index.mjs"
+  }
+}

package/stubs/d3-array/sst-env.d.ts

@@ -0,0 +1,10 @@
+/* This file is auto-generated by SST. Do not edit. */
+/* tslint:disable */
+/* eslint-disable */
+/* deno-fmt-ignore-file */
+/* biome-ignore-all lint: auto-generated */
+
+/// <reference path="../../../sst-env.d.ts" />
+
+import "sst"
+export {}

package/stubs/d3-scale/index.mjs

@@ -0,0 +1,11 @@
+// Auto-generated stub — these exports are never called at runtime.
+const _ = new Proxy(function(){}, {
+  get: () => _,
+  apply: () => _,
+  construct: () => _,
+});
+export default _;
+export const scaleLinear = _;
+export const scaleTime = _;
+export const scaleBand = _;
+export const scaleOrdinal = _;

package/stubs/d3-scale/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "d3-scale",
+  "version": "0.0.0-stub",
+  "type": "module",
+  "main": "index.mjs",
+  "exports": {
+    ".": "./index.mjs",
+    "./*": "./index.mjs"
+  }
+}