proteum 2.5.24 → 2.6.0

package/tests/client-router-prefetch.test.cjs

@@ -0,0 +1,197 @@
+const assert = require('node:assert/strict');
+
+const { ReactClientContext, createRouter, restore } = require('./clientRouterHarness.cjs');
+const { h, options } = require('preact');
+const { renderToString } = require('preact-render-to-string');
+const { Link } = require('../client/services/router/components/Link.tsx');
+
+/*----------------------------------
+- HARNESS
+----------------------------------*/
+
+const flush = () => new Promise((resolve) => setImmediate(resolve));
+
+// An unresolved route as registerRoutes() builds it from the SSR route list
+const createUnresolvedRoute = (index, routePath, load) => ({
+    index,
+    chunk: `chunk${routePath.replace(/\W/g, '_')}`,
+    regex: new RegExp(`^${routePath}$`),
+    keys: [],
+    load,
+});
+
+const createModule = (routePath) => ({
+    __register: () => ({ method: 'GET', path: routePath, options: {}, controller: () => null }),
+});
+
+const createRouterWithRoutes = (paths, { config, failing = [] } = {}) => {
+    const loads = [];
+    const router = createRouter(config);
+    router.routes = paths.map((routePath, index) =>
+        createUnresolvedRoute(index, routePath, () => {
+            loads.push(routePath);
+            return failing.includes(routePath)
+                ? Promise.reject(new Error('ChunkLoadError'))
+                : Promise.resolve(createModule(routePath));
+        }),
+    );
+
+    return { router, loads };
+};
+
+/*----------------------------------
+- TESTS
+----------------------------------*/
+
+test('prefetch(path) loads the matching route chunk once and keeps it resolved', async () => {
+    const { router, loads } = createRouterWithRoutes(['/radars', '/sales']);
+
+    await Promise.all([router.prefetch('/sales?tab=near#top'), router.prefetch('/sales')]);
+    await router.prefetch('/sales');
+
+    assert.deepEqual(loads, ['/sales']);
+    assert.equal('load' in router.routes[1], false);
+    assert.equal(router.routes[1].path, '/sales');
+    assert.deepEqual(router.routes[1].regex, /^\/sales$/);
+    assert.equal('load' in router.routes[0], true);
+});
+
+test('a navigation joins a prefetch already in flight', async () => {
+    const { router, loads } = createRouterWithRoutes(['/radars']);
+    const route = router.routes[0];
+
+    const prefetch = router.prefetch('/radars');
+    const navigationRoute = await router['load'](route);
+    await prefetch;
+
+    assert.deepEqual(loads, ['/radars']);
+    assert.equal(navigationRoute.path, '/radars');
+});
+
+test('prefetch ignores unknown paths and leaves failures to the navigation', async () => {
+    let updates = 0;
+    const { router, loads } = createRouterWithRoutes(['/radars'], { failing: ['/radars'] });
+    router.app.handleUpdate = () => updates++;
+
+    await router.prefetch('https://example.com/elsewhere');
+    await router.prefetch('/unknown');
+    await router.prefetch('/radars');
+
+    assert.deepEqual(loads, ['/radars']);
+    assert.equal(updates, 0);
+    // Still unresolved: the next navigation loads it again and reports a failure itself
+    assert.equal('load' in router.routes[0], true);
+});
+
+test('the router config prefetch list loads at idle, one chunk at a time', async () => {
+    const idleCallbacks = [];
+    window.requestIdleCallback = (callback) => idleCallbacks.push(callback);
+
+    try {
+        const { router, loads } = createRouterWithRoutes(['/radars', '/sales', '/tlds'], {
+            config: { prefetch: ['/sales', '/radars'] },
+        });
+        let releaseSales;
+        const salesLoad = router.routes[1].load;
+        router.routes[1].load = () => new Promise((resolve) => (releaseSales = () => resolve(salesLoad())));
+
+        router['prefetchAtIdle']();
+        assert.equal(idleCallbacks.length, 1);
+        await flush();
+        assert.deepEqual(loads, []);
+
+        idleCallbacks[0]();
+        await flush();
+        // The second chunk waits for the first
+        assert.deepEqual(loads, []);
+        releaseSales();
+        await flush();
+        assert.deepEqual(loads, ['/sales', '/radars']);
+
+        // Nothing to schedule without a list
+        createRouterWithRoutes(['/radars']).router['prefetchAtIdle']();
+        assert.equal(idleCallbacks.length, 1);
+    } finally {
+        delete window.requestIdleCallback;
+    }
+});
+
+test('without requestIdleCallback the prefetch waits a real delay, not one millisecond', async () => {
+    const timers = [];
+    window.setTimeout = (callback, delay) => timers.push({ callback, delay });
+
+    try {
+        const { router, loads } = createRouterWithRoutes(['/radars'], { config: { prefetch: ['/radars'] } });
+        router['prefetchAtIdle']();
+
+        assert.equal(timers.length, 1);
+        // Safari and iOS have no idle callback: the page's own requests go first
+        assert.ok(timers[0].delay >= 1000, `fallback delay ${timers[0].delay}ms`);
+        assert.deepEqual(loads, []);
+
+        timers[0].callback();
+        await flush();
+        assert.deepEqual(loads, ['/radars']);
+    } finally {
+        // The harness window has no timers of its own
+        delete window.setTimeout;
+    }
+});
+
+test('data saver turns the idle prefetch off', () => {
+    const idleCallbacks = [];
+    window.requestIdleCallback = (callback) => idleCallbacks.push(callback);
+    window.navigator = { connection: { saveData: true } };
+
+    try {
+        createRouterWithRoutes(['/radars'], { config: { prefetch: ['/radars'] } }).router['prefetchAtIdle']();
+        assert.equal(idleCallbacks.length, 0);
+
+        // Saver off, or no Network Information API at all: the prefetch is scheduled
+        window.navigator = { connection: { saveData: false } };
+        createRouterWithRoutes(['/radars'], { config: { prefetch: ['/radars'] } }).router['prefetchAtIdle']();
+        window.navigator = {};
+        createRouterWithRoutes(['/radars'], { config: { prefetch: ['/radars'] } }).router['prefetchAtIdle']();
+        assert.equal(idleCallbacks.length, 2);
+    } finally {
+        delete window.requestIdleCallback;
+        window.navigator = {};
+    }
+});
+
+test('Link prefetch loads the route on hover and focus, and keeps the caller handlers', async () => {
+    const { router, loads } = createRouterWithRoutes(['/radars']);
+    const anchors = [];
+    const previousVnodeHook = options.vnode;
+    options.vnode = (vnode) => {
+        if (vnode.type === 'a') anchors.push(vnode.props);
+        previousVnodeHook?.(vnode);
+    };
+
+    let hovered = 0;
+    try {
+        renderToString(
+            h(
+                ReactClientContext.Provider,
+                { value: { Router: router } },
+                h(Link, { to: '/radars', prefetch: true, onMouseEnter: () => hovered++ }, 'Radars'),
+                h(Link, { to: '/radars' }, 'Plain'),
+            ),
+        );
+    } finally {
+        options.vnode = previousVnodeHook;
+    }
+
+    const [prefetching, plain] = anchors;
+    assert.equal(plain.onMouseEnter, undefined);
+    assert.equal(plain.onFocus, undefined);
+
+    prefetching.onMouseEnter({});
+    prefetching.onFocus({});
+    await flush();
+
+    assert.equal(hovered, 1);
+    assert.deepEqual(loads, ['/radars']);
+});
+
+afterAll(restore);

