@lakutata/entrypoint 3.0.0-beta.0

package/dist/esm/adapter/electron/ElectronIPCServiceEntrypoint.js

@@ -0,0 +1,212 @@
+import { ServiceContext } from '../../context/ServiceContext.js';
+import { ServiceChannel } from '../../channel/BuiltinChannels.js';
+import { ServiceResponseCodec } from '../../lib/ServiceResponseCodec.js';
+import { EntrypointStoppedException } from '../../exceptions/EntrypointStoppedException.js';
+/**
+ * Get the IPC event of a service action's request, when {@link electronIPCServiceEntrypoint} serves it (to reach the
+ * invoking renderer or frame).
+ * @param context The service action's context (`this.context` in a controller).
+ * @returns The IPC event (Electron's `IpcMainInvokeEvent`, typed as `Event`), or `undefined` when another adapter serves
+ * the request.
+ * @example
+ * ```typescript
+ * import {Controller, ServiceContext} from 'lakutata/com/entrypoint'
+ * import {ipcEventOfContext} from 'lakutata/adapter/electron'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ * import type {IpcMainInvokeEvent} from 'electron'
+ *
+ * class WindowController extends Controller {
+ *     //ipcRenderer.invoke('lakutata:service', {cmd: 'window.url'})
+ *     @ServiceAction({cmd: 'window.url'})
+ *     public async url(): Promise<string | undefined> {
+ *         return ipcEventOfContext<IpcMainInvokeEvent>(this.context as ServiceContext)?.sender.getURL()
+ *     }
+ * }
+ * ```
+ */
+export function ipcEventOfContext(context) {
+    return context.event;
+}
+/**
+ * The ipcMain of the main process of Electron
+ */
+async function loadIPCMain() {
+    let ipcMain;
+    try {
+        //Electron is not a dependency: it is loaded where it runs
+        const electronModule = 'electron';
+        const electron = await import(electronModule);
+        ipcMain = electron.ipcMain ?? electron.default?.ipcMain;
+    }
+    catch {
+        ipcMain = undefined;
+    }
+    if (!ipcMain)
+        throw new Error('electronIPCServiceEntrypoint runs in the main process of Electron (or is given its ipcMain)');
+    return ipcMain;
+}
+/**
+ * Create a service adapter of an entrypoint served over Electron's IPC, in the main process. It needs the optional
+ * peer dependency `electron`: without the `ipcMain` option, the entrypoint fails to start outside Electron's main
+ * process.
+ *
+ * A renderer invokes the channel with the action's pattern and input, and optionally its client id:
+ * `ipcRenderer.invoke('lakutata:service', {cmd: 'echo', text: 'hi'}, clientId)`. The invocation resolves to
+ * `{success, error, payload}` (see `ServiceResponseCodec`): `payload` is the result, or `error` the whole error object
+ * when the action failed (no matching action, validation…).
+ *
+ * Each page is a client, identified by the id it gives (a non-empty string of at most 200 characters), which its
+ * requests carry as `ServiceContext.clientId`. A page registers by sending its id on `<channel>:subscribe` (or with
+ * any invocation giving it); a page reloaded in the same frame replaces its previous id. The events pushed by
+ * `Entrypoint.notify` and `Entrypoint.broadcast` are sent to the page's frame on `<channel>:event` with the event name
+ * and its arguments array. A destroyed renderer drops its clients.
+ *
+ * When a renderer is destroyed, its requests in progress are aborted (their abort signal fires). When the entrypoint
+ * stops, the new invocations resolve to an `EntrypointStoppedException` error; once the requests in progress end, the
+ * IPC handlers are removed.
+ * @param options The adapter options; by default it serves the channel `'lakutata:service'` on Electron's `ipcMain`.
+ * @returns The adapter, to give to the `service` option of `buildEntrypoints`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ * import {electronIPCServiceEntrypoint} from 'lakutata/adapter/electron'
+ * import type {IpcRenderer, IpcRendererEvent} from 'electron'
+ *
+ * class EchoController extends Controller {
+ *     @ServiceAction({cmd: 'echo'})
+ *     public async echo(input: {text: string}): Promise<string> {
+ *         return input.text
+ *     }
+ * }
+ *
+ * //In the main process
+ * Application.run({
+ *     id: 'desktop.app',
+ *     name: 'Desktop',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [EchoController],
+ *             service: electronIPCServiceEntrypoint()
+ *         })
+ *     }
+ * })
+ *
+ * //In the preload script of a window
+ * declare const ipcRenderer: IpcRenderer
+ * const clientId: string = crypto.randomUUID()
+ * //The events pushed by entrypoint.notify(clientId, 'progress', 50)
+ * ipcRenderer.on('lakutata:service:event', (event: IpcRendererEvent, name: string, args: unknown[]): void => console.log(name, ...args))
+ * ipcRenderer.send('lakutata:service:subscribe', clientId)
+ * //{success: true, error: null, payload: 'hi'}
+ * console.log(await ipcRenderer.invoke('lakutata:service', {cmd: 'echo', text: 'hi'}, clientId))
+ * ```
+ */
+export function electronIPCServiceEntrypoint(options = {}) {
+    const channel = options.channel ?? 'lakutata:service';
+    const eventChannel = `${channel}:event`;
+    const subscribeChannel = `${channel}:subscribe`;
+    let ipcMain;
+    let stopping = false;
+    //The clients by their ids, the renderers whose destruction removes their clients
+    const clients = new Map();
+    const watched = new WeakSet();
+    /**
+     * Register the client of a page, by the id it gives (the one of the page loaded: a page loaded again in the main
+     * frame of its window replaces its client); undefined without id
+     * @param event
+     * @param clientId
+     */
+    const register = (event, clientId) => {
+        if (typeof clientId !== 'string' || !clientId || clientId.length > 200)
+            return undefined;
+        if (clients.get(clientId)?.sender === event.sender)
+            return clientId;
+        const frame = event.processId !== undefined && event.frameId !== undefined ? [event.processId, event.frameId] : undefined;
+        const main = !event.senderFrame?.parent;
+        for (const [id, client] of clients) {
+            const sameFrame = !!frame && !!client.frame && client.frame[0] === frame[0] && client.frame[1] === frame[1];
+            if (client.sender === event.sender && (sameFrame || (main && client.main)))
+                clients.delete(id);
+        }
+        clients.set(clientId, { sender: event.sender, frame: frame, main: main });
+        if (!watched.has(event.sender)) {
+            watched.add(event.sender);
+            event.sender.once('destroyed', () => {
+                for (const [id, client] of clients)
+                    if (client.sender === event.sender)
+                        clients.delete(id);
+            });
+        }
+        return clientId;
+    };
+    /**
+     * Send an event to a client, in its frame
+     * @param clientId
+     * @param client
+     * @param event
+     * @param args
+     */
+    const send = (clientId, client, event, args) => {
+        if (client.sender.isDestroyed?.()) {
+            clients.delete(clientId);
+            return false;
+        }
+        if (client.frame && client.sender.sendToFrame)
+            client.sender.sendToFrame(client.frame, eventChannel, event, args);
+        else if (client.sender.send)
+            client.sender.send(eventChannel, event, args);
+        else
+            return false;
+        return true;
+    };
+    return {
+        channel: 'service',
+        definition: ServiceChannel,
+        name: options.name,
+        middlewares: options.middlewares,
+        start: async (runtime) => {
+            ipcMain = options.ipcMain ?? await loadIPCMain();
+            ipcMain.on?.(subscribeChannel, (event, clientId) => register(event, clientId));
+            ipcMain.handle(channel, async (event, data, clientId) => {
+                if (stopping)
+                    return ServiceResponseCodec.encodeError(new EntrypointStoppedException('The entrypoint is stopping'));
+                //The request is aborted when its renderer is destroyed
+                const request = new AbortController();
+                const abort = () => request.abort();
+                event.sender.once('destroyed', abort);
+                try {
+                    const context = new ServiceContext({ data: data && typeof data === 'object' ? data : {}, event: event, clientId: register(event, clientId) });
+                    return ServiceResponseCodec.encode(await runtime.dispatch(context, { signal: request.signal }), false);
+                }
+                catch (error) {
+                    return ServiceResponseCodec.encodeError(error);
+                }
+                finally {
+                    (event.sender.off ?? event.sender.removeListener)?.call(event.sender, 'destroyed', abort);
+                }
+            });
+        },
+        stop: () => {
+            //The new requests are refused, the requests in progress end
+            stopping = true;
+        },
+        close: () => {
+            ipcMain?.removeHandler(channel);
+            ipcMain?.removeAllListeners?.(subscribeChannel);
+            clients.clear();
+        },
+        notify: (clientId, event, args) => {
+            const client = clients.get(clientId);
+            return !!client && send(clientId, client, event, args);
+        },
+        broadcast: (event, args) => {
+            let sent = 0;
+            for (const [clientId, client] of [...clients])
+                if (send(clientId, client, event, args))
+                    sent++;
+            return sent;
+        }
+    };
+}

