@zero-server/core 1.0.2 → 1.1.0

package/lib/app.js

@@ -172,6 +172,24 @@ class App
      *   before calling `fn` so downstream sees relative paths).
      * - `use('/prefix', router)` - mount a Router sub-app at the given prefix.
      *
+     * Route matching order: the app matches its OWN verb routes (those declared
+     * with `app.get()`, `app.post()`, etc.) BEFORE probing any `use()`-mounted
+     * child routers. An app-level catch-all like `app.get('/*', ssr)` therefore
+     * shadows every mounted router. Give a catch-all its own child router and
+     * mount it LAST so real routes win:
+     *
+     * @example | Catch-all that does not shadow mounted routers
+     *   const { createApp, Router } = require('@zero-server/sdk');
+     *   const app = createApp();
+     *
+     *   const api = Router();
+     *   api.get('/users', listUsers);
+     *   app.use('/api', api);            // real routes
+     *
+     *   const ssr = Router();
+     *   ssr.get('/*', renderApp);        // SPA / SSR fallback
+     *   app.use('/', ssr);               // mounted LAST - only handles what /api did not
+     *
      * @param {string|Function}       pathOrFn - A path prefix string, or middleware function.
      * @param {Function|Router}       [fn]     - Middleware function or Router when first arg is a path.
      */

package/lib/router/index.js

@@ -75,6 +75,13 @@ class Router
         this.routes = [];
         /** @type {{ prefix: string, router: Router }[]} */
         this._children = [];
+        /**
+         * Router-level middleware. Each entry runs before the handlers of any
+         * matching route in this router (and in mounted child routers), in
+         * registration order.
+         * @type {{ prefix: string|null, handler: Function }[]}
+         */
+        this._middleware = [];
         /**
          * Parameter pre-processing handlers (set by parent App).
          * @type {Object<string, Function[]>}
@@ -104,23 +111,82 @@ class Router
     }
 
     /**
-     * Mount a child Router under a path prefix.
-     * Requests matching the prefix are delegated to the child router with
-     * the prefix stripped from `req.url`.
+     * Register router-level middleware or mount a child Router.
+     *
+     * Three forms are supported:
+     * - `use(fn, ...fns)` - middleware that runs before the handlers of every
+     *   matching route in this router (and its mounted children).
+     * - `use(prefix, fn, ...fns)` - middleware scoped to routes whose path is at
+     *   or below `prefix`.
+     * - `use(prefix, router)` - mount a child Router under a path prefix.
+     *   Requests matching the prefix are delegated to the child router with the
+     *   prefix stripped from `req.url`.
+     *
+     * Middleware runs as part of the matched route's handler chain, so it only
+     * executes when a route actually matches (a 404 runs no middleware). This
+     * makes it a natural fit for auth/feature guards. Unlike the earlier
+     * releases, passing a function is no longer silently ignored - an
+     * unsupported argument shape throws a `TypeError`.
      *
-     * @param {string} prefix - Path prefix (e.g. '/api').
-     * @param {Router} router - Child router instance.
+     * @param {string|Function} prefixOrFn - Path prefix, or a middleware function.
+     * @param {...(Function|Router)} rest  - A child `Router`, or one or more middleware functions.
      * @returns {Router} `this` for chaining.
+     * @throws {TypeError} When the argument shape is not one of the supported forms.
      */
-    use(prefix, router)
+    use(prefixOrFn, ...rest)
     {
-        if (typeof prefix === 'string' && router instanceof Router)
+        // use(prefix, router) - mount a child router
+        if (typeof prefixOrFn === 'string' && rest.length === 1 && rest[0] instanceof Router)
         {
-            const cleanPrefix = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
-            this._children.push({ prefix: cleanPrefix, router });
+            const cleanPrefix = prefixOrFn.endsWith('/') ? prefixOrFn.slice(0, -1) : prefixOrFn;
+            this._children.push({ prefix: cleanPrefix, router: rest[0] });
             log.debug('mounted child router at %s', cleanPrefix);
+            return this;
+        }
+
+        // use(fn, ...fns) - global router middleware
+        if (typeof prefixOrFn === 'function')
+        {
+            for (const fn of [prefixOrFn, ...rest])
+            {
+                if (typeof fn !== 'function')
+                    throw new TypeError('Router.use(): every middleware argument must be a function');
+                this._middleware.push({ prefix: null, handler: fn });
+            }
+            log.debug('registered %d router middleware', 1 + rest.length);
+            return this;
+        }
+
+        // use(prefix, fn, ...fns) - prefix-scoped router middleware
+        if (typeof prefixOrFn === 'string' && rest.length > 0 && rest.every(f => typeof f === 'function'))
+        {
+            const cleanPrefix = prefixOrFn.endsWith('/') ? prefixOrFn.slice(0, -1) : prefixOrFn;
+            for (const fn of rest) this._middleware.push({ prefix: cleanPrefix, handler: fn });
+            log.debug('registered %d router middleware at %s', rest.length, cleanPrefix);
+            return this;
+        }
+
+        throw new TypeError(
+            'Router.use() expects use(fn), use(prefix, fn), or use(prefix, router)'
+        );
+    }
+
+    /**
+     * Collect the router-level middleware whose scope matches a path.
+     * @param {string} url - Router-local request path (query already stripped).
+     * @returns {Function[]} Applicable middleware handlers in registration order.
+     * @private
+     */
+    _applicableMiddleware(url)
+    {
+        if (this._middleware.length === 0) return [];
+        const out = [];
+        for (const m of this._middleware)
+        {
+            if (m.prefix === null || url === m.prefix || url.startsWith(m.prefix + '/'))
+                out.push(m.handler);
         }
-        return this;
+        return out;
     }
 
     /**
@@ -159,15 +225,20 @@ class Router
      *
      * @param {import('./request')}  req - HTTP request object.
      * @param {import('./response')} res - HTTP response object.
+     * @param {Function[]} [inherited] - Middleware inherited from parent routers,
+     *        already resolved as applicable to this request.
      * @returns {boolean} Boolean result.
      * @private
      */