package/tests/clientRouterHarness.cjs

@@ -0,0 +1,70 @@
+const Module = require('node:module');
+const path = require('node:path');
+
+const coreRoot = path.join(__dirname, '..');
+require('module-alias').addAliases({
+    '@client': path.join(coreRoot, 'client'),
+    '@common': path.join(coreRoot, 'common'),
+    '@server': path.join(coreRoot, 'server'),
+});
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+require('ts-node/register/transpile-only');
+
+const { createContext } = require('preact');
+
+const ReactClientContext = createContext(undefined);
+// What the default `useContext()` export returns: a test that mounts the router component sets it
+const clientContext = { value: {} };
+const stubs = {
+    '@/client/context': Object.assign(() => clientContext.value, { ReactClientContext }),
+    '@client/app/component': { default: () => null },
+    '@client/pages/_layout': { default: () => null },
+    '@generated/client/layouts': { default: {}, layoutOrder: [] },
+    '@generated/client/routes': { default: {} },
+    '@generated/common/controllers': { __esModule: true, default: () => ({}) },
+    'react-dom': { hydrate: () => {} },
+};
+
+const originalLoad = Module._load;
+Module._load = function load(request, parent, isMain) {
+    if (request in stubs) return stubs[request];
+    if (request === 'react') return originalLoad.call(this, 'preact/compat', parent, isMain);
+
+    return originalLoad.call(this, request, parent, isMain);
+};
+
+const previous = { window: global.window, document: global.document, dev: global.__DEV__ };
+global.__DEV__ = false;
+global.window = {
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    history: { state: {}, pushState: () => {}, replaceState: () => {} },
+    location: { hash: '', host: 'localhost', origin: 'http://localhost', pathname: '/', protocol: 'http:', search: '' },
+    navigator: {},
+    scrollTo: () => {},
+};
+global.document = { defaultView: global.window };
+
+const ClientRouter = require('../client/services/router/index.tsx').default;
+
+// A router instance without the app boot: tests set routes and config themselves
+const createRouter = (config = {}) => {
+    const app = { registerService: () => {}, handleUpdate: () => {} };
+    return new ClientRouter(app, { preload: [], context: () => ({}), ...config });
+};
+
+const restore = () => {
+    Module._load = originalLoad;
+    for (const [key, value] of Object.entries(previous)) {
+        const name = key === 'dev' ? '__DEV__' : key;
+        if (value === undefined) delete global[name];
+        else global[name] = value;
+    }
+};
+
+const setClientContext = (value) => {
+    clientContext.value = value;
+};
+
+module.exports = { ClientRouter, ReactClientContext, createRouter, restore, setClientContext };

