asljs-appbase 0.0.0-stage → 0.1.4

package/dist/server.d.ts

@@ -0,0 +1,152 @@
+import { type Logger } from 'asljs-logging';
+import { IncomingMessage, Server, ServerResponse } from 'node:http';
+import { type BrowserModule } from './browser-modules.js';
+/**
+ * The first port `startServer` tries without a port.
+ */
+export declare const DEFAULT_PORT = 3000;
+/**
+ * Answers a request by its URL, whose path is relative to where the handler
+ * is mounted: `/` is the handler's own root.
+ */
+export type RequestHandler = (request: IncomingMessage, response: ServerResponse, url: URL) => Promise<void>;
+export interface ServerOptions {
+    /**
+     * The folder whose files the server serves.
+     */
+    folder: string;
+    /**
+     * The HTML of `/`, made again on every request, e.g. the page of a viewer
+     * that loads its data; `/` is not found without it.
+     */
+    index?: () => Promise<string>;
+    /**
+     * The port to listen on, exactly; 0 picks a free one. When absent, the
+     * first free port from `DEFAULT_PORT` on.
+     */
+    port?: number;
+    host?: string;
+    /**
+     * Values sent as JSON, by path, e.g. `/_/data.json`: the value for the
+     * request URL, with its query, or a `jsonReply` for another status.
+     */
+    json?: Readonly<Record<string, (url: URL) => Promise<unknown>>>;
+    /**
+     * The request methods answered, e.g. `[ 'GET', 'HEAD' ]`; any other is
+     * refused with 405. All by default.
+     */
+    methods?: readonly string[];
+    /**
+     * The extensions of the module files served, e.g. `[ '.js', '.mjs' ]`;
+     * every file of a known type by default.
+     */
+    moduleTypes?: readonly string[];
+    /**
+     * Answers a `POST` with a JSON body, by the request URL and the parsed
+     * body: the status, and the value sent back as JSON. Without it, a `POST`
+     * is not found. A `POST` is answered only when its `Content-Type` is
+     * `application/json`, it was sent to the server by a local name, and, when
+     * it has an `Origin`, from a page of the server itself; any other is
+     * refused, so that another site cannot use it.
+     */
+    post?: (url: URL, body: unknown) => Promise<PostReply>;
+    /**
+     * Packages served under `MODULES_PREFIX`, for pages that import them through
+     * the import map `createImportMap(modules, MODULES_PREFIX)` gives; see
+     * `findBrowserModules`.
+     */
+    modules?: readonly BrowserModule[];
+    /**
+     * Whether a file may be served, by its path relative to `folder` with `/`
+     * separators; any file by default. A file it refuses is not found.
+     */
+    allow?: (relative: string) => boolean;
+    /**
+     * Where the server logs that it listens, at `information`, each request, at
+     * `trace`, and a request that failed, at `error`; nothing is logged when
+     * absent.
+     */
+    logger?: Logger;
+}
+/**
+ * What `createHandler` takes: the options of `startServer` without where it
+ * listens.
+ */
+export type HandlerOptions = Omit<ServerOptions, 'port' | 'logger'>;
+/**
+ * Where `serve` listens, and where it logs.
+ */
+export type ListenOptions = Pick<ServerOptions, 'port' | 'host' | 'logger'>;
+/**
+ * The answer to a `POST`: its status, and the value sent back as JSON.
+ */
+export interface PostReply {
+    status: number;
+    body: unknown;
+}
+/**
+ * The reply to a save of a document that changed since its editor read it.
+ */
+export declare function versionConflict(): PostReply;
+/**
+ * Starts a web server for a folder: `/` is `index`, a path of `json` that
+ * value, and a file of the folder is served as it is, a `.md` file as its
+ * markdown text; nothing outside the folder, or that `allow` refuses, is
+ * served. The server sends data, never a rendering of it: rendering is the
+ * page's. Returns once it listens.
+ */
+export declare function startServer(options: ServerOptions): Promise<Server>;
+/**
+ * The handler of `startServer`, for a folder, to mount it with
+ * `mountHandlers` or to serve it with `serve`.
+ */
+export declare function createHandler(options: HandlerOptions): RequestHandler;
+/**
+ * A handler that passes a request whose path starts with `/<name>/` to the
+ * handler of `name` in `mounts`, with the path relative to it, and redirects
+ * `/<name>` to `/<name>/`. Any other request goes to `fallback`, or is not
+ * found.
+ */
+export declare function mountHandlers(mounts: Readonly<Record<string, RequestHandler>>, fallback?: RequestHandler): RequestHandler;
+/**
+ * Starts a web server that answers every request with `handler`. Returns
+ * once it listens.
+ */
+export declare function serve(handler: RequestHandler, options?: ListenOptions): Promise<Server>;
+/**
+ * Resolves once the server has closed. The first of `signals` closes it: it
+ * stops accepting connections and drops the open ones, so that whoever waits
+ * can release what the server used, such as a logger, before the process
+ * exits.
+ */
+export declare function untilStopped(server: Server, signals?: readonly NodeJS.Signals[]): Promise<void>;
+/**
+ * The address a server listens on, e.g. `http://127.0.0.1:3000/`.
+ */
+export declare function serverUrl(server: Server): string;
+/**
+ * An HTML page with the shared style and `style`.
+ */
+export declare function page(title: string, body: string, style?: string): string;
+declare const JSON_REPLY: unique symbol;
+/**
+ * A value of a `json` route with a status other than 200.
+ */
+export interface JsonReply extends PostReply {
+    [JSON_REPLY]: true;
+}
+/**
+ * What a `json` route answers with a status other than 200, e.g. 422 with
+ * the error.
+ */
+export declare function jsonReply(status: number, body: unknown): JsonReply;
+/**
+ * JSON that is safe inside a `<script>` element.
+ */
+export declare function scriptJson(value: unknown): string;
+export declare function escapeHtml(text: string): string;
+/**
+ * Answers with `status` and `body`.
+ */
+export declare function send(response: ServerResponse, status: number, contentType: string, body: string | Buffer): void;
+export {};

