@ericminassian/plat 0.0.0-stage → 0.2.0

package/src/dev/router.ts

@@ -0,0 +1,246 @@
+import { createReadStream, existsSync, statSync } from 'node:fs';
+import {
+  createServer,
+  request as httpRequest,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from 'node:http';
+import { connect, type Socket } from 'node:net';
+import { extname, join, normalize, sep } from 'node:path';
+import { decide, HOST_HEADER, type RouteRecord } from '@ericminassian/platform-core';
+
+/**
+ * `plat dev`'s stand-in for the CloudFront router: the same `decide()` the
+ * edge function runs, against a local route record. Server routes go to the
+ * local web server; static routes go to the frontend dev server (original URL,
+ * so it can do HMR and its own SPA fallback) or to files in `web.static`.
+ */
+export interface Target {
+  host: string;
+  port: number;
+}
+
+export interface LocalRouterState {
+  record: RouteRecord;
+  server?: Target;
+  webDev?: Target;
+  /** A frontend dev server is configured but not accepting connections yet. */
+  webDevStarting?: boolean;
+  staticDir?: string;
+}
+
+export type LocalDecision =
+  | { kind: 'server'; target: Target }
+  | { kind: 'webdev'; target: Target }
+  | { kind: 'file'; path: string }
+  | { kind: 'unavailable'; reason: string }
+  | { kind: 'notfound' };
+
+/** Pure routing decision, shared by the router and tests. */
+export function localDecision(state: LocalRouterState, uri: string): LocalDecision {
+  const pathname = uri.split('?')[0] ?? '/';
+  const d = decide(state.record, pathname);
+  if (d.t === 'notfound') return { kind: 'notfound' };
+  if (d.t === 'server') {
+    return state.server
+      ? { kind: 'server', target: state.server }
+      : { kind: 'unavailable', reason: 'the web server is starting' };
+  }
+  if (state.webDev) return { kind: 'webdev', target: state.webDev };
+  if (state.webDevStarting) return { kind: 'unavailable', reason: 'the frontend dev server is starting' };
+  if (!state.staticDir)
+    return { kind: 'unavailable', reason: 'no frontend: set web.static or web.dev in plat.config.ts' };
+  const prefix = `/${state.record.s ?? ''}`;
+  const rel = d.key.startsWith(prefix) ? d.key.slice(prefix.length) : d.key;
+  const file = safeJoin(state.staticDir, decodeURIComponent(rel));
+  return file ? { kind: 'file', path: file } : { kind: 'notfound' };
+}
+
+/** Local route record for an app (mirrors what the engine writes to the KVS). */
+export function localRouteRecord(opts: {
+  app: string;
+  stage: string;
+  deploymentId: string;
+  hasServer: boolean;
+  hasStatic: boolean;
+  serverRoutes: string[];
+  spa: boolean;
+}): RouteRecord {
+  return {
+    v: 1,
+    app: opts.app,
+    stage: opts.stage,
+    d: opts.deploymentId,
+    ...(opts.hasServer ? { o: 'local-server' } : {}),
+    ...(opts.hasStatic ? { s: 'local' } : {}),
+    ...(opts.hasServer && opts.hasStatic ? { r: opts.serverRoutes } : {}),
+    spa: opts.spa ? 1 : 0,
+  };
+}
+
+export type Interceptor = (req: IncomingMessage, res: ServerResponse, url: URL) => Promise<boolean> | boolean;
+
+export interface LocalRouterOptions {
+  port: number;
+  host?: string;
+  state: () => LocalRouterState;
+  /** Handled before routing (local sign-in, dev endpoints). Return true when handled. */
+  intercept?: Interceptor[];
+  onRequest?: (line: { method: string; url: string; status: number; ms: number; kind: string }) => void;
+}
+
+export function startLocalRouter(opts: LocalRouterOptions): Promise<Server> {
+  const server = createServer(async (req, res) => {
+    const started = Date.now();
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+    let kind = 'intercept';
+    res.once('finish', () =>
+      opts.onRequest?.({
+        method: req.method ?? 'GET',
+        url: req.url ?? '/',
+        status: res.statusCode,
+        ms: Date.now() - started,
+        kind,
+      }),
+    );
+    try {
+      for (const fn of opts.intercept ?? []) if (await fn(req, res, url)) return;
+      const d = localDecision(opts.state(), req.url ?? '/');
+      kind = d.kind;
+      switch (d.kind) {
+        case 'server':
+          return proxy(req, res, d.target, true);
+        case 'webdev':
+          return proxy(req, res, d.target, false);
+        case 'file':
+          return serveFile(res, d.path);
+        case 'unavailable':
+          return text(res, 503, `${d.reason}\n`);
+        case 'notfound':
+          return text(res, 404, 'Not found\n');
+      }
+    } catch (err) {
+      if (!res.headersSent) text(res, 502, `plat dev router error: ${(err as Error).message}\n`);
+      else res.destroy();
+    }
+  });
+
+  server.on('upgrade', (req, socket, head) => {
+    const d = localDecision(opts.state(), req.url ?? '/');
+    // Web Functions don't do WebSockets; only the frontend dev server (HMR) gets upgrades.
+    if (d.kind !== 'webdev') {
+      socket.end('HTTP/1.1 501 Not Implemented\r\n\r\n');
+      return;
+    }
+    tunnel(req, socket as Socket, head, d.target);
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(opts.port, opts.host ?? '127.0.0.1', () => resolve(server));
+  });
+}
+
+/** Headers the edge would add, so apps see their public host. */
+export function forwardedHeaders(
+  req: IncomingMessage,
+  toServer: boolean,
+): Record<string, string | string[] | undefined> {
+  const headers: Record<string, string | string[] | undefined> = { ...req.headers };
+  const host = req.headers.host ?? 'localhost';
+  if (toServer) {
+    headers[HOST_HEADER] = host;
+    headers['x-forwarded-host'] = host;
+    headers['x-forwarded-proto'] = 'http';
+  }
+  return headers;
+}
+
+function proxy(req: IncomingMessage, res: ServerResponse, target: Target, toServer: boolean): Promise<void> {
+  return new Promise((resolve) => {
+    const upstream = httpRequest(
+      {
+        host: target.host,
+        port: target.port,
+        method: req.method,
+        path: req.url,
+        headers: forwardedHeaders(req, toServer),
+      },
+      (up) => {
+        res.writeHead(up.statusCode ?? 502, up.statusMessage, up.headers);
+        up.pipe(res);
+        up.once('end', resolve);
+      },
+    );
+    upstream.once('error', (err) => {
+      if (!res.headersSent)
+        text(res, 502, `upstream ${target.host}:${target.port} unavailable: ${err.message}\n`);
+      resolve();
+    });
+    req.pipe(upstream);
+  });
+}
+
+function tunnel(req: IncomingMessage, socket: Socket, head: Buffer, target: Target): void {
+  const up = connect(target.port, target.host, () => {
+    const lines = [`${req.method} ${req.url} HTTP/${req.httpVersion}`];
+    for (let i = 0; i < req.rawHeaders.length; i += 2)
+      lines.push(`${req.rawHeaders[i]}: ${req.rawHeaders[i + 1]}`);
+    up.write(`${lines.join('\r\n')}\r\n\r\n`);
+    if (head.length) up.write(head);
+    up.pipe(socket);
+    socket.pipe(up);
+  });
+  const close = () => {
+    up.destroy();
+    socket.destroy();
+  };
+  up.once('error', close);
+  socket.once('error', close);
+}
+
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json',
+  '.map': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.txt': 'text/plain; charset=utf-8',
+  '.wasm': 'application/wasm',
+  '.webmanifest': 'application/manifest+json',
+};
+
+function serveFile(res: ServerResponse, path: string): void {
+  if (!existsSync(path) || !statSync(path).isFile()) {
+    text(res, 404, 'Not found\n');
+    return;
+  }
+  res.writeHead(200, {
+    'content-type': MIME[extname(path)] ?? 'application/octet-stream',
+    'cache-control': 'no-cache',
+  });
+  createReadStream(path).pipe(res);
+}
+
+function text(res: ServerResponse, status: number, body: string): void {
+  res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' });
+  res.end(body);
+}
+
+/** Join without escaping `root` (path traversal). */
+export function safeJoin(root: string, rel: string): string | null {
+  const full = normalize(join(root, rel));
+  const base = normalize(root.endsWith(sep) ? root : root + sep);
+  return full === normalize(root) || full.startsWith(base) ? full : null;
+}