package/tests/definition-contracts.test.cjs

@@ -28,7 +28,8 @@ const {
     schema,
 } = require('../server/app/controller/index.ts');
 const Service = require('../server/app/service/index.ts').default;
-const { expressHandler, registerRouteDefinition } = require('../common/router/definitions.ts');
+const { definePageRoute, expressHandler, registerRouteDefinition } = require('../common/router/definitions.ts');
+const { validatePageDataResult } = require('../common/router/pageData.ts');
 const { parseProteumEnvConfig } = require('../common/env/proteumEnv.ts');
 
 const createTempDir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-definition-contracts-'));
@@ -153,6 +154,49 @@ export default definePageRoute({
     assert.deepEqual(definition.normalizedOptionKeys, ['auth', 'authTracking']);
 });
 
+test('route indexer accepts the navigation page option', () => {
+    const root = createTempDir();
+    const filepath = path.join(root, 'client/pages/radars.tsx');
+
+    writeFile(
+        filepath,
+        `import { definePageRoute } from '@common/router/definitions';
+
+export default definePageRoute({
+    path: '/radars',
+    options: { auth: true, navigation: 'deferred' },
+    data: ({ Radars }) => ({ radars: Radars.list() }),
+    render: ({ radars, navigation }) => null,
+});
+`,
+    );
+
+    const [definition] = indexRouteDefinitions({ side: 'client', sourceFilepath: filepath });
+
+    assert.deepEqual(definition.normalizedOptionKeys, ['auth', 'navigation']);
+    assert.deepEqual(definition.invalidOptionKeys, []);
+});
+
+test('definePageRoute keeps the navigation option and page data keeps "navigation" for blocking pages only', () => {
+    const render = () => null;
+    const definition = definePageRoute({ path: '/radars', options: { navigation: 'deferred' }, data: () => ({}), render });
+
+    assert.equal(definition.kind, 'page');
+    assert.equal(definition.options.navigation, 'deferred');
+    assert.equal(definition.render, render);
+
+    const route = (options) => ({ path: '/radars', options: { filepath: 'client/pages/radars.tsx', ...options } });
+    const data = { navigation: { menu: [] }, rows: [] };
+
+    // Blocking pages already return a "navigation" data key
+    assert.equal(validatePageDataResult(route({}), data), data);
+    assert.equal(validatePageDataResult(route({ navigation: 'blocking' }), data), data);
+    assert.throws(() => validatePageDataResult(route({ navigation: 'deferred' }), data), /cannot return key "navigation"/);
+    assert.equal(validatePageDataResult(route({ navigation: 'deferred' }), { rows: [] }).rows.length, 0);
+    // Other route option keys stay reserved
+    assert.throws(() => validatePageDataResult(route({}), { auth: true }), /reserved key "auth"/);
+});
+
 test('router port override updates absolute runtime URLs', () => {
     const root = createTempDir();
 

package/tests/fakeDom.cjs

@@ -0,0 +1,90 @@
+/*
+ * The smallest document Preact's `render` needs to mount and update a tree in Node: element and text nodes,
+ * child lists, attributes. No layout, no events: a test that clicks drives the component's handlers itself.
+ */
+
+class FakeNode {
+    constructor(nodeType) {
+        this.nodeType = nodeType;
+        this.parentNode = null;
+        this.childNodes = [];
+    }
+
+    get firstChild() {
+        return this.childNodes[0] || null;
+    }
+
+    get nextSibling() {
+        if (!this.parentNode) return null;
+        const siblings = this.parentNode.childNodes;
+        return siblings[siblings.indexOf(this) + 1] || null;
+    }
+
+    insertBefore(node, reference) {
+        if (node.parentNode) node.parentNode.removeChild(node);
+        const index = reference ? this.childNodes.indexOf(reference) : -1;
+        if (index < 0) this.childNodes.push(node);
+        else this.childNodes.splice(index, 0, node);
+        node.parentNode = this;
+        return node;
+    }
+
+    appendChild(node) {
+        return this.insertBefore(node, null);
+    }
+
+    removeChild(node) {
+        this.childNodes.splice(this.childNodes.indexOf(node), 1);
+        node.parentNode = null;
+        return node;
+    }
+
+    get textContent() {
+        return this.childNodes.map((child) => child.textContent).join('');
+    }
+}
+
+class FakeText extends FakeNode {
+    constructor(data) {
+        super(3);
+        this.data = String(data);
+    }
+
+    get textContent() {
+        return this.data;
+    }
+}
+
+class FakeElement extends FakeNode {
+    constructor(localName, namespaceURI) {
+        super(1);
+        this.localName = localName;
+        this.namespaceURI = namespaceURI;
+        this.attributes = {};
+        this.style = {};
+    }
+
+    setAttribute(name, value) {
+        this.attributes[name] = String(value);
+    }
+
+    removeAttribute(name) {
+        delete this.attributes[name];
+    }
+
+    getAttribute(name) {
+        return name in this.attributes ? this.attributes[name] : null;
+    }
+
+    addEventListener() {}
+
+    removeEventListener() {}
+}
+
+const createFakeDocument = () => ({
+    createElement: (name) => new FakeElement(name, 'http://www.w3.org/1999/xhtml'),
+    createElementNS: (namespace, name) => new FakeElement(name, namespace),
+    createTextNode: (data) => new FakeText(data),
+});
+
+module.exports = { createFakeDocument };

package/tests/http-server-cleanup.test.cjs

@@ -0,0 +1,115 @@
+const assert = require('node:assert/strict');
+const Module = require('node:module');
+const path = require('node:path');
+
+const coreRoot = path.join(__dirname, '..');
+require('module-alias').addAliases({
+    '@client': path.join(coreRoot, 'client'),
+    '@common': path.join(coreRoot, 'common'),
+    '@server': path.join(coreRoot, 'server'),
+});
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+require('ts-node/register/transpile-only');
+
+// The app container reads the app's proteum.config.ts at import; the HTTP server only needs it at runtime.
+const httpServerModulePath = path.join(coreRoot, 'server/services/router/http/index.ts');
+const originalLoad = Module._load;
+Module._load = function patchedLoad(request, parent, isMain) {
+    if (parent?.filename === httpServerModulePath && request === '@server/app/container') {
+        return { __esModule: true, default: {} };
+    }
+
+    return originalLoad.call(this, request, parent, isMain);
+};
+
+let HttpServer;
+let httpDrainDeadlineMs;
+try {
+    ({ default: HttpServer, httpDrainDeadlineMs } = require('../server/services/router/http/index.ts'));
+} finally {
+    Module._load = originalLoad;
+}
+
+/** A real HttpServer wired to a fake app, with its node server swapped for a recorder. */
+const createDrainingServer = () => {
+    const hooks = {};
+    const app = {
+        env: { name: 'local' },
+        on: (name, callback) => {
+            hooks[name] = callback;
+        },
+    };
+    const server = new HttpServer({ domain: 'localhost', port: 0, ssl: false }, { app });
+
+    const calls = [];
+    let closeCallback;
+    server.http = {
+        close: (callback) => {
+            calls.push('close');
+            closeCallback = callback;
+        },
+        closeIdleConnections: () => calls.push('closeIdleConnections'),
+        closeAllConnections: () => calls.push('closeAllConnections'),
+    };
+
+    let settled = false;
+    const runCleanupHook = () => {
+        const drained = hooks.cleanup();
+        void drained.then(() => {
+            settled = true;
+        });
+        return drained;
+    };
+
+    return { calls, runCleanupHook, isSettled: () => settled, finishClose: () => closeCallback() };
+};
+
+const flushMicrotasks = async () => {
+    for (let index = 0; index < 5; index++) await Promise.resolve();
+};
+
+afterEach(() => {
+    vi.useRealTimers();
+});
+
+test('http server cleanup waits for close and clears the drain deadline', async () => {
+    vi.useFakeTimers();
+    const server = createDrainingServer();
+
+    const drained = server.runCleanupHook();
+    await flushMicrotasks();
+
+    assert.equal(server.isSettled(), false, 'cleanup must not resolve while responses are still in flight');
+    assert.deepEqual(server.calls, ['close', 'closeIdleConnections']);
+    assert.equal(vi.getTimerCount(), 1);
+
+    server.finishClose();
+    await drained;
+
+    assert.equal(server.isSettled(), true);
+    assert.equal(vi.getTimerCount(), 0, 'the drain deadline must be cleared once close() calls back');
+    assert.deepEqual(server.calls, ['close', 'closeIdleConnections']);
+});
+
+test('http server cleanup force-closes connections when the drain deadline passes', async () => {
+    vi.useFakeTimers();
+    const server = createDrainingServer();
+
+    const drained = server.runCleanupHook();
+
+    await vi.advanceTimersByTimeAsync(httpDrainDeadlineMs - 1);
+    assert.equal(server.isSettled(), false);
+    assert.deepEqual(server.calls, ['close', 'closeIdleConnections']);
+
+    await vi.advanceTimersByTimeAsync(1);
+    await drained;
+
+    assert.equal(server.isSettled(), true);
+    assert.deepEqual(server.calls, ['close', 'closeIdleConnections', 'closeAllConnections']);
+});
+
+test('http server drain deadline stays under the 20 second host drain window', () => {
+    assert.equal(httpDrainDeadlineMs, 10_000);
+    assert.ok(httpDrainDeadlineMs < 20_000);
+});