gina 0.7.1 → 0.7.2

package/framework/{v0.7.1 → v0.7.2}/core/server.js

@@ -1412,6 +1412,18 @@ function Server(options) {
                 'W/"' + crypto.createHash('sha1').update(self._clientRoutingAssets.stripped).digest('hex').substr(0, 16) + '"';
             serverOpt.clientRoutingAssets.fullEtag     = self._clientRoutingAssets.fullEtag;
             serverOpt.clientRoutingAssets.strippedEtag = self._clientRoutingAssets.strippedEtag;
+            // #P48 — per-variant routing-table tokens, the head of the same sha1 as
+            // the ETags: a routing change mints a new one, a restart with the same
+            // routes keeps it. The page names its variant's token on gina's own
+            // script tag; both engines' handlers answer `immutable` only to the
+            // token of the variant they serve (a mis-classified request fails the
+            // check and revalidates).
+            self._clientRoutingAssets.fullVersion =
+                crypto.createHash('sha1').update(self._clientRoutingAssets.full).digest('hex').substring(0, 10);
+            self._clientRoutingAssets.strippedVersion =
+                crypto.createHash('sha1').update(self._clientRoutingAssets.stripped).digest('hex').substring(0, 10);
+            serverOpt.clientRoutingAssets.fullVersion     = self._clientRoutingAssets.fullVersion;
+            serverOpt.clientRoutingAssets.strippedVersion = self._clientRoutingAssets.strippedVersion;
 
             Engine = require('./server.' + ((typeof (serverOpt.engine) != 'undefined' && serverOpt.engine != '') ? serverOpt.engine : 'express'));
             var engine = new Engine(serverOpt);
@@ -1615,6 +1627,27 @@ function Server(options) {
                 console.debug('[ BUNDLE ][ server ][ init ] Registered '+ _msvCount +' route message validator(s) for [ '+ self.appName +' ]');
             }
 
+            // #P49 — register every routing.json-declared fast-lane route at BOOT.
+            // A route opts into controller-free dispatch with `param.lane`, naming a
+            // `<bundle>/lanes/<name>.js` module whose `param.control` export answers it
+            // (`module.exports.list = function (ctx) { ... };`). lib/lane lints each
+            // route and requires its module HERE, so the request path is an O(1)
+            // registry read, and a route the lane cannot serve faithfully (route
+            // middleware, `cache`, or a gate the lane does not run yet) refuses to
+            // BOOT instead of silently losing that behaviour (the #B57 rule, as for the
+            // registrars above). A lane module edit hot-reloads in dev mode (core/gna.js
+            // watches the lane directories); a routing change needs a bundle restart.
+            var _laneConf  = self.conf[self.appName][self.env];
+            var _laneCount = lib.lane.registerRoutes(serverOpt.routing || {}, {
+                bundle      : self.appName,
+                bundlesPath : _laneConf.bundlesPath,
+                settings    : ( _laneConf.content ) ? _laneConf.content.settings : null,
+                server      : _laneConf.server
+            });
+            if ( _laneCount > 0 ) {
+                console.debug('[ BUNDLE ][ server ][ init ] Registered '+ _laneCount +' lane route(s) for [ '+ self.appName +' ]');
+            }
+
             // #COMPLY1 — lint every declared authorization flag and resolve the login
             // bounce target at BOOT. A route gates its access with `param.requireAuth`;
             // `lib/authz-gate` enforces it at both core/router.js dispatch sites.
@@ -2827,6 +2860,17 @@ function Server(options) {
                 instance._cacheName = lib.RenderCache.resolveCacheName(self.conf[self.appName][self.env].server.cache);
             }
 
+            // #P48 — the routing table's per-variant tokens (built with the maps in
+            // init, before the engine), stamped where the controller reads them to
+            // render `data-gina-routing-v` on gina's own script tag. Absent maps
+            // leave it unset: the page then fetches the table unversioned.
+            if ( typeof(instance._routingVersion) == 'undefined' && self._clientRoutingAssets ) {
+                instance._routingVersion = {
+                    full     : self._clientRoutingAssets.fullVersion,
+                    stripped : self._clientRoutingAssets.strippedVersion
+                };
+            }
+
             // #MS5 — per-authority query circuit-breaker policy, resolved ONCE
             // from the post-fold `server.query.circuitBreaker` and stamped where
             // `controller.query()` reads it (mirrors the `_cache*` scalars above;
@@ -3744,6 +3788,67 @@ function Server(options) {
         }
     }
 
