@volter/world-core 3.0.163 → 3.0.165

package/src/serve-http.ts

@@ -1,7 +1,7 @@
 // The HTTP server seam of the kernel (docs/contributing/architecture.md#the-serve-seam): a fetch handler on
 // a port, in the shape every `Bun.serve` call already has, so the serve path meets the runtime in
-// ONE place. Bun-backed where Bun is the runtime; `node:http`-backed otherwise, the request rebuilt
-// as a standard Request and the handler's Response written back. Async, because binding a port is
+// ONE place. Ordinary HTTP uses `node:http`; requested WebSockets retain Bun's native backend.
+// The request is rebuilt as a standard Request and the handler's Response written back. Async, because binding a port is
 // asynchronous on Node — Bun's synchronous bind is the special case.
 //
 // Nothing here runs at module scope (the served-handler registry is made on first use), and `node:http` is reached through `process.getBuiltinModule`
@@ -10,6 +10,7 @@
 
 import type { TwinStream } from './twin-fetch.ts';
 import { worldBootAnswer } from './world-boot.ts';
+import { DEFAULT_MAX_DECODED_REQUEST_BODY_SIZE, RequestBodyTooLargeError } from './request-body.ts';
 
 /** One socket library at the host seam, shared by inbound upgrades and authenticated outbound relays. */
 const socketLibrary = () => import('ws');
