functionalscript 0.46.0 → 0.47.0

package/fjs/types/ts/types.d.ts

@@ -5,6 +5,10 @@
  * @module
  */
 export type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+export type And<A extends boolean, B extends boolean> = [
+    A,
+    B
+] extends [true, true] ? true : false;
 /**
  * A `struct` field: the key, its type expression, and — when the third
  * element is `true` — an optional-key marker (`"key"?: type`).

package/fjs/web/module.f.d.mts

@@ -0,0 +1,115 @@
+/**
+ * A static file server: `fjs web [root] [port]` maps each request path to a
+ * file under `root` and answers with its bytes.
+ *
+ * The module is split so that the decision is pure and the socket handling is a
+ * thin shell around it. `resolve` turns a URL into a path and does every check
+ * that can be made without touching the disk; `respond` reads the file that
+ * path names and builds the response frame, performing IO but no networking;
+ * `main` is the only part that creates a server, listens, and blocks. That is
+ * why `respond` can be proven end to end against an in-memory file system.
+ *
+ * ## Responses
+ *
+ * | case                                          | status |
+ * |-----------------------------------------------|--------|
+ * | file found                                     | `200`  |
+ * | `GET`/`HEAD` on a missing, dot-prefixed, or non-regular path | `404` |
+ * | any other method                               | `405` with `Allow` |
+ * | a `Host` this server does not answer for       | `403`  |
+ * | a path that escapes `root`, or an undecodable URL | `400`  |
+ * | a file larger than one `Vec`                   | `413`  |
+ * | any other host failure                         | `500`  |
+ *
+ * Failures carry a `text/plain` body. Nothing else is configurable in this
+ * version — no directory listing, no range requests, no compression, no caching
+ * headers, no TLS.
+ *
+ * See `./README.md` for what is deliberately absent, and `./types.ts` for the
+ * type-level API.
+ *
+ * @module
+ *
+ * @import { Effect } from '../effects/types.ts'
+ * @import { FileStat, IoChannel, Program, ReadFile, ServerResponse } from '../effects/node/types.ts'
+ * @import { Nullable } from '../types/nullable/types.ts'
+ * @import { Result } from '../types/result/types.ts'
+ * @import { Vec } from '../types/bit_vec/types.ts'
+ * @import { Refusal, Resolve, Respond, WebOp } from './types.ts'
+ */
+import type { Program } from '../effects/node/types.ts';
+import type { Nullable } from '../types/nullable/types.ts';
+import type { Resolve, Respond, WebOp } from './types.ts';
+export type _Target = {
+    readonly authority: Nullable<string>;
+    readonly path: string;
+};
+/**
+ * Maps a request URL to a path under `root`, or explains why none exists.
+ *
+ * A directory request — a path ending in `/`, including the bare `/` — is
+ * answered with its `index.html`, which is what makes a generated site browsable
+ * at all.
+ *
+ * An empty `root` is read as the working directory — see {@link served}.
+ *
+ * **Dot-prefixed segments are not served.** `.git/config`, `.env` and
+ * `.ssh/id_rsa` are the files whose exposure the loopback binding exists to
+ * prevent, and a static server that hands them to anyone who asks has the
+ * boundary in the wrong place. The answer is `404` rather than `403`: whether
+ * such a file exists is itself the thing not being disclosed.
+ *
+ * **A NUL is a malformed URL, not a host error.** `%00` decodes to a byte no
+ * path can contain; left to the file system it comes back as an
+ * `ERR_INVALID_ARG_VALUE` and a `500`, reporting a host failure for what is
+ * plainly a bad request.
+ *
+ * **Traversal is rejected in segment space, not by string comparison.**
+ * `escapes` folds the path with its root taken off, so a `..` with nothing left
+ * to cancel survives to be counted; that is the whole check. `parse` cannot
+ * answer it — `parse` folds *with* the root in place, and clamping away such a
+ * `..` is precisely what it does, which is why reading its output for one
+ * silently stopped working. Nor is taking the root off the same as dropping a
+ * leading `/`: the remainder of `///../x` is `//../x`, which reads as rooted
+ * again, so the question belongs to `fjs/path` rather than to string surgery
+ * here. Comparing the joined path against `root` textually is the weaker test;
+ * it became expressible once `normalize` began keeping roots, and is still not
+ * what is done.
+ *
+ * @type {Resolve}
+ */
+export declare const resolve: Resolve;
+export type _TooLarge = readonly ['tooLarge', number];
+export type _NotRegular = readonly ['notRegular'];
+/**
+ * Answers one request: resolve, read, and frame the result.
+ *
+ * The host is checked first, against the loopback names this server answers for
+ * — see {@link servedHosts} for why binding loopback is not enough on its own.
+ * An absolute-form target names its own host, and RFC 9112 §3.2.2 says to
+ * believe that over the `Host` header.
+ *
+ * `HEAD` is answered exactly like `GET`, bytes included: Node drops the body of
+ * a `HEAD` response itself and keeps the headers, so the one frame serves both
+ * — and because {@link response} states `Content-Length`, a `HEAD` client still
+ * learns the size it asked for.
+ *
+ * @type {Respond}
+ */
+export declare const respond: Respond;
+/**
+ * `fjs web [root] [port]` — serve `root` (default `.`) on `port` (default
+ * `8080`), bound to {@link loopback}.
+ *
+ * Both arguments are positional because `fjs/cli` has no notion of a named
+ * option yet; `port` becomes `--port` once one exists, and `--host` is what
+ * would let a caller bind anything but loopback.
+ *
+ * The chain ends in `forever`, so the program only stops when the process does.
+ * A runner that cannot block forever answers `notImplemented` there, which is
+ * how the whole program remains runnable — and observable — under the virtual
+ * runner.
+ *
+ * @type {Program<WebOp>}
+ */
+export declare const main: Program<WebOp>;