+    /**
+     * Appends field names to a response's `Vary` header (RFC 9110 § 12.5.5).
+     * `Vary` is a list, so a value already set (by a middleware, by the
+     * configured `server.response.header`, or by the caller) is kept: a name
+     * already listed, in any case, is not added again, and nothing is added
+     * after a `*`, which already varies on everything. Takes one name, a
+     * comma-separated list, or an array of either, so a value read back with
+     * `getHeader('vary')` can be passed straight in to restore it. Does nothing
+     * once the headers are sent. Keep in sync with the twin in
+     * core/server.isaac.js (#B743).
+     *
+     * @inner
+     * @private
+     * @param {object} response - Server response object (HTTP/1.x, or the HTTP/2 compatibility API)
+     * @param {string|string[]|null|undefined} names - Field name(s) to add; an empty value adds nothing
+     * @returns {void}
+     *
+     * @example
+     * // Vary: Origin  →  Vary: Origin, Accept-Encoding
+     * appendVary(response, 'Accept-Encoding');
+     *
+     * @example
+     * // restore what a later setHeader('vary', …) replaced
+     * var before = response.getHeader('vary');   // 'Origin, Accept-Encoding'
+     * response.setHeader('vary', 'Origin');
+     * appendVary(response, before);              // Vary: Origin, Accept-Encoding
+     */
+    var appendVary = function(response, names) {
+        if (
+            !response
+            || typeof(response.getHeader) != 'function'
+            || typeof(response.setHeader) != 'function'
+            || response.headersSent
+        ) {
+            return;
+        }
+        var list = ( Array.isArray(names) ) ? names.join(',') : names;
+        if ( typeof(list) == 'undefined' || list === null || String(list).trim() === '' ) {
+            return;
+        }
+        var current = response.getHeader('vary');
+        if ( Array.isArray(current) ) {
+            current = current.join(', ');
+        }
+        current = ( typeof(current) == 'undefined' || current === null ) ? '' : String(current).trim();
+        var present = ( current === '' ) ? [] : current.toLowerCase().split(',').map(function(n) { return n.trim(); });
+        var added = [];
+        String(list).split(',').forEach(function(n) {
+            n = n.trim();
+            if ( n === '' || present.indexOf('*') > -1 || present.indexOf(n.toLowerCase()) > -1 ) {
+                return;
+            }
+            present.push(n.toLowerCase());
+            added.push(n);
+        });
+        if ( added.length == 0 ) {
+            return;
+        }
+        response.setHeader('vary', ( current === '' ) ? added.join(', ') : current +', '+ added.join(', '));
+    }
+
     /**
      * Returns the negotiated response protocol string (e.g. `'http/1.1'` or
      * `'http/2'`). Upgrades to `'http/2'` when the bundle is configured for
@@ -3824,6 +3929,10 @@ function Server(options) {
             , preferedEncoding = bundleConf.server.preferedCompressionEncodingOrder
             , acceptEncodingArr = (request.headers['accept-encoding']) ? request.headers['accept-encoding'].replace(/\s+/g, '').split(/\,/) : []
             , acceptEncoding = null
+            // #P48 — the content token a request asks for (`?v=`) and whether it
+            // names the bytes served (production only, set below)
+            , versionRequested = null
+            , versionMatched = false
         ;
 
         // catch `statics.json` defined paths
@@ -3965,14 +4074,53 @@ function Server(options) {
                     var lastModified = stat.mtime.toUTCString();
                     var etag = '"' + stat.size + '-' + stat.mtime.getTime() + '"';
 
+                    // #B743 — in production, HTTP/1.x serves a precompressed copy
+                    // (`.br`, `.gz`) in place of the file when the request accepts its
+                    // coding (below), so the response varies on Accept-Encoding; HTTP/2
+                    // always sends the file itself. Set before the conditional-GET
+                    // decision so the 304 carries the Vary its 200 would (RFC 9110
+                    // § 15.4.5): that includes a configured `vary`, which
+                    // completeHeaders() sets on the 200 only, read from the same block.
+                    // Appended to any Vary already set.
+                    if ( !isCacheless && !/http\/2/.test(protocol) ) {
+                        var _varyConfHeader = ( bundleConf.server.response && bundleConf.server.response.header ) ? bundleConf.server.response.header : {};
+                        for (let h in _varyConfHeader) {
+                            if ( /^vary$/i.test(h) ) {
+                                appendVary(response, _varyConfHeader[h]);
+                            }
+                        }
+                        appendVary(response, 'Accept-Encoding');
+                    }
+
                     // 304 Not Modified — only in production (dev always re-serves for live reload)
                     if (!isCacheless) {
+                        // #P48 — a gina content token (10 hex: an author's own `v=` is
+                        // left alone) is honoured only when it names THIS file's bytes:
+                        // `immutable` then, `no-cache` for any other token, today's
+                        // headers without one. Read off the original URL (request.url
+                        // is query-free here on both engines); over 8 MiB no token
+                        // matches (the lib/sri cap).
+                        versionRequested = lib.sri.getRequestedVersion(request.originalUrl || request.url);
+                        if ( versionRequested !== null && !/^[0-9a-f]{10}$/.test(versionRequested) ) {
+                            versionRequested = null;
+                        }
+                        versionMatched = ( versionRequested !== null && versionRequested === lib.sri.computeVersion(filename) ) ? true : false;
                         var ifNoneMatch     = request.headers['if-none-match'];
                         var ifModifiedSince = request.headers['if-modified-since'];
                         var isNotModified   = (ifNoneMatch && ifNoneMatch === etag)
                                             || (!ifNoneMatch && ifModifiedSince && new Date(ifModifiedSince) >= stat.mtime);
                         if (isNotModified) {
-                            if ( /http\/2/.test(protocol) ) {
+                            if ( /http\/2/.test(protocol) && versionMatched ) {
+                                // #P48 — the Cache-Control its 200 carries (RFC 9110
+                                // § 15.4.5): HTTP/2 serves the source file itself. The
+                                // other 304s carry no Cache-Control: the HTTP/1.x one is
+                                // decided before a precompressed sibling is picked, and a
+                                // 304 without it keeps what the browser stored with its
+                                // copy. (The HTTP/1.x 304 does carry the Vary set above,
+                                // #B743.)
+                                stream.respond({ ':status': 304, 'cache-control': 'public, max-age=31536000, immutable' });
+                                stream.end();
+                            } else if ( /http\/2/.test(protocol) ) {
                                 stream.respond({ ':status': 304 });
                                 stream.end();
                             } else {
@@ -4058,6 +4206,11 @@ function Server(options) {
                                 // production: ETag + Last-Modified enable conditional GET (304) (#Next)
                                 header['last-modified'] = lastModified;
                                 header['etag'] = etag;
+                                // #P48 — a token request: a year when the token names
+                                // these bytes, revalidate-before-use otherwise
+                                if ( versionRequested !== null ) {
+                                    header['cache-control'] = ( versionMatched ) ? 'public, max-age=31536000, immutable' : 'no-cache';
+                                }
                             }
 
                             header  = completeHeaders(header, request, response);
@@ -4069,7 +4222,14 @@ function Server(options) {
                             }
                         } else {
 
+                            // #B743 — completeHeaders() re-applies the configured response
+                            // headers with setHeader, so a configured `vary` replaces the
+                            // Vary set above: restore it (the 304 above carried all of it).
+                            var _varyBeforeComplete = response.getHeader('vary');
                             completeHeaders(null, request, response);
+                            if ( !isCacheless ) {
+                                appendVary(response, _varyBeforeComplete);
+                            }
                             response.setHeader('content-type', contentType +'; charset='+ bundleConf.encoding);
                             // if (/\.(woff|woff2)$/i.test(filename) )  {
                             //     response.setHeader("transfer-encoding", 'Identity')
@@ -4081,9 +4241,13 @@ function Server(options) {
 
                                 // acceptEncodingArr = request.headers['accept-encoding'].replace(/\s+/g, '').split(/\,/);
                                 // acceptEncoding = null;
+                                // #B742 — the coding's NAME (`gzip`), kept beside its file
+                                // extension (`acceptEncoding`, `.gz`): Content-Encoding takes the name.
+                                var acceptEncodingName = null;
                                 for (let e=0, eLen=preferedEncoding.length; e<eLen; e++) {
                                     if ( acceptEncodingArr && acceptEncodingArr.indexOf(preferedEncoding[e]) > -1 ) {
                                         acceptEncoding = bundleConf.server.coreConfiguration.encoding[ preferedEncoding[e] ] ;
+                                        acceptEncodingName = preferedEncoding[e];
                                         break;
                                     }
                                 }
@@ -4095,9 +4259,24 @@ function Server(options) {
                                 ) {
                                     filename += acceptEncoding;
                                     // https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Encoding
-                                    response.setHeader('content-encoding', acceptEncoding.replace(/^\./, ''));
+                                    // was: response.setHeader('content-encoding', acceptEncoding.replace(/^\./, ''));
+                                    // #B742 — the extension without its dot is not a coding name for
+                                    // gzip (`gz`), deflate (`zip`), compress (`z`) or zstd (`zst`), and
+                                    // a browser does not decode such a response.
+                                    response.setHeader('content-encoding', acceptEncodingName);
                                     // override content length
-                                    response.setHeader('content-length', fs.statSync(filename).size);
+                                    var siblingStat = fs.statSync(filename);
+                                    response.setHeader('content-length', siblingStat.size);
+                                    // #P48 — the token names the SOURCE's bytes: a sibling
+                                    // older than its source may be stale, so it is never
+                                    // served `immutable` (it revalidates instead). Compared in
+                                    // whole seconds, the resolution of Last-Modified: a
+                                    // compressor that keeps its source's timestamp truncates
+                                    // it (brotli to the second, gzip to the microsecond), so a
+                                    // sibling of the same build lands inside its source's second.
+                                    if ( versionMatched && Math.floor(siblingStat.mtimeMs / 1000) < Math.floor(stat.mtimeMs / 1000) ) {
+                                        versionMatched = false;
+                                    }
                                 }
                             }
 
@@ -4118,6 +4297,10 @@ function Server(options) {
 
                             } else {
                                 // production: ETag + Last-Modified enable conditional GET (304) (#Next)
+                                // #P48 — as the HTTP/2 branch (a stale sibling was downgraded above)
+                                if ( versionRequested !== null ) {
+                                    response.setHeader('cache-control', ( versionMatched ) ? 'public, max-age=31536000, immutable' : 'no-cache');
+                                }
                                 response.writeHead(200, {
                                     'last-modified': lastModified,
                                     'etag': etag
@@ -4546,9 +4729,8 @@ function Server(options) {
             // onInstance response, so they are inherited, not re-set.
             if (
                 request.method.toUpperCase() === 'GET'
-                // #B717 — `(?:\?|$)`: a query string no longer misses the handler (on
-                // express request.url still carries it here)
-                && /\/_gina\/assets\/routing\.json(?:\?|$)/i.test(request.url)
+                // #P48 — the path alone: a versioned fetch carries `?v=<token>`
+                && /\/_gina\/assets\/routing\.json$/i.test(request.url.split('?')[0])
                 && self._clientRoutingAssets
             ) {
                 // #B65-twin — per-request proxied classification (keep in sync with
@@ -4576,6 +4758,17 @@ function Server(options) {
                 // (usually a 304), so a restart's new route table reaches returning
                 // browsers immediately instead of after a 24h max-age window.
                 response.setHeader('cache-control', ( _croutProxied === true ) ? 'private, no-cache' : 'public, no-cache');
+                // #P48 — a request naming the token of the variant it is served (the
+                // page's `data-gina-routing-v`) may keep the table for a year: a
+                // routing change mints a new token, which the next page names. Read
+                // off the original URL (Express may have query-stripped request.url).
+                var _croutVersion = lib.sri.getRequestedVersion(request.originalUrl || request.url);
+                if (
+                    _croutVersion
+                    && _croutVersion === ( ( _croutProxied === true ) ? self._clientRoutingAssets.strippedVersion : self._clientRoutingAssets.fullVersion )
+                ) {
+                    response.setHeader('cache-control', ( ( _croutProxied === true ) ? 'private' : 'public' ) + ', max-age=31536000, immutable');
+                }
                 response.setHeader('x-content-type-options', 'nosniff');
                 response.setHeader('x-frame-options', 'DENY');
                 response.setHeader('x-xss-protection', '1; mode=block');
@@ -7409,6 +7602,8 @@ function Server(options) {
                 if ( nextMiddleware._nextAction == 'route' ) {
                     router._server = self.instance;
                     router.route(nextMiddleware._request, nextMiddleware._response, nextMiddleware._next, nextMiddleware._request.routing);
+                } else if ( nextMiddleware._nextAction == 'lane' ) { // #P49 — a fast-lane route
+                    lib.lane.dispatch(nextMiddleware._laneEntry, nextMiddleware._request, nextMiddleware._response, nextMiddleware._next, self.instance, ( self.conf[nextMiddleware._request.routing.bundle] || self.conf[self.appName] )[self.env]);
                 } else { // handle statics
                     handleStatics(nextMiddleware._staticProps, nextMiddleware._request, nextMiddleware._response, nextMiddleware._next);
                 }
@@ -7575,7 +7770,12 @@ function Server(options) {
                 for (var ph in _pending) { _sh[ph] = _pending[ph]; }
                 res.stream.respond(_sh);
                 res.stream.end(_hitContent);
-                res.headersSent = true;
+                // #B750 — `headersSent` is a getter-only accessor on the HTTP/2 compat
+                // response and already reports this send (it reads the stream's state).
+                // Assigning it threw a TypeError in this strict-mode file AFTER the body
+                // went out: on every redis L2 warm served over HTTP/2 the access-log line
+                // below was skipped and an unhandled rejection was logged instead.
+                // was: res.headersSent = true;
             }
         } else {
             if ( !res.headersSent && !res.writableEnded ) {
@@ -8297,6 +8497,12 @@ function Server(options) {
                 return;
             }
 
+            // #P49 — a fast-lane route (`param.lane`, registered at boot) skips the
+            // controller: on isaac it becomes the middleware chain's terminal, so the
+            // bundle's session and CSRF middleware still run; on express, whose app
+            // layers ran before this handler, it is dispatched directly below.
+            var _laneEntry = ( req.routing.param && req.routing.param.lane ) ? lib.lane.lookup(req.routing) : null;
+
             if ( /^isaac/.test(self.engine) && self.instance._expressMiddlewares.length > 0) {
                 installH2SendShim(res); // #B562
                 // FRAMEWORK PATCH: Bug I — per-request dispatcher
@@ -8307,12 +8513,21 @@ function Server(options) {
                 nextMiddleware._response     = res;
                 nextMiddleware._next         = next;
                 nextMiddleware._nextAction   = 'route';
+                if ( _laneEntry ) {
+                    nextMiddleware._nextAction = 'lane';
+                    nextMiddleware._laneEntry  = _laneEntry;
+                }
                 // #FI — express middleware start
                 nextMiddleware._timelineStart = (req._devTimeline) ? Date.now() : 0;
 
                 return nextMiddleware()
             }
 
+            if ( _laneEntry ) {
+                lib.lane.dispatch(_laneEntry, req, res, next, self.instance, ( self.conf[req.routing.bundle] || self.conf[self.appName] )[self.env]);
+                return;
+            }
+
             router._server = self.instance;
 
             return router.route(req, res, next, req.routing);
@@ -8494,6 +8709,13 @@ function Server(options) {
                         for (var _ejk in _pendingEJ) {
                             if (!(_ejk in header)) header[_ejk] = _pendingEJ[_ejk];
                         }
+                        // #B749 — the raw respond() below bypasses the compat response, whose
+                        // statusCode kept its default 200 (the shim swallows writeHead(code)),
+                        // so a 'finish' reader such as the metrics hook counted every HTTP/2
+                        // error as a 200. The setter throws on an invalid code, undefined
+                        // among them, which respond() still sends as 200: the send must not
+                        // depend on it.
+                        try { res.statusCode = code; } catch (e) {}
                         stream.respond(header);
                         stream.end(errBody);
                     };
@@ -8655,6 +8877,9 @@ function Server(options) {
                         for (var _ehk in _pendingEH) {
                             if (!(_ehk in header)) header[_ehk] = _pendingEH[_ehk];
                         }
+                        // #B749 — as in __ginaSendErrJSON above: the compat response must
+                        // carry the code the raw frame sends, or a 'finish' reader sees 200.
+                        try { res.statusCode = code; } catch (e) {}
                         stream.respond(header);
                         stream.end(errBody);
                     };

package/framework/{v0.7.1 → v0.7.2}/core/template/boilerplate/bundle/index.js

@@ -35,7 +35,8 @@ var ${bundle} = require('gina');
 //    // Configure connectors.json: { "session": { "connector": "redis", "host": "...", "port": 6379, "ttl": 86400 } }
 //    //
 //    // SQLite — dev / staging / single-pod (requires: Node >= 22.5.0, zero npm deps)
-//    // Configure connectors.json: { "session": { "connector": "sqlite", "database": ":memory:", "ttl": 86400 } }
+//    // Configure connectors.json: { "session": { "connector": "sqlite", "file": ":memory:", "ttl": 86400 } }
+//    // (a file path, e.g. "/var/lib/myapp/sessions.db", also goes in "file", never in "database")
 //    //
 //    // The store factory keys on express-session's function name — the literal
 //    // "session", which is read-only and cannot be re-pointed — so the

package/framework/{v0.7.1 → v0.7.2}/core/template/conf/templates.json

@@ -27,6 +27,7 @@
     ],
     "javascriptsDeferEnabled": true, // will place scripts in defer mode in the head by default. If false, will place in the footer
     "sriEnabled": false, // opt-in Subresource Integrity: adds integrity= + crossorigin= to same-origin <script>/<link> tags whose files resolve on disk; external URLs and unresolvable paths are skipped (fail-open)
+    "assetVersioningEnabled": true, // #P48: appends ?v=<10 hex of the file's sha384> to the same-origin asset URLs gina emits (tags + their preload hints) so they can be cached for a year; false keeps today's URLs. Never applied to js external plugins, layoutless renders or dev (fail-open: an unresolvable file keeps its plain URL)
     "javascripts": [
       {
         "name"      : "gina",

package/framework/{v0.7.1 → v0.7.2}/lib/cmd/bundle/inc/name.js

@@ -31,7 +31,7 @@ var scopeName = require('../../scope/inc/name');
  *
  * @example
  *  isValidBundleName('api');           // true
- *  isValidBundleName('design-system'); // true
+ *  isValidBundleName('my-app');        // true
  *  isValidBundleName('Admin');         // false — starts with an uppercase letter
  *  isValidBundleName('a$b');           // false — `$` is not allowed
  *  isValidBundleName('constructor');   // false — every object inherits it

package/framework/{v0.7.1 → v0.7.2}/lib/cmd/project/inc/name.js

@@ -32,7 +32,7 @@ var scopeName = require('../../scope/inc/name');
  *
  * @example
  *  isValidProjectName('myproject');     // true
- *  isValidProjectName('design-system'); // true
+ *  isValidProjectName('my-app');        // true
  *  isValidProjectName('Myproject');     // false — starts with an uppercase letter
  *  isValidProjectName('..');            // false — its home would be ~/..
  *  isValidProjectName('constructor');   // false — every object inherits it

package/framework/v0.7.2/lib/error-ref/package.json

@@ -0,0 +1,7 @@
+{
+    "name": "error-ref",
+    "description": "#ERRREF incident-ref mint for error responses answered outside a controller: honours a relay-safe caller-supplied ref, else mints 6 uppercase hex characters",
+    "version": "0.0.1",
+    "private": true,
+    "main": "src/main"
+}

package/framework/v0.7.2/lib/error-ref/src/main.js

@@ -0,0 +1,70 @@
+/*
+ * This file is part of the gina package.
+ * Copyright (c) 2009-2026 Rhinostone <contact@gina.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+'use strict';
+
+/**
+ * @module gina/lib/error-ref
+ *
+ * #ERRREF — the incident-ref mint for error responses answered outside a
+ * controller (the fast lane, #P49, is its first caller).
+ *
+ * Every JSON error body carries a top-level `ref`: a short correlation code an
+ * end user can relay by voice or typing, paired server-side with the full error
+ * detail in ONE log line. A caller-supplied ref is honoured when it is
+ * relay-safe — 1 to 32 word characters, dots or dashes, the same bounded-length,
+ * restricted-charset discipline as an inbound `X-Request-Id`, which keeps it out
+ * of reach of log forging — and anything else gets a fresh mint of 6 uppercase
+ * hex characters (`crypto.randomBytes(3)`).
+ *
+ * The controller (`core/controller/controller.js`) and the server
+ * (`core/server.js`) keep their own byte-identical copies of this rule: the
+ * controller is evicted per request in dev mode, and both copies are pinned by
+ * `test/core/error-ref.test.js`. `test/lib/error-ref.test.js` drives this module
+ * against the controller's copy so the three cannot drift apart.
+ *
+ * Server-side only, stateless; plain-required by the registry (`lib.errorRef`).
+ */
+
+var crypto = require('crypto');
+
+/**
+ * The relay-safe shape a caller-supplied ref must match to be honoured.
+ *
+ * @constant
+ * @type {RegExp}
+ * @private
+ */
+var RELAY_SAFE = /^[\w.\-]{1,32}$/;
+
+/**
+ * Return the caller's ref when it is relay-safe, else mint a fresh one.
+ *
+ * Never throws; any non-string `supplied` (undefined, null, a number, an
+ * object) mints.
+ *
+ * @memberof module:gina/lib/error-ref
+ * @param {string} [supplied] - A caller- or producer-provided ref candidate
+ * @returns {string} `supplied` when relay-safe, else 6 fresh uppercase hex characters
+ *
+ * @example
+ * var errorRef = require('gina').lib.errorRef;
+ * errorRef.mint();                 // 'A1B2C3' — fresh, random
+ * errorRef.mint('ORDER-42');       // 'ORDER-42' — honoured
+ * errorRef.mint('bad ref!');       // '9F0E1D' — space and `!` are refused, so a fresh mint
+ * errorRef.mint('x'.repeat(33));   // a fresh mint — 33 characters is over the 32 cap
+ */
+function mint(supplied) {
+    if ( typeof(supplied) == 'string' && RELAY_SAFE.test(supplied) ) {
+        return supplied;
+    }
+    return crypto.randomBytes(3).toString('hex').toUpperCase();
+}
+
+module.exports = {
+    mint : mint
+};

