@morojs/moro 1.8.10 → 1.8.11

package/README.md

@@ -68,6 +68,10 @@ import { createApp, z } from '@morojs/moro';
       return { success: true, data: req.body };
     });
 
+  // A literal body is the whole handler: on Moro's native engine it is
+  // answered without entering JS at all
+  app.get('/health').handler('ok');
+
   app.listen(3000);
 })();
 ```

package/dist/core/http/moro-engine-server.d.ts

@@ -191,6 +191,9 @@ export declare class MoroEngineServer {
     /** @internal */ _respondPreparedEmpty?: (reqId: number, tplId: number) => void;
     /** @internal */ _endWith?: (reqId: number, chunk: any) => void;
     private _templatesOn;
+    /** @internal */ _setStaticRoute?: (serverId: number, method: number, path: string, status: number, headersFlat: string[] | null, body: any) => void;
+    private _staticOn;
+    private staticRoutes;
     private _batchDesc;
     private _batchCtl;
     private _batchPaths;
@@ -225,6 +228,7 @@ export declare class MoroEngineServer {
     /** @internal read by EngineResponse for buffered-response compression */
     _compression: CompressionSettings;
     private closed;
+    private _drainArmed;
     private routerHandler?;
     private errorHandler?;
     private directRoutes;
@@ -256,6 +260,21 @@ export declare class MoroEngineServer {
      *  headers) or the engine's per-server store is full. */
     _template(kind: number, status: number): number;
     private _resetTemplates;
+    /** Whether this engine build answers static routes itself. */
+    get staticRoutesEnabled(): boolean;
+    /**
+     * Register a fixed reply for one (method, path) that the engine serves
+     * without calling into JS: no routing, no middleware, no hooks and no
+     * header building per request. The bytes on the wire are those of
+     * respond(status, headers, body). Returns false when this engine cannot
+     * take it (no capability, or a method the engine does not index), so the
+     * caller keeps its JS handler as the answer. Registering the same
+     * (method, path) again replaces the earlier reply.
+     */
+    setStaticRoute(method: string, path: string, status?: number, headers?: Record<string, string | number | string[]> | string[] | null, body?: string | Buffer | Uint8Array | ArrayBuffer | null): boolean;
+    /** Drop every engine-answered static route; the JS routes are untouched. */
+    clearStaticRoutes(): void;
+    private _reapplyStaticRoutes;
     private registerWithEngine;
     private onRequestBatch;
     private dispatchOne;
@@ -288,6 +307,7 @@ export declare class MoroEngineServer {
     private dispatchDirectRoute;
     setNativeRouteProvider(_provider: () => Array<any>, _onError?: (...args: any[]) => any): void;
     private onRequest;
+    private _armMicrotaskDrain;
     private onAborted;
     private onWritable;
     private finishUnrouted;

package/dist/core/http/moro-engine-server.js

@@ -14,6 +14,7 @@
 // Date, chunked encoding, HEAD body suppression and native 413/400 are all
 // engine concerns - this adapter never sees them. No dependency on the uWS
 // adapter: shared helpers live in ./utils.
+import { setImmediate } from 'node:timers';
 import { randomUUID } from 'crypto';
 import { createFrameworkLogger } from '../logger/index.js';
 import { loadNativeEngine, getNativeEngineLoadErrors, } from '../utilities/package-utils.js';
@@ -104,6 +105,31 @@ const TPL_HEADERS = [
 ];
 const TPL_CONTENT_TYPE = TPL_HEADERS.map(h => h?.[1]);
 const TPL_KINDS = TPL_HEADERS.length;
+// Engine-answered static routes take the engine's method index; only the
+// named methods (GET..OPTIONS) can short-circuit - 'OTHER' never does.
+const STATIC_ROUTE_METHODS = 7;
+// [k1, v1, k2, v2, ...] for the engine, from any header shape a caller holds.
+// null when there is nothing to send, so the wire bytes equal respond(null).
+function flattenHeaders(headers) {
+    if (headers === undefined || headers === null)
+        return null;
+    if (Array.isArray(headers))
+        return headers.length === 0 ? null : headers.map(String);
+    let flat = null;
+    for (const key in headers) {
+        const value = headers[key];
+        if (flat === null)
+            flat = [];
+        if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++)
+                flat.push(key, String(value[i]));
+        }
+        else {
+            flat.push(key, String(value));
+        }
+    }
+    return flat;
+}
 // Content-Type sniff for send(): does the body start with '{' or '[' after
 // optional leading whitespace? Regex `\s` matches exactly the set trimStart()
 // strips, and the match stops at the first non-space character, so this costs
@@ -1434,6 +1460,14 @@ export class MoroEngineServer {
     /** @internal */ _respondPreparedEmpty;
     /** @internal */ _endWith;
     _templatesOn = false;
+    // Engine-answered static routes (engine >= 1.1.6, capabilities.staticRoutes):
+    // a fixed reply for one (method, path) that the engine sends without calling
+    // into JS. Assigned only when the flag AND the function are present (the
+    // same guard as templates). The list is kept because listen() after close()
+    // registers a fresh native server that knows nothing of the old one's routes.
+    /** @internal */ _setStaticRoute;
+    _staticOn = false;
+    staticRoutes = [];
     // Batched pipelined dispatch (engine >= 1.1.6, capabilities.batchDispatch):
     // the engine parses complete pipelined requests ahead and delivers them in
     // one onRequestBatch(count) call; the descriptors/control/paths buffers are
@@ -1491,6 +1525,8 @@ export class MoroEngineServer {
     // Set by close(); listen() then registers a fresh native server, because the
     // old serverId's uv handles are torn down and must never be reused.
     closed = false;
+    // See _armMicrotaskDrain.
+    _drainArmed = false;
     // Direct router dispatch (set from Moro.listen via setRouterHandler)
     routerHandler;
     // Global error handler (Moro.setErrorHandler) - shapes errors thrown from
@@ -1553,6 +1589,10 @@ export class MoroEngineServer {
             this._endWith = surface.endWith;
             this._templatesOn = true;
         }
+        if (this._capabilities?.staticRoutes === true && typeof surface.setStaticRoute === 'function') {
+            this._setStaticRoute = surface.setStaticRoute;
+            this._staticOn = true;
+        }
         if (this._capabilities?.batchDispatch === true &&
             typeof surface.getBatchBuffers === 'function' &&
             typeof surface.getPath === 'function') {
@@ -1626,6 +1666,58 @@ export class MoroEngineServer {
         for (const m of this._tpl)
             m.clear();
     }
+    /** Whether this engine build answers static routes itself. */
+    get staticRoutesEnabled() {
+        return this._staticOn;
+    }
+    /**
+     * Register a fixed reply for one (method, path) that the engine serves
+     * without calling into JS: no routing, no middleware, no hooks and no
+     * header building per request. The bytes on the wire are those of
+     * respond(status, headers, body). Returns false when this engine cannot
+     * take it (no capability, or a method the engine does not index), so the
+     * caller keeps its JS handler as the answer. Registering the same
+     * (method, path) again replaces the earlier reply.
+     */
+    setStaticRoute(method, path, status = 200, headers, body) {
+        const fn = this._setStaticRoute;
+        if (!this._staticOn || fn === undefined)
+            return false;
+        // The engine sends the stored bytes as they are; with compression on, the
+        // JS handler would negotiate an encoding, so the two replies would differ.
+        if (this._compression.enabled)
+            return false;
+        const methodIdx = METHODS.indexOf(method.toUpperCase());
+        if (methodIdx < 0 || methodIdx >= STATIC_ROUTE_METHODS)
+            return false;
+        const headersFlat = flattenHeaders(headers);
+        const fixedBody = body === undefined ? null : body;
+        const entry = { methodIdx, path, status, headersFlat, body: fixedBody };
+        const at = this.staticRoutes.findIndex(r => r.methodIdx === methodIdx && r.path === path);
+        if (at === -1)
+            this.staticRoutes.push(entry);
+        else
+            this.staticRoutes[at] = entry;
+        fn(this.serverId, methodIdx, path, status, headersFlat, fixedBody);
+        return true;
+    }
+    /** Drop every engine-answered static route; the JS routes are untouched. */
+    clearStaticRoutes() {
+        this.staticRoutes.length = 0;
+        if (this._staticOn && typeof this._engine.clearStaticRoutes === 'function') {
+            this._engine.clearStaticRoutes(this.serverId);
+        }
+    }
+    // listen() after close() registers a fresh native server; give it every
+    // static route the old one had.
+    _reapplyStaticRoutes() {
+        const fn = this._setStaticRoute;
+        if (fn === undefined)
+            return;
+        for (const r of this.staticRoutes) {
+            fn(this.serverId, r.methodIdx, r.path, r.status, r.headersFlat, r.body);
+        }
+    }
     // Register callbacks + limits with the native engine, returning the new
     // serverId. Called from the constructor and again by listen() after a
     // close() (the old native server is gone; a restart needs a fresh one).
@@ -2008,7 +2100,25 @@ export class MoroEngineServer {
         if (!httpRes.writableEnded) {
             httpRes._registered = true;
             this.inflight.set(reqId, httpRes);
-        }
+            this._armMicrotaskDrain();
+        }
+    }
+    // The engine invokes onRequest with a plain V8 call from its own uv
+    // callback, outside a Node callback scope, so microtasks queued during
+    // dispatch - an await on an already-settled promise, a .then chain, the
+    // router's own async 404 continuation - do not run when the callback
+    // returns. They run at the next Node-managed callback, which on a quiet
+    // server is whatever timer fires next: seconds away. A no-op immediate is
+    // that callback: Node drains nextTicks and microtasks when its scope
+    // closes, in this loop iteration's check phase. One per burst is enough,
+    // so it is armed once and re-armed only after it has fired.
+    _armMicrotaskDrain() {
+        if (this._drainArmed)
+            return;
+        this._drainArmed = true;
+        setImmediate(() => {
+            this._drainArmed = false;
+        });
     }
     onAborted(reqId) {
         const httpRes = this.inflight.get(reqId);
@@ -2344,6 +2454,7 @@ export class MoroEngineServer {
             if (this.closed) {
                 this.serverId = this.registerWithEngine();
                 this._resetTemplates();
+                this._reapplyStaticRoutes();
                 this.closed = false;
             }
             // Synchronous bind; throws on bind errors, returns the actual port