package/src/dev/server-entry.ts

@@ -0,0 +1,21 @@
+// Entry for the local web server under `plat dev` (run with `tsx watch`, so
+// edits to the app restart it). Loads the app's fetch handler and starts it
+// with the SDK server wrapper — the same wrapper the Web Function runs — using
+// the app's own copy of the SDK so app code and wrapper share state.
+import { pathToFileURL } from 'node:url';
+
+const entry = process.env.PLATFORM_ENTRY;
+const sdkServer = process.env.PLATFORM_SDK_SERVER ?? '@ericminassian/platform/server';
+if (!entry) {
+  console.error('PLATFORM_ENTRY is not set (this file is started by `plat dev`)');
+  process.exit(1);
+}
+
+const mod = (await import(pathToFileURL(entry).href)) as { default?: unknown };
+if (!mod.default) {
+  console.error(`${entry} has no default export; export your app (e.g. \`export default app\`)`);
+  process.exit(1);
+}
+const sdkUrl = sdkServer.startsWith('/') ? pathToFileURL(sdkServer).href : sdkServer;
+const { startServer } = (await import(sdkUrl)) as typeof import('@ericminassian/platform/server');
+await startServer(mod.default as Parameters<typeof startServer>[0]);

package/src/dev/test.ts

@@ -0,0 +1,68 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { EMULATOR_INSTALL_HINT } from '@ericminassian/platform-engine';
+import { withLocalBin } from '../build.ts';
+import { loadProject } from '../project.ts';
+import { CliError, step, success } from '../util/output.ts';
+import { localEnv, startLocalStage } from './local-stage.ts';
+import { type Dispatcher, type LocalWorker, startLocalWorker, startWorkerDispatch } from './worker.ts';
+
+export const INTEGRATION_CONFIG = 'vitest.integration.config.ts';
+
+/**
+ * `plat test`: a throwaway emulator with this app's resources (stage `test`),
+ * then vitest with the same environment the deployed code gets. Uses
+ * `vitest.integration.config.ts` when present.
+ */
+export async function runTests(opts: { cwd: string; args: string[] }): Promise<number> {
+  const { root, manifest } = await loadProject(opts.cwd);
+  step('starting the AWS Emulator');
+  let stage: Awaited<ReturnType<typeof startLocalStage>>;
+  try {
+    stage = await startLocalStage({ root, manifest, stage: 'test', port: 3999 });
+  } catch (err) {
+    if ((err as Error).message === EMULATOR_INSTALL_HINT)
+      throw new CliError('the AWS Emulator is not installed', { hint: EMULATOR_INSTALL_HINT });
+    throw err;
+  }
+  success(`provisioned ${manifest.name} (stage test)`);
+  let worker: LocalWorker | undefined;
+  let dispatcher: Dispatcher | undefined;
+  try {
+    if (manifest.worker) {
+      worker = await startLocalWorker(stage, manifest, root, { watch: false });
+      worker.child.stdout?.pipe(process.stdout);
+      worker.child.stderr?.pipe(process.stderr);
+      dispatcher = await startWorkerDispatch(stage, manifest, worker);
+    }
+    const args = ['run'];
+    if (existsSync(join(root, INTEGRATION_CONFIG)) && !opts.args.includes('--config'))
+      args.push('--config', INTEGRATION_CONFIG);
+    args.push(...opts.args);
+    return await new Promise<number>((resolve, reject) => {
+      const child = spawn('vitest', args, {
+        cwd: root,
+        stdio: 'inherit',
+        shell: process.platform === 'win32',
+        env: withLocalBin(
+          root,
+          localEnv(stage, manifest, {
+            PLATFORM_TEST: '1',
+            ...(worker ? { PLATFORM_LOCAL_WORKER_URL: `http://127.0.0.1:${worker.port}/` } : {}),
+          }),
+        ),
+      });
+      child.once('exit', (code) => resolve(code ?? 1));
+      child.once('error', (err) =>
+        reject(
+          new CliError(`could not run vitest: ${err.message}`, { hint: 'add vitest to devDependencies' }),
+        ),
+      );
+    });
+  } finally {
+    dispatcher?.stop();
+    worker?.stop();
+    await stage.stop();
+  }
+}

