gina 0.6.8 → 0.6.9

package/framework/{v0.6.8 → v0.6.9}/core/server.express.js

@@ -14,10 +14,16 @@
  * **Inspector endpoints:** This file has no `/_gina/*` handlers.
  * `server.js` registers all Inspector endpoints (`/_gina/inspector/*`,
  * `/_gina/logs`, `/_gina/agent`) on the Express `app` instance returned
- * here, inside its `onRequest()` catch-all (`self.instance.all('*', ...)`).
+ * here, inside its `onRequest()` catch-all (`self.instance.all(/(.*)/, ...)`
+ * — a RegExp since #B211, because Express 5's router rejects the former
+ * bare-string `'*'` at mount time).
  * No fast-path is needed in this adapter because Express request handling
  * already flows through `server.js`.
  *
+ * **Supported Express range: >= 4 < 6** (#B211 — both majors verified live;
+ * an out-of-range major logs a loud warning at engine construction and
+ * boots anyway).
+ *
  * @class ServerEngineClass
  * @constructor
  * @param {object} options - Server configuration
@@ -246,6 +252,39 @@ function ServerEngineClass(options) {
 
 
 
+    // #B211 — Express version awareness. The supported range is declared HERE
+    // (express is consumer-provided by design — deliberately NOT a dependency,
+    // and NEVER a peerDependency: npm >= 7 auto-installs peers, which would
+    // force express onto every consumer of the framework).
+    var expressVersion = 'unknown';
+    try {
+        expressVersion = require('express/package.json').version;
+    } catch (_e) { /* best effort — version display only */ }
+    var expressMajor = parseInt(expressVersion, 10);
+    console.info('engine: express v' + expressVersion + ' (supported: >= 4 < 6)');
+    if ( !isNaN(expressMajor) && (expressMajor < 4 || expressMajor >= 6) ) {
+        // WARN, never refuse (gate decision 2026-08-15): an unverified future
+        // major may work, and a wrong refusal is a total outage while a wrong
+        // warning is a log line. Verified majors: 4 and 5.
+        console.warn('engine: express v' + expressVersion + ' is OUTSIDE the verified range (>= 4 < 6) — the bundle will boot, but this combination is unverified; pin express@^4 or express@^5 if anything misbehaves.');
+    }
+
+    // #B211 — Express 5 defines `req.query` as a prototype GETTER (v4 assigned
+    // it from its auto-mounted query middleware as an own property). Gina's
+    // request pipeline (core/server.js) computes and ASSIGNS `request.query`
+    // itself under 'use strict', which throws
+    //   TypeError: Cannot set property query ... which has only a getter
+    // on every request under Express 5. Shadowing the getter with a writable
+    // own DATA property on the per-app request prototype restores gina's
+    // owns-the-query-parse contract; on Express 4 the property does not exist
+    // on the prototype chain as a getter, so this is a measured no-op there.
+    Object.defineProperty(app.request, 'query', {
+        value: undefined,
+        writable: true,
+        configurable: true,
+        enumerable: false
+    });
+
     return {
         instance: app,
         middleware: express

package/framework/{v0.6.8 → v0.6.9}/core/server.isaac.js

@@ -2610,8 +2610,93 @@ function ServerEngineClass(options) {
 
         server.eio = ioServer;
 
+        /**
+         * #B365 — derive a socket's session SERVER-side, from the upgrade
+         * request's own cookie, and bind it to `socket.sessionId`.
+         *
+         * The socket's identity used to be whatever the client asserted in a
+         * message payload. Rather than re-implement cookie unsigning here —
+         * which would mean handing the framework the session secret that today
+         * lives entirely in bundle code — this replays the bundle's OWN session
+         * middleware over the upgrade request. Same secret, same store, same
+         * cookie name, no configuration, and it works whether or not the bundle
+         * adopted `gina.plugins.Session()`.
+         *
+         * The response passed to it is inert: every header/write method is a
+         * no-op, so a `Set-Cookie` can never be emitted from a socket upgrade.
+         * Combined with never touching the session object, a `saveUninitialized:
+         * false` setup creates and saves nothing.
+         *
+         * Fail CLOSED: no session middleware, no cookie, or a cookie that does
+         * not verify leaves `sessionId` unset, and an unset id matches no
+         * targeted push — such a socket receives only deliberate broadcasts.
+         *
+         * @inner
+         * @private
+         * @param {object}   socket - The engine.io socket (carries `.request`).
+         * @param {function} [cb]   - Called with the bound id (or null) once resolved.
+         * @returns {void}
+         */
+        var bindSocketSession = function(socket, cb) {
+            var done = ( typeof(cb) == 'function' ) ? cb : function() {};
+            var req  = socket.request;
+            if ( req == null || !server._expressMiddlewares || !server._expressMiddlewares.length ) {
+                return done(null);
+            }
+            // express-session's middleware is a NAMED function expression
+            // (`return function session(req, res, next)`), and the gina wrapper's
+            // absolute-timeout variant is `ginaSessionAbsoluteTimeout` — both are
+            // matched here so an adopting and a non-adopting bundle behave alike.
+            var chain = [];
+            for (var i = 0, len = server._expressMiddlewares.length; i < len; ++i) {
+                var fn = server._expressMiddlewares[i];
+                if ( typeof(fn) == 'function' && /^(session|ginaSessionAbsoluteTimeout)$/.test(fn.name) ) {
+                    chain[chain.length] = fn;
+                }
+            }
+            if ( !chain.length ) {
+                return done(null);
+            }
+            var noop     = function() { return inertRes; };
+            var inertRes = {
+                setHeader: noop, getHeader: function() { return undefined; },
+                removeHeader: noop, appendHeader: noop, writeHead: noop,
+                write: function() { return true; }, end: noop,
+                on: noop, once: noop, emit: function() { return false; },
+                headersSent: false, finished: false
+            };
+            var idx = 0;
+            var next = function(err) {
+                if (err) {
+                    console.warn('[IO SERVER ] could not derive a session for socket #'+ socket.id +': '+ (err.message || err));
+                    return done(null);
+                }
+                if ( idx >= chain.length ) {
+                    var sid = ( typeof(req.sessionID) != 'undefined' && req.sessionID ) ? req.sessionID : null;
+                    if (sid) {
+                        socket.sessionId = sid;
+                    }
+                    return done(sid);
+                }
+                var mw = chain[idx++];
+                try {
+                    mw(req, inertRes, next);
+                } catch (mwErr) {
+                    console.warn('[IO SERVER ] session middleware threw while deriving a socket session: '+ (mwErr.message || mwErr));
+                    return done(null);
+                }
+            };
+            next();
+        };
+
         ioServer.on('connection', function (socket) {
 
+            // #B365 — bind identity from the connection's own cookie before any
+            // message can assert one. Asynchronous (the session store is), so a
+            // push racing the handshake simply finds no match yet.
+            bindSocketSession(socket);
+
+
             socket.send(JSON.stringify({
                 id: this.id,//socket.id,
                 handshake: 'Welcomed to `'+ options.bundle +'` main socket !',
@@ -2638,9 +2723,31 @@ function ServerEngineClass(options) {
                 try {
                     console.debug('[IO SERVER ] receiving '+ payload);
                     payload = JSON.parse(payload);
-                    // bind to session ID
-                    if ( typeof(payload.session) != 'undefined' ) {
-                        this.sessionId = payload.session.id;
+                    // #B365 — the recipient of a targeted push is resolved from
+                    // `socket.sessionId`, and that used to be set RIGHT HERE from
+                    // `payload.session.id`: a value the CLIENT sends, on every
+                    // message, never checked against the connection's own session.
+                    // Any client could claim another user's session and receive
+                    // the pushes addressed to it — and the page renders the BARE
+                    // session id into its bootstrap script, so claiming one needed
+                    // strictly less than stealing the cookie.
+                    //
+                    // The binding now happens once, server-side, at connection
+                    // (see bindSocketSession below) from the upgrade request's own
+                    // signed cookie. What is left here is a DETECTOR: a client that
+                    // still asserts an id we did not derive gets logged and ignored.
+                    if (
+                        typeof(payload.session) != 'undefined'
+                        && payload.session != null
+                        && typeof(payload.session.id) != 'undefined'
+                        && payload.session.id !== this.sessionId
+                    ) {
+                        console.warn(
+                            '[IO SERVER ] socket #'+ this.id +' asserted session `'+ payload.session.id
+                            + '` which does not match the session derived from its own cookie'
+                            + ( this.sessionId ? ' (`'+ this.sessionId +'`)' : ' (none)' )
+                            + '. Ignoring the assertion (#B365).'
+                        );
                     }
                     // Inspector: respond to data pull request. #INS10 — the engine.io
                     // channel is UNAUTHENTICATED, so never serve the captured snapshot

package/framework/{v0.6.8 → v0.6.9}/core/server.js

@@ -4029,10 +4029,20 @@ function Server(options) {
 
 
     /**
-     * Attaches the catch-all `*` route handler to the server instance.
+     * Attaches the catch-all route handler to the server instance.
      * Handles statics, preflight (CORS OPTIONS), body parsing, Express
      * middleware chain, and final routing delegation to the Router.
      *
+     * The catch-all pattern is ENGINE-CONDITIONAL (#B211): Express mounts a
+     * RegExp — Express 5 routes through path-to-regexp v8, which rejects a
+     * bare `'*'` path string at mount time (`TypeError: Missing parameter
+     * name`), while a RegExp path bypasses string parsing on Express 4 AND 5,
+     * measured live-dispatching `/`, `/web/` and deep paths on both majors.
+     * Isaac KEEPS the string `'*'`: its request listener's dispatch gate is
+     * `path === '*' || path == request.url` (server.isaac.js:2366), so a
+     * RegExp there matches NOTHING and every request hangs without a
+     * response — measured, a deterministic container-boot timeout.
+     *
      * @inner
      * @private
      * @returns {void}
@@ -4043,7 +4053,11 @@ function Server(options) {
         var webrootLen = self.conf[self.appName][self.env].server.webroot.length;
 
         // catch all (request urls)
-        self.instance.all('*', function onInstance(request, response, next) {
+        // #B211 — was: self.instance.all('*', ...) unconditionally. Express 5's
+        // router rejects the bare-string wildcard at mount (boot abort before
+        // listen()); isaac's dispatch gate REQUIRES it (see the JSDoc above).
+        var catchAllPattern = ( /^express/.test(self.engine) ) ? /(.*)/ : '*';
+        self.instance.all(catchAllPattern, function onInstance(request, response, next) {
 
             // #M12b / #COMPLY2 — stamp the request id + entry time at request entry.
             //

package/framework/{v0.6.8 → v0.6.9}/helpers/path.js

@@ -674,12 +674,20 @@ function PathHelper() {
      *
      *  })
      *
-     * @ram {string} target
+     * @param {string} target
      * @param {array} [ excluded ] - Excluded list
      *
      * @callback callback
-     * @param {string} errResponse
+     * @param {boolean|Error} errResponse - `false` on success, an `Error` on
+     *      failure (#B227 — was a plain string on stream-copy failures)
      * @param {string} [pathResponse]
+     *
+     * @example
+     *  // copy a file, overwriting the destination atomically
+     *  new _('/tmp/a.txt').cp('/tmp/b.txt', function(err, destination) {
+     *      if (err) return console.error(err.stack);
+     *      console.log('copied to ' + destination);
+     *  });
      * */
 
     _.prototype.cp = function(target, excluded, cb) {
@@ -1056,11 +1064,13 @@ function PathHelper() {
      * @param {string} source
      * @param {string} destination
      * @param {number} [i]
-     * @param {number} [fileCount]
+     * @param {Array} [excluded] - Filenames (strings) or RegExps to skip
      *
      * @callback callback
-     * @param {bool|string} err
-     *
+     * @param {boolean|Error} err - `false` on success, an `Error` on failure
+     *                              (was a plain string pre-#B227)
+     * @param {string} source
+     * @param {number} i
      * */
     var copyFileToFile = function(source, destination, i, callback, excluded) {
         var isExcluded = false;
@@ -1096,21 +1106,32 @@ function PathHelper() {
                         destination += path
                     }
 
-                    exists(destination, function(replaceFlag) {
-                        if (replaceFlag) {
-                            fs.unlink(destination, function(err) {
-                                //TODO - log error.
-                                startCopy(source, destination, i, function(err, i) {
-
-                                    callback(err, source, i)
-                                })
-                            })
-                        } else {
-                            startCopy(source, destination, i, function(err, i) {
-                                //TODO - log error.
-                                callback(err, source, i)
-                            })
-                        }
+                    // #B227 — no destination pre-delete: copyFile now stages to a
+                    // temp sibling and publishes with an atomic rename, which
+                    // replaces an existing destination only once the new content is
+                    // fully written. The unlink below destroyed the previous content
+                    // BEFORE the copy had succeeded (a 404/zero-byte window, and a
+                    // copy failure after it left nothing at all) — and its own error
+                    // was silently discarded.
+                    // was:
+                    // exists(destination, function(replaceFlag) {
+                    //     if (replaceFlag) {
+                    //         fs.unlink(destination, function(err) {
+                    //             //TODO - log error.
+                    //             startCopy(source, destination, i, function(err, i) {
+                    //
+                    //                 callback(err, source, i)
+                    //             })
+                    //         })
+                    //     } else {
+                    //         startCopy(source, destination, i, function(err, i) {
+                    //             //TODO - log error.
+                    //             callback(err, source, i)
+                    //         })
+                    //     }
+                    // })
+                    startCopy(source, destination, i, function(err, i) {
+                        callback(err, source, i)
                     })
                 }//EO if (err)
             })
@@ -1129,18 +1150,70 @@ function PathHelper() {
         }
     }
 
+    /**
+     * Copy one file's bytes — the writer behind `_.cp()` / `PathObject.mv()`
+     *
+     * #B227 — mirrors the #B223 `movefiles` rework: bytes land in a temp
+     * sibling inside the destination's own directory (so the publish rename
+     * is always same-filesystem, while the stream copy itself may cross
+     * filesystems) and publish atomically via `renameSync`, so a reader can
+     * never observe a truncated destination and a failed copy never destroys
+     * the previous content.
+     *
+     * @inner
+     * @param {string} source
+     * @param {string} destination
+     * @param {number} i - Caller's iteration cursor, passed back untouched
+     *
+     * @callback callback
+     * @param {boolean|Error} err - `false` on success, an `Error` on failure
+     *                              (was a plain string pre-#B227)
+     * @param {number} i
+     * */
     var copyFile = function(source, destination, i, callback) {
 
+        var _tmpTarget  = destination + '.' + process.pid + '.' + Math.random().toString(36).slice(2, 8) + '.tmp';
+        var _settled    = false;
+
         var sourceStream = fs.createReadStream(source);
-        var destinationStream = fs.createWriteStream(destination);
+        // #B227 — no direct write to the final name
+        // was: var destinationStream = fs.createWriteStream(destination);
+        var destinationStream = fs.createWriteStream(_tmpTarget);
+
+        var onCopyError = function(err) {
+            if (_settled) return;
+            _settled = true;
+            try { destinationStream.destroy() } catch (_e) {}
+            try { if ( fs.existsSync(_tmpTarget) ) fs.unlinkSync(_tmpTarget) } catch (_e) {}
+            // #B227 — propagate a real Error (was a plain string, so callers
+            // printing `err.stack` logged `undefined`); keep the historical
+            // message prefix for log continuity
+            if ( !(err instanceof Error) ) {
+                err = new Error('Error on Path.cp(...): could not copy `'+ source +'` to `'+ destination +'`');
+            }
+            callback(err, i)
+        };
+
+        // #B227 — the source stream previously had NO error listener: an
+        // unreadable/vanished source raised an unhandled 'error' event
+        // (uncaughtException → process kill)
+        sourceStream.on('error', onCopyError);
 
         sourceStream
             .pipe(destinationStream)
-            .on('error', function() {
-                var err = 'Error on Path.cp(...): Not found ' + source +' or ' + destination;
-                callback(err, i)
-            })
+            .on('error', onCopyError)
             .on('close', function() {
+                // 'close' also follows 'error' on an autoDestroyed stream — the
+                // settled latch keeps a failed copy from settling the callback a
+                // SECOND time as a success (the pre-fix shape did exactly that,
+                // and in browseCopy's recursion each double-settle forked the
+                // directory walk)
+                if (_settled) return;
+                try {
+                    fs.renameSync(_tmpTarget, destination);
+                } catch (err) {
+                    return onCopyError(err)
+                }
                 callback(false, i)
             })
     }
@@ -1149,11 +1222,20 @@ function PathHelper() {
     /**
      * move or rename, file or folder
      *
+     * Implemented as `cp()` then `rm(source)` — the byte-writer is `copyFile`,
+     * so the #B227 temp+rename semantics apply here too.
+     *
      * @param {string} target
      *
      * @callback callback
-     * @param {string} errResponse
+     * @param {boolean|Error} errResponse - `false`/falsy on success, an `Error`
+     *      on failure (#B227 — was a plain string on stream-copy failures)
      * @param {string} [pathResponse]
+     *
+     * @example
+     *  new _('/tmp/staged.pdf').mv('/var/shared/final.pdf', function(err) {
+     *      if (err) return console.error(err.stack);
+     *  });
      * */
 
     _.prototype.mv = function(target, callback) {

package/framework/{v0.6.8 → v0.6.9}/lib/cmd/bundle/build.js

@@ -82,6 +82,33 @@ function Build(opt, cmd) {
         // Getting manifest
         local.manifest = JSON.clone(self.projectData);
 
+        // #B373 — per-scope deployment. `bundles[<name>].scopes` is an optional
+        // allow-list (absent = every scope). This verb targets ONE bundle by name,
+        // so an excluded target is an EXPLICIT ask for something the manifest says
+        // is not deployed here — refuse by name rather than silently producing no
+        // artifact, which on a deploy script would read as success.
+        var _buildTargets = ( self.bundles || [] ).slice();
+        for (let _b = 0, _bLen = _buildTargets.length; _b < _bLen; ++_b) {
+            let _target = _buildTargets[_b]
+                , _entry = local.manifest.bundles[_target]
+            ;
+            if ( !_entry ) {
+                continue;
+            }
+            if (
+                typeof(_entry.scopes) != 'undefined' && _entry.scopes !== null
+                && !Array.isArray(_entry.scopes)
+            ) {
+                return end( new Error('[ manifest ] `bundles.'+ _target +'.scopes` must be an array of scope names (got '+ typeof(_entry.scopes) +'). Remove the key to deploy `'+ _target +'` in every scope, or list the scopes it belongs to.') );
+            }
+            if ( Array.isArray(_entry.scopes) && _entry.scopes.indexOf(process.env.NODE_SCOPE) < 0 ) {
+                return end( new Error('Cannot build `'+ _target +'` for scope `'+ process.env.NODE_SCOPE +'`: the bundle is not deployed there. '
+                    + '`bundles.'+ _target +'.scopes` in manifest.json declares '
+                    + ( _entry.scopes.length ? '`'+ _entry.scopes.join('`, `') +'`' : 'no scope at all' )
+                    + '. Add `'+ process.env.NODE_SCOPE +'` to that list to build it here.') );
+            }
+        }
+
         globalBuildScripts = ( typeof(local.manifest.buildScripts) != 'undefined' ) ? local.manifest.buildScripts : null;
 
         // User Pre build
@@ -164,6 +191,16 @@ function Build(opt, cmd) {
             // per scope
             for (let i = 0, len = local.scopes.length; i < len; i++) {
                 let scope = local.scopes[i]
+                // #B373 — do not seed a scope the bundle opts out of. This loop walks
+                // EVERY project scope (not just --scope), so without the filter it
+                // re-creates the release entries the allow-list exists to remove, and
+                // the opt-out silently regrows on the next build.
+                if (
+                    Array.isArray(local.manifest.bundles[bundle].scopes)
+                    && local.manifest.bundles[bundle].scopes.indexOf(scope) < 0
+                ) {
+                    continue;
+                }
                 if ( typeof(local.manifest.bundles[bundle].releases[scope]) == 'undefined' ) {
                     local.manifest.bundles[bundle].releases[scope] = {}
                 }