@@ -41,7 +42,7 @@ export type ServeHttpOptions = {
   fetch: HttpHandler;
   /** seconds a connection may idle (Bun honors it; Node's keep-alive timeout is set from it) */
   idleTimeout?: number;
-  /** Explicit transport limit in bytes; absent, Bun retains its 128 MiB default. */
+  /** Explicit transport limit in bytes; absent, 128 MiB on both runtimes. */
   maxRequestBodySize?: number;
   /** what a thrown handler answers with; absent, a 500 carrying the error (as Bun.serve) */
   error?: (error: Error) => Response | Promise<Response>;
@@ -101,7 +102,7 @@ export async function serveHttp(options: ServeHttpOptions): Promise<HttpServer>
   const hostname = options.hostname ?? '127.0.0.1';
   const urlHost = options.hostname ?? '127.0.0.1';
   const bun = bunRuntime();
-  if (bun) {
+  if (bun && (options.upgrade !== undefined || 'websocket' in options)) {
     // the global `Bun.serve` — the request journal's wrap of it (serve.ts) applies to packs and to
     // this seam alike, so the seam never decorates twice on Bun
     const upgrade = options.upgrade;
@@ -184,17 +185,19 @@ const STREAM_HIGH_WATER = 4 * 1024 * 1024;
 /** A raw-TCP twin's listener (the seam's byte-stream half): its `create<Name>TwinStream` served on a TCP port, each
  *  socket one connection, on loopback unless the caller names a hostname. Runtime-neutral, as `serveHttp` is: Node's
  *  `net` reached at call time, never imported. A stream that declares `maxConnections` (a live ingest) is held to it. */
-export async function serveStream(options: { port?: number; hostname?: string; stream: TwinStream; maxConnections?: number }): Promise<{ port: number; stop: () => void }> {
+export async function serveStream(options: { port?: number; hostname?: string; stream: TwinStream; maxConnections?: number }): Promise<{ port: number; stop: () => Promise<void> }> {
   const get = (process as { getBuiltinModule?: (id: string) => unknown }).getBuiltinModule;
   const net = typeof get === 'function' ? get('node:net') as typeof import('node:net') | undefined : undefined;
   if (!net || typeof net.createServer !== 'function') throw new StreamListenerUnavailable('this runtime has no TCP listener (node:net)');
   const cap = options.maxConnections ?? (options.stream as { maxConnections?: number }).maxConnections;
   let open = 0;
+  const accepted = new Set<import('node:net').Socket>();
   const server = net.createServer((socket) => {
     // past its cap a connection is closed before the stream sees it, so connections that never get anywhere cannot pile up
     if (cap !== undefined && open >= cap) { socket.destroy(); return; }
     open += 1;
-    socket.once('close', () => { open -= 1; });
+    accepted.add(socket);
+    socket.once('close', () => { open -= 1; accepted.delete(socket); });
     const conn = options.stream({ write: (bytes) => { socket.write(bytes); }, end: () => { socket.end(); } }, socket.remoteAddress ?? '127.0.0.1');
     // a connection that says what waits (`backlog`: whole messages its work has not reached) is read no further past the
     // high-water mark until that work has settled, so a peer faster than the twin (a live ingest pushed faster than real
@@ -211,7 +214,13 @@ export async function serveStream(options: { port?: number; hostname?: string; s
   });
   await new Promise<void>((resolve, reject) => { server.once('error', reject); server.listen(options.port ?? 0, options.hostname ?? '127.0.0.1', () => resolve()); });
   const address = server.address();
-  return { port: typeof address === 'object' && address ? address.port : options.port ?? 0, stop: () => { server.close(); } };
+  // stop is the listener's real retirement: it settles once the listener is closed and every connection it accepted has
+  // ended (each is closed here, so none holds the close open)
+  const stop = (): Promise<void> => new Promise<void>((resolve) => {
+    server.close(() => resolve());
+    for (const socket of accepted) socket.destroy();
+  });
+  return { port: typeof address === 'object' && address ? address.port : options.port ?? 0, stop };
 }
 function builtin<T>(name: string): T {
   const get = (process as { getBuiltinModule?: (id: string) => unknown }).getBuiltinModule;
@@ -221,7 +230,8 @@ function builtin<T>(name: string): T {
 
 async function serveOnNode(options: ServeHttpOptions & { hostname: string; urlHost: string }): Promise<HttpServer> {
   const http = builtin<NodeHttp>('node:http');
-  const { Readable } = builtin<NodeStream>('node:stream');
+  const { Readable, Transform } = builtin<NodeStream>('node:stream');
+  const requestLimit = options.maxRequestBodySize ?? DEFAULT_MAX_DECODED_REQUEST_BODY_SIZE;
   if ('websocket' in options) throw new Error('serveHttp: use the portable upgrade callbacks for WebSocket support on Node');
   const protocol = options.tls ? 'https' : 'http';
   const factory = (handler: import('node:http').RequestListener) => options.tls
@@ -245,23 +255,35 @@ async function serveOnNode(options: ServeHttpOptions & { hostname: string; urlHo
     } catch { /* hostile thrown values are still reported by stage */ }
     try { process.stderr.write(`serveHttp ${stage}: ${detail.slice(0, 512)}\n`); } catch { /* stderr is best-effort */ }
   };
-  const active = new Set<AbortController>();
+  const active = new Set<() => void>();
   // Node's Request signal is dependent on the source signal. Neither a pending
   // handler nor a streaming response necessarily keeps the Request alive, so
   // retain it until the whole HTTP response path (including body cleanup) ends.
   const activeRequests = new Set<Request>();
   const server = factory((req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => {
     const controller = new AbortController();
-    active.add(controller);
-    const abort = () => { if (!controller.signal.aborted) controller.abort(); };
+    const socket = req.socket;
+    const hasInputBody = req.headers['transfer-encoding'] !== undefined || Number(req.headers['content-length']) > 0;
+    let incoming: import('node:stream').Transform | undefined;
+    let flushingBodyRefusal = false;
+    const abort = () => {
+      if (!controller.signal.aborted) controller.abort();
+      incoming?.destroy(controller.signal.reason);
+      if (!flushingBodyRefusal) {
+        req.destroy();
+        if (!res.writableFinished) res.destroy();
+        socket.destroy();
+      }
+    };
+    active.add(abort);
     const onRequestClose = () => { if (!req.complete) abort(); };
-    const onResponseClose = () => { if (!res.writableFinished) abort(); };
+    const onResponseClose = () => { if (!res.writableFinished) { flushingBodyRefusal = false; abort(); } };
     const onSocketClose = () => { if (!res.writableFinished) abort(); };
     req.on('aborted', abort);
     req.on('close', onRequestClose);
     req.on('error', abort);
-    req.socket.on('close', onSocketClose);
-    req.socket.on('error', abort);
+    socket.on('close', onSocketClose);
+    socket.on('error', abort);
     res.on('close', onResponseClose);
     res.on('error', abort);
     const disconnected = () => controller.signal.aborted || res.destroyed;
@@ -288,17 +310,50 @@ async function serveOnNode(options: ServeHttpOptions & { hostname: string; urlHo
       if (disconnected()) closed();
     });
     let request: Request | undefined;
+    let bodyTooLarge = false;
+    const rejectBody = () => {
+      if (bodyTooLarge) return;
+      bodyTooLarge = true;
+      const error = new RequestBodyTooLargeError();
+      if (incoming) req.unpipe(incoming);
+      req.pause();
+      if (!res.headersSent && !res.destroyed) {
+        for (const name of res.getHeaderNames()) res.removeHeader(name);
+        flushingBodyRefusal = true;
+        res.writeHead(413, { 'connection': 'close', 'content-type': 'text/plain', 'content-length': Buffer.byteLength(error.message) });
+        res.once('finish', () => { flushingBodyRefusal = false; req.destroy(); });
+        res.end(error.message);
+      } else if (!res.destroyed) res.destroy(error);
+      abort();
+    };
+    const inputSettled = new Promise<void>((resolve) => {
+      const settled = () => { req.off('end', settled); req.off('close', settled); resolve(); };
+      req.once('end', settled);
+      req.once('close', settled);
+    });
     const handle = async () => {
       const method = req.method ?? 'GET';
+      if (Number(req.headers['content-length']) > requestLimit) { rejectBody(); return; }
       let response: Response;
       try {
         const headers = new Headers();
         for (const [k, v] of Object.entries(req.headers)) { if (v === undefined) continue; if (Array.isArray(v)) for (const one of v) headers.append(k, one); else headers.set(k, v); }
         const url = `${protocol}://${req.headers.host ?? `${options.hostname}:${(server.address() as { port: number } | null)?.port ?? 0}`}${req.url ?? '/'}`;
         const withBody = method !== 'GET' && method !== 'HEAD';
-        const init: RequestInit & { duplex?: 'half' } = { method, headers, signal: controller.signal, ...(withBody ? { body: Readable.toWeb(req) as unknown as ReadableStream, duplex: 'half' } : {}) };
+        let received = 0;
+        incoming = new Transform({ transform(chunk: Buffer, _encoding, callback) {
+          received += chunk.byteLength;
+          if (received > requestLimit) { rejectBody(); callback(new RequestBodyTooLargeError()); }
+          else callback(null, chunk);
+        } });
+        const inputClosed = () => { if (!req.readableEnded) abort(); };
+        incoming.on('error', inputClosed);
+        incoming.once('close', inputClosed);
+        const init: RequestInit & { duplex?: 'half' } = { method, headers, signal: controller.signal, ...(withBody ? { body: Readable.toWeb(incoming) as unknown as ReadableStream, duplex: 'half' } : {}) };
         request = new Request(url, init);
         activeRequests.add(request);
+        req.pipe(incoming);
+        if (!withBody) incoming.resume();
         response = await options.fetch(request);
       } catch (error) {
         if (disconnected()) return;
@@ -340,6 +395,7 @@ async function serveOnNode(options: ServeHttpOptions & { hostname: string; urlHo
         if (disconnected()) { await cancelOwnedReader(); return; }
         res.statusCode = response.status;
         for (const [k, v] of response.headers) { if (k !== 'set-cookie') res.setHeader(k, v); }
+        res.strictContentLength = response.headers.has('content-length');
         const cookies = response.headers.getSetCookie?.() ?? [];
         if (cookies.length) res.setHeader('set-cookie', cookies);
         if (reader) {
@@ -382,12 +438,18 @@ async function serveOnNode(options: ServeHttpOptions & { hostname: string; urlHo
       if (!res.destroyed) res.destroy(error instanceof Error ? error : new Error(String(error)));
     }).then(async () => {
       await responseSettled;
-      active.delete(controller);
+      // A runtime may retire its native body forwarding when the response ends.
+      // Close unfinished input after the response flushes; a consumed upload keeps its connection.
+      if (hasInputBody && !incoming?.readableEnded) abort();
+      else incoming?.resume();
+      await inputSettled;
+      if (incoming) { req.unpipe(incoming); incoming.destroy(); }
+      active.delete(abort);
       req.off('aborted', abort);
       req.off('close', onRequestClose);
       req.off('error', abort);
-      req.socket.off('close', onSocketClose);
-      req.socket.off('error', abort);
+      socket.off('close', onSocketClose);
+      socket.off('error', abort);
       res.off('close', onResponseClose);
       res.off('error', abort);
     });
@@ -415,7 +477,7 @@ async function serveOnNode(options: ServeHttpOptions & { hostname: string; urlHo
   const port = (server.address() as { port: number }).port;
   return {
     hostname: options.hostname, port, url: new URL(`${protocol}://${options.urlHost}:${port}/`),
-    stop: (closeActive = true) => new Promise<void>((resolve) => { if (closeActive) { for (const controller of active) controller.abort(); for (const peer of socketServer?.clients ?? []) peer.terminate(); } socketServer?.close(); server.close(() => { if (closeActive && active.size) reportCleanup('forced stop left pending handler cleanup', `${active.size} request(s)`); resolve(); }); if (closeActive) server.closeAllConnections(); }),
+    stop: (closeActive = true) => new Promise<void>((resolve) => { if (closeActive) { for (const abort of active) abort(); for (const peer of socketServer?.clients ?? []) peer.terminate(); } socketServer?.close(); server.close(() => { if (closeActive && active.size) reportCleanup('forced stop left pending handler cleanup', `${active.size} request(s)`); resolve(); }); if (closeActive) server.closeAllConnections(); }),
   };
 }
 

package/src/smtp-server.ts

@@ -0,0 +1,166 @@
+// THE KERNEL'S SMTP SERVER MACHINE (`smtpServer`, from `@volter/world-core`): RFC 5321's mechanics every pack that serves an
+// SMTP server shares (a relay's submission server, a mailbox provider's receiving server: ADR 0032 §4), behind the kernel's
+// stream boundary (TwinStream). It frames a connection's bytes into commands, a message's data and an AUTH response,
+// carries them to the pack's front over the pack's own fetch (a private bridge the pack's key signs), and parses the
+// RFC's command arguments. What a server answers, which senders and recipients it takes and what it keeps stay in each
+// pack: its replies, its policy and its writes. The kernel names no vendor. docs/contributing/architecture.md, "Other
+// wires: lanes, headers and line protocols".
+// source: RFC 5321 §4.1.1.4 "In particular, the sequence \"<LF>.<LF>\" (bare line feeds, without carriage returns) MUST NOT be treated as equivalent to <CRLF>.<CRLF> as the end of mail data indication."
+// source: RFC 5321 §4.5.2 "If the first character is a period and there are other characters on the line, the first character is deleted."
+import type { HandlerContext } from './derived-core.ts';
+import type { TwinStream } from './twin-fetch.ts';
+
+/** What a server's front answers the stream: its reply lines, the moved session, and whether the stream reads a
+ *  message's data next (`data`), an AUTH response (`auth`) or commands, or closes. */
+export type SmtpAnswer<S> = { replies: string[]; session: S; mode: 'command' | 'data' | 'auth'; close?: boolean };
+
+/** The bridge between a connection and the pack's front: the header that carries the pack's key, the key, a fresh
+ *  session, and the pack's answer when its front cannot answer (its words for a local error). */
+export type SmtpBridge<S> = { header: string; key: () => string; fresh: () => S; failure: (session: S) => SmtpAnswer<S> };
+
+/** A connection's bytes framed as SMTP frames them, each piece posted to the pack's front (`smtpFront`) through its
+ *  fetch with the session the connection carries: commands are lines ended by CRLF; after a 354, the message's lines up
+ *  to the lone dot, their leading dot removed; after a 334, one line of AUTH response. Pipelined commands are answered
+ *  in order. */
+export function smtpStream<S>(fetch: (request: Request) => Response | Promise<Response>, bridge: SmtpBridge<S>): TwinStream {
+  return (sink, peer) => {
+    const encoder = new TextEncoder();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let session = bridge.fresh();
+    let mode: SmtpAnswer<S>['mode'] = 'command';
+    let data: string[] = [];
+    let closed = false;
+    let chain: Promise<void> = Promise.resolve();
+
+    const post = async (body: Record<string, unknown>): Promise<void> => {
+      if (closed) return;
+      let a: SmtpAnswer<S>;
+      try {
+        const res = await fetch(new Request('http://smtp.wire/', { method: 'POST', headers: { 'content-type': 'application/json', [bridge.header]: bridge.key(), 'x-forwarded-for': peer }, body: JSON.stringify({ session, ...body }) }));
+        a = res.ok ? (await res.json()) as SmtpAnswer<S> : bridge.failure(session);
+        if (!Array.isArray(a.replies) || !a.session || !['command', 'data', 'auth'].includes(a.mode)) a = bridge.failure(session);
+      } catch { a = bridge.failure(session); }
+      session = a.session;
+      mode = a.mode;
+      sink.write(encoder.encode(a.replies.map((r) => `${r}\r\n`).join('')));
+      if (a.close) { closed = true; sink.end(); }
+    };
+
+    const line = async (text: string): Promise<void> => {
+      if (mode === 'data') {
+        if (text === '.') { const message = data.join('\r\n') + (data.length ? '\r\n' : ''); data = []; mode = 'command'; await post({ data: message }); return; }
+        data.push(text.startsWith('.') ? text.slice(1) : text);
+        return;
+      }
+      if (mode === 'auth') { await post({ response: text }); return; }
+      await post({ line: decoder.decode(Uint8Array.from(text, (c) => c.charCodeAt(0))) });
+    };
+
+    const pump = (): void => {
+      let at: number;
+      while ((at = buffer.indexOf('\r\n')) >= 0) {
+        const text = buffer.slice(0, at);
+        buffer = buffer.slice(at + 2);
+        chain = chain.then(() => line(text));
+      }
+    };
+
+    chain = chain.then(() => post({ open: true }));
+    return {
+      data(chunk) { if (closed) return; buffer += Array.from(chunk, (b) => String.fromCharCode(b)).join(''); pump(); },
+      settled: () => chain,
+      close() { closed = true; },
+    };
+  };
+}
+
+/** What a pack's front does with each piece the stream carries: the greeting, a command line, a message's data, an AUTH
+ *  response (a server that takes none leaves it out). */
+type SmtpServer<S> = {
+  open(): SmtpAnswer<S> | Promise<SmtpAnswer<S>>;
+  command(session: S, line: string): SmtpAnswer<S> | Promise<SmtpAnswer<S>>;
+  data(session: S, data: string): SmtpAnswer<S> | Promise<SmtpAnswer<S>>;
+  response?(session: S, response: string): SmtpAnswer<S> | Promise<SmtpAnswer<S>>;
+};
+
+/** The pack's front (its `around`): a request the stream signed with the pack's key is a piece of a connection, answered
+ *  by the pack's server; any other request is the pack's own (its doors and screens). */
+export async function smtpFront<S>(ctx: HandlerContext, next: (request?: Request) => Promise<Response>, bridge: SmtpBridge<S>, server: SmtpServer<S>): Promise<Response> {
+  const request = ctx.call.request;
+  if (!request.headers.has(bridge.header)) return next();
+  if (request.headers.get(bridge.header) !== bridge.key()) return new Response('not the server\'s wire', { status: 403 });
+  const w = (ctx.body ?? {}) as { session?: S; open?: boolean; line?: string; data?: string; response?: string };
+  const s = w.session ?? bridge.fresh();
+  if (w.open) return Response.json(await server.open());
+  if (w.data !== undefined) return Response.json(await server.data(s, w.data));
+  if (w.response !== undefined && server.response) return Response.json(await server.response(s, w.response));
+  return Response.json(await server.command(s, String(w.line ?? '')));
+}
+
+/** A command's verb (upper-cased) and its argument. */
+export function smtpCommand(line: string): { verb: string; arg: string } {
+  const [verb = '', ...rest] = line.split(' ');
+  return { verb: verb.toUpperCase(), arg: rest.join(' ') };
+}
+
+/** The session machine's word on a command from where a session stands (the manifest's states): a refusal's reply, or
+ *  undefined to go on. */
+export function smtpOrder(ctx: Pick<HandlerContext, 'legal'>, machine: string, stage: string, op: string, to?: string): string | undefined {
+  const refusal = ctx.legal(machine, 'stage', op, stage, to);
+  return refusal ? `${refusal.status} ${String(refusal.code)} ${refusal.message}` : undefined;
+}
+
+/** EHLO's multi-line 250 reply: the server's name, then each keyword. */
+// source: RFC 5321 §4.1.1.1 "ehlo-ok-rsp"
+export const smtpEhlo = (keywords: string[]): string[] => keywords.map((k, i) => `250${i === keywords.length - 1 ? ' ' : '-'}${k}`);
+
+/** An address in angle brackets (`<a@b>`, `<>` for the null sender), or undefined when it is not one. */
+function smtpAddress(arg: string): string | undefined {
+  const m = /^<([^<>\s]*)>$/.exec(arg.trim());
+  if (!m) return undefined;
+  const a = m[1]!;
+  if (a === '') return '';
+  return /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(a) ? a : undefined;
+}
+
+/** An address's domain, lower-cased. */
+export const smtpDomain = (address: string): string => address.slice(address.lastIndexOf('@') + 1).toLowerCase();
+
+/** MAIL's argument: the sender and its SIZE, BODY and SMTPUTF8 parameters, or why it is refused (the pack words it). */
+// source: RFC 5321 §4.1.1.2 "MAIL FROM:<reverse-path> [SP <mail-parameters> ] <CRLF>"
+export function smtpMailFrom(arg: string): { from: string; size?: number; smtputf8: boolean } | { refused: 'syntax' | 'sender' | 'size' } | { refused: 'parameter'; parameter: string } {
+  const m = /^FROM:\s*(<[^>]*>)((?:\s+\S+)*)\s*$/i.exec(arg);
+  if (!m) return { refused: 'syntax' };
+  const from = smtpAddress(m[1]!);
+  if (from === undefined) return { refused: 'sender' };
+  let size: number | undefined;
+  let smtputf8 = false;
+  for (const parameter of m[2]!.trim().split(/\s+/).filter(Boolean)) {
+    const [k = '', v] = parameter.split('=');
+    if (k.toUpperCase() === 'SIZE') { if (!/^\d+$/.test(v ?? '')) return { refused: 'size' }; size = Number(v); }
+    else if (k.toUpperCase() === 'BODY' && ['7BIT', '8BITMIME'].includes((v ?? '').toUpperCase())) continue;
+    else if (k.toUpperCase() === 'SMTPUTF8' && v === undefined) smtputf8 = true;
+    else return { refused: 'parameter', parameter };
+  }
+  return { from, ...(size !== undefined ? { size } : {}), smtputf8 };
+}
+
+/** RCPT's argument: the recipient, or why it is refused (the pack words it). */
+// source: RFC 5321 §4.1.1.3 "RCPT TO:<forward-path> [ SP <rcpt-parameters> ] <CRLF>"
+export function smtpRcptTo(arg: string): { to: string } | { refused: 'syntax' | 'recipient' } | { refused: 'parameter'; parameter: string } {
+  const m = /^TO:\s*(<[^>]*>)(?:\s+\S+)*\s*$/i.exec(arg);
+  if (!m) return { refused: 'syntax' };
+  // source: RFC 5321 §4.1.1.11 "command, it will return code 555."
+  if (/^TO:\s*<[^>]*>\s+\S/i.test(arg)) return { refused: 'parameter', parameter: arg.slice(arg.indexOf('>') + 1).trim() };
+  const to = smtpAddress(m[1]!);
+  return to ? { to } : { refused: 'recipient' };
+}
+
+/** A transaction's state cleared, the greeting kept (RSET, a new EHLO, the end of DATA): the session's `stage`,
+ *  `greeted` and an empty `rcpt`, with whatever of the session the pack keeps across transactions (`kept`). */
+// source: RFC 5321 §4.1.1.5 "This command specifies that the current mail transaction will be aborted."
+export function smtpCleared<S extends { stage: string; rcpt: string[]; greeted?: 'helo' | 'ehlo' }>(s: S, stage: string, kept: Omit<S, 'stage' | 'rcpt' | 'greeted' | 'from'>): Omit<S, 'stage' | 'rcpt' | 'greeted' | 'from'> & { stage: string; rcpt: string[]; greeted?: 'helo' | 'ehlo' } {
+  const greeted = stage === 'helo' || stage === 'ehlo' ? stage : s.greeted;
+  return { ...kept, stage, rcpt: [], ...(greeted ? { greeted } : {}) };
+}