package/dist/esm/adapter/express/ExpressHTTPEntrypoint.js

@@ -0,0 +1,295 @@
+import express from 'express';
+import { createServer } from 'node:http';
+import path from 'node:path';
+import { HTTPContext } from '../../context/HTTPContext.js';
+import { HTTPChannel } from '../../channel/BuiltinChannels.js';
+import { EventsResult, FileResult, StatusResult } from '../../lib/Result.js';
+import { RouteNotFoundException } from '../../exceptions/RouteNotFoundException.js';
+import { JSONResponder } from './Responders.js';
+/**
+ * The first segments of the routes
+ * @param routes
+ */
+function actionPrefixesOf(routes) {
+    const prefixes = new Set();
+    for (const route of routes) {
+        const segment = route.split('/').find((part) => !!part);
+        //A route starting with a parameter matches every path
+        if (segment && !/^[:*]/.test(segment))
+            prefixes.add(`/${segment}`);
+    }
+    return [...prefixes];
+}
+/**
+ * The data of an event of a stream
+ * @param data
+ * @param event
+ * @param id
+ */
+function eventFrame(data, event, id) {
+    let frame = '';
+    if (id !== undefined)
+        frame += `id: ${id}\n`;
+    if (event !== undefined)
+        frame += `event: ${event}\n`;
+    const text = typeof data === 'string' ? data : JSON.stringify(data);
+    for (const line of text.split(/\r?\n/))
+        frame += `data: ${line}\n`;
+    return `${frame}\n`;
+}
+/**
+ * Create the HTTP adapter of an entrypoint served by an express application: each HTTP action (`@GET`, `@POST`,
+ * `@HTTPAction`…) becomes an express route. It needs the optional peer dependency `express`.
+ *
+ * An action's input is the request's query and body (see the `input` option) with the route parameters merged over
+ * them. Its result is written by the responder (JSON by default, 204 for no result); a `StatusResult` sets the status
+ * and the headers, a `FileResult` sends a file, a buffer or a stream (304 when its ETag matches `If-None-Match`), and an
+ * `EventsResult` streams Server-Sent Events. An action that writes the response itself (through
+ * `HTTPContext.response`) is left alone. The errors are written by the responder with their status (400 for the
+ * validation failures, 500 by default).
+ *
+ * When the client disconnects before the response, the action's abort signal fires and nothing is written. When the
+ * entrypoint stops, the server stops accepting connections, the event streams end, and the requests in progress are
+ * given up to one second after they settle to send their responses before the remaining connections are closed.
+ * @param options The adapter options; by default it listens on port 80 of all the interfaces with a new express
+ * application.
+ * @returns The adapter, to give to the `http` option of `buildEntrypoints`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {GET, POST} from 'lakutata/decorator/ctrl'
+ * import {expressHTTPEntrypoint, staticUI} from 'lakutata/adapter/express'
+ *
+ * class UserController extends Controller {
+ *     //GET /users/1?verbose=true: the route parameter id merged over the query
+ *     @GET('/users/:id')
+ *     public async get(input: {id: string, verbose?: string}): Promise<{id: string}> {
+ *         return {id: input.id}
+ *     }
+ *
+ *     //POST /users with the JSON body {"name": "Ada"}
+ *     @POST('/users')
+ *     public async create(input: {name: string}): Promise<{name: string}> {
+ *         return {name: input.name}
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'web.app',
+ *     name: 'Web',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [UserController],
+ *             http: expressHTTPEntrypoint({
+ *                 port: 8080,
+ *                 body: {limit: '5mb'},
+ *                 //The application's own routes, before the actions
+ *                 before: (app): void => {
+ *                     app.get('/health', (request, response): void => void response.send('ok'))
+ *                 },
+ *                 //The pages of the UI built in ./ui/dist, for the paths outside /users
+ *                 fallback: staticUI('./ui/dist')
+ *             })
+ *         })
+ *     }
+ * })
+ * ```
+ */
+export function expressHTTPEntrypoint(options = {}) {
+    const respond = options.respond ?? JSONResponder;
+    const input = options.input ?? ((request) => ({ ...request.query, ...(request.body && typeof request.body === 'object' ? request.body : {}) }));
+    const streams = new Set();
+    let server;
+    let closed;
+    let stopping = false;
+    //The responses of the actions not sent yet
+    const responding = new Set();
+    /**
+     * Stream the events of a result
+     * @param result
+     * @param request
+     * @param response
+     */
+    const streamEvents = async (result, request, response) => {
+        const abortController = new AbortController();
+        streams.add(abortController);
+        response.status(200).set({
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': 'no-cache, no-transform',
+            'Connection': 'keep-alive',
+            'X-Accel-Buffering': 'no'
+        }).flushHeaders();
+        const heartbeat = setInterval(() => response.write(': ping\n\n'), options.heartbeat ?? 15000);
+        const close = () => abortController.abort();
+        response.on('close', close);
+        try {
+            await result.producer((data, event, id) => {
+                if (!abortController.signal.aborted)
+                    response.write(eventFrame(data, event, id));
+            }, abortController.signal);
+        }
+        catch {
+            //The stream is already started, its error ends it
+        }
+        finally {
+            clearInterval(heartbeat);
+            response.off('close', close);
+            streams.delete(abortController);
+            if (!response.writableEnded)
+                response.end();
+        }
+    };
+    /**
+     * Send a file
+     * @param result
+     * @param request
+     * @param response
+     */
+    const sendFile = async (result, request, response) => {
+        const { contentType, filename, etag, headers } = result.options;
+        if (headers)
+            response.set(headers);
+        if (etag) {
+            response.set('ETag', `"${etag}"`);
+            if (request.headers['if-none-match'] === `"${etag}"`) {
+                response.status(304).end();
+                return;
+            }
+        }
+        if (filename)
+            response.attachment(filename);
+        if (contentType)
+            response.type(contentType);
+        const source = result.source;
+        if (typeof source === 'string') {
+            await new Promise((resolve, reject) => response.sendFile(path.resolve(source), (error) => error ? reject(error) : resolve()));
+        }
+        else if (Buffer.isBuffer(source)) {
+            response.send(source);
+        }
+        else {
+            await new Promise((resolve, reject) => {
+                source.once('error', reject).pipe(response).once('finish', resolve);
+            });
+        }
+    };
+    /**
+     * Write the result of an action
+     * @param result
+     * @param request
+     * @param response
+     */
+    const output = async (result, request, response) => {
+        //The action wrote the response itself
+        if (response.headersSent)
+            return;
+        if (result instanceof EventsResult)
+            return await streamEvents(result, request, response);
+        if (result instanceof FileResult)
+            return await sendFile(result, request, response);
+        if (result instanceof StatusResult) {
+            response.status(result.status).set(result.headers);
+            return respond.success(response, result.data, request);
+        }
+        respond.success(response, result, request);
+    };
+    /**
+     * The handler of the requests of an action
+     * @param runtime
+     * @param action
+     */
+    const actionHandler = (runtime, action) => (request, response) => {
+        const abortController = new AbortController();
+        const responded = new Promise((resolve) => void response.once('close', resolve));
+        responding.add(responded);
+        //The client left before the response was sent
+        response.on('close', () => {
+            responding.delete(responded);
+            if (!response.writableFinished)
+                abortController.abort();
+        });
+        //While the adapter stops, the connections are closed once their response is sent
+        response.on('finish', () => {
+            if (stopping)
+                setImmediate(() => server?.closeIdleConnections());
+        });
+        const dispatch = async () => {
+            const context = new HTTPContext({
+                route: action.address.route,
+                method: action.address.method,
+                request: request,
+                response: response,
+                data: input(request)
+            });
+            const result = await runtime.dispatchTo(action, context, { signal: abortController.signal, params: { ...request.params } });
+            if (!abortController.signal.aborted)
+                await output(result, request, response);
+        };
+        dispatch().catch((error) => {
+            if (!response.headersSent && !abortController.signal.aborted)
+                respond.error(response, error, request, 'action');
+        });
+    };
+    return {
+        channel: 'http',
+        definition: HTTPChannel,
+        name: options.name,
+        middlewares: options.middlewares,
+        start: async (runtime) => {
+            const app = options.app ?? express();
+            server = createServer(options.server ?? {}, app);
+            const routes = new Map();
+            for (const action of runtime.actions)
+                routes.set(action.address.route, (routes.get(action.address.route) ?? new Set()).add(action.address.method));
+            const actionPrefixes = actionPrefixesOf(routes.keys());
+            const isActionPath = (requestPath) => actionPrefixes.some((prefix) => requestPath === prefix || requestPath.startsWith(`${prefix}/`));
+            await options.before?.(app, { module: runtime.module, server: server, routes: routes, actionPrefixes: actionPrefixes, isActionPath: isActionPath });
+            if (options.body !== false)
+                app.use(express.json({ limit: options.body?.limit ?? '1mb' }), express.urlencoded({ extended: true, limit: options.body?.limit ?? '1mb' }));
+            for (const action of runtime.actions) {
+                const method = String(action.address.method).toLowerCase();
+                const register = app[method];
+                if (typeof register !== 'function')
+                    throw new TypeError(`Unsupported HTTP method "${action.address.method}" of the route "${action.address.route}"`);
+                register.call(app, action.address.route, actionHandler(runtime, action));
+            }
+            const fallback = options.fallback;
+            if (fallback)
+                app.use((request, response, next) => isActionPath(request.path) ? next() : fallback(request, response, next));
+            app.use((request, response) => respond.error(response, new RouteNotFoundException('Route {route} not found', { route: request.path }), request, 'request'));
+            app.use((error, request, response, next) => {
+                if (response.headersSent)
+                    return next(error);
+                respond.error(response, error, request, 'request');
+            });
+            //The adapter starts once the server listens (an occupied port fails the start)
+            await new Promise((resolve, reject) => {
+                server.once('error', reject).listen(options.port ?? 80, options.host, () => {
+                    server.off('error', reject);
+                    resolve();
+                });
+            });
+        },
+        stop: () => {
+            //The event streams end, the server stops accepting connections and closes the idle ones
+            stopping = true;
+            streams.forEach((stream) => stream.abort());
+            if (!server?.listening)
+                return;
+            closed = new Promise((resolve) => void server.close(() => resolve()));
+            server.closeIdleConnections();
+        },
+        close: async () => {
+            //The requests in progress ended or were aborted: their responses are written, then the remaining connections are closed
+            let timer;
+            await Promise.race([Promise.all(responding), new Promise((resolve) => {
+                    timer = setTimeout(resolve, 1000);
+                })]);
+            clearTimeout(timer);
+            server?.closeAllConnections();
+            await closed;
+            await options.stop?.();
+        }
+    };
+}