-    _matchAndExecute(req, res)
+    _matchAndExecute(req, res, inherited = [])
     {
         const method = req.method.toUpperCase();
         const url = req.url.split('?')[0];
         log.debug('%s %s', method, url);
 
+        // Middleware applicable at this router for the current path
+        const ownMiddleware = this._applicableMiddleware(url);
+
         // Try own routes first
         for (let ri = 0; ri < this.routes.length; ri++)
         {
@@ -248,8 +319,37 @@ class Router
                 }
             };
 
-            if (paramCount > 0) runParams();
-            else runHandlers();
+            // Middleware (inherited from parents, then this router's own) runs
+            // ahead of param handlers and route handlers. A middleware that
+            // sends a response without calling next() short-circuits the chain.
+            const middleware = inherited.length || ownMiddleware.length
+                ? [...inherited, ...ownMiddleware]
+                : null;
+            const startChain = () => (paramCount > 0 ? runParams() : runHandlers());
+
+            if (middleware)
+            {
+                let mIdx = 0;
+                const runMiddleware = () =>
+                {
+                    if (mIdx < middleware.length)
+                    {
+                        const fn = middleware[mIdx++];
+                        try
+                        {
+                            const result = fn(req, res, runMiddleware);
+                            if (result && typeof result.catch === 'function')
+                            {
+                                result.catch(e => this._handleRouteError(e, req, res));
+                            }
+                        }
+                        catch (e) { this._handleRouteError(e, req, res); }
+                    }
+                    else { startChain(); }
+                };
+                runMiddleware();
+            }
+            else { startChain(); }
             return true;
         }
 
@@ -262,11 +362,21 @@ class Router
                 const origUrl = req.url;
                 const origBaseUrl = req.baseUrl || '';
                 req.baseUrl = origBaseUrl + child.prefix;
-                req.url = req.url.slice(child.prefix.length) || '/';
+                // Keep the query string attached to a normalized path: a
+                // request for exactly the mount prefix plus a query
+                // ('/api/files?x=1') must delegate as '/?x=1', not '?x=1'.
+                const rest = req.url.slice(child.prefix.length);
+                req.url = rest === '' || rest.startsWith('?') ? '/' + rest : rest;
                 child.router._paramHandlers = this._paramHandlers;
+                // Carry this router's applicable middleware down so mounted
+                // routes are guarded too. Applicability is resolved here, against
+                // the parent-relative URL, before the prefix is stripped.
+                const childInherited = inherited.length || ownMiddleware.length
+                    ? [...inherited, ...ownMiddleware]
+                    : inherited;
                 try
                 {
-                    const found = child.router._matchAndExecute(req, res);
+                    const found = child.router._matchAndExecute(req, res, childInherited);
                     if (found) return true;
                 }
                 catch (e) { this._handleRouteError(e, req, res); return true; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zero-server/core",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "App factory, Router, and the HTTP Request/Response wrappers.",
   "keywords": [
     "zero-server",
@@ -45,14 +45,14 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@zero-server/realtime": "1.0.2",
-    "@zero-server/grpc": "1.0.2",
-    "@zero-server/lifecycle": "1.0.2",
-    "@zero-server/observe": "1.0.2",
-    "@zero-server/auth": "1.0.2"
+    "@zero-server/realtime": "1.1.0",
+    "@zero-server/grpc": "1.1.0",
+    "@zero-server/lifecycle": "1.1.0",
+    "@zero-server/observe": "1.1.0",
+    "@zero-server/auth": "1.1.0"
   },
   "peerDependencies": {
-    "@zero-server/sdk": ">=1.0.2"
+    "@zero-server/sdk": ">=1.1.0"
   },
   "peerDependenciesMeta": {
     "@zero-server/sdk": {