functionalscript 0.46.1 → 0.47.0

package/fjs/effects/node/module.mjs

@@ -16,6 +16,7 @@
  * @import { IoResult, Server as EffectServer, Headers, Module, NodeOp, RequestListener as Erl, NodeProgram, NodeProgramOptions, WriteConsoles, TestContext, TestFn, } from './types.ts'
  * @import { Result } from '../../types/result/types.ts'
  * @import { StringMap } from '../../types/object/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
  */
 
 import http from 'node:http'
@@ -30,14 +31,28 @@ import * as testContext from 'node:test'
 import { concat, normalize, toPosix } from '../../path/module.f.mjs'
 import { asyncRun } from '../module.mjs'
 import { memoryOperationMap } from './memory/module.mjs'
-import { exitCode, toIoError, usesInlineTestContext } from './module.f.mjs'
+import {
+    emptyHost, emptyHostCode, emptyHostMessage, exitCode, toIoError, usesInlineTestContext,
+} from './module.f.mjs'
 import { asBase, asNominal } from '../../types/nominal/module.f.mjs'
 import { error, ok, unwrap } from '../../types/result/module.f.mjs'
-import { asyncTryCatch } from '../../types/result/module.mjs'
+import { asyncTryCatch, tryCatch } from '../../types/result/module.mjs'
 import { fromVec, listToVec, toVec } from '../../types/uint8array/module.f.mjs'
 import { maxLengthBytes } from '../../types/bit_vec/module.f.mjs'
 
-/** @typedef {{ readonly listen: (port: number) => void }} _Server */
+/** The one thing this runner does with the socket a `connect` event hands it.
+ *
+ * @typedef {{ readonly end: (data: string) => void }} _Socket
+ */
+
+/**
+ * @typedef {{
+ *   readonly listen: (port: number, host: string) => void,
+ *   readonly once: (event: string, f: (e: unknown) => void) => void,
+ *   on(event: string, f: (req: unknown, socket: _Socket) => void): void,
+ *   readonly removeListener: (event: string, f: (e: unknown) => void) => void,
+ * }} _Server
+ */
 
 /** @typedef {AsyncIterable<Uint8Array>} _Readable */
 
@@ -53,6 +68,7 @@ import { maxLengthBytes } from '../../types/bit_vec/module.f.mjs'
  * @typedef {{
  *   readonly writeHead: (status: number, headers: StringMap<string>) => _ServerResponse,
  *   readonly end: (body: Uint8Array) => void,
+ *   readonly headersSent: boolean,
  * }} _ServerResponse
  */
 
@@ -86,30 +102,146 @@ const io = async f => {
 }
 
 /**
- * @template T
- * @param {AsyncIterable<T>} v
- * @returns {Promise<readonly T[]>}
+ * Reads a request body, giving up at the `Vec` cap rather than at the point
+ * where converting it would throw.
+ *
+ * `listToVec` on an oversized body throws *after* the whole thing has been
+ * buffered, which is the wrong end of the problem twice over: the memory is
+ * already spent, and the throw lands inside an `async` request handler whose
+ * promise nobody awaits. Counting as the chunks arrive stops both.
+ *
+ * **The accumulator is mutated, deliberately.** Rebuilding the array per chunk
+ * — `result = [...result, a]`, the shape the rest of this repository is written
+ * in — copies every chunk received so far on every chunk received, which is
+ * quadratic in the *number* of chunks. The byte cap does not bound that: 20,000
+ * one-byte chunks are 20 KB and 200 million copies, and took 2,794 ms of event
+ * loop to reach an answer the server had already decided on — 167 ms now, and
+ * the growth went from ×4 per doubling to ×2. A cap on payload size is not a cap
+ * on chunk count, and a request that will be refused must not cost more than one
+ * that is served. The array never leaves this function before it
+ * is finished, so nothing observes the mutation — which is the condition under
+ * which the impure shell is allowed to be impure.
+ *
+ * @param {_Readable} v
+ * @returns {Promise<Nullable<readonly Uint8Array[]>>} `null` past the cap.
  */
