gina 0.5.4 → 0.5.5

package/framework/{v0.5.4 → v0.5.5}/core/config.js

@@ -210,14 +210,20 @@ function Config(opt, contextResetNeeded) {
                     };
 
                 } catch(err) {
-                    console.error(err.stack||err.message);
+                    var _coreMsg = (err.stack||err.message);
+                    console.error(_coreMsg);
+                    // Guarantee the reason survives process.exit() on an async pipe (e.g. bin/gina-container).
+                    try { fs.writeSync(2, _coreMsg + '\n'); } catch (_e) { /* best-effort */ }
                     process.exit(1)
                 }
 
                 loadBundlesConfiguration( function(err, file, routing) {
 
                     if (err) {
-                        console.error(err.stack||err.message);
+                        var _bundlesMsg = (err.stack||err.message);
+                        console.error(_bundlesMsg);
+                        // Guarantee the reason survives process.exit() on an async pipe (e.g. bin/gina-container).
+                        try { fs.writeSync(2, _bundlesMsg + '\n'); } catch (_e) { /* best-effort */ }
                         setTimeout(() => {
                             process.exit(1);
                         }, 0);
@@ -361,8 +367,11 @@ function Config(opt, contextResetNeeded) {
         try {
             return self.envConf[bundle][env].server['coreConfiguration']
         } catch(err) {
-            console.debug('Could not get server core configuration for <'+ bundle +'>:<'+ env +'>');
+            var _coreConfCtx = 'Could not get server core configuration for <'+ bundle +'>:<'+ env +'>';
+            console.debug(_coreConfCtx);
             console.error(err.stack||err.message);
+            // Guarantee the reason survives process.exit() on an async pipe (e.g. bin/gina-container).
+            try { fs.writeSync(2, _coreConfCtx + '\n' + (err.stack||err.message) + '\n'); } catch (_e) { /* best-effort */ }
             process.exit(1);
         }
     }
@@ -1029,6 +1038,8 @@ function Config(opt, contextResetNeeded) {
                     appPort = portsReverse[app+'@'+self.projectName][env][ newContent[app][env].server.protocol ][ newContent[app][env].server.scheme ];
                 } catch (err) {
                     console.emerg('[CONFIG][ settings.server.protocol ] Protocol or scheme settings inconsistency found in `'+ app +'/config/settings`. To fix this, try to run `gina project:import @'+ self.projectName +' --path='+  projectConf.path +'`\n\r'+ err.stack);
+                    // Guarantee the reason survives process.exit() on an async pipe (e.g. bin/gina-container).
+                    try { fs.writeSync(2, '[CONFIG][ settings.server.protocol ] Protocol or scheme settings inconsistency for `'+ app +'` — run `gina project:import @'+ self.projectName +'`\n'+ (err.stack||err.message) + '\n'); } catch (_e) { /* best-effort */ }
                     process.exit(1)
                 }
                 //I had to for this one...
@@ -1978,7 +1989,10 @@ function Config(opt, contextResetNeeded) {
                     ) {
                         let ruleName = ( !/\@/.test(rule) ) ? rule +'@'+ bundle : rule;
                         err = new Error('['+ruleName+'] Bad routing syntax for `'+r+'` in requirements : must start with `/` or `validator::`');
-                        console.emerg(err.stack||err.message);
+                        var _routeMsg = (err.stack||err.message);
+                        console.emerg(_routeMsg);
+                        // Guarantee the reason survives process.exit() on an async pipe (e.g. bin/gina-container).
+                        try { fs.writeSync(2, _routeMsg + '\n'); } catch (_e) { /* best-effort */ }
                         process.exit(1);
                     }
                 }

package/framework/{v0.5.4 → v0.5.5}/core/controller/controller.js

@@ -2874,6 +2874,11 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
         },
         // Will try x3 (0, 1, 2). Hard ceiling is 10 (see retry handler) to bound timer accumulation under sustained failure.
         maxRetry            : 2,
+        // #B53 — when true, allow auto-retry of a non-safe method (POST/PUT/PATCH/DELETE) after
+        // a post-send transient failure. Default false: only safe methods (GET/HEAD/OPTIONS/TRACE)
+        // auto-retry, so a request the upstream already executed is never silently re-run. Opt in
+        // per call only when the target endpoint is genuinely replay-safe. See isRetryableMethod().
+        retryUnsafe         : false,
         // Socket inactivity timeout — accepts "30s", "500ms", "1m" or a number (ms)
         requestTimeout      : "10s",
         agent               : false/**,
@@ -3358,6 +3363,37 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
     //     });
     // };
 
+    /**
+     * #B53 — Idempotency guard for inter-bundle client retries.
+     *
+     * A transient failure can land AFTER the upstream bundle already executed its handler
+     * (stream timeout, ECONNRESET, GOAWAY premature-close, proxy 502) — only the response is
+     * lost, not the side effect. Auto-retrying then silently re-executes the request, so a
+     * non-idempotent POST/PUT/PATCH/DELETE runs twice. Both client paths
+     * (handleHTTP1ClientRequest / handleHTTP2ClientRequest) therefore re-send on a transient
+     * failure only when replay is safe.
+     *
+     * Idempotency (PUT/DELETE) is a transport property, not a side-effect property — a PUT or
+     * DELETE fronting a side-effecting handler is still unsafe to replay — so by default only
+     * the HTTP "safe" methods (no side effects, idempotent) auto-retry. A caller that owns a
+     * genuinely replay-safe non-safe endpoint opts in per-call with `retryUnsafe: true`.
+     *
+     * @inner
+     * @param   {string}  method        - HTTP method, any case (HTTP/2 `:method` is already upper-cased).
+     * @param   {boolean} [retryUnsafe] - When strictly `true`, allow re-sending any method.
+     * @returns {boolean} `true` when the request may be safely re-sent on a transient failure.
+     *
+     * @example
+     * isRetryableMethod('GET');         // → true  (safe method)
+     * isRetryableMethod('post');        // → false (non-idempotent, not opted in)
+     * isRetryableMethod('POST', true);  // → true  (caller affirmed replay-safety)
+     */
+    var SAFE_HTTP_METHODS = { GET: true, HEAD: true, OPTIONS: true, TRACE: true };
+    var isRetryableMethod = function(method, retryUnsafe) {
+        if (retryUnsafe === true) { return true; }
+        return SAFE_HTTP_METHODS[ String(method || '').toUpperCase() ] === true;
+    };
+
     var handleHTTP1ClientRequest = function(browser, options, callback, retryCount = 0) {
 
 
@@ -3502,7 +3538,11 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
         req.on('error', function onError(err) {
 
             // If conn is down (ECONNRESET, ETIMEDOUT),retry
-            if (retryCount < Math.min(options.maxRetry, 10)) {
+            // #B53 — but only re-send when replay is safe: a safe method, or a caller that opted
+            // in via options.retryUnsafe. This handler also fires for post-send failures (the
+            // requestTimeout below calls req.destroy() after the body is written), so an unguarded
+            // retry would silently re-execute a non-idempotent request.
+            if (retryCount < Math.min(options.maxRetry, 10) && isRetryableMethod(options.method, options.retryUnsafe)) {
                 const delay = 500 * (retryCount + 1); // Délai progressif
                 return setTimeout(() => handleHTTP1ClientRequest(browser, options, callback, retryCount + 1), delay);
             }
@@ -3979,7 +4019,7 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
         var _NON_HTTP_OPTS = new Set([
             '_body', '_comment', 'ca', 'hostname', 'host', 'port',
             'requestTimeout', 'keepAlive', 'maxSockets', 'keepAliveMsecs', 'maxFreeSockets',
-            'rejectUnauthorized', 'maxRetry', 'agent', 'protocol', 'scheme',
+            'rejectUnauthorized', 'maxRetry', 'retryUnsafe', 'agent', 'protocol', 'scheme',
             'nameservers', 'settings', 'webroot', 'queryData', 'method', 'path'
         ]);
         var headerKeys = Object.keys(headers);
@@ -4059,7 +4099,8 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
             var _tIdx = self.serverInstance._http2Sessions.indexOf(sessKey);
             if (_tIdx !== -1) self.serverInstance._http2Sessions.splice(_tIdx, 1);
             if (!client.destroyed) client.destroy(); // no error arg — suppresses session 'error' event
-            if (retryCount < HTTP2_MAX_RETRIES) {
+            // #B53 — only re-send non-idempotent methods when the caller opted in (replay-safe).
+            if (retryCount < HTTP2_MAX_RETRIES && isRetryableMethod(options[':method'], options.retryUnsafe)) {
                 options.queryData = options._body;
                 var _tNext = retryCount + 1;
                 if (_tNext > 1) {
@@ -4099,7 +4140,7 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
 
             // If the session closed exactly when we sent the request (Race Condition)
             // Retry with a fresh connection (up to HTTP2_MAX_RETRIES, with backoff)
-            if (retryCount < HTTP2_MAX_RETRIES && (errorCode === 'ERR_HTTP2_STREAM_ERROR' || errorCode === 'ECONNRESET')) {
+            if (retryCount < HTTP2_MAX_RETRIES && (errorCode === 'ERR_HTTP2_STREAM_ERROR' || errorCode === 'ECONNRESET') && isRetryableMethod(options[':method'], options.retryUnsafe)) {
                 isFinished = true; // Mark current attempt as done
                 cache.delete(sessKey);
                 if (!client.destroyed) client.destroy();
@@ -4185,7 +4226,8 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
             if (isFinished) return;
             isFinished = true;
             console.warn('[HTTP2] Premature stream close on '+ options[':method'] +' '+ options[':path'] +' — GOAWAY / session reset (attempt '+ (retryCount + 1) +'/'+ (HTTP2_MAX_RETRIES + 1) +')');
-            if (retryCount < HTTP2_MAX_RETRIES) {
+            // #B53 — only re-send non-idempotent methods when the caller opted in (replay-safe).
+            if (retryCount < HTTP2_MAX_RETRIES && isRetryableMethod(options[':method'], options.retryUnsafe)) {
                 cache.delete(sessKey);
                 var _cIdx = self.serverInstance._http2Sessions.indexOf(sessKey);
                 if (_cIdx !== -1) self.serverInstance._http2Sessions.splice(_cIdx, 1);
@@ -4241,7 +4283,7 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
             // drop between nginx and the bundle — transient on OrbStack ARM64 and in
             // production after a keepalive expiry). Retry after a short delay to give
             // nginx time to reconnect to the bundle before surfacing the error to the caller.
-            if (httpStatus === 502 && retryCount < HTTP2_MAX_RETRIES) {
+            if (httpStatus === 502 && retryCount < HTTP2_MAX_RETRIES && isRetryableMethod(options[':method'], options.retryUnsafe)) {
                 var _502Next = retryCount + 1;
                 console.warn('[HTTP2][RETRYING] 502 from '+ options[':authority'] + options[':path'] +' — retry '+ _502Next +'/'+ HTTP2_MAX_RETRIES +' in 2s');
                 setTimeout(function onHttp2RetryAfter502() {

package/framework/{v0.5.4 → v0.5.5}/core/gna.js

@@ -184,6 +184,48 @@ if (process.argv.length >= 3 /**&& /gina$/.test(process.argv[1])*/ ) {
                     : _fwPath;
                 require('module').Module._initPaths();
             }
+
+            // Bun reads NODE_PATH only at process start, and the Module._initPaths()
+            // call above is a callable no-op under it — so bare require('lib/<name>')
+            // from framework entities and controllers fails to resolve at request
+            // time. Re-implement NODE_PATH fallback semantics for Bun: when the
+            // default resolver cannot find a *bare* specifier, retry it against each
+            // NODE_PATH dir (the list now includes the framework path). isBun-gated,
+            // so Node keeps its native NODE_PATH / _initPaths resolution untouched
+            // (zero Node-side change — the shim is never installed under Node).
+            var _runtime = require(ctxObj.paths.gina.root + '/utils/runtime');
+            var _Module  = require('module');
+            if ( _runtime.isBun() && !_Module._ginaBunResolvePatched ) {
+                _Module._ginaBunResolvePatched = true;
+                var _resolvePath      = require('path');
+                var _ginaOrigResolve  = _Module._resolveFilename;
+                var _ginaFallbackDirs = (process.env.NODE_PATH || '').split(_resolvePath.delimiter).filter(Boolean);
+                if ( _ginaFallbackDirs.indexOf(_fwPath) < 0 ) {
+                    _ginaFallbackDirs.push(_fwPath);
+                }
+                _Module._resolveFilename = function (request, parent, isMain, options) {
+                    try {
+                        return _ginaOrigResolve.call(this, request, parent, isMain, options);
+                    } catch (resolveErr) {
+                        // Only bare specifiers fall back — never relative ('./' '../')
+                        // or absolute ('/' '\' 'C:') requests.
+                        if (
+                            typeof request === 'string'
+                            && request.charAt(0) !== '.'
+                            && request.charAt(0) !== '/'
+                            && request.charAt(0) !== '\\'
+                            && !/^[A-Za-z]:/.test(request)
+                        ) {
+                            for (var _gi = 0; _gi < _ginaFallbackDirs.length; _gi++) {
+                                try {
+                                    return _ginaOrigResolve.call(this, _resolvePath.join(_ginaFallbackDirs[_gi], request), parent, isMain, options);
+                                } catch (fallbackErr) { /* try the next NODE_PATH dir */ }
+                            }
+                        }
+                        throw resolveErr;
+                    }
+                };
+            }
         }
 
         setContext('paths', ctxObj.paths);//And so on if you need to.
@@ -291,18 +333,42 @@ var env                     = (typeof(process.env.NODE_ENV) != 'undefined' && pr
     , scope                 = (typeof(process.env.NODE_SCOPE) != 'undefined' && process.env.NODE_SCOPE) ? process.env.NODE_SCOPE : projects[projectName]['def_scope']
     , isLocalScope          = (scope === projects[projectName]['local_scope']) ? true : false
     , isProductionScope     = (scope === projects[projectName]['production_scope']) ? true : false
-    , port                  = reversePorts[process.env.NODE_BUNDLE +'@'+ process.env.NODE_PROJECT][env][projects[projectName]['def_protocol']][projects[projectName]['def_scheme']]
     , scheme                = projects[projectName]['def_scheme']
 ;
 
+// Guard the ports.reverse.json lookup: a desynced/corrupt manifest (a missing
+// bundle@project / env / protocol / scheme key) otherwise throws a cryptic
+// `TypeError: Cannot read properties of undefined` at module load (bundle exit 1,
+// no actionable reason). Fail fast with a clear, pipe-flushed diagnostic instead.
+var _bundleKey  = process.env.NODE_BUNDLE +'@'+ process.env.NODE_PROJECT
+    , _defProto = projects[projectName]['def_protocol']
+    , _byEnv    = reversePorts[_bundleKey] && reversePorts[_bundleKey][env]
+    , _byProto  = _byEnv && _byEnv[_defProto]
+    , port      = ( _byProto && typeof(_byProto[scheme]) != 'undefined' ) ? _byProto[scheme] : null
+;
+if ( port == null ) {
+    var _portMsg = '[ FRAMEWORK ] could not resolve the listening port for [ '+ _bundleKey +' ] '
+                 + '(env: '+ env +', protocol: '+ _defProto +', scheme: '+ scheme +') — check '
+                 + GINA_HOMEDIR +'/ports.reverse.json';
+    console.emerg(_portMsg);
+    try { fs.writeSync(2, _portMsg + '\n'); } catch (_e) { /* best-effort */ }
+    process.exit(1);
+}
+
 gna.env = process.env.NODE_ENV = env;
 gna.scope = process.env.NODE_SCOPE = scope;
 gna.os.isWin32 = process.env.isWin32 = isWin32;
 gna.isAborting = false;
 //Cacheless is also defined in the main config : Config::isCacheless().
-process.env.NODE_ENV_IS_DEV = (/^true$/i.test(isDev)) ? true : false;
-process.env.NODE_SCOPE_IS_LOCAL = (/^true$/i.test(isLocalScope)) ? true : false;
-process.env.NODE_SCOPE_IS_PRODUCTION = (/^true$/i.test(isProductionScope)) ? true : false;
+// Stored as STRING literals, not booleans: Node coerces a non-string
+// process.env assignment to a string, but Bun preserves the original type —
+// so a boolean here makes the downstream readers throw under Bun
+// (`process.env.NODE_ENV_IS_DEV.toLowerCase()`) or compare wrong
+// (`process.env.NODE_ENV_IS_DEV == 'false'` is never true for a boolean).
+// 'true'/'false' are byte-identical to Node's implicit coercion.
+process.env.NODE_ENV_IS_DEV = (/^true$/i.test(isDev)) ? 'true' : 'false';
+process.env.NODE_SCOPE_IS_LOCAL = (/^true$/i.test(isLocalScope)) ? 'true' : 'false';
+process.env.NODE_SCOPE_IS_PRODUCTION = (/^true$/i.test(isProductionScope)) ? 'true' : 'false';
 process.env.NODE_PORT = parseInt(port);
 // Proxy check thru proxy.json [Optional]
 var proxyPathObj    = new _(projects[projectName].path + '/proxy.json', true);

package/framework/{v0.5.4 → v0.5.5}/core/server.isaac.js

@@ -697,29 +697,138 @@ function ServerEngineClass(options) {
              * default refusal table above keeps answering 501 for websocket
              * streams when no consumer exists. With handlers registered, an
              * accepted websocket stream is matched on its `:path` pathname
-             * (query string stripped): a hit is answered `:status 200` via
-             * lib.wsSession.accept and handed to the handler as a live
-             * session; a miss is refused with 404. No express middleware runs
+             * (query string stripped): an exact-path hit first, then (#H13
+             * slice 2) an ordered scan of `:param` patterns whose captured
+             * segments populate `request.params` (colon-stripped keys, the
+             * same shape an HTTP controller reads). A hit is answered
+             * `:status 200` via lib.wsSession.accept and handed to the handler
+             * as a live session; a miss is refused with 404. No express middleware runs
              * on the CONNECT path — authentication is the handler's concern
              * (it receives the full request for header/cookie inspection).
+             * Registering a path that already has a handler warns and overwrites
+             * (last-write-wins): a programmatic call overrides a routing.json
+             * `method:"ws"` declaration for the same path (declarations are
+             * registered at bundle bootstrap, before onInitialize).
+             *
+             * #H13 slice 3a — an optional 3rd argument carries per-route session
+             * options (maxPayload / protocol / closeTimeout) forwarded verbatim to
+             * lib.wsSession.accept; a routing.json `method:"ws"` route supplies them
+             * via `param.wsOptions`. Overwriting a path replaces handler AND options.
              */
             server._wsHandlers = {};
-            server.onWebSocket = function(wsPath, wsHandler) {
+            // #H13 slice 3a — parallel exact-path → per-route options map. Kept
+            // separate from _wsHandlers so that stays a pure path→handler map (the
+            // collision guard tests the literal `_wsHandlers[wsPath]` shape).
+            server._wsHandlerOptions = {};
+            // #H13 slice 2 — ordered registry of `:param` patterns, scanned only
+            // on an exact-match miss. Each entry: { pattern, segments, handler }.
+            // First-registered wins among overlapping equal-length patterns —
+            // mirrors gina's HTTP router, which is first-match by declaration
+            // order (core/server.js routing loop breaks on the first matching
+            // route; there is no cross-route best-score selection). Keeping the
+            // same rule here means WS routing resolves consistently with HTTP.
+            server._wsParamHandlers = [];
+
+            // #H13 slice 2 — match a request pathname against the `:param`
+            // registry. Exact routes are resolved by the caller BEFORE this runs.
+            // Splits on '/' (keeping the leading '' from the leading slash, so
+            // pattern/request segments index-align, mirroring lib/routing). A
+            // strict segment-count gate, then per-segment: a literal must equal
+            // exactly; a `:name` segment captures any NON-EMPTY segment as
+            // `params[name]` (colon-stripped key + decodeURIComponent — the same
+            // shape an HTTP controller reads off req.params). Returns
+            // { handler, params } for the first matching pattern, else null.
+            server._wsMatchParam = function(pathname) {
+                var reqSegs = String(pathname || '').split('/');
+                for (var i = 0; i < server._wsParamHandlers.length; i++) {
+                    var entry = server._wsParamHandlers[i];
+                    if (entry.segments.length !== reqSegs.length) { continue; }
+                    var params = {};
+                    var ok = true;
+                    for (var s = 0; s < entry.segments.length; s++) {
+                        var pat = entry.segments[s];
+                        if (pat.charAt(0) === ':') {
+                            if (reqSegs[s] === '') { ok = false; break; } // reject empty captured segment
+                            params[pat.substring(1)] = decodeURIComponent(reqSegs[s]);
+                        } else if (pat !== reqSegs[s]) {
+                            ok = false; break;
+                        }
+                    }
+                    if (ok) { return { handler: entry.handler, params: params, options: entry.options }; }
+                }
+                return null;
+            };
+
+            server.onWebSocket = function(wsPath, wsHandler, wsOptions) {
                 if (typeof wsPath !== 'string' || wsPath.length === 0 || typeof wsHandler !== 'function') {
                     throw new TypeError('onWebSocket(path, handler) requires a non-empty path string and a handler function');
                 }
-                server._wsHandlers[wsPath] = wsHandler;
+                // #H13 slice 3b — capture, once, the bundle/env this server serves
+                // (a server serves one bundle) for session.query. The routing.json
+                // registrar (core/server.js) sets server._wsBundle/_wsEnv explicitly
+                // from self.appName/self.env before its first call here; a purely
+                // programmatic caller (onInitialize) falls back to getContext, which
+                // is correct at boot. Capturing at registration avoids the shared
+                // ctx.bundle stack-walk mutation hazard that would bite a lazy
+                // connect/message-time read on a long-lived interleaved session.
+                if (typeof server._wsBundle === 'undefined') {
+                    server._wsBundle = (typeof getContext === 'function') ? getContext('bundle') : null;
+                    server._wsEnv    = (typeof getContext === 'function') ? getContext('env') : null;
+                }
+                // #H13 slice 2 — a path with a `:` segment is a param pattern
+                // (same placeholder convention as lib/routing's hasParams: /\:/).
+                if ( /\:/.test(wsPath) ) {
+                    var _existing = -1;
+                    for (var _p = 0; _p < server._wsParamHandlers.length; _p++) {
+                        if (server._wsParamHandlers[_p].pattern === wsPath) { _existing = _p; break; }
+                    }
+                    if (_existing > -1) {
+                        console.warn('[ SERVER ] onWebSocket: pattern `'+ wsPath +'` already has a handler — overwriting');
+                        server._wsParamHandlers[_existing].handler = wsHandler;
+                        server._wsParamHandlers[_existing].options = wsOptions || null;
+                    } else {
+                        server._wsParamHandlers.push({ pattern: wsPath, segments: wsPath.split('/'), handler: wsHandler, options: wsOptions || null });
+                    }
+                } else {
+                    if ( typeof server._wsHandlers[wsPath] === 'function' ) {
+                        console.warn('[ SERVER ] onWebSocket: path `'+ wsPath +'` already has a handler — overwriting');
+                    }
+                    server._wsHandlers[wsPath] = wsHandler;
+                    server._wsHandlerOptions[wsPath] = wsOptions || null;
+                }
                 if (typeof server._extendedConnectHandler !== 'function') {
                     server._extendedConnectHandler = function(request, response) {
                         var _wsPathname = String(request.headers[':path'] || '').split('?')[0];
+                        // Exact match wins (slice-1 precedence preserved).
                         var _wsTarget = server._wsHandlers[_wsPathname];
+                        var _wsParams = null;
+                        // #H13 slice 3a — per-route session options resolved alongside
+                        // the handler: an exact hit reads the exact options map; a
+                        // param hit takes the matched entry's options below.
+                        var _wsOpts   = server._wsHandlerOptions[_wsPathname] || null;
+                        // #H13 slice 2 — param fallback only on an exact miss.
+                        if (typeof _wsTarget !== 'function' && server._wsParamHandlers.length) {
+                            var _m = server._wsMatchParam(_wsPathname);
+                            if (_m) { _wsTarget = _m.handler; _wsParams = _m.params; _wsOpts = _m.options || null; }
+                        }
                         if (typeof _wsTarget !== 'function') {
                             // No handler registered for this pathname.
                             response.writeHead(404);
                             response.end();
                             return;
                         }
-                        var _wsSession = lib.wsSession.accept(request);
+                        // Populate request.params (named keys, colon-stripped) so a
+                        // channel handler reads the same shape an HTTP controller does.
+                        request.params = _wsParams || {};
+                        var _wsSession = lib.wsSession.accept(request, _wsOpts || undefined);
+                        // #H13 slice 3b — give the channel handler a cross-bundle HTTP
+                        // capability (session.query(options[, data]) → Promise), mirroring
+                        // a controller's self.query(). Attached AFTER accept so
+                        // lib/ws-session stays controller-free. The bundle/env this server
+                        // serves were captured at registration (server._wsBundle/_wsEnv) —
+                        // never resolved lazily here, where the shared getContext('bundle')
+                        // is rewritten by every getConfig/getLib stack-walk.
+                        _wsSession.query = lib.wsQuery.build(server, server._wsBundle, server._wsEnv);
                         _wsTarget(_wsSession, request);
                     };
                 }

package/framework/{v0.5.4 → v0.5.5}/core/server.js

@@ -688,6 +688,80 @@ function Server(options) {
                 process.env.TZ = options.conf[self.appName][self.env].content.settings.region.timeZone;
             }
 
+            // #H13 — register routing.json-declared WebSocket routes (`"method": "ws"`).
+            // Each such route names a connection-handler module via `param.wsHandler`,
+            // resolved under the bundle's `channels/` dir. We register through the
+            // engine's own `onWebSocket(path, handler)` (set up during `new Engine()`
+            // above): on an http/2 isaac bundle with `enableConnectProtocol` it wires
+            // the real dispatcher; otherwise it hits the warn-noop stub, so we never
+            // write a registry nothing reads. This runs BEFORE the `configured` emit
+            // (hence before the bundle's onInitialize), so a programmatic
+            // `app.onWebSocket()` in onInitialize overrides a declaration here.
+            // WS dispatch happens in the engine's extended-CONNECT handler — these
+            // routes never reach handle()/router.route (the `:4816` method filter +
+            // the method-keyed route cache keep a `ws` route from matching an HTTP
+            // request, and the radix-trie candidate is method-filtered in the loop).
+            var _wsRouting           = serverOpt.routing || {};
+            var _wsRegistered        = {};
+            var _wsUnsupportedWarned = false;
+            for (var _wsRule in _wsRouting) {
+                var _wsRoute = _wsRouting[_wsRule];
+                if ( typeof(_wsRoute) != 'object' || _wsRoute === null || !/^ws$/i.test(_wsRoute.method || '') ) {
+                    continue;
+                }
+                if ( typeof(engine.instance.onWebSocket) != 'function' ) {
+                    if ( !_wsUnsupportedWarned ) {
+                        console.warn('[ SERVER ] WebSocket route(s) declared but the `'+ serverOpt.engine +'` engine has no WebSocket support (requires the isaac engine with http2Options.enableConnectProtocol = true)');
+                        _wsUnsupportedWarned = true;
+                    }
+                    continue;
+                }
+                var _wsName = ( _wsRoute.param && typeof(_wsRoute.param.wsHandler) == 'string' && _wsRoute.param.wsHandler != '' )
+                    ? _wsRoute.param.wsHandler
+                    : null;
+                if ( !_wsName ) {
+                    throw new Error('[ SERVER ] WebSocket route `'+ _wsRule +'` must declare `param.wsHandler` (the channels/<name> module to handle it).');
+                }
+                // #H13 slice 3a — optional per-route session options (maxPayload /
+                // protocol / closeTimeout), threaded to lib.wsSession.accept via
+                // onWebSocket. Present-but-not-an-object fails loudly at boot (mirrors
+                // the wsHandler fail-fast); absent → null (accept defaults apply).
+                if ( _wsRoute.param && typeof(_wsRoute.param.wsOptions) != 'undefined'
+                        && ( typeof(_wsRoute.param.wsOptions) != 'object' || _wsRoute.param.wsOptions === null ) ) {
+                    throw new Error('[ SERVER ] WebSocket route `'+ _wsRule +'`: `param.wsOptions` must be an object');
+                }
+                var _wsOptions = ( _wsRoute.param && typeof(_wsRoute.param.wsOptions) == 'object' && _wsRoute.param.wsOptions !== null )
+                    ? _wsRoute.param.wsOptions
+                    : null;
+                var _wsFile = _(self.conf[self.appName][self.env].bundlesPath + '/' + self.appName + '/channels/' + _wsName + '.js', true);
+                var _wsHandlerFn = null;
+                try {
+                    _wsHandlerFn = require(_wsFile);
+                } catch (_wsErr) {
+                    throw new Error('[ SERVER ] WebSocket route `'+ _wsRule +'`: channel module `channels/'+ _wsName +'.js` could not be loaded ('+ _wsFile +'):\n'+ _wsErr.message);
+                }
+                if ( typeof(_wsHandlerFn) != 'function' ) {
+                    throw new Error('[ SERVER ] WebSocket route `'+ _wsRule +'`: channel module `channels/'+ _wsName +'.js` must export a function (session, request).');
+                }
+                // A route URL may be comma-separated (multi-url) — register each.
+                var _wsUrls = String(_wsRoute.url || '').split(',');
+                for (var _wsi = 0, _wsLen = _wsUrls.length; _wsi < _wsLen; ++_wsi) {
+                    var _wsUrl = _wsUrls[_wsi].trim();
+                    if ( !_wsUrl ) { continue; }
+                    if ( _wsRegistered[_wsUrl] ) {
+                        console.warn('[ SERVER ] WebSocket path `'+ _wsUrl +'` is declared by more than one `method:"ws"` route — last wins (`'+ _wsRule +'`)');
+                    }
+                    _wsRegistered[_wsUrl] = true;
+                    // #H13 slice 3b — record the bundle/env this server serves (a server
+                    // serves one bundle) so the dispatcher can build session.query. Set
+                    // explicitly here (self.appName/self.env are guaranteed correct at
+                    // boot) before onWebSocket, so its getContext fallback is skipped.
+                    engine.instance._wsBundle = self.appName;
+                    engine.instance._wsEnv    = self.env;
+                    engine.instance.onWebSocket(_wsUrl, _wsHandlerFn, _wsOptions);
+                }
+            }
+
             self.emit('configured', false, engine.instance, engine.middleware, self.conf[self.appName][self.env]);
 
         } catch (err) {

package/framework/{v0.5.4 → v0.5.5}/lib/archiver/src/main.js

@@ -486,8 +486,117 @@ function Archiver() {
 
 
 
+    /**
+     * decompress
+     *
+     * Inverse of `compress()` — extracts a `.zip` archive into a target directory.
+     * Mirrors compress()'s completion contract: emits `archiver-decompress#complete`
+     * `(err, target)` on the singleton and returns an `{ onComplete: fn }` handle
+     * (a trailing callback is also accepted for `promisify`). Uses JSZip 3.x
+     * (`loadAsync` + per-entry `async('nodebuffer')`).
+     *
+     * @param {string} src - absolute path to the `.zip` archive
+     * @param {string} target - output directory (created if missing); entries are
+     *  written at their archive-relative paths under it
+     * @param {object} [options] - reserved for future use
+     * @returns {{ onComplete: function }} completion handle
+     *
+     * @example
+     *  lib.archiver.decompress('/dump/app.zip', '/srv/app/').onComplete(function (err, dir) {
+     *      if (err) { return; }
+     *      // dir now holds the extracted tree
+     *  });
+     */
     this.decompress = function(src, target, options) {
 
+        var path   = require('path');
+        var handle = {
+            onComplete: function onDecompressionCompleted(cb) {
+                self.once('archiver-decompress#complete', function (err, t) {
+                    cb(err, t)
+                })
+            }
+        };
+
+        // Used for `promisify` — same trailing-callback contract as compress()
+        if ( typeof(arguments[arguments.length-1]) == 'function' ) {
+            var _pcb = arguments[arguments.length-1];
+            self.once('archiver-decompress#complete', function (err, t) {
+                return _pcb(err, t)
+            })
+        }
+
+        if ( !/\/$/.test(target) ) {
+            target += '/'
+        }
+        if ( !fs.existsSync(target) ) {
+            fs.mkdirSync(target, { recursive: true });
+        }
+        var targetAbs = path.resolve(target);
+
+        if ( !fs.existsSync(src) ) {
+            // defer so a synchronous error still reaches a listener attached
+            // via the returned handle's onComplete() on the same tick
+            process.nextTick(function () {
+                self.emit('archiver-decompress#complete', new Error('archive not found `'+ src +'`'), null);
+            });
+            return handle;
+        }
+
+        try {
+            var buf = fs.readFileSync(src);
+            JSZip.loadAsync(buf).then(function (zip) {
+
+                var entries = [];
+                zip.forEach(function (relPath, entry) {
+                    entries.push({ relPath: relPath, entry: entry });
+                });
+
+                var i = 0;
+                var next = function () {
+                    if ( i >= entries.length ) {
+                        self.emit('archiver-decompress#complete', false, target);
+                        return;
+                    }
+                    var it   = entries[i++];
+                    var dest = path.resolve(targetAbs, it.relPath);
+
+                    // zip-slip guard: an entry must never escape the target dir
+                    if ( dest !== targetAbs && dest.indexOf(targetAbs + path.sep) !== 0 ) {
+                        self.emit('archiver-decompress#complete', new Error('unsafe entry path in archive: `'+ it.relPath +'`'), null);
+                        return;
+                    }
+
+                    if ( it.entry.dir ) {
+                        if ( !fs.existsSync(dest) ) {
+                            fs.mkdirSync(dest, { recursive: true });
+                        }
+                        return next();
+                    }
+
+                    var parent = path.dirname(dest);
+                    if ( !fs.existsSync(parent) ) {
+                        fs.mkdirSync(parent, { recursive: true });
+                    }
+                    it.entry.async('nodebuffer').then(function (content) {
+                        fs.writeFileSync(dest, content);
+                        next();
+                    }).catch(function (err) {
+                        self.emit('archiver-decompress#complete', err, null);
+                    });
+                };
+                next();
+
+            }).catch(function (err) {
+                self.emit('archiver-decompress#complete', err, null);
+            });
+        } catch (err) {
+            process.nextTick(function () {
+                self.emit('archiver-decompress#complete', err, null);
+            });
+        }
+
+        return handle;
     }
 
     this.compressFromStream = function(readStream, target, options) {

package/framework/v0.5.5/lib/cmd/bundle/man.js

@@ -0,0 +1,10 @@
+/**
+ * @module gina/lib/cmd/bundle/man
+ * @description `gina bundle:man` — shows the bundle manual. No
+ * `gina-bundle.1.md` source exists yet, so the shared engine falls back to
+ * `lib/cmd/bundle/help.txt`. Thin re-export of
+ * {@link module:gina/lib/cmd/man-render}, which picks the group from
+ * `opt.task.topic`.
+ */
+// alias
+module.exports = require('../man-render');