package/dist/server.js

@@ -0,0 +1,354 @@
+import { NullLogger } from 'asljs-logging';
+import { once } from 'node:events';
+import { readFile, stat } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import path from 'node:path';
+import { findModuleFile, MODULES_PREFIX } from './browser-modules.js';
+/**
+ * The first port `startServer` tries without a port.
+ */
+export const DEFAULT_PORT = 3000;
+/**
+ * How many ports from `DEFAULT_PORT` on `startServer` tries.
+ */
+const PORT_ATTEMPTS = 100;
+/**
+ * The largest body a `POST` may have, in bytes.
+ */
+const MAX_POST_BYTES = 10 * 1024 * 1024;
+const CONTENT_TYPES = new Map([['.css',
+        'text/css; charset=utf-8'],
+    ['.gif',
+        'image/gif'],
+    ['.jpeg',
+        'image/jpeg'],
+    ['.jpg',
+        'image/jpeg'],
+    ['.js',
+        'text/javascript; charset=utf-8'],
+    ['.json',
+        'application/json; charset=utf-8'],
+    ['.map',
+        'application/json; charset=utf-8'],
+    ['.md',
+        'text/markdown; charset=utf-8'],
+    ['.mjs',
+        'text/javascript; charset=utf-8'],
+    ['.pdf',
+        'application/pdf'],
+    ['.png',
+        'image/png'],
+    ['.svg',
+        'image/svg+xml'],
+    ['.txt',
+        'text/plain; charset=utf-8']]);
+const STYLE = `body { font-family: system-ui, sans-serif; max-width: 960px; margin: 2rem auto; padding: 0 1rem; line-height: 1.5; }
+pre { overflow-x: auto; }
+pre:not(.mermaid) { background: #f4f4f4; padding: 0.75rem; }
+code { font-family: ui-monospace, monospace; }`;
+/**
+ * The reply to a save of a document that changed since its editor read it.
+ */
+export function versionConflict() {
+    return { status: 409,
+        body: { error: 'The document changed since the editor opened it; copy your text, reload the page and edit again.' } };
+}
+/**
+ * Starts a web server for a folder: `/` is `index`, a path of `json` that
+ * value, and a file of the folder is served as it is, a `.md` file as its
+ * markdown text; nothing outside the folder, or that `allow` refuses, is
+ * served. The server sends data, never a rendering of it: rendering is the
+ * page's. Returns once it listens.
+ */
+export async function startServer(options) {
+    return await serve(createHandler(options), options);
+}
+/**
+ * The handler of `startServer`, for a folder, to mount it with
+ * `mountHandlers` or to serve it with `serve`.
+ */
+export function createHandler(options) {
+    return async (request, response, url) => await handle(options, request, response, url);
+}
+/**
+ * A handler that passes a request whose path starts with `/<name>/` to the
+ * handler of `name` in `mounts`, with the path relative to it, and redirects
+ * `/<name>` to `/<name>/`. Any other request goes to `fallback`, or is not
+ * found.
+ */
+export function mountHandlers(mounts, fallback) {
+    return async (request, response, url) => {
+        const match = /^\/([^/]+)(\/.*)?$/.exec(url.pathname);
+        const name = match === null
+            ? undefined
+            : decodeURIComponent(match[1]);
+        if (name !== undefined
+            && Object.hasOwn(mounts, name)) {
+            if (match[2] === undefined) {
+                response.writeHead(302, { location: `${url.pathname}/${url.search}` });
+                response.end();
+                return;
+            }
+            const inner = new URL(url);
+            inner.pathname = match[2];
+            await mounts[name](request, response, inner);
+            return;
+        }
+        if (fallback !== undefined) {
+            await fallback(request, response, url);
+            return;
+        }
+        send(response, 404, 'text/plain; charset=utf-8', `Not found: ${url.pathname}`);
+    };
+}
+/**
+ * Starts a web server that answers every request with `handler`. Returns
+ * once it listens.
+ */
+export async function serve(handler, options = {}) {
+    const logger = options.logger ?? new NullLogger();
+    const server = createServer((request, response) => {
+        logger.trace({ method: request.method,
+            url: request.url }, 'request');
+        handler(request, response, new URL(request.url ?? '/', 'http://localhost'))
+            .catch((error) => {
+            logger.error({ err: error,
+                url: request.url }, 'request failed');
+            send(response, 500, 'text/plain; charset=utf-8', error instanceof Error
+                ? error.message
+                : String(error));
+        });
+    });
+    const host = options.host ?? '127.0.0.1';
+    if (options.port === undefined) {
+        await listenOnFreePort(server, host);
+    }
+    else {
+        await listen(server, options.port, host);
+    }
+    logger.information({ url: serverUrl(server) }, 'listening');
+    return server;
+}
+/**
+ * Resolves once the server has closed. The first of `signals` closes it: it
+ * stops accepting connections and drops the open ones, so that whoever waits
+ * can release what the server used, such as a logger, before the process
+ * exits.
+ */
+export async function untilStopped(server, signals = ['SIGINT',
+    'SIGTERM']) {
+    const closed = once(server, 'close');
+    const stop = () => {
+        server.close();
+        server.closeAllConnections();
+    };
+    for (const signal of signals) {
+        process.once(signal, stop);
+    }
+    try {
+        await closed;
+    }
+    finally {
+        for (const signal of signals) {
+            process.off(signal, stop);
+        }
+    }
+}
+/**
+ * The address a server listens on, e.g. `http://127.0.0.1:3000/`.
+ */
+export function serverUrl(server) {
+    const address = server.address();
+    const host = address.family === 'IPv6'
+        ? `[${address.address}]`
+        : address.address;
+    return `http://${host}:${address.port}/`;
+}
+/**
+ * An HTML page with the shared style and `style`.
+ */
+export function page(title, body, style = '') {
+    return `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>
+${STYLE}
+${style}
+</style>
+</head>
+<body>
+${body}
+</body>
+</html>
+`;
+}
+const JSON_REPLY = Symbol('jsonReply');
+/**
+ * What a `json` route answers with a status other than 200, e.g. 422 with
+ * the error.
+ */
+export function jsonReply(status, body) {
+    return { [JSON_REPLY]: true,
+        status,
+        body };
+}
+function isJsonReply(value) {
+    return typeof value === 'object'
+        && value !== null
+        && JSON_REPLY in value;
+}
+/**
+ * JSON that is safe inside a `<script>` element.
+ */
+export function scriptJson(value) {
+    return JSON.stringify(value)
+        .replace(/</g, '\\u003c');
+}
+export function escapeHtml(text) {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+function listen(server, port, host) {
+    return new Promise((resolve, reject) => {
+        const fail = (error) => reject(error);
+        server.once('error', fail);
+        server.listen(port, host, () => {
+            server.off('error', fail);
+            resolve();
+        });
+    });
+}
+/**
+ * Listens on the first port from `DEFAULT_PORT` on that is not in use.
+ */
+async function listenOnFreePort(server, host) {
+    for (let offset = 0; offset < PORT_ATTEMPTS; offset += 1) {
+        try {
+            await listen(server, DEFAULT_PORT + offset, host);
+            return;
+        }
+        catch (error) {
+            if (error.code
+                !== 'EADDRINUSE') {
+                throw error;
+            }
+        }
+    }
+    throw new Error(`No free port from ${DEFAULT_PORT} to ${DEFAULT_PORT + PORT_ATTEMPTS - 1}; give one with --port.`);
+}
+async function handle(options, request, response, url) {
+    const pathname = decodeURIComponent(url.pathname);
+    if (options.methods !== undefined
+        && !options.methods.includes(request.method ?? 'GET')) {
+        response.writeHead(405, { 'content-type': 'text/plain; charset=utf-8',
+            allow: options.methods.join(', ') });
+        response.end('Method not allowed');
+        return;
+    }
+    if (request.method === 'POST') {
+        await handlePost(options, request, response, url);
+        return;
+    }
+    if (pathname === '/'
+        && options.index !== undefined) {
+        send(response, 200, 'text/html; charset=utf-8', await options.index());
+        return;
+    }
+    if (options.modules !== undefined
+        && pathname.startsWith(MODULES_PREFIX)) {
+        const target = findModuleFile(pathname.slice(MODULES_PREFIX.length), options.modules);
+        const type = target === null
+            || options.moduleTypes !== undefined
+                && !options.moduleTypes.includes(path.extname(target).toLowerCase())
+            ? undefined
+            : CONTENT_TYPES.get(path.extname(target).toLowerCase());
+        if (target !== null
+            && type !== undefined
+            && (await stat(target).catch(() => null))?.isFile()) {
+            send(response, 200, type, await readFile(target));
+        }
+        else {
+            send(response, 404, 'text/plain; charset=utf-8', `Not found: ${pathname}`);
+        }
+        return;
+    }
+    const valueOf = options.json !== undefined
+        && Object.hasOwn(options.json, pathname)
+        ? options.json[pathname]
+        : undefined;
+    if (valueOf !== undefined) {
+        const value = await valueOf(url);
+        const reply = isJsonReply(value)
+            ? value
+            : { status: 200,
+                body: value };
+        send(response, reply.status, 'application/json; charset=utf-8', JSON.stringify(reply.body));
+        return;
+    }
+    const file = path.resolve(options.folder, `.${pathname}`);
+    const relative = path.relative(options.folder, file);
+    if (relative.startsWith('..')
+        || path.isAbsolute(relative)
+        || options.allow?.(relative.split(path.sep).join('/'))
+            === false
+        || !(await stat(file).catch(() => null))?.isFile()) {
+        send(response, 404, 'text/plain; charset=utf-8', `Not found: ${pathname}`);
+        return;
+    }
+    send(response, 200, CONTENT_TYPES.get(path.extname(file).toLowerCase())
+        ?? 'application/octet-stream', await readFile(file));
+}
+async function handlePost(options, request, response, url) {
+    if (options.post === undefined) {
+        send(response, 404, 'text/plain; charset=utf-8', `Not found: ${url.pathname}`);
+        return;
+    }
+    const host = request.headers.host ?? '';
+    const hostname = new URL(`http://${host}`).hostname;
+    const origin = request.headers.origin;
+    if (!/^application\/json(?:;|$)/i.test(request.headers['content-type'] ?? '')
+        || !['localhost',
+            '127.0.0.1',
+            '[::1]',
+            options.host ?? '127.0.0.1']
+            .includes(hostname)
+        || origin !== undefined
+            && origin !== `http://${host}`) {
+        send(response, 403, 'text/plain; charset=utf-8', 'Forbidden');
+        return;
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > MAX_POST_BYTES) {
+            send(response, 413, 'text/plain; charset=utf-8', 'The body is too large.');
+            return;
+        }
+        chunks.push(chunk);
+    }
+    let body;
+    try {
+        body =
+            JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        send(response, 400, 'text/plain; charset=utf-8', 'The body is not JSON.');
+        return;
+    }
+    const reply = await options.post(url, body);
+    send(response, reply.status, 'application/json; charset=utf-8', JSON.stringify(reply.body));
+}
+/**
+ * Answers with `status` and `body`.
+ */
+export function send(response, status, contentType, body) {
+    response.writeHead(status, { 'content-type': contentType });
+    response.end(body);
+}

