@everystack/server 0.1.0

package/src/index.ts

@@ -0,0 +1,324 @@
+/**
+ * @everystack/server — Lambda runtime primitives.
+ *
+ * Composable building blocks for Lambda handlers:
+ * - eventToRequest / responseToResult — Lambda ↔ Web Standard adapters
+ * - createRouter — path-based request dispatch
+ * - createLambdaHandler — full handler with lazy init, routing, error handling
+ * - log — structured JSON logging
+ */
+
+import type {
+  APIGatewayProxyEventV2,
+  APIGatewayProxyStructuredResultV2,
+} from 'aws-lambda';
+
+// --- Types ---
+
+export type Handler = (request: Request) => Promise<Response>;
+
+export interface Route {
+  /** URL path prefix (or exact path if `exact` is true) */
+  path: string;
+  /** HTTP method filter — if omitted, matches all methods */
+  method?: string;
+  /** If true, path must match exactly instead of prefix match */
+  exact?: boolean;
+  /** The handler function for this route */
+  handler: Handler;
+}
+
+/**
+ * Optional log sink for writing structured request logs to persistent storage.
+ * Structurally compatible with S3LogStorage from @everystack/logging — pass it
+ * directly without importing the logging package.
+ */
+export interface LogSink {
+  ingest(entries: Array<{
+    id: string;
+    timestamp: number;
+    level: 'info' | 'error' | 'warn' | 'debug' | 'fatal';
+    message: string;
+    data?: Record<string, unknown>;
+    source?: string;
+    traceId?: string;
+  }>): Promise<void>;
+}
+
+/** Cache-Control configuration for the Lambda handler's fallback headers. */
+export interface ServerCacheConfig {
+  /** Unauthenticated GET/HEAD responses.
+   *  Default: 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5' */
+  public?: string;
+  /** Authenticated GET/HEAD responses.
+   *  Default: 'private, no-store' */
+  private?: string;
+  /** Non-GET/HEAD (mutations).
+   *  Default: 'no-store' */
+  mutation?: string;
+}
+
+export interface LambdaHandlerOptions {
+  /** Async factory that creates and returns named handlers. Called once, cached. */
+  init: () => Promise<Record<string, Handler>>;
+  /** Given initialized handlers, returns route definitions (evaluated once). */
+  routes: (handlers: Record<string, Handler>) => Route[];
+  /** Fallback handler when no route matches. Given initialized handlers. */
+  fallback?: (handlers: Record<string, Handler>) => Handler;
+  /**
+   * Handle direct CLI invocations via Lambda Invoke.
+   * IAM is the auth — if you can invoke the Lambda, you're authenticated.
+   * Called when the event has an `_action` field (not an HTTP event).
+   */
+  onAction?: (action: string, payload: unknown, handlers: Record<string, Handler>) => Promise<unknown>;
+  /** Override default fallback Cache-Control headers. */
+  cache?: ServerCacheConfig;
+  /** Optional log sink — writes structured request logs to S3 or other storage.
+   *  Non-blocking: if the sink fails, logs still go to CloudWatch via stdout. */
+  logSink?: LogSink;
+}
+
+// --- Event Adapter ---
+
+export function eventToRequest(event: APIGatewayProxyEventV2): Request {
+  const url = new URL(
+    event.rawPath + (event.rawQueryString ? '?' + event.rawQueryString : ''),
+    `https://${event.requestContext.domainName}`
+  );
+
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(event.headers || {})) {
+    if (value) headers.set(key, value);
+  }
+
+  const method = event.requestContext.http.method;
+  const hasBody = method !== 'GET' && method !== 'HEAD';
+  let body: BodyInit | undefined;
+
+  if (hasBody && event.body) {
+    body = event.isBase64Encoded
+      ? new Uint8Array(Buffer.from(event.body, 'base64'))
+      : event.body;
+  }
+
+  return new Request(url.toString(), {
+    method,
+    headers,
+    body: hasBody ? body : undefined,
+  });
+}
+
+function isBinaryContentType(ct: string): boolean {
+  if (ct.startsWith('image/')) return true;
+  if (ct.startsWith('audio/')) return true;
+  if (ct.startsWith('video/')) return true;
+  if (ct.includes('octet-stream')) return true;
+  if (ct.includes('protobuf')) return true;
+  return false;
+}
+
+export async function responseToResult(
+  response: Response
+): Promise<APIGatewayProxyStructuredResultV2> {
+  const headers: Record<string, string> = {};
+  response.headers.forEach((value, key) => {
+    // Skip set-cookie — handled separately below for multi-value support
+    if (key.toLowerCase() !== 'set-cookie') {
+      headers[key] = value;
+    }
+  });
+
+  // Lambda Function URLs require Set-Cookie values as a separate `cookies` array
+  // because the plain headers object can only hold one value per key.
+  const cookies: string[] =
+    typeof response.headers.getSetCookie === 'function'
+      ? response.headers.getSetCookie()
+      : [];
+
+  const contentType = response.headers.get('content-type') || '';
+  const isBinary = isBinaryContentType(contentType);
+
+  let body: string;
+  let isBase64Encoded = false;
+
+  if (isBinary) {
+    const buffer = await response.arrayBuffer();
+    body = Buffer.from(buffer).toString('base64');
+    isBase64Encoded = true;
+  } else {
+    body = await response.text();
+  }
+
+  return {
+    statusCode: response.status,
+    headers,
+    ...(cookies.length > 0 ? { cookies } : {}),
+    body,
+    isBase64Encoded,
+  };
+}
+
+// --- Router ---
+
+export function createRouter(
+  routes: Route[],
+  fallback?: Handler
+): (path: string, method: string) => Handler {
+  const notFound: Handler = async () =>
+    new Response('Not Found', { status: 404 });
+
+  return (path: string, method: string): Handler => {
+    for (const route of routes) {
+      if (route.method && route.method !== method) continue;
+      if (route.exact) {
+        if (path === route.path) return route.handler;
+      } else {
+        if (path.startsWith(route.path)) return route.handler;
+      }
+    }
+    return fallback || notFound;
+  };
+}
+
+// --- Main Handler ---
+
+export function createLambdaHandler(
+  options: LambdaHandlerOptions
+): (event: APIGatewayProxyEventV2 | Record<string, unknown>) => Promise<APIGatewayProxyStructuredResultV2 | unknown> {
+  let cached: {
+    router: (path: string, method: string) => Handler;
+    handlers: Record<string, Handler>;
+  } | null = null;
+
+  async function ensureInitialized() {
+    if (cached) return cached;
+
+    const handlers = await options.init();
+    const routeDefs = options.routes(handlers);
+    const fallback = options.fallback?.(handlers);
+    const router = createRouter(routeDefs, fallback);
+
+    cached = { router, handlers };
+    log('info', 'Handlers initialized');
+    return cached;
+  }
+
+  return async (
+    event: APIGatewayProxyEventV2 | Record<string, unknown>
+  ): Promise<APIGatewayProxyStructuredResultV2 | unknown> => {
+    // Direct CLI invoke via Lambda Invoke — IAM is the auth layer.
+    // Events with _action are NOT HTTP events (no requestContext.http).
+    if ('_action' in event && typeof event._action === 'string' && options.onAction) {
+      const { handlers } = await ensureInitialized();
+      log('info', 'CLI action invoked', { action: event._action });
+      try {
+        return await options.onAction(event._action, event._payload, handlers);
+      } catch (error) {
+        log('error', 'CLI action error', { action: event._action, 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 } = 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 — CloudWatch is the primary log)
+      if (options.logSink) {
+        options.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) }
+            : {}),
+        }),
+      };
+    }
+  };
+}
+
+// --- Structured Logging ---
+
+export function log(
+  level: string,
+  message: string,
+  meta?: Record<string, unknown>
+): void {
+  console.log(
+    JSON.stringify({
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      ...meta,
+    })
+  );
+}

package/src/migrate.ts

@@ -0,0 +1,16 @@
+/**
+ * @everystack/server/migrate — Drizzle migration runner.
+ *
+ * Called directly from onAction handler (CLI → IAM → Lambda invoke).
+ * No HTTP, no auth — IAM is the authorization layer.
+ */
+
+import { migrate } from 'drizzle-orm/postgres-js/migrator';
+
+export async function runMigrations(
+  db: any,
+  migrationsFolder: string
+): Promise<{ success: boolean; message: string }> {
+  await migrate(db, { migrationsFolder });
+  return { success: true, message: 'Migrations applied' };
+}