functionalscript 0.46.1 → 0.47.0

package/fjs/effects/node/virtual/proof.f.mjs

@@ -1,20 +1,31 @@
 /**
- * @import { Dir } from './types.ts'
- * @import { NodeOp } from '../types.ts'
+ * @import { Dir, State } from './types.ts'
+ * @import { IncomingMessage, NodeOp, RequestListener } from '../types.ts'
  * @import { Effect } from '../../types.ts'
  * @import { IoChannel } from '../types.ts'
  */
 
 import { assert, assertEq } from '../../../asserts/module.f.mjs'
-import { access, awaitIfPromise, exec, fetch, log, rm, writeFile, readFile, readdir, import_, rename, readBytes, writeBytes, stat, createExclusive } from '../module.f.mjs'
+import { access, awaitIfPromise, exec, fetch, log, rm, writeFile, readFile, readdir, import_, rename, readBytes, writeBytes, stat, createExclusive, createServer, forever, listen } from '../module.f.mjs'
 import { empty, length, maxLengthBytes, vec, vec8 } from '../../../types/bit_vec/module.f.mjs'
+import { history, historyStep, pureOk, step } from '../../module.f.mjs'
+import { utf8, utf8ToString } from '../../../text/module.f.mjs'
 import { emptyState, virtual } from './module.f.mjs'
 import { do_ } from '../../module.f.mjs'
 import { catchStep } from '../../module.f.mjs'
 
 /**
- * Asserts that a channel error is a host failure carrying `message` — the
+ * Asserts that a channel error is a host failure carrying `code` — the
  * normalized shape every runner reports, virtual and Node alike.
+ * @type {(e: IoChannel, code: string) => void}
+ */
+const assertIoCode = (e, code) => {
+    assert(e[0] === 'ioError', e)
+    assertEq(e[1].code, code)
+}
+
+/**
+ * Asserts that a channel error is a host failure carrying `message`.
  * @type {(e: IoChannel, message: string) => void}
  */
 const assertIoMessage = (e, message) => {
@@ -334,6 +345,18 @@ export const proof = {
         const [, result] = virtual({ ...emptyState, root })(rename('myfile', 'mydir'))
         assert(result[0] === 'error')
     },
+    renameForeignArrayFileOntoDirectory: () => {
+        // An array with another constructor's prototype models the observable
+        // instanceof behavior of an array received from another realm.
+        const foreignFile = Reflect.construct(Array, [], Object)
+        assert(Array.isArray(foreignFile))
+        assert(!(foreignFile instanceof Array))
+        /** @type {Dir} */
+        const root = { 'myfile': foreignFile, 'mydir': {} }
+        const [, result] = virtual({ ...emptyState, root })(rename('myfile', 'mydir'))
+        assert(result[0] === 'error')
+        assertIoMessage(result[1], "'mydir' is a directory")
+    },
     readFileTooLarge: () => {
         // a file stored as two max-size chunks exceeds the limit; readFile must return an error
         const chunk0 = vec(maxLengthBytes * 8n)(0n)
@@ -396,14 +419,38 @@ export const proof = {
         const [, result] = virtual({ ...emptyState, root })(writeBytes('file', 5, vec8(0x43n)))
         assert(result[0] === 'error')
     },
+    statOnDirectory: () => {
+        // A host stats a directory successfully and says it is not a file. The
+        // empty remaining path is how one arrives here: `operation` has already
+        // descended into it.
+        /** @type {Dir} */
+        const root = { docs: { 'index.html': [vec8(0x41n)] } }
+        const [, result] = virtual({ ...emptyState, root })(stat('docs'))
+        assert(result[0] === 'ok', result)
+        assertEq(result[1].isFile, false)
+    },
+    statOnEmptyPath: () => {
+        // An empty path is not the root, though `parse` collapses both to no
+        // segments at all. A host answers `ENOENT`, so this does.
+        const [, result] = virtual(emptyState)(stat(''))
+        assert(result[0] === 'error', result)
+        assertIoCode(result[1], 'ENOENT')
+        // `.` *is* the root, and stats as the directory it is.
+        const [, root] = virtual(emptyState)(stat('.'))
+        assert(root[0] === 'ok', root)
+        assertEq(root[1].isFile, false)
+    },
     statOnJsModule: () => {
-        // stat on a JsModule entry (neither an array nor a descendable
-        // directory) covers the !Array.isArray(file) branch of statOp.
+        // A `JsModule` entry is this file system's non-regular name: it exists
+        // and stats fine, and says it is not a file — the shape a host reports
+        // for a FIFO or a device, and what a caller's guard against reading one
+        // has to be able to see.
         /** @type {Dir} */
         const root = { 'a.f.ts': () => ({}) }
         const [, result] = virtual({ ...emptyState, root })(stat('a.f.ts'))
-        assert(result[0] === 'error')
-        assertIoMessage(result[1], `'a.f.ts' is not a file`)
+        assert(result[0] === 'ok', result)
+        assertEq(result[1].isFile, false)
+        assertEq(result[1].size, 0)
     },
     largeFileReadBytes: () => {
         // A file stored as two 128 KiB chunks is larger than maxLengthBytes.
@@ -416,4 +463,181 @@ export const proof = {
         const [, result] = virtual({ ...emptyState, root })(readBytes('large', chunkSize, 1))
         assert(result[0] === 'ok')
     },
+    // A server without a socket: `createServer` stores the listener and
+    // `listen` hands it the requests the fixture queued, which is what makes a
+    // request-in / response-out proof possible here at all.
+    http: {
+        answersQueuedRequests: () => {
+            /** @type {(url: string) => IncomingMessage} */
+            const get = url => ({ method: 'GET', url, headers: {}, body: empty })
+            /** @type {RequestListener<never>} */
+            const listener = ({ url }) =>
+                pureOk({ status: 200, headers: {}, body: utf8(`echo ${url}`) })
+            const e = step(createServer(listener), server => listen(server, 8080, '127.0.0.1'))
+            /** @type {State} */
+            const state = { ...emptyState, requests: [get('/a'), get('/b')] }
+            const [s, result] = virtual(state)(e)
+            assert(result[0] === 'ok', result)
+            assertEq(s.listening.map(b => b.address).join(), '127.0.0.1:8080')
+            // The queue is emptied, so a second `listen` cannot answer the same
+            // request twice.
+            assertEq(s.requests.length, 0)
+            assertEq(s.responses.map(r => utf8ToString(r.body)).join(', '), 'echo /a, echo /b')
+        },
+        // Two servers in one program are two servers here, as they are on a
+        // host: `listen` answers with the listener its *handle* carries, not
+        // with whichever was created last.
+        dispatchesThroughTheHandle: () => {
+            /** @type {(name: string) => RequestListener<never>} */
+            const named = name => () => pureOk({ status: 200, headers: {}, body: utf8(name) })
+            // Flat, because the third link needs the *first* one's value: a
+            // history carries `a` forward instead of a nested continuation
+            // closing over it.
+            const created = history(createServer(named('a')))
+            const both = historyStep(created, () => createServer(named('b')))
+            const first = step(both, ([, a]) => listen(a, 8080, '127.0.0.1'))
+            /** @type {State} */
+            const state = {
+                ...emptyState,
+                requests: [{ method: 'GET', url: '/', headers: {}, body: empty }],
+            }
+            const [s, result] = virtual(state)(first)
+            assert(result[0] === 'ok', result)
+            assertEq(utf8ToString(s.responses[0].body), 'a')
+        },
+        // A port a host would refuse is refused here, or a program that cannot
+        // run anywhere could still be proven.
+        badPort: () => {
+            /** @type {RequestListener<never>} */
+            const listener = () => pureOk({ status: 200, headers: {}, body: empty })
+            /** @type {(port: number) => void} */
+            const rejects = port => {
+                const e = step(createServer(listener), server => listen(server, port, '127.0.0.1'))
+                const [s, result] = virtual(emptyState)(e)
+                assert(result[0] === 'error', result)
+                assertIoCode(result[1], 'ERR_SOCKET_BAD_PORT')
+                // The message is Node's own, type and all — the shape is the
+                // claim this runner makes.
+                assertIoMessage(
+                    result[1],
+                    `options.port should be >= 0 and < 65536. Received type number (${port}).`)
+                assertEq(s.listening.length, 0)
+            }
+            rejects(-1)
+            rejects(1.5)
+            rejects(65536)
+            rejects(NaN)
+        },
+        // Port `0` names no port: two servers asking the host for a free one
+        // both get one, so refusing the second would reject a program that runs.
+        ephemeralPorts: () => {
+            /** @type {RequestListener<never>} */
+            const listener = () => pureOk({ status: 200, headers: {}, body: empty })
+            const first = history(createServer(listener))
+            const second = historyStep(first, () => createServer(listener))
+            const bound = historyStep(second, b => listen(b, 0, '127.0.0.1'))
+            const e = step(bound, ([, , a]) => listen(a, 0, '127.0.0.1'))
+            const [s, result] = virtual(emptyState)(e)
+            assert(result[0] === 'ok', result)
+            assertEq(s.listening.length, 2)
+        },
+        // Binding fails here the way it fails on a host, which is the whole
+        // point of `Listen` being fallible: a program that mishandles either
+        // failure must not look correct against this runner.
+        addressInUse: () => {
+            /** @type {RequestListener<never>} */
+            const listener = () => pureOk({ status: 200, headers: {}, body: empty })
+            const first = history(createServer(listener))
+            const second = historyStep(first, () => createServer(listener))
+            // `historyStep` spreads the history over its continuation, newest
+            // first: `b` here is the second server, and `a` the first.
+            const bound = historyStep(second, b => listen(b, 8080, '127.0.0.1'))
+            const e = step(bound, ([, , a]) => listen(a, 8080, '127.0.0.1'))
+            const [s, result] = virtual(emptyState)(e)
+            assert(result[0] === 'error', result)
+            assertIoCode(result[1], 'EADDRINUSE')
+            // The first server keeps the address it took.
+            assertEq(s.listening.length, 1)
+        },
+        // A DNS name is case-insensitive, so `LOCALHOST` takes the address
+        // `localhost` then asks for — checked on Linux with Node 22.22.2 and on
+        // Darwin with Node 23.11.0, where the second bind is `EADDRINUSE`.
+        addressInUseIgnoresCase: () => {
+            /** @type {RequestListener<never>} */
+            const listener = () => pureOk({ status: 200, headers: {}, body: empty })
+            const first = history(createServer(listener))
+            const second = historyStep(first, () => createServer(listener))
+            const bound = historyStep(second, b => listen(b, 8080, 'LOCALHOST'))
+            const e = step(bound, ([, , a]) => listen(a, 8080, 'localhost'))
+            const [s, result] = virtual(emptyState)(e)
+            assert(result[0] === 'error', result)
+            assertIoCode(result[1], 'EADDRINUSE')
+            assertIoMessage(
+                result[1],
+                'listen EADDRINUSE: address already in use localhost:8080')
+            // Recorded lower-cased, whichever case asked for it.
+            assertEq(s.listening.length, 1)
+            assertEq(s.listening[0].address, 'localhost:8080')
+        },
+        // `''` is the host a program did not state, and Node binds every
+        // interface for it — so both runners refuse it rather than forward it.
+        emptyHostRefused: () => {
+            /** @type {RequestListener<never>} */
+            const listener = () => pureOk({ status: 200, headers: {}, body: empty })
+            const created = history(createServer(listener))
+            const e = step(created, ([server]) => listen(server, 8080, ''))
+            const [s, result] = virtual(emptyState)(e)
+            assert(result[0] === 'error', result)
+            assertIoCode(result[1], 'ERR_INVALID_ARG_VALUE')
+            assertIoMessage(
+                result[1],
+                `The argument 'host' must not be empty. Received ''`)
+            // Nothing bound.
+            assertEq(s.listening.length, 0)
+        },
+        // And it is refused *first*: a server already listening, retried with
+        // an empty host, names the host and not the state. Node has no order of
+        // its own to copy here — it binds `''` — so the two runners have only
+        // to agree, and the Node runner asks this before it touches the socket.
+        emptyHostBeatsAlreadyListening: () => {
+            /** @type {RequestListener<never>} */
+            const listener = () => pureOk({ status: 200, headers: {}, body: empty })
+            const created = history(createServer(listener))
+            const bound = historyStep(created, server => listen(server, 8080, '127.0.0.1'))
+            const e = step(bound, ([, server]) => listen(server, 9090, ''))
+            const [, result] = virtual(emptyState)(e)
+            assert(result[0] === 'error', result)
+            assertIoCode(result[1], 'ERR_INVALID_ARG_VALUE')
+        },
+        alreadyListening: () => {
+            /** @type {RequestListener<never>} */
+            const listener = () => pureOk({ status: 200, headers: {}, body: empty })
+            /** @type {(second: number) => IoChannel} */
+            const again = second => {
+                const created = history(createServer(listener))
+                const bound = historyStep(created, server => listen(server, 8080, '127.0.0.1'))
+                const e = step(bound, ([, server]) => listen(server, second, '127.0.0.1'))
+                const [, result] = virtual(emptyState)(e)
+                assert(result[0] === 'error', result)
+                return result[1]
+            }
+            assertIoCode(again(9090), 'ERR_SERVER_ALREADY_LISTEN')
+            // And it is asked before the port is: a server already listening
+            // reports this for a port no server could take, where the same
+            // value on a fresh server is `ERR_SOCKET_BAD_PORT`. That is the
+            // order Node asks in, checked on Linux with Node 22.22.2 and on
+            // Darwin with Node 23.11.0.
+            assertIoCode(again(-1), 'ERR_SERVER_ALREADY_LISTEN')
+            assertIoCode(again(65536), 'ERR_SERVER_ALREADY_LISTEN')
+            assertIoCode(again(NaN), 'ERR_SERVER_ALREADY_LISTEN')
+        },
+        // `forever` is the operation this runner cannot answer — its result
+        // type leaves it nothing but `notImplemented` to return — so a server
+        // program run here ends where it would otherwise have blocked.
+        foreverIsNotImplemented: () => {
+            const [, result] = virtual(emptyState)(forever())
+            assert(result[0] === 'error', result)
+            assertEq(result[1][1], 'forever')
+        },
+    },
 }

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

@@ -5,7 +5,8 @@
  * @module
  */
 import type { Vec } from '../../../types/bit_vec/types.ts';
-import type { Module } from '../types.ts';
+import type { Effect } from '../../types.ts';
+import type { IncomingMessage, Module, NodeOp, ServerResponse } from '../types.ts';
 /**
  * In-memory JS module entry. When `import_` is called on the path, the
  * function is invoked and its return value is the module value (with a
@@ -20,6 +21,48 @@ export type _Entity = readonly Vec[] | Dir | JsModule;
 export type Dir = {
     readonly [name in string]?: _Entity;
 };
+/**
+ * The listener a virtual `Server` handle carries, at the operation set this
+ * runner can actually run it with. `CreateServer` declares its listener over
+ * `Operation` — an unresolved type parameter would leak into every consumer of
+ * `Server` — so the handler narrows it, exactly as the Node runner does before
+ * handing a request to it. It rides in the handle rather than in the state, so
+ * that two servers in one program are two servers here too.
+ *
+ * @internal
+ */
+export type _VirtualListener = (request: IncomingMessage) => Effect<NodeOp, ServerResponse, never>;
+/**
+ * What a virtual `Server` handle carries.
+ *
+ * It is a record rather than the listener itself so that each `createServer`
+ * gets its own identity: on a host, creating two servers from one listener
+ * gives two servers, and a handle that *was* the listener would make them the
+ * same one — which `listen` would then read as the same server listening twice.
+ *
+ * @internal
+ */
+export type _VirtualServer = {
+    readonly listener: _VirtualListener;
+};
+/**
+ * A server that is listening, and the address it took.
+ *
+ * The *server* is what is recorded, not its listener: two servers built from one
+ * listener are two servers, and only the second `listen` on the same **server**
+ * is the one Node refuses as already listening.
+ *
+ * @internal
+ */
+export type _Binding = {
+    /**
+     * `host:port`, with the host lower-cased — a name is case-insensitive, and
+     * so is the hexadecimal of an IPv6 literal, so `LOCALHOST` and `localhost`
+     * are one address here as they are on a host.
+     */
+    readonly address: string;
+    readonly server: _VirtualServer;
+};
 export type State = {
     stdout: string;
     stderr: string;
@@ -36,4 +79,17 @@ export type State = {
     };
     /** Monotonically increasing counter returned by `randomInt`; starts at 0. */
     randomNext: number;
+    /**
+     * What is listening, oldest first. An address appears once: a second
+     * `listen` on one that is taken fails, as it does on a host.
+     */
+    listening: readonly _Binding[];
+    /**
+     * The requests a fixture queues for the server to answer. `listen` delivers
+     * every one of them to the {@link _VirtualListener} its handle carries, and
+     * empties the queue — the virtual counterpart of accepting connections.
+     */
+    requests: readonly IncomingMessage[];
+    /** What the listener answered, oldest first. */
+    responses: readonly ServerResponse[];
 };

package/fjs/emergent_testing/browser/proof.d.mts

@@ -0,0 +1,55 @@
+/**
+ * Proofs for the browser runner.
+ *
+ * The runner reaches the page only through the root element it is handed, so
+ * the DOM stand-in below is enough to drive every rendering branch from Node —
+ * no headless browser, and no global `window`/`document` for these proofs to
+ * install and unset.
+ */
+export type _Element = {
+    readonly tag: string;
+    readonly attributes: Map<string, string>;
+    readonly ownerDocument: _Document;
+    textContent: string;
+    children: readonly _Element[];
+    readonly setAttribute: (name: string, value: string) => void;
+    readonly querySelector: (selector: string) => _Element | null;
+    readonly replaceChildren: (...nodes: readonly _Element[]) => void;
+    readonly append: (node: _Element) => void;
+};
+export type _Document = {
+    defaultView: _View | null;
+    readonly createElement: (tag: string) => _Element;
+};
+export type _View = {
+    events: readonly CustomEvent[];
+    readonly dispatchEvent: (event: Event) => boolean;
+    fjsBrowserTestReport?: Promise<unknown>;
+};
+export declare const proof: {
+    namedThrow: () => Promise<void>;
+    path: () => Promise<void>;
+    arbitraryThrow: () => Promise<void>;
+    errorFields: () => Promise<void>;
+    errorAccessorThrows: () => Promise<void>;
+    revokedErrorProxy: () => Promise<void>;
+    crossRealmError: () => Promise<void>;
+    errorWithoutStack: () => Promise<void>;
+    expectedThrow: () => Promise<void>;
+    crossRealmPromise: () => Promise<void>;
+    spoofedPromiseTag: () => Promise<void>;
+    frozenPromiseTag: () => Promise<void>;
+    exportedTreeThrows: () => Promise<void>;
+    returnedTreeThrows: () => Promise<void>;
+    speciesResultIsNotAPromise: () => Promise<void>;
+    reportingThrows: () => Promise<void>;
+    thenIsATestName: () => Promise<void>;
+    batches: () => Promise<void>;
+    render: () => Promise<void>;
+    renderWithoutView: () => Promise<void>;
+    renderReport: () => void;
+    sources: () => Promise<void>;
+    sourcesProgress: () => Promise<void>;
+    sourcesImporterThrows: () => Promise<void>;
+    sourcesLoadFailure: () => Promise<void>;
+};