-const collect = async v => {
-    /** @type {readonly T[]} */
-    let result = []
+const collectBounded = async v => {
+    /** @type {Uint8Array[]} */
+    const result = []
+    let size = 0
     for await (const a of v) {
-        result = [...result, a]
+        size += a.length
+        if (size > maxFileSizeBytes) { return null }
+        result.push(a)
     }
     return result
 }
 
+/**
+ * The runner's own answer, for the cases a listener never gets to give one: a
+ * request body too large to hand it, and a listener that threw.
+ *
+ * **It closes the connection**, which is the whole difference between refusing
+ * a request and surviving the refusal. Both cases answer without having read
+ * the request to its end, and on a keep-alive connection Node then waits for
+ * the rest of a body that is never coming — the socket is stuck, and the next
+ * request on it is never answered. A client that declares ten megabytes and
+ * sends a hundred kilobytes could hold connections open that way for as long as
+ * it liked. Draining the remainder would be the polite alternative and the
+ * wrong one: it reads bytes this server has already decided it will not use.
+ *
+ * @type {(res: _ServerResponse) => (status: number) => (message: string) => void}
+ */
+const respondWith = res => status => message => {
+    const body = textEncoder.encode(`${message}\n`)
+    res
+        .writeHead(status, {
+            'content-type': 'text/plain; charset=utf-8',
+            'content-length': `${body.length}`,
+            connection: 'close',
+        })
+        .end(body)
+}
+
+/**
+ * The whole HTTP response to a `CONNECT`, as bytes on a raw socket.
+ *
+ * Written by hand rather than through {@link respondWith}, because the `connect`
+ * event hands over a socket and not a `ServerResponse` — there is no object to
+ * ask for a status line.
+ *
+ * @type {string}
+ */
+const connectRefusal =
+    'HTTP/1.1 501 Not Implemented\r\n'
+    + 'content-type: text/plain; charset=utf-8\r\n'
+    + 'content-length: 26\r\n'
+    + 'connection: close\r\n'
+    + '\r\n'
+    + 'this server cannot tunnel\n'
+
+/**
+ * Answers one request through `listener`, or explains that it could not.
+ *
+ * A body past the cap never reaches the listener: `IncomingMessage.body` is a
+ * single `Vec`, so there is no request value to build, and `413` is the accurate
+ * answer rather than a truncated one. Streaming bodies lift the whole limit —
+ * see `./todo/streaming-http-bodies.md`.
+ *
+ * `unwrap` is total here: a `RequestListener` answers
+ * `Effect<…, ServerResponse, never>`, because the response frame *is* where a
+ * listener puts its failures.
+ *
+ * @type {(listener: Erl<NodeOp>) => _RequestListener}
+ */
+const answerRequest = listener => async (req, res) => {
+    const body = await collectBounded(req)
+    if (body === null) {
+        respondWith(res)(413)('request body too large')
+        return
+    }
+    const { method, url, headers } = req
+    const { status, headers: outHeaders, body: outBody } = unwrap(await runNodeEffect(listener({
+        method,
+        url,
+        headers,
+        body: listToVec(body),
+    })))
+    res.writeHead(status, outHeaders).end(fromVec(outBody))
+}
+
+/**
+ * What a request gets when answering it threw.
+ *
+ * Once the listener has started writing there is no status left to change, so
+ * the only thing owed is an end to the response — leaving it open would hang
+ * the connection until it times out.
+ *
+ * @type {(res: _ServerResponse) => void}
+ */
+const failSafe = res => {
+    if (res.headersSent) {
+        res.end(emptyBody)
+        return
+    }
+    respondWith(res)(500)('internal server error')
+}
+
 const { mkdir, open, readFile, readdir, rename, writeFile, rm, access, stat } = fs.promises
 
 const { exec } = childProcess
 
 const maxFileSizeBytes = Number(maxLengthBytes)
 
+const textEncoder = new TextEncoder()
+
+const emptyBody = new Uint8Array()
+
 const prefix = /** @type {const} */ ('file:///')
 
 /** @type {(v: string) => Promise<Module>} */
 const asyncImport = v => {
-    const s0 = v.includes(':') || v.startsWith('/') ? v : concat(process.cwd())(v)
+    const s0 = v.includes(':') ? v : concat(process.cwd())(v)
     const s1 = s0.startsWith(prefix) ? s0 : `${prefix}${s0}`
     return import(s1)
 }
@@ -291,7 +423,10 @@ const runNodeEffect = asyncRun({
             await fh.close()
         }
     }),
