create-agent-rig 0.4.0 → 0.6.0

package/templates/skeleton/node-service/services/api/src/server.ts

@@ -2,7 +2,7 @@
 // configured) serving the built web bundle. No second runtime for the
 // frontend — the same process serves the static export.
 import { createReadStream } from 'node:fs';
-import { stat } from 'node:fs/promises';
+import { realpath, stat } from 'node:fs/promises';
 import { createServer, type Server } from 'node:http';
 import path from 'node:path';
 import type { CreateNoteDeps } from './usecases/create-note.js';
@@ -18,6 +18,14 @@ export interface ServerOptions {
   staticDir?: string;
 }
 
+/**
+ * Largest request body `POST /notes` will buffer — that route and no other:
+ * the cap is applied where the body is read, so a second route that reads one
+ * brings its own. A note is a title and some tags; anything past this is a
+ * mistake or an attack, and either way the process must not hold it in memory.
+ */
+const MAX_BODY_BYTES = 1024 * 1024;
+
 const CONTENT_TYPES: Record<string, string> = {
   '.html': 'text/html; charset=utf-8',
   '.css': 'text/css',
@@ -39,11 +47,34 @@ export function makeServer(deps: ServerDeps, options: ServerOptions = {}): Serve
       response.end(result.body);
     };
     const notFound = () => respond({ statusCode: 404, body: JSON.stringify({ error: 'not found' }) });
+    const badRequest = () =>
+      respond({ statusCode: 400, body: JSON.stringify({ error: 'bad request' }) });
 
     if (request.method === 'POST' && request.url === '/notes') {
       const chunks: Buffer[] = [];
-      request.on('data', (chunk: Buffer) => chunks.push(chunk));
+      let size = 0;
+      let refused = false;
+      // A socket that dies mid-upload emits 'error'; unhandled, it takes the
+      // process with it.
+      request.on('error', () => {
+        refused = true;
+      });
+      request.on('data', (chunk: Buffer) => {
+        if (refused) return;
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES) {
+          refused = true;
+          chunks.length = 0;
+          respond({ statusCode: 413, body: JSON.stringify({ error: 'payload too large' }) });
+          // Keep draining rather than destroying the socket: a client that is
+          // still uploading has to stay connected to read the refusal.
+          request.resume();
+          return;
+        }
+        chunks.push(chunk);
+      });
       request.on('end', () => {
+        if (refused) return;
         void createNote(Buffer.concat(chunks).toString('utf8')).then(respond);
       });
       return;
@@ -55,7 +86,21 @@ export function makeServer(deps: ServerDeps, options: ServerOptions = {}): Serve
     }
 
     if (request.method === 'GET' && options.staticDir) {
-      void serveStatic(options.staticDir, request.url ?? '/', response, notFound);
+      // The rejection handler is the point: without it a throw in here is an
+      // unhandled rejection, which ends the process on one malformed request.
+      void serveStatic(options.staticDir, request.url ?? '/', response, notFound, badRequest).catch(
+        (error: unknown) => {
+          // Say nothing to the client beyond the code, but never swallow it —
+          // a static path that fails silently is a blind spot in every
+          // generated project.
+          deps.log.error('static serve failed', { url: request.url, error: String(error) });
+          if (response.headersSent) {
+            response.destroy();
+            return;
+          }
+          respond({ statusCode: 500, body: JSON.stringify({ error: 'internal error' }) });
+        },
+      );
       return;
     }
 
