gina 0.5.10-alpha.1 → 0.5.10

package/CHANGELOG.md

@@ -6,6 +6,10 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.5.10 - 2026-07-05
+### Fixed
+* Fixed a cross-bundle `getRoute(...).toUrl()` link resolving to an unreachable internal host with a doubled web root on reverse-proxied deployments; a proxied request now resolves the public host for both the Isaac and Express engines.
+
 ## 0.5.9 - 2026-07-04
 ### Fixed
 * Fixed `connector:add`, `connector:rm`, and `connector:migrate --fix` corrupting a `connectors.json` that carries a comment header. The scaffolded bundle template's example block contains a `{` inside a `//` comment, and the write-back split the file at the first raw `{` — which landed inside that comment, commenting out the JSON body's opening brace and dropping the rest of the header, so the file no longer parsed (`connector:list`, `connector:test`, and the bundle's own connector load then failed). The header/body split is now comment-aware and preserves the full comment header verbatim; a comment-free `connectors.json` rewrites byte-for-byte as before.

package/README.md

@@ -42,12 +42,9 @@ open https://localhost:3100
 
 > **npm 12+** blocks install scripts by default, and gina's post-install bootstraps `~/.gina` and the framework dependencies. Install with `npm install -g gina@latest --allow-scripts=gina`, or allow it once for all global installs with `npm config set allow-scripts=gina --location=user`. (Not needed on npm ≤ 11.)
 
-## What's in 0.5.9
+## What's in 0.5.10
 
-- **Security — reverse-proxied deployments no longer disclose a bundle's internal host to the browser (#B66).** The client `gina.config.hostname` and the fetched `/_gina/assets/routing.json` no longer serialize each bundle's internal `scheme://host:port` — a proxied client now receives a public host-only origin and a host-stripped routing map, while direct `host:port` access stays byte-identical. This also fixes cross-bundle client `getRoute(...).toUrl()`, which previously resolved to the unreachable internal host on such deployments and now resolves same-origin.
-- **Fixed — server-side proxy host context is request-scoped (#B66).** The server-side URL, redirect, and config resolvers (`self.getConfig()`, `self.redirect()`, server-rendered asset host resolution, and the per-request routing clone) now resolve the host of the request in hand rather than the last proxied host the worker served. A worker that serves a mix of proxied and direct traffic — or several public hostnames — no longer inherits a stale proxied host. Single-public-host-per-worker deployments are unchanged.
-- **Fixed — `connector:add` / `connector:rm` / `connector:migrate --fix` no longer corrupt a comment-headed `connectors.json`.** The header/body split is now comment-aware, so a `connectors.json` that carries a leading comment header (including the scaffolded example block) is preserved verbatim instead of being truncated into an unparseable file. A comment-free `connectors.json` still rewrites byte-for-byte as before.
-- **Fixed — latent `ReferenceError` in server-side URL resolution for redirect routes.** A leftover debug statement referenced an undefined variable and would throw whenever a redirect-flagged route's `toUrl()` was resolved server-side; it has been removed.
+- **Fixed — server-side cross-bundle `getRoute('route@bundle').toUrl()` now resolves the public host on reverse-proxied deployments (#B67).** A controller building a cross-bundle URL server-side — e.g. `self.redirect(getRoute('<route>@<otherBundle>').toUrl())` — could emit an unreachable internal host with a doubled web root on a proxied request; it now resolves the public host for both the Isaac and Express engines. This completes the `0.5.9` client-side cross-bundle URL fix (#B66) on the server side. Single-public-host-per-worker deployments are otherwise unchanged.
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -34,6 +34,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q3 2026** | `0.5.7` ✅ | Durable async-job stores — `jobs.store` (app.json) → `connectors.json` entry: SQLite (`node:sqlite`, zero new dependencies) · MongoDB (shared mongod, multi-pod) · Redis (`ioredis`, atomic per-state + expiry indexes, Redis Cluster via hash-tagged prefix); restart-durable, cross-process, fail-fast on an unbuildable store · opt-in failed-job retry (`maxAttempts` + exponential backoff; completion webhook fires exactly once) · npm 12 readiness (install + release tooling, `--allow-scripts=gina` guidance) · render-delegate concurrency fixes (production cross-request data bleed / wrong-controller error routing / cached-route 500) · `"connector": "redis"` entry no longer aborts boot · **Security**: static-asset path-traversal fix — resolver paths canonicalised and confined to their `statics.json` mapping target (404 on any escape, `%2F` / `%2e%2e` forms included) |
 | **Q3 2026** | `0.5.8` ✅ | `connector:models` — list a configured AI connector's provider models (the read sibling of `connector:test --connect`) · per-group `gina help [<group>]` · **Fixed**: reverse-proxy host context request-scoped — `PROXY_HOST` / `PROXY_HOSTNAME` no longer freeze at the first proxied request (single-hop and multi-hop `X-Forwarded-Host` both handled; raw `host:port` unchanged) · CLI help polish (per-group help output, clean message for an unknown action, em-dash flag typos) |
 | **Q3 2026** | `0.5.9` ✅ | **Security**: reverse-proxied deployments no longer disclose a bundle's internal `scheme://host:port` to the browser — the client `gina.config.hostname` and the fetched `/_gina/assets/routing.json` serve a public host-only origin and a host-stripped routing map to proxied clients (direct `host:port` access byte-identical), also fixing cross-bundle client `getRoute(...).toUrl()` which previously resolved to the unreachable internal host (#B66) · **Fixed**: the server-side URL / redirect / config resolvers request-scope the proxy host, so a worker serving mixed proxied + direct traffic (or several public hosts) no longer inherits a stale proxied host (#B66 S2b) · **Fixed**: `connector:add` / `connector:rm` / `connector:migrate --fix` no longer corrupt a comment-headed `connectors.json` · **Fixed**: a latent `ReferenceError` in server-side URL resolution for redirect-flagged routes |
+| **Q3 2026** | `0.5.10` ✅ | **Fixed**: server-side cross-bundle `getRoute('route@bundle').toUrl()` now resolves the public host on reverse-proxied deployments — a controller building a cross-bundle URL server-side (e.g. via `self.redirect`) could emit an unreachable internal host with a doubled web root on a proxied request; it now resolves the public host for both the Isaac and Express engines. Completes the `0.5.9` client-side cross-bundle URL fix on the server side (#B67) |
 | **Q1 2027** | `0.5.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · Beemaster admin + visual translation editor |
 | **Q3 2027** | `1.0.0` | First stable release — Windows alpha compatibility is a hard gate |
 

package/framework/v0.5.10/VERSION

@@ -0,0 +1 @@
+0.5.10

package/framework/{v0.5.10-alpha.1 → v0.5.10}/core/controller/controller.js

@@ -614,12 +614,21 @@ function SuperController(options) {
                 ctx.config.envConf._isRoutingUpdateNeeded = false;
             }
 
+            // #B67 — a hostname must never carry a webroot. Previously this wrote
+            // `hostname` (= _config.hostname + server.webroot), so getRoute's
+            // `PROXY_HOSTNAME || envConf._proxyHostname` fallback (main.js:1105)
+            // appended a child bundle's webroot to a value already ending in the
+            // parent's webroot -> the <host>/<webroot>//<webroot> blend. Write the
+            // host-only `_config.hostname`; the primary public-host resolution now
+            // comes from the engine-agnostic PROXY_HOSTNAME refresh (router.js),
+            // leaving this a webroot-free fallback. Compare host-only too, so the
+            // change-detection does not spuriously refire every request.
             if (
                 typeof(ctx.config.envConf._proxyHostname) == 'undefined'
                 ||
-                hostname != ctx.config.envConf._proxyHostname
+                _config.hostname != ctx.config.envConf._proxyHostname
             ) {
-                ctx.config.envConf._proxyHostname = (isProxyHost) ? hostname : null;
+                ctx.config.envConf._proxyHostname = (isProxyHost) ? _config.hostname : null;
                 ctx.config.envConf._isRoutingUpdateNeeded = true;
             }
 

package/framework/{v0.5.10-alpha.1 → v0.5.10}/core/router.js

@@ -245,6 +245,38 @@ function Router(env, scope) {
 
         setContext('isProxyHost', isProxyHost);
 
+        // #B67 — lift the reverse-proxy host derivation to this engine-agnostic
+        // point so BOTH engines (isaac + express) resolve a cross-bundle
+        // getRoute('<route>@<bundle>').toUrl() to the PUBLIC host. server.isaac.js
+        // already stashes the per-request slots + refreshes the worker-global
+        // process.gina.PROXY_HOSTNAME (host-only, public), but that block is
+        // isaac-only; an Express-engine request (or a slot-less isaac request)
+        // reaches getRoute with getContext('isProxyHost')=true, PROXY_HOSTNAME
+        // falsy, and envConf._proxyHostname = host+webroot -> getRoute falls back
+        // (main.js:1105) to the host+webroot value -> the
+        // <host>/<webroot>//<webroot> blend. Gated on THIS request's proxied
+        // classification (port-less inbound Host, or an X-Forwarded-Host), NOT on
+        // the sticky isProxyHost latch, so it can never freeze at a `host:port`
+        // (raw) value (the #B65 freeze-guard). Host-only, public; scheme prefers
+        // X-Forwarded-Proto (TLS-terminating proxy) then PROXY_SCHEME then the
+        // bundle scheme.
+        var proxyReqHost = request.headers.host || request.headers[':authority'];
+        var proxyReqIsProxied = (
+            ( proxyReqHost && !/\:[0-9]+$/.test(proxyReqHost) )
+            || request.headers['x-forwarded-host']
+        ) ? true : false;
+        if ( proxyReqIsProxied ) {
+            var proxyReqScheme = request.headers['x-forwarded-proto']
+                || process.gina.PROXY_SCHEME
+                || conf.server.scheme;
+            if ( request.headers['x-forwarded-host'] ) {
+                process.gina.PROXY_HOSTNAME = proxyReqScheme +'://'+ request.headers['x-forwarded-host'];
+                process.gina.PROXY_HOST     = request.headers['x-forwarded-host'];
+            } else {
+                process.gina.PROXY_HOSTNAME = proxyReqScheme +'://'+ proxyReqHost;
+                process.gina.PROXY_HOST     = proxyReqHost;
+            }
+        }
 
 
         /**

package/framework/{v0.5.10-alpha.1 → v0.5.10}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.5.10-alpha.1",
+  "version": "0.5.10",
   "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.10-alpha.1/core/gna');
+var _gna = require('./framework/v0.5.10/core/gna');
 
 // SuperController and EntitySuper — loaded from their source modules
-var SuperController = require('./framework/v0.5.10-alpha.1/core/controller');
-var EntitySuper     = require('./framework/v0.5.10-alpha.1/core/model/entity');
+var SuperController = require('./framework/v0.5.10/core/controller');
+var EntitySuper     = require('./framework/v0.5.10/core/model/entity');
 
 // uuid — from the lib registry
-var uuid = require('./framework/v0.5.10-alpha.1/lib/uuid');
+var uuid = require('./framework/v0.5.10/lib/uuid');
 
 module.exports = {
 

package/llms.txt

@@ -795,7 +795,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 80. **CSRF — three-phase protection (`#CSRF1` Session plugin / `#CSRF2` signed double-submit token / `#CSRF3` Origin pre-filter)** — Session plugin hardens `express-session` cookie defaults from `settings.json > session.cookie.{sameSite, httpOnly, secure}` (opt-in, one-line bundle bootstrap swap, never transparent because bundles legitimately set `httpOnly: false`); signed token middleware uses `crypto.timingSafeEqual` HMAC-SHA256 bound to `req.session.id` with per-route `routing.json > "csrfExempt": true` opt-out (see `routing-and-http2.md § "Per-route flags"` for `req.routing.csrfExempt` two-step propagation: `lib/routing` extracts → `core/server.js` hoists, top-level on `req.routing` not under `param.*`); Origin pre-filter folded INSIDE `gina.plugins.Csrf()` BEFORE token verify on mutating methods, allowlist via `settings.json > csrf.allowedOrigins` (empty defaults to `[bundleHostname]` auto-derived). Negative-invariant lock: matching token + mismatching Origin still 403s — token layer ≠ Origin layer. Implementation traps from the trilogy: plan-vs-shipped attribute drift (downstream commits must `grep -n '<attribute>' <upstream-source-file>` before referencing — source on develop wins, not the plan); CI flake-vs-regression triage (same-message-different-SHA pairs need `git diff --stat A..B` first); source-inspection `indexOf` matches the function DEFINITION before the call site (use unique assignment LHS like `requestOrigin = parseRequestOrigin(req)`); `Origin: "null"` is a real browser value (sandboxed iframes / `file://`) and needs an explicit `s === 'null'` guard so the parser falls through to Referer instead of 403'ing for "origin not allowed".
 
-93. **Reverse-proxy path-prefix awareness via `X-Forwarded-Prefix` — the bundle's internal `server.webroot` stays `/`, but the value templated into `gina.config.webroot` carries the proxy's mount path so client-side root-relative URLs (`/_gina/assets/routing.json`, the `gina.min.css` link injection, etc.) target the correct upstream through the proxy instead of routing to whichever bundle answered bare `/`.** Standard header used by Spring Boot, Traefik, FastAPI, ASP.NET Core, NestJS, Quarkus. Capture site: `core/server.isaac.js` proxy-detection block (sibling to the `X-Forwarded-Host` / `X-Forwarded-Proto` reads); normalisation rules — leading slash added if missing, trailing slashes stripped, empty / `"/"` dropped; stored on `process.gina.PROXY_PREFIX`. Composition site: `core/controller/controller.js` at the `set('page.environment.webroot', ...)` call (~line 513) — when `PROXY_PREFIX` is set, public webroot becomes `prefix + bundle.server.webroot` (slash-normalised), then templated into `gina.onload.min.js`. Internal disk-path resolution and asset-rewrite call sites (e.g. `controller.js:927,956`) still use the bundle's native `server.webroot` — only the browser-facing `gina.config.webroot` carries the prefix; the proxy strips the prefix when forwarding upstream so the bundle's static handlers receive native paths. Symptom shape that surfaces this gap: browser fetches `/_gina/*` URLs that nginx routes to the wrong upstream (the bundle that owns bare `/`, not the bundle that rendered the page); inspector indicator names one bundle but `routing.json` contents come from another. Server-side asset URL rewriting at `controller.js:927,956` and the `linkTo` family also write URLs intended for browser consumption — same prefix-awareness gap, deferred follow-up. The bare `/_gina/assets/routing.json` handler exists only in `server.isaac.js` with no engine-agnostic equivalent in `server.js`; bundles using the Express engine don't have this endpoint at all — independent of this slice but worth noting on the next `/_gina/*` parity sweep. Established 2026-05-06 after the symptom surfaced from a multi-bundle nginx deployment where a sub-path bundle's pages were fetching the root bundle's `routing.json`. **Sibling fix — reverse-proxy HOST context request-scoped (`#B65`, 2026-07-04):** the same one-shot `!isProxyHost` gate froze the `PROXY_HOST` / `PROXY_HOSTNAME` worker-globals (derived from a port-less `Host` or `X-Forwarded-Host`) at the FIRST proxied request's value, and internal `Controller::query()` forwards read that frozen global. `core/server.isaac.js` now request-scopes them — per-request `request._ginaIsProxyHost` / `_ginaProxyHost` / `_ginaProxyHostname` slots (mirroring `_ginaProxyPrefix`), and the worker-global is refreshed on EVERY proxied request so it can never freeze (and, being written ONLY from proxied requests, can never freeze to a raw `host:port`); `core/controller/controller.js` forwards THIS request's proxied host from the slot (worker-global fallback for req-less callers: released-response / ws-query). Classification: a request is proxied when its inbound `Host` is port-less OR it carries `X-Forwarded-Host` — which separates all three topologies safely: RAW `host:port` (never classified proxied → URL builders keep the static config host, unchanged), single-hop (port-less Host → host = Host), multi-hop (`X-Forwarded-Host` wins). `setContext('isProxyHost', true)` stays monotonic (cert-skip readers unaffected). Server-side only, NO dist rebuild; the SERVER-side serve-time rewrites are S2b (shipped 2026-07-04 — see the end of this entry), and the browser-bundled `lib/routing` `toUrl` worker-global proxy read (#B66 S2c) was MEASURED INERT and CLOSED (2026-07-04, no code — inert in single-public-host all-proxied topologies; only mixed-worker / multi-host contaminate; a server-side caller-override fix needs NO dist rebuild — see the end of this entry). Tests: `server.isaac.test.js §15/§15b` (three-topology + freeze-fix + gate-removal subtract), `controller.test.js §30/§30b` (slot-wins-over-stale-global forward, raw-no-forward, req-less→global fallback). **Follow-up — browser-side residual fixed (`#B66`, 2026-07-04):** #B65 fixed the SERVER-side host context; the BROWSER still received every bundle's INTERNAL `scheme://host:port` via two surfaces — the inline `gina.config.hostname` whisper (`controller.js` ~556) AND the boot-static `/_gina/assets/routing.json` blob (`server.isaac.js`). #B66 closes both, SERVER-SIDE, gated on the SAME per-request `request._ginaIsProxyHost` slot (RAW byte-identical, NO dist rebuild): **S1** whispers `page.environment.hostname = local.req._ginaProxyHostname` (host-only, port-less, forwarded scheme) when proxied — the internal `hostname` var + `_proxyHostname` stay byte-identical (grep-confirmed no server-side reader of `page.environment.hostname` besides the whisper template); **S2** boot-builds a SECOND host-stripped `routing.json` (drops each route's `host`+`hostname`, KEEPS `webroot`, still `.br`/`.gz`), served instead of the full blob when proxied with `Cache-Control: private` (a shared cache must not cross-serve variants). The host-only whisper is what flips the browser routing self-check (`lib/routing/src/main.js:1034` — it can't strip a port/webroot the whispered value carries, so an internal `host:port(+webroot)` leaves it false), after which cross-bundle `toUrl` (`:1189/1193`) resolves same-origin instead of the unreachable internal host. Measured (daemonless 2-bundle + reverse-proxy-header repro, real `getRoute().toUrl()` 4-state matrix): S1 ALONE fixes the function (route.hostname intact → public origin); stripping `route.hostname` is SAFE (the design's "degrades to a same-origin URL, no throw" holds) and matters ONLY in states where S1 hasn't flipped the self-check, which are UNREACHABLE in production because S1+S2 are COUPLED by the same per-request gate (both fire when proxied, neither when raw). Precision correction to the design's raw-form claim: in that unreachable strip-without-S1 state the RAW `toUrl` return carries an `"undefined"` segment — `''+this.hostname` with the host/hostname key absent → `"undefined/webroot/path"`, which the browser resolves RELATIVE to the current origin (same-origin, wrong path — i.e. the design's "relative same-origin" is functionally right; its "no undefined" summary just missed the raw segment); `"no throw"` holds because `webroot` is kept. The one out-of-scope edge is a mode-2 proxied deploy whose PUBLIC url carries an explicit port (self-check needs `!location.port`), already broken today. Tests: `controller.test.js §31/§31b`, `server.isaac.test.js §16/§16b` (+ the §09 fixed-window X-Powered-By pin converted to a structural ordering pin — the handler insert displaced it, sanctioned test change). **S2b shipped (2026-07-04, server-side, NO dist rebuild):** the 4 serve-time host rewrites in `controller.js` — the setOptions routing-clone gate + the `page.environment.proxyHost/Hostname` whisper, `getNodeRes`'s proxied-host build, `redirect`'s target host, and `getConfig`'s hostname/host override — now read THIS request's per-request slot (`local.req._ginaIsProxyHost` / `_ginaProxyHost` / `_ginaProxyHostname`) with the worker-global as a MANDATORY fallback (the Express engine — the default when `engine` is unset — never sets the slots, and `getConfig` is reachable req-less: ws-query / released-response / async health probe). Closes the mixed-worker/multi-tenant/concurrent-request residual — a direct or interleaved request on a worker that just served a proxied one no longer resolves the stale last-proxied host. Measured non-leaks left out of scope: the isSpecialCase `:host != PROXY_HOST` comparisons (a cross-bundle-link heuristic a stale global can't flip) and `query()`'s `PROXY_SCHEME` (boot-static, never per-request-refreshed). §12 reconcile — the getConfig re-point is neutral-or-better for the Origin-header false-positive: `_ginaIsProxyHost` is classified in `server.isaac.js` (`:1704`) BEFORE the Origin→Host rewrite (`:2089`), so a same-origin direct POST classifies `false` and getConfig no longer overwrites the config hostname. Live before/after on the REAL getConfig (mixed proxied-A → raw → proxied-B interleave: 2 fails → 5/5). Tests: `controller.test.js §32/§32b` (source pins on all 4 sites + pure-logic replicas + subtract). The browser-bundled `lib/routing` `toUrl`/`getRoute` worker-global proxy read (#B66 S2c) was MEASURED INERT and CLOSED (2026-07-04, no code) — inert in the single-public-host all-proxied topology (only mixed-worker / multi-host contaminate); a server-side caller-override fix (NO dist rebuild) is the ready recipe if a future topology needs it.
+93. **Reverse-proxy path-prefix awareness via `X-Forwarded-Prefix` — the bundle's internal `server.webroot` stays `/`, but the value templated into `gina.config.webroot` carries the proxy's mount path so client-side root-relative URLs (`/_gina/assets/routing.json`, the `gina.min.css` link injection, etc.) target the correct upstream through the proxy instead of routing to whichever bundle answered bare `/`.** Standard header used by Spring Boot, Traefik, FastAPI, ASP.NET Core, NestJS, Quarkus. Capture site: `core/server.isaac.js` proxy-detection block (sibling to the `X-Forwarded-Host` / `X-Forwarded-Proto` reads); normalisation rules — leading slash added if missing, trailing slashes stripped, empty / `"/"` dropped; stored on `process.gina.PROXY_PREFIX`. Composition site: `core/controller/controller.js` at the `set('page.environment.webroot', ...)` call (~line 513) — when `PROXY_PREFIX` is set, public webroot becomes `prefix + bundle.server.webroot` (slash-normalised), then templated into `gina.onload.min.js`. Internal disk-path resolution and asset-rewrite call sites (e.g. `controller.js:927,956`) still use the bundle's native `server.webroot` — only the browser-facing `gina.config.webroot` carries the prefix; the proxy strips the prefix when forwarding upstream so the bundle's static handlers receive native paths. Symptom shape that surfaces this gap: browser fetches `/_gina/*` URLs that nginx routes to the wrong upstream (the bundle that owns bare `/`, not the bundle that rendered the page); inspector indicator names one bundle but `routing.json` contents come from another. Server-side asset URL rewriting at `controller.js:927,956` and the `linkTo` family also write URLs intended for browser consumption — same prefix-awareness gap, deferred follow-up. The bare `/_gina/assets/routing.json` handler exists only in `server.isaac.js` with no engine-agnostic equivalent in `server.js`; bundles using the Express engine don't have this endpoint at all — independent of this slice but worth noting on the next `/_gina/*` parity sweep. Established 2026-05-06 after the symptom surfaced from a multi-bundle nginx deployment where a sub-path bundle's pages were fetching the root bundle's `routing.json`. **Sibling fix — reverse-proxy HOST context request-scoped (`#B65`, 2026-07-04):** the same one-shot `!isProxyHost` gate froze the `PROXY_HOST` / `PROXY_HOSTNAME` worker-globals (derived from a port-less `Host` or `X-Forwarded-Host`) at the FIRST proxied request's value, and internal `Controller::query()` forwards read that frozen global. `core/server.isaac.js` now request-scopes them — per-request `request._ginaIsProxyHost` / `_ginaProxyHost` / `_ginaProxyHostname` slots (mirroring `_ginaProxyPrefix`), and the worker-global is refreshed on EVERY proxied request so it can never freeze (and, being written ONLY from proxied requests, can never freeze to a raw `host:port`); `core/controller/controller.js` forwards THIS request's proxied host from the slot (worker-global fallback for req-less callers: released-response / ws-query). Classification: a request is proxied when its inbound `Host` is port-less OR it carries `X-Forwarded-Host` — which separates all three topologies safely: RAW `host:port` (never classified proxied → URL builders keep the static config host, unchanged), single-hop (port-less Host → host = Host), multi-hop (`X-Forwarded-Host` wins). `setContext('isProxyHost', true)` stays monotonic (cert-skip readers unaffected). Server-side only, NO dist rebuild; the SERVER-side serve-time rewrites are S2b (shipped 2026-07-04 — see the end of this entry), and the browser-bundled `lib/routing` `toUrl` worker-global proxy read (#B66 S2c) was MEASURED INERT and CLOSED (2026-07-04, no code — inert in single-public-host all-proxied topologies; only mixed-worker / multi-host contaminate; a server-side caller-override fix needs NO dist rebuild — see the end of this entry). Tests: `server.isaac.test.js §15/§15b` (three-topology + freeze-fix + gate-removal subtract), `controller.test.js §30/§30b` (slot-wins-over-stale-global forward, raw-no-forward, req-less→global fallback). **Follow-up — browser-side residual fixed (`#B66`, 2026-07-04):** #B65 fixed the SERVER-side host context; the BROWSER still received every bundle's INTERNAL `scheme://host:port` via two surfaces — the inline `gina.config.hostname` whisper (`controller.js` ~556) AND the boot-static `/_gina/assets/routing.json` blob (`server.isaac.js`). #B66 closes both, SERVER-SIDE, gated on the SAME per-request `request._ginaIsProxyHost` slot (RAW byte-identical, NO dist rebuild): **S1** whispers `page.environment.hostname = local.req._ginaProxyHostname` (host-only, port-less, forwarded scheme) when proxied — the internal `hostname` var + `_proxyHostname` stay byte-identical (grep-confirmed no server-side reader of `page.environment.hostname` besides the whisper template); **S2** boot-builds a SECOND host-stripped `routing.json` (drops each route's `host`+`hostname`, KEEPS `webroot`, still `.br`/`.gz`), served instead of the full blob when proxied with `Cache-Control: private` (a shared cache must not cross-serve variants). The host-only whisper is what flips the browser routing self-check (`lib/routing/src/main.js:1034` — it can't strip a port/webroot the whispered value carries, so an internal `host:port(+webroot)` leaves it false), after which cross-bundle `toUrl` (`:1189/1193`) resolves same-origin instead of the unreachable internal host. Measured (daemonless 2-bundle + reverse-proxy-header repro, real `getRoute().toUrl()` 4-state matrix): S1 ALONE fixes the function (route.hostname intact → public origin); stripping `route.hostname` is SAFE (the design's "degrades to a same-origin URL, no throw" holds) and matters ONLY in states where S1 hasn't flipped the self-check, which are UNREACHABLE in production because S1+S2 are COUPLED by the same per-request gate (both fire when proxied, neither when raw). Precision correction to the design's raw-form claim: in that unreachable strip-without-S1 state the RAW `toUrl` return carries an `"undefined"` segment — `''+this.hostname` with the host/hostname key absent → `"undefined/webroot/path"`, which the browser resolves RELATIVE to the current origin (same-origin, wrong path — i.e. the design's "relative same-origin" is functionally right; its "no undefined" summary just missed the raw segment); `"no throw"` holds because `webroot` is kept. The one out-of-scope edge is a mode-2 proxied deploy whose PUBLIC url carries an explicit port (self-check needs `!location.port`), already broken today. Tests: `controller.test.js §31/§31b`, `server.isaac.test.js §16/§16b` (+ the §09 fixed-window X-Powered-By pin converted to a structural ordering pin — the handler insert displaced it, sanctioned test change). **S2b shipped (2026-07-04, server-side, NO dist rebuild):** the 4 serve-time host rewrites in `controller.js` — the setOptions routing-clone gate + the `page.environment.proxyHost/Hostname` whisper, `getNodeRes`'s proxied-host build, `redirect`'s target host, and `getConfig`'s hostname/host override — now read THIS request's per-request slot (`local.req._ginaIsProxyHost` / `_ginaProxyHost` / `_ginaProxyHostname`) with the worker-global as a MANDATORY fallback (the Express engine — the default when `engine` is unset — never sets the slots, and `getConfig` is reachable req-less: ws-query / released-response / async health probe). Closes the mixed-worker/multi-tenant/concurrent-request residual — a direct or interleaved request on a worker that just served a proxied one no longer resolves the stale last-proxied host. Measured non-leaks left out of scope: the isSpecialCase `:host != PROXY_HOST` comparisons (a cross-bundle-link heuristic a stale global can't flip) and `query()`'s `PROXY_SCHEME` (boot-static, never per-request-refreshed). §12 reconcile — the getConfig re-point is neutral-or-better for the Origin-header false-positive: `_ginaIsProxyHost` is classified in `server.isaac.js` (`:1704`) BEFORE the Origin→Host rewrite (`:2089`), so a same-origin direct POST classifies `false` and getConfig no longer overwrites the config hostname. Live before/after on the REAL getConfig (mixed proxied-A → raw → proxied-B interleave: 2 fails → 5/5). Tests: `controller.test.js §32/§32b` (source pins on all 4 sites + pure-logic replicas + subtract). The browser-bundled `lib/routing` `toUrl`/`getRoute` worker-global proxy read (#B66 S2c) was MEASURED INERT and CLOSED (2026-07-04, no code) — inert in the single-public-host all-proxied topology (only mixed-worker / multi-host contaminate); a server-side caller-override fix (NO dist rebuild) is the ready recipe if a future topology needs it. **#B67 fixed (2026-07-05, commit `439a49a1`):** the SERVER-side *proxied* cross-bundle `getRoute('<route>@<child>').toUrl()` redirect — a genuine residual the "S2c inert" claim did NOT cover (a direct `getRoute().toUrl()` has no `url`-filter override, so it emitted an unreachable host+webroot blend `<parent-internal-host>:<port>/<parent-webroot>//<child-webroot>` instead of `<public-host>/<child-webroot>`) — is now fixed engine-agnostically WITHOUT touching getRoute (NO dist rebuild): `core/router.js` refreshes the host-only worker-global `PROXY_HOSTNAME` at the engine-agnostic routing point (right after `setContext('isProxyHost', …)`) on every request classified proxied by THIS request's Host (`port-less Host || X-Forwarded-Host` — the #B65 gate, not the sticky latch, so no freeze), and `core/controller/controller.js:622` writes a host-ONLY `_proxyHostname` (was host+webroot), so getRoute's `PROXY_HOSTNAME || _proxyHostname` fallback reads the public host for BOTH engines and the double-webroot blend is gone. The MIXED-worker raw-after-proxied edge stays #B66 S2c (inert; ready escalation = the Approach-A ALS above — a req-less singleton like getRoute needs an ALS OR a reliably-refreshed engine-agnostic worker-global, never a per-request slot it can't read). Tests: `router.test.js §12` (3-topology × both-engine composition + subtract) + `controller.test.js §33`.
 
 94. **ScyllaDB / Cassandra connector — `cassandra-driver` wrapper + fictitious `@scylladb/scylla-driver` registry placeholder + CQL ergonomics + `USING TTL` session store** — The Node.js ecosystem has no first-party shard-aware ScyllaDB driver (Python / Java / Go / Rust drivers are first-party shard-aware; Node.js is not), so the framework `scylladb` connector wraps `cassandra-driver` (Apache Software Foundation, `>=4.0.0` requires Node >=20, eval-safe per #SCS1 posture). Pre-#CN5 `lib/connector-registry/src/main.js` pinned `@scylladb/scylla-driver@>=1.0.0` as a placeholder — that npm package does not exist (404), which would have failed at install time the moment `connector:add primary --connector=scylladb --driver-version=...` printed its install hint. **Always `npm view <pkg>` to confirm the package exists** when populating registry-style mappings — same shape as the #I18N2 `intl-messageformat@9.13.0` non-existent-version trap. **CQL ORM** mirrors the SQL connector shape: entity files at `models/<keyspace>/cql/<Entity>/*.sql` (distinct dir like Couchbase's `n1ql/`, uniform `.sql` extension), `?` positional placeholders, `client.execute(query, args, { prepare: true })` returning Promise + `.onComplete()` shim, `@param` casting for CQL types (text/int/bigint/uuid/timeuuid/timestamp/boolean/blob/list/set/map/decimal/double/inet), `@return` coercion handling SELECT rows / LWT `[applied]` / write defaults. **CQL session store** has no Redis-EXPIRE equivalent — `set()` issues `INSERT … USING TTL <ttl>` (atomic write + expiry); `touch()` issues `UPDATE … USING TTL <ttl> SET sess = ? WHERE sid = ?` (rewrites data with fresh TTL); `clear()` uses CQL `TRUNCATE` (heavy cluster op — the only full-table delete CQL allows). Required schema: `CREATE TABLE sessions (sid TEXT PRIMARY KEY, sess TEXT) WITH default_time_to_live = 86400`. Promise → callback safety mirrors post-#CB-BUG-4: write methods MUST call `fn(null)` explicitly inside `.then()`, never `.then(fn)` directly. Established 2026-05-09 (#CN5). **MongoDB connector (#CN6)** — wraps the official `mongodb` driver (`>=7.0.0`); JSON op files at `models/<db>/pipelines/<Entity>/*.json` with `{"$arg":N}` / `{"$oid":hex}` / `"$scope"` placeholders + `castParam` BSON coercion (`objectid`/`int`/`long`/`double`/`date`/etc.); self-contained TTL-index session store auto-creates `{expiresAt:1}` (`expireAfterSeconds:0`, one-shot `_ttlReady` guard, `IndexOptionsConflict` warn-and-continue) and filters `{expiresAt:{$gt:now}}` because Mongo's TTL monitor lags up to 60s (vs Scylla's server-side `USING TTL` reap — same intent, different mechanism). Both connectors' registry pins must EXIST and be CURRENT (`npm view <pkg>` — the `@scylladb/scylla-driver` 404 + stale `mongodb>=5` traps). Established 2026-05-09 (#CN6).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina",
-  "version": "0.5.10-alpha.1",
+  "version": "0.5.10",
   "description": "Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency",
   "keywords": [
     "nodejs",
@@ -73,12 +73,12 @@
     "gina-container": "bin/gina-container",
     "gina-init": "bin/gina-init"
   },
-  "main": "./framework/v0.5.10-alpha.1/core/gna",
+  "main": "./framework/v0.5.10/core/gna",
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
       "import": "./index.mjs",
-      "require": "./framework/v0.5.10-alpha.1/core/gna.js"
+      "require": "./framework/v0.5.10/core/gna.js"
     },
     "./gna": {
       "types": "./types/gna.d.ts",

package/framework/v0.5.10-alpha.1/VERSION

@@ -1 +0,0 @@
-0.5.10-alpha.1