@wabot-dev/framework 0.9.27 → 2.0.0-beta.0

package/dist/src/feature/ui-controller/renderer/UiRendererRegistry.js

@@ -0,0 +1,42 @@
+import { __decorate } from 'tslib';
+import { singleton } from '../../../core/injection/index.js';
+
+let UiRendererRegistry = class UiRendererRegistry {
+    renderers = new Map();
+    defaultRenderer = null;
+    /** Register a renderer. The first one registered becomes the default. */
+    register(renderer) {
+        this.renderers.set(renderer.id, renderer);
+        if (!this.defaultRenderer)
+            this.defaultRenderer = renderer;
+    }
+    /** Register a renderer and make it the default. */
+    setDefault(renderer) {
+        this.renderers.set(renderer.id, renderer);
+        this.defaultRenderer = renderer;
+    }
+    has(id) {
+        return this.renderers.has(id);
+    }
+    hasDefault() {
+        return this.defaultRenderer != null;
+    }
+    get(id) {
+        if (id) {
+            const renderer = this.renderers.get(id);
+            if (!renderer) {
+                throw new Error(`UI renderer "${id}" is not registered`);
+            }
+            return renderer;
+        }
+        if (!this.defaultRenderer) {
+            throw new Error('No default UI renderer registered. Import "@wabot-dev/framework/ui" to register the Preact renderer, or register your own with UiRendererRegistry.setDefault().');
+        }
+        return this.defaultRenderer;
+    }
+};
+UiRendererRegistry = __decorate([
+    singleton()
+], UiRendererRegistry);
+
+export { UiRendererRegistry };

package/dist/src/feature/ui-controller/runUiControllers.js