@@ -68,22 +113,60 @@ async function serveStatic(
   rawUrl: string,
   response: import('node:http').ServerResponse,
   notFound: () => void,
+  badRequest: () => void,
 ): Promise<void> {
-  const pathname = decodeURIComponent(new URL(rawUrl, 'http://local').pathname);
+  let pathname: string;
+  try {
+    pathname = decodeURIComponent(new URL(rawUrl, 'http://local').pathname);
+  } catch {
+    // A malformed escape (`GET /%`) is the client's error, not ours.
+    return badRequest();
+  }
   const relative = pathname.endsWith('/') ? `${pathname}index.html` : pathname;
-  const resolved = path.normalize(path.join(staticDir, relative));
+  // Resolve the root first: a configured dir with a trailing separator would
+  // otherwise build a `//` prefix that no resolved path can start with, and
+  // every request would 404.
+  const root = path.resolve(staticDir);
+  const resolved = path.resolve(root, `.${path.sep}${relative}`);
   // Path-traversal guard: whatever the URL said, we never leave staticDir.
-  if (!resolved.startsWith(path.normalize(staticDir) + path.sep)) {
+  // The string test is only half of it — it says where the path points, not
+  // what the filesystem will open, and stat/open both follow symlinks.
+  if (!within(root, resolved)) {
     return notFound();
   }
+  let file: string;
   try {
-    const stats = await stat(resolved);
+    // …so ask the filesystem too, and test the answer the same way. A missing
+    // file throws here, which is the 404 we would give it anyway.
+    file = await realpath(resolved);
+    if (!within(await realpath(root), file)) return notFound();
+    const stats = await stat(file);
     if (!stats.isFile()) return notFound();
   } catch {
     return notFound();
   }
-  response.writeHead(200, {
-    'content-type': CONTENT_TYPES[path.extname(resolved)] ?? 'application/octet-stream',
+  // Open before the headers go out: a file that passes stat can still fail to
+  // open (EACCES, or it is gone by now), and after writeHead(200) there is no
+  // way left to say so — which is one GET away from an unhandled stream error.
+  const stream = createReadStream(file);
+  await new Promise<void>((resolve, reject) => {
+    stream.once('error', reject);
+    stream.once('open', () => {
+      stream.removeListener('error', reject);
+      response.writeHead(200, {
+        'content-type': CONTENT_TYPES[path.extname(file)] ?? 'application/octet-stream',
+      });
+      // Past the headers the only honest answer to a read failure is to cut
+      // the response short, so the client sees a truncated body rather than a
+      // complete one.
+      stream.once('error', () => response.destroy());
+      stream.pipe(response);
+      resolve();
+    });
   });
-  createReadStream(resolved).pipe(response);
+}
+
+/** Whether `candidate` is `root` itself or sits underneath it. */
+function within(root: string, candidate: string): boolean {
+  return candidate === root || candidate.startsWith(root + path.sep);
 }

package/templates/skeleton/node-service/services/api/src/static-dir.ts

@@ -0,0 +1,20 @@
+// Where the built web bundle lives, resolved relative to the composition root.
+// A pure function rather than an inline expression in main.ts: main.ts is wiring
+// that tests never import, and this resolution has a bug worth pinning —
+// `new URL(url).pathname` leaves percent-escapes in place (a checkout under
+// "/Users/a b/" resolves to "/Users/a%20b/") and prefixes a slash on Windows.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** `apps/web/out`, three levels up from a module in `services/api/src`. */
+export function defaultStaticDirFor(moduleUrl: string): string {
+  return path.resolve(
+    path.dirname(fileURLToPath(moduleUrl)),
+    '..',
+    '..',
+    '..',
+    'apps',
+    'web',
+    'out',
+  );
+}

package/templates/skeleton/node-service/services/api/test/server.test.ts

@@ -1,6 +1,6 @@
 // Integration: the real HTTP server over a real socket, with real file
 // storage and a real spool directory — the whole request path at once.
-import { mkdir, mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, mkdtemp, readdir, rm, symlink, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import type { AddressInfo } from 'node:net';
 import path from 'node:path';
@@ -75,8 +75,43 @@ describe('the service end to end', () => {
     const { notes } = (await response.json()) as { notes: Array<{ title: string }> };
     expect(notes).toHaveLength(2);
   });
+
+  it('refuses a request body larger than the cap with 413', async () => {
+    // Well-formed JSON on purpose: what is rejected is the size, not the shape.
+    // The server must answer before it has buffered the whole upload, and must
+    // stay readable long enough for the client to see that answer.
+    const body = JSON.stringify({ title: 'x'.repeat(1024 * 1024 + 1024) });
+    const response = await fetch(`${baseUrl}/notes`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body,
+    });
+    expect(response.status).toBe(413);
+  });
 });
 
+/** A listening server serving `staticDir`, plus its base URL. */
+async function startStaticServer(staticDir: string): Promise<{ server: Server; base: string }> {
+  const server = makeServer(
+    {
+      notes: new JsonFileNoteStore(path.join(dir, 'data', 'notes.json')),
+      events: new SpoolEventPublisher(path.join(dir, 'queue'), () => 'm'),
+      newId: () => 'id',
+      now: () => '2024-01-01T00:00:00.000Z',
+      log: createLogger({}, () => {}),
+    },
+    { staticDir },
+  );
+  await new Promise<void>((resolve) => server.listen(0, resolve));
+  return { server, base: `http://127.0.0.1:${(server.address() as AddressInfo).port}` };
+}
+
+// Windows has no POSIX mode bits, and root reads a 0o000 file regardless — in
+// both cases the "unreadable file" this test needs cannot be built at all.
+const cannotMakeFileUnreadable = process.platform === 'win32' || process.getuid?.() === 0;
+// Creating a symlink on Windows needs a privilege the test runner may not hold.
+const cannotSymlink = process.platform === 'win32';
+
 describe('static serving (the built web bundle)', () => {
   let staticServer: Server;
   let staticBase: string;
@@ -84,18 +119,9 @@ describe('static serving (the built web bundle)', () => {
   beforeEach(async () => {
     await mkdir(path.join(dir, 'static'), { recursive: true });
     await writeFile(path.join(dir, 'static', 'index.html'), '<h1>web shell</h1>');
-    staticServer = makeServer(
-      {
-        notes: new JsonFileNoteStore(path.join(dir, 'data', 'notes.json')),
-        events: new SpoolEventPublisher(path.join(dir, 'queue'), () => 'm'),
-        newId: () => 'id',
-        now: () => '2024-01-01T00:00:00.000Z',
-        log: createLogger({}, () => {}),
-      },
-      { staticDir: path.join(dir, 'static') },
-    );
-    await new Promise<void>((resolve) => staticServer.listen(0, resolve));
-    staticBase = `http://127.0.0.1:${(staticServer.address() as AddressInfo).port}`;
+    ({ server: staticServer, base: staticBase } = await startStaticServer(
+      path.join(dir, 'static'),
+    ));
   });
 
   afterEach(async () => {
@@ -120,4 +146,63 @@ describe('static serving (the built web bundle)', () => {
     expect(response.status).toBe(200);
     expect(response.headers.get('content-type')).toContain('application/json');
   });
+
+  it('answers 400 to an undecodable URL and keeps serving afterwards', async () => {
+    // The signal is a leash, not a relaxation: a server that dies on this URL
+    // never answers at all, and the run should say so in seconds.
+    const response = await fetch(staticBase + '/%', { signal: AbortSignal.timeout(5000) });
+    expect(response.status).toBe(400);
+
+    const afterwards = await fetch(staticBase + '/');
+    expect(afterwards.status).toBe(200);
+    expect(await afterwards.text()).toContain('web shell');
+  });
+
+  it.skipIf(cannotMakeFileUnreadable)(
+    'answers a file it cannot open and keeps serving afterwards',
+    async () => {
+      // A file that passes stat() but fails open() (EACCES here; in production
+      // the stat/open race gives ENOENT). Before the headers are held back
+      // until the stream opens, that error reached no handler at all and the
+      // process paid for one unreadable file.
+      const locked = path.join(dir, 'static', 'locked.txt');
+      await writeFile(locked, 'unreadable');
+      await chmod(locked, 0o000);
+      try {
+        const response = await fetch(staticBase + '/locked.txt', {
+          signal: AbortSignal.timeout(5000),
+        });
+        expect(response.status).toBe(500);
+
+        const afterwards = await fetch(staticBase + '/');
+        expect(afterwards.status).toBe(200);
+        expect(await afterwards.text()).toContain('web shell');
+      } finally {
+        // Restore before afterEach removes the temp dir.
+        await chmod(locked, 0o600);
+      }
+    },
+  );
+
+  it.skipIf(cannotSymlink)('refuses a symlink that escapes the static dir', async () => {
+    // A lexical guard inspects only the resolved string, while stat and the
+    // read stream follow the link wherever it points — which is why the guard
+    // asks realpath as well.
+    await writeFile(path.join(dir, 'secret-target.txt'), 'nope');
+    await symlink(path.join(dir, 'secret-target.txt'), path.join(dir, 'static', 'escape.txt'));
+
+    const response = await fetch(staticBase + '/escape.txt');
+    expect(response.status).toBe(404);
+  });
+
+  it('serves the bundle when the configured static dir has a trailing separator', async () => {
+    const { server, base } = await startStaticServer(path.join(dir, 'static') + path.sep);
+    try {
+      const response = await fetch(base + '/');
+      expect(response.status).toBe(200);
+      expect(await response.text()).toContain('web shell');
+    } finally {
+      await new Promise((resolve) => server.close(resolve));
+    }
+  });
 });

package/templates/skeleton/node-service/services/api/test/static-dir.test.ts

@@ -0,0 +1,28 @@
+// The composition root resolves the built web bundle relative to itself; the
+// resolution is a pure function so it can be tested without importing main.ts.
+//
+// What is NOT pinned here: the Windows half of the same defect — the old
+// `new URL(url).pathname` yielded `/C:/…`. Both expressions are identical on a
+// POSIX runner, so observing the difference would mean passing a path flavour
+// into `defaultStaticDirFor`, i.e. a parameter that exists only for the test.
+// The decision was to leave that hook out; percent-decoding below is the same
+// bug's POSIX-visible half, and it fails against the old expression.
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { defaultStaticDirFor } from '../src/static-dir.js';
+
+describe('resolving the default static dir from the module url', () => {
+  it('decodes percent-escapes in the path (a directory may contain a space)', () => {
+    const resolved = defaultStaticDirFor('file:///Users/a%20b/proj/services/api/src/main.ts');
+
+    expect(resolved).toContain('a b');
+    expect(resolved).not.toContain('%20');
+  });
+
+  it('points three levels up from services/api/src at apps/web/out', () => {
+    const resolved = defaultStaticDirFor('file:///Users/a%20b/proj/services/api/src/main.ts');
+
+    expect(resolved.endsWith(path.join('a b', 'proj', 'apps', 'web', 'out'))).toBe(true);
+    expect(path.isAbsolute(resolved)).toBe(true);
+  });
+});