package/dist/state-folder.d.ts

@@ -0,0 +1,20 @@
+import { type Config } from 'asljs-cmdbase';
+/**
+ * A state folder given on the command line: the option, else the variable,
+ * e.g. `KB_STATE_DIR`, both resolving against `cwd`. A service gives none:
+ * its projects are configured by their own files.
+ */
+export interface GivenStateFolder {
+    option?: string;
+    variable?: string;
+    env?: Readonly<Record<string, string | undefined>>;
+    cwd: string;
+}
+/**
+ * The folder where application `app` keeps what it stores between runs for
+ * the project in `folder`: the one `given` names, else `stateDir` of
+ * `config`, against the folder of the file, else `.<app>` in `folder`, e.g.
+ * `.kb`. Every application keeps its state in such a folder, which a
+ * project's `.gitignore` leaves out.
+ */
+export declare function stateFolder(folder: string, app: string, config: Config, given?: GivenStateFolder): string;

package/dist/state-folder.js

@@ -0,0 +1,21 @@
+import { configPath } from 'asljs-cmdbase';
+import path from 'node:path';
+/**
+ * The folder where application `app` keeps what it stores between runs for
+ * the project in `folder`: the one `given` names, else `stateDir` of
+ * `config`, against the folder of the file, else `.<app>` in `folder`, e.g.
+ * `.kb`. Every application keeps its state in such a folder, which a
+ * project's `.gitignore` leaves out.
+ */
+export function stateFolder(folder, app, config, given) {
+    const named = given?.option
+        || (given?.variable === undefined
+            ? undefined
+            : given.env?.[given.variable])
+        || undefined;
+    if (named !== undefined) {
+        return path.resolve(given.cwd, named);
+    }
+    return configPath(config, 'stateDir')
+        ?? path.join(path.resolve(folder), `.${app}`);
+}