package/framework/{v0.7.1 → v0.7.2}/lib/index.js

@@ -260,6 +260,18 @@ function Lib() {
         // PLAIN require, like rate-limit/idempotency: router-bound, load-once, and
         // its registry lives on process.gina (survives refreshCore, dies on restart).
         messageValidator : require('./message-validator'),
+        // #P49 — the fast lane: the param.lane boot registry, the handler context and
+        // its JSON/error writers, dispatched by core/server.js at the end of the
+        // middleware chain. PLAIN require, like the router-bound gates above:
+        // core/server.js captures it at load, it performs no per-request require()
+        // of a hot-reloaded sibling (#B32-residual), and its registry lives on
+        // process.gina (survives refreshCore, dies on restart). Its dev-mode reload of
+        // the lane handler modules is its own, gated on the #M6 watcher flag.
+        lane            : require('./lane'),
+        // #ERRREF — the incident-ref mint for errors answered outside a controller
+        // (the lane's error writer). Stateless; PLAIN require because the lane, a
+        // load-once module, binds it at load.
+        errorRef        : require('./error-ref'),
         // Per-bundle login session cookie lifetimes declared in security.json
         // (`session.expires` / `session.remember`), applied by core/router.js at
         // req.login(). PLAIN require, like the router-bound gates above: load-once,

package/framework/v0.7.2/lib/lane/package.json

@@ -0,0 +1,7 @@
+{
+    "name": "lane",
+    "description": "The fast lane: opt-in, controller-free dispatch for JSON routes (param.lane), with its boot registry, request context and JSON/error writers",
+    "version": "0.0.1",
+    "private": true,
+    "main": "src/main"
+}