package/dist/esm/adapter/express/Responders.js

@@ -0,0 +1,66 @@
+import { describeError, statusOfError } from '../../lib/HTTPErrors.js';
+export { describeError, statusOfError };
+/**
+ * The default responder of {@link expressHTTPEntrypoint}: a result is sent as JSON, no result as an empty 204 (or the
+ * status set by a `StatusResult`); an error is sent as `{errno, errMsg}` (see `describeError`) with its HTTP status
+ * (see `statusOfError`: the first 4xx status in its cause chain, its own status, or 500).
+ */
+export const JSONResponder = {
+    success: (response, data) => {
+        if (data === undefined) {
+            response.status(response.statusCode === 200 ? 204 : response.statusCode).end();
+            return;
+        }
+        response.json(data);
+    },
+    error: (response, error) => {
+        response.status(statusOfError(error)).json(describeError(error));
+    }
+};
+/**
+ * Create a responder for {@link expressHTTPEntrypoint} that wraps every response in the envelope
+ * `{errno, errMsg, data}`: a result as `{errno: null, errMsg: null, data}` (`data` is `null` when the action returned
+ * nothing, and its status is not turned into 204), an error as `{errno, errMsg, data: null}` with the error's status,
+ * the `errorStatus` option, or for the errors of the actions the `actionErrorStatus` option.
+ * @param options The envelope options.
+ * @returns The responder, to give to the `respond` option of `expressHTTPEntrypoint`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ * import {expressHTTPEntrypoint, jsonEnvelope} from 'lakutata/adapter/express'
+ *
+ * class PingController extends Controller {
+ *     //GET /ping answers {"errno": null, "errMsg": null, "data": "pong"}
+ *     @GET('/ping')
+ *     public async ping(): Promise<string> {
+ *         return 'pong'
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'web.app',
+ *     name: 'Web',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [PingController],
+ *             //The errors of the actions answered with 200 too (as the applications of lakutata 2.x), the routes not
+ *             //found and the errors of the express middlewares with their status (404, 401…)
+ *             http: expressHTTPEntrypoint({port: 8080, respond: jsonEnvelope({actionErrorStatus: 200})})
+ *         })
+ *     }
+ * })
+ * ```
+ */
+export function jsonEnvelope(options = {}) {
+    return {
+        success: (response, data) => {
+            response.json({ errno: null, errMsg: null, data: data === undefined ? null : data });
+        },
+        error: (response, error, _request, origin) => {
+            const status = origin === 'action' ? options.actionErrorStatus ?? options.errorStatus : options.errorStatus;
+            response.status(status ?? statusOfError(error)).json({ ...describeError(error), data: null });
+        }
+    };
+}

