@volter/world-core 3.0.163 → 3.0.165

package/dist/src/serve-http.js

@@ -1,13 +1,14 @@
 // 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`
 // rather than a static import: this module rides into browser client bundles through the kernel's
 // entrypoint, where a static `node:` import is the 2026-09-06 class of break.
 import { worldBootAnswer } from "./world-boot.js";
+import { DEFAULT_MAX_DECODED_REQUEST_BODY_SIZE, RequestBodyTooLargeError } from "./request-body.js";
 /** One socket library at the host seam, shared by inbound upgrades and authenticated outbound relays. */
 const socketLibrary = () => import('ws');
 export async function connectWebSocket(url, headers, protocols = []) {
@@ -56,7 +57,7 @@ export async function serveHttp(options) {
     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;
@@ -152,6 +153,7 @@ export async function serveStream(options) {
         throw new StreamListenerUnavailable('this runtime has no TCP listener (node:net)');
     const cap = options.maxConnections ?? options.stream.maxConnections;
     let open = 0;
+    const accepted = new Set();
     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) {
@@ -159,7 +161,8 @@ export async function serveStream(options) {
             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
@@ -181,7 +184,14 @@ export async function serveStream(options) {
     });
     await new Promise((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 = () => new Promise((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(name) {
     const get = process.getBuiltinModule;
@@ -191,7 +201,8 @@ function builtin(name) {
 }
 async function serveOnNode(options) {
     const http = builtin('node:http');
-    const { Readable } = builtin('node:stream');
+    const { Readable, Transform } = builtin('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';
@@ -230,20 +241,35 @@ async function serveOnNode(options) {
     const activeRequests = new Set();
     const server = factory((req, res) => {
         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;
+        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;
@@ -279,8 +305,38 @@ async function serveOnNode(options) {
                 closed();
         });
         let request;
+        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((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;
             try {
                 const headers = new Headers();
@@ -295,9 +351,26 @@ async function serveOnNode(options) {
                 }
                 const url = `${protocol}://${req.headers.host ?? `${options.hostname}:${server.address()?.port ?? 0}`}${req.url ?? '/'}`;
                 const withBody = method !== 'GET' && method !== 'HEAD';
-                const init = { method, headers, signal: controller.signal, ...(withBody ? { body: Readable.toWeb(req), duplex: 'half' } : {}) };
+                let received = 0;
+                incoming = new Transform({ transform(chunk, _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 = { method, headers, signal: controller.signal, ...(withBody ? { body: Readable.toWeb(incoming), duplex: 'half' } : {}) };
                 request = new Request(url, init);
                 activeRequests.add(request);
+                req.pipe(incoming);
+                if (!withBody)
+                    incoming.resume();
                 response = await options.fetch(request);
             }
             catch (error) {
@@ -365,6 +438,7 @@ async function serveOnNode(options) {
                     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);
@@ -424,12 +498,23 @@ async function serveOnNode(options) {
                 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);
         });
@@ -462,8 +547,8 @@ async function serveOnNode(options) {
     return {
         hostname: options.hostname, port, url: new URL(`${protocol}://${options.urlHost}:${port}/`),
         stop: (closeActive = true) => new Promise((resolve) => { if (closeActive) {
-            for (const controller of active)
-                controller.abort();
+            for (const abort of active)
+                abort();
             for (const peer of socketServer?.clients ?? [])
                 peer.terminate();
         } socketServer?.close(); server.close(() => { if (closeActive && active.size)

package/dist/src/smtp-server.d.ts

@@ -0,0 +1,78 @@
+import type { HandlerContext } from './derived-core.js';
+import type { TwinStream } from './twin-fetch.js';
+/** 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 declare function smtpStream<S>(fetch: (request: Request) => Response | Promise<Response>, bridge: SmtpBridge<S>): TwinStream;
+/** 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 declare function smtpFront<S>(ctx: HandlerContext, next: (request?: Request) => Promise<Response>, bridge: SmtpBridge<S>, server: SmtpServer<S>): Promise<Response>;
+/** A command's verb (upper-cased) and its argument. */
+export declare function smtpCommand(line: string): {
+    verb: string;
+    arg: string;
+};
+/** 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 declare function smtpOrder(ctx: Pick<HandlerContext, 'legal'>, machine: string, stage: string, op: string, to?: string): string | undefined;
+/** EHLO's multi-line 250 reply: the server's name, then each keyword. */
+export declare const smtpEhlo: (keywords: string[]) => string[];
+/** An address's domain, lower-cased. */
+export declare const smtpDomain: (address: string) => string;
+/** MAIL's argument: the sender and its SIZE, BODY and SMTPUTF8 parameters, or why it is refused (the pack words it). */
+export declare function smtpMailFrom(arg: string): {
+    from: string;
+    size?: number;
+    smtputf8: boolean;
+} | {
+    refused: 'syntax' | 'sender' | 'size';
+} | {
+    refused: 'parameter';
+    parameter: string;
+};
+/** RCPT's argument: the recipient, or why it is refused (the pack words it). */
+export declare function smtpRcptTo(arg: string): {
+    to: string;
+} | {
+    refused: 'syntax' | 'recipient';
+} | {
+    refused: 'parameter';
+    parameter: string;
+};
+/** 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`). */
+export declare 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';
+};
+export {};

package/dist/src/smtp-server.js

@@ -0,0 +1,160 @@
+/** 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(fetch, bridge) {
+    return (sink, peer) => {
+        const encoder = new TextEncoder();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let session = bridge.fresh();
+        let mode = 'command';
+        let data = [];
+        let closed = false;
+        let chain = Promise.resolve();
+        const post = async (body) => {
+            if (closed)
+                return;
+            let a;
+            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()) : 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) => {
+            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 = () => {
+            let at;
+            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; },
+        };
+    };
+}
+/** 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(ctx, next, bridge, server) {
+    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 ?? {});
+    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) {
+    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, machine, stage, op, to) {
+    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) => 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) {
+    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) => 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) {
+    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;
+    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) {
+    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, stage, kept) {
+    const greeted = stage === 'helo' || stage === 'ehlo' ? stage : s.greeted;
+    return { ...kept, stage, rcpt: [], ...(greeted ? { greeted } : {}) };
+}

package/dist/src/smtp.d.ts

@@ -1,16 +1,34 @@
-/** Where a mail goes: the SMTP host and port, and the sender. */
-export type SmtpRoute = {
-    host: string;
-    port: number;
+import type { TwinStream } from './twin-fetch.js';
+/** One mail, from its sender to its recipients: the sender's own message bytes, or a vendor's HTML mail the kernel
+ *  composes (GoTrue's links). */
+export type Mail = {
     from: string;
+    to: string[];
+} & ({
+    raw: Uint8Array | string;
+} | {
     senderName?: string;
-};
-/** One mail: its recipient, subject and HTML body. */
-export type Mail = {
-    to: string;
     subject: string;
     html: string;
+    headers?: Record<string, string>;
+});
+/** One recipient's answer: the receiving server's reply to its `RCPT`, or to the message when it accepted the
+ *  recipient; or the kernel's own refusal when no server receives the recipient's domain. */
+export type MailReply = {
+    to: string;
+    code: number;
+    reply: string;
+};
+/** A mail server this process answers itself (a journey walk's companion over the walk's own World): its SMTP side
+ *  port's byte-stream door (`create<Name>TwinStream`), for the domains `receives` names (its host rules). */
+type InProcessMailServer = {
+    vendor: string;
+    receives: (domain: string) => boolean;
+    stream: TwinStream;
 };
-/** Send one mail. Throws when it cannot be delivered (refused by the World's egress rule, unreachable, or refused by the
- *  server), so the vendor answers its own mailer failure. */
-export declare function sendMail(route: SmtpRoute, mail: Mail, headers?: Record<string, string>): Promise<void>;
+/** The mail servers this process answers itself, consulted before the instance's; returns those set before, which the
+ *  caller puts back. */
+export declare function setInProcessMailServers(servers: ReadonlyArray<InProcessMailServer>): ReadonlyArray<InProcessMailServer>;
+/** Hand one mail to each recipient's mailbox provider; every recipient's reply, in the order given. */
+export declare function sendMail(mail: Mail): Promise<MailReply[]>;
+export {};