package/src/dev/worker-host.ts

@@ -0,0 +1,62 @@
+// Local worker host for `plat dev` / `plat test`. The AWS Emulator's Lambda
+// runtime is an embedded JS sandbox without node:http/https/net/async_hooks,
+// so a worker that talks to AWS (through the SDK) can't run inside it. This
+// process runs the worker in real Node instead: it builds the same handler the
+// Lambda would (`createWorkerHandler(def)` from the app's SDK) and accepts
+// Lambda-shaped events over a loopback HTTP endpoint. The CLI feeds it SQS
+// messages, EventBridge events and crons from the emulator.
+import { randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+import { pathToFileURL } from 'node:url';
+
+const entry = process.env.PLATFORM_WORKER_ENTRY;
+const sdkWorker = process.env.PLATFORM_SDK_WORKER ?? '@ericminassian/platform/worker';
+const port = Number(process.env.PLATFORM_WORKER_PORT);
+const timeoutMs = Number(process.env.PLATFORM_WORKER_TIMEOUT_MS ?? 60_000);
+const functionName = process.env.PLATFORM_WORKER_FUNCTION ?? 'local-worker';
+if (!entry || !port) {
+  console.error('PLATFORM_WORKER_ENTRY / PLATFORM_WORKER_PORT not set (this file is started by `plat dev`)');
+  process.exit(1);
+}
+
+const mod = (await import(pathToFileURL(entry).href)) as { default?: unknown };
+if (!mod.default) {
+  console.error(
+    `${entry} has no default export; export your worker (\`export default defineWorker({...})\`)`,
+  );
+  process.exit(1);
+}
+const sdkUrl = sdkWorker.startsWith('/') ? pathToFileURL(sdkWorker).href : sdkWorker;
+const { createWorkerHandler } = (await import(sdkUrl)) as typeof import('@ericminassian/platform/worker');
+const handler = createWorkerHandler(mod.default as Parameters<typeof createWorkerHandler>[0]);
+
+createServer((req, res) => {
+  let body = '';
+  req.setEncoding('utf8');
+  req.on('data', (c) => (body += c));
+  req.on('end', async () => {
+    const started = Date.now();
+    const context = {
+      awsRequestId: randomUUID(),
+      functionName,
+      functionVersion: '$LATEST',
+      invokedFunctionArn: `arn:aws:lambda:${process.env.AWS_REGION ?? 'us-east-1'}:000000000000:function:${functionName}`,
+      memoryLimitInMB: '512',
+      logGroupName: `/aws/lambda/${functionName}`,
+      logStreamName: 'local',
+      callbackWaitsForEmptyEventLoop: false,
+      getRemainingTimeInMillis: () => Math.max(0, started + timeoutMs - Date.now()),
+    };
+    let reply: unknown;
+    try {
+      reply = { ok: true, result: (await handler(JSON.parse(body || '{}'), context)) ?? null };
+    } catch (err) {
+      const e = err as Error;
+      reply = {
+        ok: false,
+        error: { name: e?.name ?? 'Error', message: e?.message ?? String(err), stack: e?.stack },
+      };
+    }
+    res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(reply));
+  });
+}).listen(port, '127.0.0.1');