package/dist/esm/adapter/express/StaticUI.js

@@ -0,0 +1,96 @@
+import express from 'express';
+import path from 'node:path';
+import { parseDuration } from '../../lib/schedule/Cron.js';
+/**
+ * Whether a file of a built UI has a content hash in its name: a script, a style, a font or an image whose name ends
+ * with a dot or a dash followed by at least 8 letters, digits, `_` or `-`, among them a digit or an uppercase letter
+ * @param file
+ * @internal
+ */
+export function isHashedAsset(file) {
+    const matched = /[.-]([0-9A-Za-z_-]{8,})\.(?:js|mjs|css|woff2?|png|jpe?g|svg|gif|webp|avif)$/.exec(file);
+    return !!matched && /[0-9A-Z]/.test(matched[1]);
+}
+/**
+ * The seconds the hashed assets are cached: a number of seconds, or a duration
+ * @param value
+ * @internal
+ */
+export function assetsMaxAge(value) {
+    if (value === undefined)
+        return 31536000;
+    const seconds = typeof value === 'number' || /^\d+(?:\.\d+)?$/.test(value) ? Number(value) : parseDuration(value) / 1000;
+    if (!Number.isFinite(seconds) || seconds < 0)
+        throw new RangeError(`Invalid assetsMaxAge "${value}": a number of seconds or a duration ("30d")`);
+    return Math.floor(seconds);
+}
+/**
+ * Create an express handler serving a built web UI (the `dist` directory of a Vite application): its files, and its
+ * index for the paths of its client-side routes. Given as the `fallback` of {@link expressHTTPEntrypoint}, it never
+ * receives the paths of the actions. It needs the optional peer dependency `express`.
+ *
+ * The files with a content hash in their name are cached for a long time (`assetsMaxAge`), the other files and the
+ * index are revalidated on each request. A request matching no file that is not a page request (an asset, a non-GET
+ * request, a client not accepting HTML) is passed on to the next handler.
+ * @param directory The directory of the built UI, resolved from the current working directory.
+ * @param options How the index is served and the assets cached.
+ * @returns The express request handler.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ * import {expressHTTPEntrypoint, staticUI} from 'lakutata/adapter/express'
+ *
+ * class DeviceController extends Controller {
+ *     //GET /api/devices answers the action; GET /settings answers the index of the UI
+ *     @GET('/api/devices')
+ *     public async list(): Promise<string[]> {
+ *         return ['sensor-1']
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'console.app',
+ *     name: 'Console',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [DeviceController],
+ *             http: expressHTTPEntrypoint({
+ *                 port: 8080,
+ *                 fallback: staticUI('./ui/dist', {assetsMaxAge: 86400})
+ *             })
+ *         })
+ *     }
+ * })
+ * ```
+ */
+export function staticUI(directory, options = {}) {
+    const root = path.resolve(directory);
+    const index = options.index ?? 'index.html';
+    const maxAge = assetsMaxAge(options.assetsMaxAge);
+    const files = express.static(root, {
+        index: false,
+        setHeaders: (response, file) => {
+            if (isHashedAsset(file))
+                response.setHeader('Cache-Control', `public, max-age=${maxAge}, immutable`);
+            else
+                response.setHeader('Cache-Control', 'no-cache');
+        }
+    });
+    return (request, response, next) => {
+        files(request, response, (error) => {
+            if (error)
+                return next(error);
+            //The routes of the application are its index; the missing files are not
+            const wantsPage = (request.method === 'GET' || request.method === 'HEAD') && !path.extname(request.path) && request.accepts('html') === 'html';
+            if (options.spa === false || !wantsPage)
+                return next();
+            response.setHeader('Cache-Control', 'no-cache');
+            response.sendFile(path.join(root, index), (sendError) => {
+                if (sendError)
+                    next(sendError);
+            });
+        });
+    };
+}