@@ -0,0 +1,285 @@
+import { CustomError, errorToPlainObject } from '../../core/error/CustomError.js';
+import '../../core/error/setupErrorHandlers.js';
+import { container } from '../../core/injection/index.js';
+import { Logger } from '../../core/logger/Logger.js';
+import { validateModel } from '../../core/validation/core/validateModel.js';
+import { ValidationMetadataStore } from '../../core/validation/metadata/ValidationMetadataStore.js';
+import { ExpressProvider } from '../express/ExpressProvider.js';
+import '../rest-controller/metadata/RestControllerMetadataStore.js';
+import { json, urlencoded } from 'express';
+import path__default from 'node:path';
+import { EXPRESS_REQ, EXPRESS_RES } from '../rest-controller/injection-tokens.js';
+import 'node:http';
+import { createHash } from 'node:crypto';
+import { UiControllerMetadataStore } from './metadata/UiControllerMetadataStore.js';
+import { UiRendererRegistry } from './renderer/UiRendererRegistry.js';
+import { renderDocument } from './document/renderDocument.js';
+import { isRedirect } from './document/helpers.js';
+import { escapeHtml } from './document/escape.js';
+import { Container } from '../../core/injection/Container.js';
+
+function buildRequest(req) {
+    return Object.assign({}, req.body, req.query, req.params);
+}
+function joinRoute(...parts) {
+    return path__default.join(...parts).replaceAll('\\', '/');
+}
+/** Header the client nav runtime sends to request a fragment instead of a full document. */
+const NAV_HEADER = 'X-Wabot-Nav';
+/** Canonical form of a route path: leading slash, no trailing slash (except root). */
+function normalizeRoutePath(routePath) {
+    return '/' + routePath.replace(/^\/+|\/+$/g, '');
+}
+/** Turn a controller's head hints into <link> attribute maps for renderDocument. */
+function headLinks(head) {
+    if (!head)
+        return undefined;
+    const links = [];
+    for (const entry of head.preconnect ?? []) {
+        const { href, crossorigin } = typeof entry === 'string' ? { href: entry, crossorigin: undefined } : entry;
+        links.push({ rel: 'preconnect', href, ...(crossorigin ? { crossorigin: true } : {}) });
+    }
+    for (const p of head.preload ?? []) {
+        // Fonts are always fetched cross-origin; default crossorigin so the preload
+        // matches the real request instead of fetching the font twice.
+        const crossorigin = p.crossorigin ?? (p.as === 'font' ? true : undefined);
+        links.push({
+            rel: 'preload',
+            href: p.href,
+            as: p.as,
+            ...(p.type ? { type: p.type } : {}),
+            ...(crossorigin ? { crossorigin } : {}),
+            ...(p.media ? { media: p.media } : {}),
+        });
+    }
+    return links.length ? links : undefined;
+}
+function registerUiControllers(controllers, options = {}) {
+    const logger = new Logger('wabot:ui');
+    const baseContainer = options.baseContainer ?? container;
+    const store = baseContainer.resolve(UiControllerMetadataStore);
+    const expressProvider = options.expressProvider ?? baseContainer.resolve(ExpressProvider);
+    const validationStore = baseContainer.resolve(ValidationMetadataStore);
+    const rendererRegistry = baseContainer.resolve(UiRendererRegistry);
+    const expressApp = expressProvider.getExpress();
+    const dev = process.env.NODE_ENV !== 'production';
+    controllers.forEach((controller) => {
+        const viewInfos = store.getControllerViewsInfo(controller);
+        // The exact view routes of this controller: the nav runtime soft-navigates
+        // only these, so a controller mounted at "/" doesn't hijack the whole origin.
+        const appRoutes = viewInfos.map((v) => normalizeRoutePath(joinRoute(v.controller.path, v.config?.path ?? '')));
+        viewInfos.forEach((view) => {
+            const route = joinRoute(view.controller.path, view.config?.path ?? '');
+            const middlewareCtors = [
+                ...view.controller.middlewares,
+                ...view.middlewares.map((m) => m.middlewareConstructor),
+            ];
+            logger.info(`view  GET  ${route}`);
+            // A parameterized view under boosted nav needs an swr.version(params) so
+            // revalidation keys off the parameter; otherwise it can only revalidate by
+            // hashing a full re-render on every visit.
+            const isParameterized = route.split('/').some((seg) => seg.startsWith(':'));
+            if (view.controller.app && isParameterized && !view.config?.swr?.version) {
+                logger.warn(`view GET ${route}: parameterized app views should declare swr.version(params) ` +
+                    `so boosted navigation can revalidate per parameter without re-rendering`);
+            }
+            expressApp.get(route, json(), urlencoded({ extended: true }), async (req, res) => {
+                const requestContainer = newRequestContainer(baseContainer, req, res);
+                try {
+                    if (await runMiddlewares(middlewareCtors, requestContainer, req, res))
+                        return;
+                    const isApp = view.controller.app === true;
+                    const softNav = isApp && !!req.get(NAV_HEADER);
+                    // Cheap revalidation: if the view declares a `version`, answer 304
+                    // without running the handler or SSR when it matches If-None-Match.
+                    let versionEtag;
+                    if (softNav && view.config?.swr?.version) {
+                        const version = await view.config.swr.version(buildRequest(req));
+                        versionEtag = `"v:${version}"`;
+                        res.set('ETag', versionEtag);
+                        res.set('Cache-Control', 'no-cache');
+                        if (req.get('If-None-Match') === versionEtag) {
+                            res.status(304).end();
+                            return;
+                        }
+                    }
+                    const instance = requestContainer.resolve(view.controllerConstructor);
+                    const args = resolveHandlerArgs(view.paramsTypes, req, validationStore);
+                    const result = await instance[view.functionName].apply(instance, args);
+                    if (isRedirect(result)) {
+                        res.redirect(result.status, result.location);
+                        return;
+                    }
+                    const renderer = rendererRegistry.get();
+                    // Full loads render inside the controller's layout (the persistent
+                    // shell); boosted-nav fragments render just the view (the outlet body).
+                    const rendered = await renderer.renderToString(result, {
+                        dev,
+                        layout: softNav ? undefined : view.controller.layout,
+                    });
+                    const assets = options.pageAssets?.(rendered.islands) ?? {};
+                    const styles = [...(rendered.styles ?? []), ...(assets.styles ?? [])];
+                    // Boosted navigation: send a JSON fragment (+ ETag) instead of the
+                    // full document. A matching If-None-Match means nothing changed, so
+                    // answer 304 and let the client keep its cached view (no re-render).
+                    if (softNav) {
+                        const payload = JSON.stringify({
+                            html: rendered.html,
+                            title: view.config?.title ?? null,
+                            meta: view.config?.meta ?? null,
+                            scripts: assets.scripts ?? [],
+                            styles,
+                            maxAge: view.config?.swr?.maxAge ?? 0,
+                        });
+                        const etag = versionEtag ?? `"${createHash('sha1').update(payload).digest('base64')}"`;
+                        res.set('ETag', etag);
+                        res.set('Cache-Control', 'no-cache');
+                        if (req.get('If-None-Match') === etag) {
+                            res.status(304).end();
+                            return;
+                        }
+                        res.status(200).type('application/json').send(payload);
+                        return;
+                    }
+                    const scripts = [...(assets.scripts ?? [])];
+                    let headHtml = assets.headHtml;
+                    if (isApp && assets.navScript) {
+                        // `<` escaped so a route string can never break out of the inline script.
+                        const bootstrap = `<script>window.__wabotApp=${JSON.stringify({
+                            routes: appRoutes,
+                        }).replace(/</g, '\\u003c')}</script>`;
+                        headHtml = (headHtml ?? '') + bootstrap;
+                        scripts.push(assets.navScript);
+                    }
+                    const html = renderDocument({
+                        bodyHtml: rendered.html,
+                        title: view.config?.title,
+                        meta: view.config?.meta,
+                        styles,
+                        links: headLinks(view.controller.head),
+                        scripts,
+                        headHtml,
+                        bodyEndHtml: assets.bodyEndHtml,
+                    });
+                    res.status(200).type('html').send(html);
+                }
+                catch (err) {
+                    sendHtmlError(res, err, logger, `GET ${route}`, dev);
+                }
+                finally {
+                    requestContainer.dispose();
+                }
+            });
+        });
+        store.getControllerActionsInfo(controller).forEach((action) => {
+            const route = joinRoute(action.controller.path, '_action', action.config?.path ?? action.functionName);
+            const middlewareCtors = [
+                ...action.controller.middlewares,
+                ...action.middlewares.map((m) => m.middlewareConstructor),
+            ];
+            logger.info(`action POST ${route}`);
+            expressApp.post(route, json(), urlencoded({ extended: true }), async (req, res) => {
+                const requestContainer = newRequestContainer(baseContainer, req, res);
+                try {
+                    if (await runMiddlewares(middlewareCtors, requestContainer, req, res))
+                        return;
+                    const instance = requestContainer.resolve(action.controllerConstructor);
+                    const args = resolveHandlerArgs(action.paramsTypes, req, validationStore);
+                    const result = await instance[action.functionName].apply(instance, args);
+                    if (isRedirect(result)) {
+                        res.redirect(result.status, result.location);
+                        return;
+                    }
+                    res.status(200).json(removeCircular(result ?? null));
+                }
+                catch (err) {
+                    sendJsonError(res, err, logger, `POST ${route}`);
+                }
+                finally {
+                    requestContainer.dispose();
+                }
+            });
+        });
+    });
+    return expressProvider;
+}
+function runUiControllers(controllers, options = {}) {
+    const expressProvider = registerUiControllers(controllers, options);
+    expressProvider.listen();
+}
+function newRequestContainer(baseContainer, req, res) {
+    const requestContainer = baseContainer.createChildContainer();
+    requestContainer.register(Container, { useValue: requestContainer });
+    requestContainer.register(EXPRESS_REQ, { useValue: req });
+    requestContainer.register(EXPRESS_RES, { useValue: res });
+    return requestContainer;
+}
+/** Returns true if a middleware already handled the response (caller should stop). */
+async function runMiddlewares(middlewareCtors, requestContainer, req, res) {
+    for (const ctor of middlewareCtors) {
+        const middleware = requestContainer.resolve(ctor);
+        await middleware.handle(req, res, requestContainer);
+        if (res.headersSent)
+            return true;
+    }
+    return false;
+}
+function resolveHandlerArgs(paramsTypes, req, validationStore) {
+    if (!paramsTypes || paramsTypes.length === 0)
+        return [];
+    if (paramsTypes.length > 1) {
+        throw new Error('ui view/action handlers accept at most one parameter');
+    }
+    const paramType = paramsTypes[0];
+    if (typeof paramType !== 'function') {
+        throw new Error('invalid ui handler parameter type');
+    }
+    const paramInfo = validationStore.getModelValidatorsInfo(paramType);
+    const { value, error } = validateModel(buildRequest(req), paramInfo);
+    if (error) {
+        throw new CustomError({ httpCode: 400, message: error.description, info: error });
+    }
+    return [value];
+}
+function sendHtmlError(res, err, logger, label, dev) {
+    logger.error(`${label} failed`, err);
+    if (res.headersSent)
+        return;
+    const status = err instanceof Error ? (errorToPlainObject(err).httpCode ?? 500) : 500;
+    const message = err instanceof Error ? err.message : 'Unknown error';
+    const detail = dev && err instanceof Error && err.stack ? `<pre>${escapeHtml(err.stack)}</pre>` : '';
+    const html = renderDocument({
+        title: `Error ${status}`,
+        bodyHtml: `<main><h1>Error ${status}</h1><p>${escapeHtml(message)}</p>${detail}</main>`,
+    });
+    res.status(status).type('html').send(html);
+}
+function sendJsonError(res, err, logger, label) {
+    logger.error(`${label} failed`, err);
+    if (res.headersSent)
+        return;
+    if (err instanceof Error) {
+        const { name: _name, stack, httpCode, ...info } = errorToPlainObject(err);
+        res
+            .status(httpCode ?? 500)
+            .json(removeCircular({ error: { message: err.message, stack, ...info } }));
+    }
+    else {
+        res.status(500).json({ error: { message: 'Unknown error' } });
+    }
+}
+function removeCircular(obj, seen = new WeakSet()) {
+    if (obj && typeof obj === 'object') {
+        if (seen.has(obj))
+            return undefined;
+        seen.add(obj);
+        const clone = Array.isArray(obj) ? [] : {};
+        for (const key in obj) {
+            clone[key] = removeCircular(obj[key], seen);
+        }
+        return clone;
+    }
+    return obj;
+}
+
+export { registerUiControllers, runUiControllers };