gina 0.5.1-alpha.2 → 0.5.1

package/CHANGELOG.md

@@ -6,6 +6,15 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.5.1 - 2026-06-12
+### Added
+* Stable publishes now run a ROADMAP.md consistency gate (script/check_roadmap_consistency.js, wired into the release prepare step alongside the README freshness gate). The publish aborts when an open roadmap row still references the exact version being released (the row would become stale the moment the tag lands) or when a done row is labelled with a version newer than the one shipping; a missing "released" timeline mark is surfaced as a warning only. Alpha publishes skip the gate.
+### Fixed
+* Fixed a bundle-killing crash when an error fired after the response was already sent. A late throwError() — e.g. an entity or query callback resuming after a redirect() had already issued its 301 and released the per-request response — dereferenced the released response and threw TypeError (reading getHeaders), escalating to uncaughtException and a SIGTERM bundle shutdown that also dropped every in-flight request. Late throwError() calls now log the swallowed error and no-op, and headersSent() treats a released response as already-sent so second render calls no-op too (#B31).
+* Fixed a dev-mode per-request memory leak that could kill heavily-loaded bundles with a heap-limit OOM (SIGABRT): the hot-reload eviction cycles (refreshCore in the isaac engine, refreshCoreDependencies in the router) delete and re-require framework modules on every request, and each cache-miss require pushes the fresh Module onto its long-lived parent's children array — Node only dedupes on cache hits — pinning the dead module graphs forever (~1.8 MB of live heap retained per request measured on a minimal bundle, process death at ~2400 requests). Both cycles now prune stale Module references from every cached module's children after eviction; production mode was never affected. (#B32)
+* Fixed the inter-bundle proxy (SuperController::query() over HTTP/2) re-labeling its raw-JSON request body with the incoming request's Content-Type. When the incoming browser request was a plain urlencoded form POST, the receiving bundle parsed the raw JSON through its urlencoded branch — corrupting `+`/`%XX` sequences inside JSON string values (e.g. a `+`-alias email losing its `+`). The `application/json` label query() sets for the body it serializes itself is now preserved; the incoming-Content-Type forward is kept for non-JSON outbound bodies. (#FORMCT2)
+* Fixed a family of bundle-killing crashes when an HTTP/2 inter-bundle query outlives its own request: retry re-entries and late upstream responses ran against a response that a terminal exit (e.g. a redirect that lets the middleware chain continue) had already released, dereferencing null — the header-forward prep block on every retry re-entry, the session lookup behind isHaltedRequest, and both 3xx redirect intercepts. All sites are now null-guarded: forwards and intercepts no-op on a released request (options.headers already carries the first attempt's values, so nothing is lost), and the session lookup reports no session. Live-request behaviour is byte-identical. (#B33)
+
 ## 0.5.0 - 2026-06-11
 ### Added
 * ESM compatibility layer (#M10): package.json now declares an "exports" map with dual CJS/ESM entry points — `import gina from 'gina'` and `import gna from 'gina/gna'` work natively in ESM projects and modern bundlers (default exports only; the gina/gna getter semantics are preserved). CJS `require()` resolution is byte-identical to before, and TypeScript declarations keep resolving via per-entry "types" conditions. The documented public surface is the bare specifier, ./gna and ./package.json; undeclared deep subpaths are no longer resolvable.

package/CONVENTIONS.md

@@ -391,6 +391,7 @@ exports.setUp = function(done) {
 - Test names use `[ category ] description` format for grouping
 - Setup guards (`if (initialized) return done()`) prevent re-execution across test suites
 - New unit tests go in `test/core/` with numeric prefix for ordering
+- **Test counts in docs and changelogs are measured, never estimated.** Don't write an "N unit tests" claim before running the test — estimating from section count consistently undercounts (behaviour sections run 10-15 tests, not ~5). The corrective is mechanical: run `node --test test/core/<file>.test.js 2>&1 | tail -10`, copy the `ℹ tests N` line, and write that exact N. Use `TODO_test_count` placeholders in drafts and fill from the actual output before staging.
 
 **Recommendation:**
 Migrate to `node:test` (built-in, Node 18+) for all new test files — `nodeunit` is unmaintained. Do not convert existing tests; add `node:test` tests alongside. The HTTP/2 client mock harness (#UT1) should use `node:test + node:assert` natively.

package/README.md

@@ -39,11 +39,12 @@ gina bundle:start api @myproject
 open https://localhost:3100
 ```
 
-## What's in 0.5.0
+## What's in 0.5.1
 
-- **Native ESM entry points.** `package.json` now declares an `"exports"` map with dual CJS/ESM entries — `import gina from 'gina'` and `import gna from 'gina/gna'` work natively in ESM projects and modern bundlers (default exports only; the `gina/gna` getters resolve at access time, after framework boot). CJS `require()` resolution is byte-identical to before, and TypeScript declarations keep resolving through per-entry `types` conditions. Note: with the `exports` map in place, the package's Node-resolvable surface is exactly `gina`, `gina/gna`, and `gina/package.json` — undeclared deep subpaths are no longer resolvable.
-- **Mixed template engines per bundle.** A `templates.json` section declaring `"ext": ".njk"` (or a `self.setTemplate(file, '.njk')` call) renders through nunjucks and `".swig"` through swig — regardless of the bundle-level `render.engine` setting. `.html` and any other extension keep following `render.engine`, so existing bundles are unchanged. Bundles with `.njk` sections get the same fail-fast `NUNJUCKS_NOT_INSTALLED` startup check as nunjucks-engine bundles.
-- **Nunjucks Inspector parity (dev mode).** Dev-mode nunjucks pages now render the Inspector statusbar and expose the query log as `data.page.queries` alongside the flow timeline — the Inspector Queries tab no longer renders empty for nunjucks bundles.
+- **Released-response crash family fixed (bundle-killing).** A late `throwError()` after the response was already sent — e.g. an entity or query callback resuming after a `redirect()` had already issued its 301 — dereferenced the released response, escalating to an `uncaughtException` and a SIGTERM bundle shutdown that dropped every in-flight request. Late calls now log the swallowed error and no-op. The same guard family covers the HTTP/2 inter-bundle query paths: retry re-entries, late upstream responses, and both 3xx redirect intercepts no longer crash when the originating request has already terminated.
+- **Dev-mode hot-reload memory leak fixed.** The per-request hot-reload eviction cycles retained ~1.8 MB of live heap per request through dead `module.children` references, killing heavily-loaded dev bundles with a heap-limit OOM. Both cycles now prune stale module references after eviction; production mode was never affected.
+- **Inter-bundle proxy Content-Type fix.** `query()` over HTTP/2 no longer re-labels the raw-JSON body it serializes itself with the incoming request's Content-Type — a urlencoded browser POST proxied between bundles no longer corrupts `+`/`%XX` sequences inside JSON string values.
+- **ROADMAP consistency release gate.** Stable publishes now abort when a roadmap row is stale relative to the version being released, alongside the existing README freshness gate.
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -25,6 +25,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q2 2026** | `0.3.10` ✅ | FormValidator HTML5 form-reassociation hardening trilogy (`HTMLFormControlsCollection`-based `bindForm` + `unbindForm` symmetry · radio mutual-exclusion + IDL/attribute reconciliation · `defaultChecked` cache for reset) · `X-Forwarded-Prefix` reverse-proxy path-prefix awareness |
 | **Q2 2026** | `0.4.0` ✅ | Couchbase v2 removal (BREAKING — SDK v2 connector + session store dropped) · HTTP/2 response trailers · async-job primitive · CSP per-response nonce · `secrets:scan` / `secrets:check` CLI · SQL column-level index coverage — of the items originally targeted here: AI agents (MCP) shipped `0.3.7`, ScyllaDB `0.3.11`, CLI Tier 2 `0.4.1`, the docs offline ZIP is live on the docs site, and the Advanced tutorial · website redesign · Bun investigation moved to `0.5.x` |
 | **Q2 2026** | `0.5.0` ✅ | ESM entry points (dual CJS/ESM `exports` map) · Mixed template engines per bundle (extension-keyed `.njk` / `.swig` dispatch) · Nunjucks Inspector parity — the other items originally targeted here shipped earlier: structured logging (`0.4.5`), Alt-Svc (`0.4.2`), WebSocket over HTTP/2 (`0.4.7`), Inspector production auth (`0.4.0`) |
+| **Q2 2026** | `0.5.1` ✅ | Patch: released-response crash family — late `throwError()` and the HTTP/2 inter-bundle query retry / late-response / redirect-intercept paths no longer kill the bundle · dev-mode hot-reload `module.children` heap leak fixed (OOM under sustained load) · inter-bundle proxy JSON bodies keep their `application/json` label · ROADMAP consistency release gate |
 | **Q1 2027** | `0.5.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · CLI Tier 3 (project:move, framework:update, backup/restore, man pages) · Beemaster admin + visual translation editor |
 | **Q3 2027** | `1.0.0` | First stable release — Windows alpha compatibility is a hard gate |
 

package/framework/v0.5.1/VERSION

@@ -0,0 +1 @@
+0.5.1

package/framework/{v0.5.1-alpha.2 → v0.5.1}/core/controller/controller.js

@@ -3318,11 +3318,11 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
 		// proxy_set_header X-Ingress-IP $server_addr
 		// proxy_set_header X-Forwarded-For $remote_addr;
 		// # EO - Specific headers for Gina
-        if ( typeof(local.req.headers['x-client-ip']) != 'undefined' && local.req.headers['x-client-ip'] != options.headers['x-client-ip'] ) {
+        if ( local.req != null && typeof(local.req.headers['x-client-ip']) != 'undefined' && local.req.headers['x-client-ip'] != options.headers['x-client-ip'] ) {
             options.headers['x-client-ip'] = local.req.headers['x-client-ip']
         }
 
-        if ( typeof(local.req.headers['x-ingress-ip']) != 'undefined' && local.req.headers['x-ingress-ip'] != options.headers['x-ingress-ip'] ) {
+        if ( local.req != null && typeof(local.req.headers['x-ingress-ip']) != 'undefined' && local.req.headers['x-ingress-ip'] != options.headers['x-ingress-ip'] ) {
             options.headers['x-ingress-ip'] = local.req.headers['x-ingress-ip']
         }
 
@@ -3859,15 +3859,29 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
         } = browser.constants;
 
 
-        if ( typeof(local.req.headers['x-requested-with']) != 'undefined' ) {
+        // #B33 — every retry re-entry (setTimeout → handleHTTP2ClientRequest) re-executes
+        // these forwards, and a terminal exit (e.g. redirect-then-continue) may have
+        // released local.req in between: each forward is null-guarded with query()'s own
+        // idiom. Skipping a forward on a released request is a no-op, not a behavior
+        // change — options.headers already carries the attempt-1 values (the same options
+        // object travels through every retry).
+        if ( local.req != null && typeof(local.req.headers['x-requested-with']) != 'undefined' ) {
             options.headers['x-requested-with'] = local.req.headers['x-requested-with']
         }
 
-        if ( typeof(local.req.headers['access-control-allow-credentials']) != 'undefined' ) {
+        if ( local.req != null && typeof(local.req.headers['access-control-allow-credentials']) != 'undefined' ) {
             options.headers['access-control-allow-credentials'] = local.req.headers['access-control-allow-credentials']
         }
 
-        if ( typeof(local.req.headers['content-type']) != 'undefined' && local.req.headers['content-type'] != options.headers['content-type'] ) {
+        // #FORMCT2 — never clobber an `application/json` outbound Content-Type with the
+        // INCOMING request's. query() serializes the inter-bundle body as raw JSON
+        // (queryData = JSON.stringify) and labels it application/json; forwarding the
+        // incoming CT here re-labels that JSON body (e.g. as urlencoded when the browser
+        // request was a plain form POST — canonical case: a haltedRequest resume), and the
+        // receiving bundle's urlencoded parse then corrupts `+`/`%XX` inside JSON string
+        // values (same corruption #FORMCT fixed in the browser validator). The forward is
+        // kept for non-JSON outbound bodies (e.g. the MSIE text/plain override).
+        if ( local.req != null && typeof(local.req.headers['content-type']) != 'undefined' && local.req.headers['content-type'] != options.headers['content-type'] && !/application\/json/i.test(options.headers['content-type']) ) {
             options.headers['content-type'] = local.req.headers['content-type']
         }
 
@@ -3877,11 +3891,11 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
 		// proxy_set_header X-Ingress-IP $server_addr
 		// proxy_set_header X-Forwarded-For $remote_addr;
 		// # EO - Specific headers for Gina
-        if ( typeof(local.req.headers['x-client-ip']) != 'undefined' && local.req.headers['x-client-ip'] != options.headers['x-client-ip'] ) {
+        if ( local.req != null && typeof(local.req.headers['x-client-ip']) != 'undefined' && local.req.headers['x-client-ip'] != options.headers['x-client-ip'] ) {
             options.headers['x-client-ip'] = local.req.headers['x-client-ip']
         }
 
-        if ( typeof(local.req.headers['x-ingress-ip']) != 'undefined' && local.req.headers['x-ingress-ip'] != options.headers['x-ingress-ip'] ) {
+        if ( local.req != null && typeof(local.req.headers['x-ingress-ip']) != 'undefined' && local.req.headers['x-ingress-ip'] != options.headers['x-ingress-ip'] ) {
             options.headers['x-ingress-ip'] = local.req.headers['x-ingress-ip']
         }
 
@@ -4198,7 +4212,10 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
 
                 try {
                     // Intercepting fallback redirect (3xx)
-                    if (data.status && /^3/.test(data.status) && typeof data.headers !== 'undefined') {
+                    // #B33 — local.res may be null when the response lands after a terminal
+                    // exit released the triplet; skip the intercept and fall through to the
+                    // non-2xx handling (whose throwError no-ops on a released response).
+                    if (local.res != null && data.status && /^3/.test(data.status) && typeof data.headers !== 'undefined') {
                         local.res.writeHead(data.status, data.headers);
                         return local.res.end();
                     }
@@ -4270,7 +4287,10 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
                     }
                 }
 
-                if (data.status && /^3/.test(data.status) && typeof data.headers !== 'undefined') {
+                // #B33 — same released-response skip as the callback-mode intercept above;
+                // emitter mode falls through to the query#complete emit so listeners
+                // still learn the outcome.
+                if (local.res != null && data.status && /^3/.test(data.status) && typeof data.headers !== 'undefined') {
                     self.removeAllListeners(['query#complete']);
                     local.res.writeHead(data.status, data.headers);
                     return local.res.end();
@@ -4937,6 +4957,12 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
 
     var getSession = function() {
         var session = null;
+        // #B33 — local.req is null after a terminal exit released the triplet; callers
+        // like isHaltedRequest() run from HTTP/2 response handlers that can fire on a
+        // released request (retry/late-response paths). No session on a released request.
+        if ( local.req == null ) {
+            return null;
+        }
         if ( typeof(local.req.session) != 'undefined') {
             session = local.req.session;
         }

package/framework/{v0.5.1-alpha.2 → v0.5.1}/core/router.js

@@ -129,9 +129,38 @@ function Router(env, scope) {
         SuperController = require(_(corePath +'/controller/index.js', true));
 
         if (_hotReload) _hotReload.core = false; // #M6 — clear flag after eviction
+
+        pruneDeadModuleChildren();
         corePath = null;
     }
 
+    /**
+     * Prunes stale `Module` references from every cached module's `children`
+     * array after the eviction cycle above. Each cache-miss `require()` pushes
+     * the fresh `Module` onto the requiring module's `children` (Node only
+     * dedupes on cache hits), so without pruning this long-lived router module
+     * accumulates one dead controller `Module` per request, each pinning its
+     * whole evaluated exports graph — the dev-mode per-request memory leak.
+     *
+     * Local copy of the sweep in `core/server.isaac.js` — the engine-agnostic
+     * router cannot depend on an engine module, and the `lib` registry is
+     * itself evicted per request. Keep both copies in sync.
+     *
+     * @inner
+     * @returns {undefined}
+     */
+    var pruneDeadModuleChildren = function() {
+        var cacheIds = Object.keys(require.cache);
+        for (var i = 0, len = cacheIds.length; i < len; i++) {
+            var cached = require.cache[cacheIds[i]];
+            if (cached && cached.children && cached.children.length > 0) {
+                cached.children = cached.children.filter(function onPruneFilter(child) {
+                    return require.cache[child.id] === child;
+                });
+            }
+        }
+    }
+
     this.setServerInstance = function(serverInstance) {
         serverInstance._http2streamEventInitalized = false;
         self.serverInstance = serverInstance;

package/framework/{v0.5.1-alpha.2 → v0.5.1}/core/server.isaac.js

@@ -243,8 +243,48 @@ var refreshCore = function() {
     delete require.cache[require.resolve(pluginsIndexPath)];
     var freshPlugins = require( pluginsIndexPath );
     require.cache[_(corePath + '/gna.js', true)].exports.plugins = freshPlugins;
+
+    pruneDeadModuleChildren();
 }
 
+/**
+ * Prunes stale `Module` references from every cached module's `children` array.
+ *
+ * Each cache-miss `require()` pushes the freshly created `Module` onto the
+ * requiring module's `children` array — Node only dedupes on cache hits — so the
+ * per-request delete-and-re-require cycles in `refreshCore()` (and the router's
+ * `refreshCoreDependencies()`) make long-lived parents accumulate one dead
+ * `Module` per eviction: this engine module, `router.js`, and any module with a
+ * lazy in-function `require()` of an evicted lib. Every dead `Module` pins its
+ * entire evaluated exports graph. Measured on a minimal bundle in dev mode:
+ * ~1.8 MB of post-GC live heap retained per request, ending in a heap-limit
+ * OOM (SIGABRT) at ~2400 requests.
+ *
+ * Keeping only children whose resolved id still maps to that same instance in
+ * `require.cache` releases the dead graphs. `children` is diagnostic metadata
+ * (nothing in Node's resolution reads it), so pruning never unloads a module
+ * still referenced elsewhere.
+ *
+ * A local copy of the same sweep lives in `core/router.js` — the engine-agnostic
+ * router cannot depend on an engine module, and the `lib` registry is itself
+ * evicted per request. Keep both copies in sync.
+ *
+ * @memberof module:gina/core/server.isaac
+ * @inner
+ * @returns {undefined}
+ */
+var pruneDeadModuleChildren = function() {
+    var cacheIds = Object.keys(require.cache);
+    for (var i = 0, len = cacheIds.length; i < len; i++) {
+        var cached = require.cache[cacheIds[i]];
+        if (cached && cached.children && cached.children.length > 0) {
+            cached.children = cached.children.filter(function onPruneFilter(child) {
+                return require.cache[child.id] === child;
+            });
+        }
+    }
+};
+
 // Express compatibility
 const slice = Array.prototype.slice;
 

package/framework/{v0.5.1-alpha.2 → v0.5.1}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.5.1-alpha.2",
+  "version": "0.5.1-alpha.4",
   "dependencies": {
     "@rhinostone/swig": "^2.7.2",
     "intl-messageformat": "^11.2.4",

package/gna.js

@@ -15,14 +15,14 @@
 'use strict';
 
 // Framework core — the main gna module (lifecycle hooks, lib, etc.)
-var _gna = require('./framework/v0.5.1-alpha.2/core/gna');
+var _gna = require('./framework/v0.5.1/core/gna');
 
 // SuperController and EntitySuper — loaded from their source modules
-var SuperController = require('./framework/v0.5.1-alpha.2/core/controller');
-var EntitySuper     = require('./framework/v0.5.1-alpha.2/core/model/entity');
+var SuperController = require('./framework/v0.5.1/core/controller');
+var EntitySuper     = require('./framework/v0.5.1/core/model/entity');
 
 // uuid — from the lib registry
-var uuid = require('./framework/v0.5.1-alpha.2/lib/uuid');
+var uuid = require('./framework/v0.5.1/lib/uuid');
 
 module.exports = {