-    stat: path => io(async () => ({ size: (await stat(path)).size })),
+    stat: path => io(async () => {
+        const s = await stat(path)
+        return { size: s.size, isFile: s.isFile() }
+    }),
     import: path => io(() => asyncImport(path)),
     exec: (command, stdin) => new Promise(resolve => {
         const child = exec(command, (e, stdout, stderr) =>
@@ -300,31 +435,98 @@ const runNodeEffect = asyncRun({
         child.stdin?.end(stdin)
     }),
     createServer: async requestListener => {
-        const erl = /** @type {Erl<NodeOp>} */ (requestListener)
+        const answer = answerRequest(/** @type {Erl<NodeOp>} */ (requestListener))
+        // **Nothing may escape this handler.** Node does not await the promise
+        // an `async` request listener returns, so a throw inside one becomes an
+        // unhandled rejection and ends the *process*: one request, and the
+        // whole server is gone. A panic must not outlive the request that
+        // caused it, so the answer is caught here and the fallback — itself
+        // able to throw on a socket that has since died — is caught too.
         /** @type {_RequestListener} */
         const nodeRl = async (req, res) => {
-            const reqBody = await collect(req)
-            const { method, url, headers } = req
-            // `RequestListener` answers `Effect<…, ServerResponse, never>` —
-            // the response frame is where a listener puts its failures — so
-            // this unwrap is total.
-            const { status, headers: outHeaders, body: outBody } = unwrap(await runNodeEffect(erl({
-                method,
-                url,
-                headers,
-                body: listToVec(reqBody)
-            })))
-            res
-                .writeHead(status, outHeaders)
-                .end(fromVec(outBody))
+            const r = await asyncTryCatch(() => answer(req, res))
+            if (r[0] === 'error') { tryCatch(() => failSafe(res)) }
         }
-        return ok(/** @satisfies {EffectServer} */ (asNominal(createServer(nodeRl))))
+        const server = createServer(nodeRl)
+        // A `CONNECT` never reaches the listener: Node routes it to the
+        // `connect` event, and with no handler there it drops the socket
+        // without a byte of HTTP — checked on Linux with Node 22.22.2, where
+        // `CONNECT localhost:18084 HTTP/1.1` closed the connection while a
+        // `POST` to the same server was answered. A client that asked a
+        // question deserves an answer, so the runner gives the one it can.
+        //
+        // `501`, not `405`. A `405` must carry `Allow` (RFC 9110 §15.5.6) and
+        // only the listener knows what it allows, while `501` is exactly what
+        // RFC 9110 §15.6.2 describes — a method the server cannot support for
+        // any resource. That is true of *every* server this effect layer can
+        // build: `RequestListener` maps a request frame to a response frame and
+        // has no vocabulary for a tunnel, so no listener could answer a
+        // `CONNECT` even if it were handed one.
+        //
+        // Answering here rather than passing it on follows the `413` and `500`
+        // above: the runner answers on the listener's behalf exactly when the
+        // listener structurally cannot.
+        server.on('connect', (_, socket) => { tryCatch(() => socket.end(connectRefusal)) })
+        return ok(/** @satisfies {EffectServer} */ (asNominal(server)))
     },
-    listen: async (server, port) => {
+    // Binding is asynchronous, and its failure arrives as an `error` event
+    // rather than a throw: answering `ok` the moment `listen` was *called*
+    // reported a server that never started, and Node then killed the process
+    // with an unhandled `EADDRINUSE` — after the program had already printed
+    // the URL it was serving. So this settles on the outcome, not on the call.
+    listen: (server, port, host) => io(() => new Promise((resolve, reject) => {
         const s = /** @type {_Server} */ (asBase(server))
-        s.listen(port)
-        return ok(undefined)
-    },
+        // An empty host is the trap this operation's required `host` argument
+        // exists to close, so it is refused rather than forwarded. Node treats
+        // `''` exactly as it treats an omitted argument and binds the
+        // unspecified address — `0.0.0.0` on Linux with Node 22.22.2 and `::`
+        // on Darwin with Node 23.11.0, a different address each and the same
+        // mistake — which is how a missing configuration value publishes a
+        // server on every interface while the program believes it stated an
+        // address. A program that wants every interface says `'0.0.0.0'` or
+        // `'::'` and means it.
+        //
+        // The error is Node's own code and message shape for an argument it
+        // rejects, since a caller reading `IoError.code` should not have to
+        // learn a second vocabulary for a refusal that is this runner's own.
+        if (host === emptyHost) {
+            reject(Object.assign(new Error(emptyHostMessage), { code: emptyHostCode }))
+            return
+        }
+        // Each handler removes the other, so exactly one outcome is recorded and
+        // neither is left attached. `once` only removes the handler that fired:
+        // a failed bind used to leave its `listening` handler behind, and a
+        // caller retrying after an `EADDRINUSE` accumulated one per attempt
+        // until Node warned about the leak.
+        /** @type {() => void} */
+        const onListening = () => {
+            // A later `error` event is not this effect's to answer, and a
+            // handler still holding `reject` would swallow it into an
+            // already-settled promise.
+            s.removeListener('error', onError)
+            resolve(undefined)
+        }
+        /** @type {(e: unknown) => void} */
+        const onError = e => {
+            s.removeListener('listening', onListening)
+            reject(e)
+        }
+        s.once('error', onError)
+        s.once('listening', onListening)
+        // `listen` can also fail *synchronously* — an out-of-range port throws
+        // `ERR_SOCKET_BAD_PORT`, an already-listening server throws too — and a
+        // throw here would reject the promise past both handlers, leaving them
+        // attached: 20 attempts, 20 stale `error` handlers, each holding a
+        // `reject` that can never fire and would swallow a later error into an
+        // already-settled promise. So the synchronous path cleans up after
+        // itself, exactly as the two event paths do.
+        const started = tryCatch(() => s.listen(port, host))
+        if (started[0] === 'error') {
+            s.removeListener('error', onError)
+            s.removeListener('listening', onListening)
+            reject(started[1])
+        }
+    })),
     forever: () => new Promise(() => {}),
     now: async () => ok(now()),
     sandbox: async f => ok(await sandbox(f)),

package/fjs/effects/node/types.d.ts

@@ -127,9 +127,20 @@ export type CreateExclusive = readonly ['createExclusive', (path: string) => IoR
 export type WriteBytes = readonly ['writeBytes', (path: string, offset: number, data: Vec) => IoResult<void>];
 /** @internal */
 export type _WriteLoop = <O extends Operation>(offset: number, e: List<O, Vec, IoChannel>) => Effect<O | WriteBytes, void, IoChannel>;
-/** File metadata returned by `stat`. Only `size` (in bytes) for now. */
+/**
+ * File metadata returned by `stat`: the size in bytes, and whether the entry is
+ * a *regular* file.
+ *
+ * `isFile` is not a convenience. Reading a FIFO, a device or a socket is not
+ * reading a file: `open` on a FIFO with no writer blocks until one appears, so a
+ * `readFile` that reaches one never returns and holds a thread-pool slot for as
+ * long as it waits. Size cannot stand in for the check — a FIFO stats as zero
+ * bytes and passes every bound. It is the same question `Dirent` answers for a
+ * directory listing, asked about one path.
+ */
 export type FileStat = {
     readonly size: number;
+    readonly isFile: boolean;
 };
 export type Stat = readonly ['stat', (path: string) => IoResult<FileStat>];
 export type Fs = Mkdir | ReadFile | ReadBytes | Readdir | WriteFile | Rm | Rename | Exec | Access | CreateExclusive | WriteBytes | Stat;
@@ -153,7 +164,22 @@ export type ServerResponse = {
  */
 export type RequestListener<O extends Operation> = (_: IncomingMessage) => Effect<O, ServerResponse, never>;
 export type CreateServer = ['createServer', (listener: RequestListener<Operation>) => OpResult<Server>];
-export type Listen = ['listen', (server: Server, port: number) => OpResult<void>];
+/**
+ * Starts accepting connections on `port` of `host`.
+ *
+ * The host is **required**, and that is the whole point of it: Node's own
+ * `listen(port)` binds the unspecified address, so omitting it publishes the
+ * server to every interface — a default nobody chose, and one a program serving
+ * local files must not get by writing less. Pass `'127.0.0.1'` for loopback
+ * only, `'0.0.0.0'` (or `'::'`) to accept from anywhere.
+ *
+ * It answers an {@link IoResult} because binding is where a server most often
+ * fails — the port is taken, the address is not the host's — and that failure
+ * arrives asynchronously, as the server's `error` event. An operation that
+ * answered the moment `listen` was *called* would report a server that never
+ * started, and leave the host to kill the process a moment later.
+ */
+export type Listen = ['listen', (server: Server, port: number, host: string) => IoResult<void>];
 export type Http = CreateServer | Listen;
 export type Forever = ['forever', () => OpResult<never>];
 export type Module = StringMap<unknown>;

package/fjs/effects/node/virtual/module.f.d.mts

@@ -5,10 +5,11 @@
  *
  * @import { Vec } from '../../../types/bit_vec/types.ts'
  * @import { PartialMemOperationMap, RunInstance } from '../../mock/types.ts'
- * @import { Dirent, FileStat, IoError, IoResult, Module, NodeOp, NodeProgramOptions, SandboxResult } from '../types.ts'
+ * @import { Dirent, FileStat, IoError, IoResult, Module, NodeOp, NodeProgramOptions, OpResult, RequestListener, SandboxResult, Server } from '../types.ts'
+ * @import { Operation } from '../../types.ts'
  * @import { Result } from '../../../types/result/types.ts'
  * @import { Error } from '../../../types/result/types.ts'
- * @import { Dir, State, _Entity } from './types.ts'
+ * @import { Dir, JsModule, State, _Entity, _VirtualListener, _VirtualServer } from './types.ts'
  */
 import type { RunInstance } from '../../mock/types.ts';
 import type { NodeOp, NodeProgramOptions } from '../types.ts';
@@ -18,14 +19,22 @@ export declare const emptyState: State;
 /**
  * The virtual runner.
  *
- * **It implements part of `NodeOp`, and says so.** `exec`, `createServer`,
- * `listen`, `forever` and `test` have no meaning against an in-memory
- * filesystem, and they used to be present as `todo` handlers — entries that
- * existed only to satisfy a total operation map and threw when reached. They
- * are simply absent now, so a program that asks for one gets
- * `error(notImplemented)` back through its own continuation and decides what an
- * incompatible runner means for it, which is what `NotImplemented` was
- * introduced for. A command that is not a `NodeOp` at all still panics.
+ * **It implements part of `NodeOp`, and says so.** `exec`, `forever` and `test`
+ * have no meaning against an in-memory filesystem, and they used to be present
+ * as `todo` handlers — entries that existed only to satisfy a total operation
+ * map and threw when reached. They are simply absent now, so a program that
+ * asks for one gets `error(notImplemented)` back through its own continuation
+ * and decides what an incompatible runner means for it, which is what
+ * `NotImplemented` was introduced for. A command that is not a `NodeOp` at all
+ * still panics.
+ *
+ * `forever` is absent for a reason no implementation could remove: its result
+ * type is `Result<never, NotImplemented>`, so `error(notImplemented)` is the
+ * *only* value it can produce — a runner that cannot block forever has nothing
+ * else to answer, and a server program run here therefore ends where it would
+ * otherwise have blocked. `createServer` and `listen` do have meanings without
+ * a socket and are implemented above, which is what makes the rest of such a
+ * program provable.
  *
  * @type {RunInstance<NodeOp, State>}
  */