gina 0.6.8 → 0.6.9

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

@@ -94,6 +94,8 @@ function CmdHelper(cmd, client, debug) {
         // don't use this collection to store into files
         bundlesByProject: {}, // bundles collection will be loaded into cmd.projects[$project].bundles
         bundlesLocation : null, // symlink to cmd.projects[$project].bundles_path
+        warnedAbsentBundles : {}, // #B375 — once-per-command dedup for the declared-but-absent-bundle warning emitted by loadAssets()
+        warnedInvalidServerSettings : {}, // #B378 — once-per-command dedup for the invalid bundle protocol/scheme warning emitted by loadAssets()
 
         // current project env.json path
         envPath : null, // path to env.json - defined by filterArgs()
@@ -663,6 +665,18 @@ function CmdHelper(cmd, client, debug) {
      * A registered project whose directory exists but whose manifest.json is missing
      * (a stale ~/.gina/projects.json entry) is warned and skipped (#B24) rather than
      * aborting the whole command.
+     * On `project:add`/`project:import`, the current project's bundle list is the
+     * UNION of the manifest's declared bundles and the bundle directories found on
+     * disk (#B375): declared entries are preserved as-is, disk-only bundles are
+     * appended for additive registration, and a declared bundle whose tree is
+     * absent is warned about once per command — never auto-pruned, since the
+     * declaration may be scope-restricted (#B373).
+     * Each project's bundles are resolved against that project's OWN path (#B379),
+     * and a project's protocols/schemes lists are DERIVED bookkeeping constrained
+     * to the framework's supported sets from `~/main.json` (#B378): a bundle's
+     * declared `server.protocol`/`server.scheme` may extend its project's list
+     * only when the framework supports the value — an unsupported one is warned
+     * about once per command and never adopted or made a default.
      * Also links node_modules and gina when running start/stop/restart tasks in global mode.
      * Assigns itself to the global `loadAssets`.
      *
@@ -1373,36 +1387,53 @@ function CmdHelper(cmd, client, debug) {
                 }
 
                 cmd.bundlesByProject[project]   = (cmd.bundlesByProject[project].count() > 0) ? cmd.bundlesByProject[project] : requireJSON(projectPropertiesPath).bundles;
-                // additional checks
-                let bundlesCount = cmd.bundlesByProject[project].count();
-                if ( /^project\:(add|import)/.test(cmd.task) && bundlesCount > 0 ) {
-                    let releasesPathObj = new _(cmd.projects[project].path +'/releases', true);
-                    let _bundleConfigPath = cmd.bundlesLocation;
-                    let files = [], f = 0;
-                    if ( new _(cmd.projects[project].path +'/src', true).existsSync() ) {
-                        files = fs.readdirSync(_(cmd.projects[project].path +'/src', true));
-                    } else if (releasesPathObj.existsSync()) {
-                        _bundleConfigPath = releasesPathObj.toString();
-                        files = fs.readdirSync(releasesPathObj.toString());
-                    }
-                    let _count = 0;
-                    for (;f < files.length; ++f) {
-                        // skip hidden
-                        let name = files[f];
-                        if ( /^\./.test(name) ) continue;
-                        _count++
-                    }
-                    if (_count != bundlesCount) {
-                        cmd.bundles = [];
-                        cmd.bundlesByProject[project] = {}
-                        let updatedManifest = requireJSON(projectPropertiesPath);
-                        updatedManifest.bundles = {};
-                        lib.generator.createFileFromDataSync(
-                            updatedManifest,
-                            projectPropertiesPath
-                        )
-                    }
-                }
+                // #B375 — the "additional checks" block below (introduced 2023, absorbed into an
+                // automated version-bump commit, never revisited) compared each project's declared
+                // bundle COUNT against a readdir of `<project>/src` (else `/releases`) and, on ANY
+                // mismatch, emptied `manifest.bundles` and wrote it back to disk — for EVERY
+                // registered project, not just the one being added/imported. That destroyed every
+                // per-bundle declaration the recreation skeleton does not carry (the `scopes`
+                // allow-list — #B373 —, `gina_version`, any custom key), reset `version`/`tag` and
+                // release targets to defaults, permanently emptied bystander projects' manifests
+                // (no rebuild ever runs for a non-target project), and did the same on plain
+                // `project:add` (the rebuild only runs on import). Its one legitimate function —
+                // forcing a rescan of the bundle directories so bundles on disk but missing from
+                // the manifest still get registered on import — is now served non-destructively by
+                // the union rescan near the end of loadAssets, which no longer needs `cmd.bundles`
+                // to be emptied to fire. Manifest entries are never auto-pruned anymore: a
+                // declared bundle whose tree is absent is warned about there instead.
+                // Kept commented per the replace-don't-delete convention:
+                //
+                // // additional checks
+                // let bundlesCount = cmd.bundlesByProject[project].count();
+                // if ( /^project\:(add|import)/.test(cmd.task) && bundlesCount > 0 ) {
+                //     let releasesPathObj = new _(cmd.projects[project].path +'/releases', true);
+                //     let _bundleConfigPath = cmd.bundlesLocation;
+                //     let files = [], f = 0;
+                //     if ( new _(cmd.projects[project].path +'/src', true).existsSync() ) {
+                //         files = fs.readdirSync(_(cmd.projects[project].path +'/src', true));
+                //     } else if (releasesPathObj.existsSync()) {
+                //         _bundleConfigPath = releasesPathObj.toString();
+                //         files = fs.readdirSync(releasesPathObj.toString());
+                //     }
+                //     let _count = 0;
+                //     for (;f < files.length; ++f) {
+                //         // skip hidden
+                //         let name = files[f];
+                //         if ( /^\./.test(name) ) continue;
+                //         _count++
+                //     }
+                //     if (_count != bundlesCount) {
+                //         cmd.bundles = [];
+                //         cmd.bundlesByProject[project] = {}
+                //         let updatedManifest = requireJSON(projectPropertiesPath);
+                //         updatedManifest.bundles = {};
+                //         lib.generator.createFileFromDataSync(
+                //             updatedManifest,
+                //             projectPropertiesPath
+                //         )
+                //     }
+                // }
 
             } else {
                 cmd.projects[project].exists    = false;
@@ -1456,10 +1487,18 @@ function CmdHelper(cmd, client, debug) {
                 cmd.bundlesByProject[project][bundle].schemes   = cmd.projects[project].schemes;
                 cmd.bundlesByProject[project][bundle].def_scheme = cmd.defaultScheme;
 
-                if ( fs.existsSync(_(cmd.projectLocation + '/'+ cmd.bundlesByProject[project][bundle].src )) ) {
+                // #B379 — resolve each project's bundles against ITS OWN path. This loop
+                // runs over EVERY registered project, while the singular
+                // `cmd.projectLocation` names only the CURRENT one — so a same-named
+                // bundle in another project used to be read out of the wrong tree: its
+                // `exists` flag, `configPaths` and default protocol/scheme all came from
+                // the current project's files, and whatever its namesake declared there
+                // leaked into the other project's registry entry.
+                let _ownProjectPath = cmd.projects[project].path;
+                if ( fs.existsSync(_(_ownProjectPath + '/'+ cmd.bundlesByProject[project][bundle].src )) ) {
                     cmd.bundlesByProject[project][bundle].exists = true;
                     // adding configurations
-                    bundleConfigPath = _(cmd.projectLocation + '/'+ cmd.bundlesByProject[project][bundle].src +'/config' );
+                    bundleConfigPath = _(_ownProjectPath + '/'+ cmd.bundlesByProject[project][bundle].src +'/config' );
                     cmd.bundlesByProject[project][bundle].configPaths = {
                         settings: _(bundleConfigPath +'/settings.json')
                     };
@@ -1471,22 +1510,40 @@ function CmdHelper(cmd, client, debug) {
                             typeof(settings.server) != 'undefined'
                             && typeof(settings.server.protocol) != 'undefined'
                         ) {
-                            // adding in case of bad configuration : exists in bundle, but not listed in available/global settings
-                            if (cmd.bundlesByProject[project][bundle].protocols.indexOf(settings.server.protocol) < 0)
-                                cmd.bundlesByProject[project][bundle].protocols.push(settings.server.protocol);
-
-                            cmd.bundlesByProject[project][bundle].def_protocol = settings.server.protocol
+                            // #B378 — a bundle's declared protocol may extend the project's
+                            // list ONLY when the framework itself supports it. The entry's
+                            // `.protocols` deliberately aliases the project's own array
+                            // (assigned above): that aliasing is how the project's port
+                            // matrix learns what its bundles use — and it persists to
+                            // ~/.gina/projects.json on the next registry write, from where
+                            // `image:build` bakes the list into a container's environment.
+                            // So an unsupported value is surfaced by name instead of
+                            // adopted, and never becomes the entry's default either.
+                            if ( cmd.protocolsAvailable.indexOf(settings.server.protocol) > -1 ) {
+                                if (cmd.bundlesByProject[project][bundle].protocols.indexOf(settings.server.protocol) < 0)
+                                    cmd.bundlesByProject[project][bundle].protocols.push(settings.server.protocol);
+
+                                cmd.bundlesByProject[project][bundle].def_protocol = settings.server.protocol
+                            } else if ( !cmd.warnedInvalidServerSettings[project +'/'+ bundle +':protocol'] ) {
+                                cmd.warnedInvalidServerSettings[project +'/'+ bundle +':protocol'] = true;
+                                console.warn('Bundle `'+ bundle +'` of project `@'+ project +'` declares `server.protocol: "'+ settings.server.protocol +'"`, which is not an allowed protocol (allowed: '+ cmd.protocolsAvailable.join(', ') +' — check your framework configuration `~/main.json`). Ignoring it: the bundle keeps the default `'+ cmd.bundlesByProject[project][bundle].def_protocol +'`.');
+                            }
                         }
 
                         if (
                             typeof(settings.server) != 'undefined'
                             && typeof(settings.server.scheme) != 'undefined'
                         ) {
-                            // adding in case of bad configuration : exists in bundle, but not listed in available/global settings
-                            if (cmd.bundlesByProject[project][bundle].schemes.indexOf(settings.server.scheme) < 0)
-                                cmd.bundlesByProject[project][bundle].schemes.push(settings.server.scheme);
-
-                            cmd.bundlesByProject[project][bundle].def_scheme = settings.server.scheme
+                            // #B378 — same rule as the protocol above.
+                            if ( cmd.schemesAvailable.indexOf(settings.server.scheme) > -1 ) {
+                                if (cmd.bundlesByProject[project][bundle].schemes.indexOf(settings.server.scheme) < 0)
+                                    cmd.bundlesByProject[project][bundle].schemes.push(settings.server.scheme);
+
+                                cmd.bundlesByProject[project][bundle].def_scheme = settings.server.scheme
+                            } else if ( !cmd.warnedInvalidServerSettings[project +'/'+ bundle +':scheme'] ) {
+                                cmd.warnedInvalidServerSettings[project +'/'+ bundle +':scheme'] = true;
+                                console.warn('Bundle `'+ bundle +'` of project `@'+ project +'` declares `server.scheme: "'+ settings.server.scheme +'"`, which is not an allowed scheme (allowed: '+ cmd.schemesAvailable.join(', ') +' — check your framework configuration `~/main.json`). Ignoring it: the bundle keeps the default `'+ cmd.bundlesByProject[project][bundle].def_scheme +'`.');
+                            }
                         }
                     }
 
@@ -1525,10 +1582,22 @@ function CmdHelper(cmd, client, debug) {
             return false;
         }
 
+        // #B375 — this rescan used to be gated on `!cmd.bundles.length`, which only ever
+        // opened after the destructive count-mismatch reset (now retired, see above) had
+        // emptied the list: that reset WAS the discovery mechanism for bundles present on
+        // disk but missing from the manifest. The rescan now always runs for
+        // `project:add`/`project:import` on the current project and UNIONS the two sources
+        // instead: manifest-declared bundles keep their existing entries untouched
+        // (`scopes`, `version`, custom keys, release targets — all preserved), and only
+        // bundles found on disk but absent from the manifest are appended, for
+        // `addBundleToManifest` to seed additively (#B55). A bundle declared in the
+        // manifest but absent from disk is warned about, never auto-pruned: the
+        // declaration may be deliberate (a bundle restricted to other scopes — #B373 —
+        // whose tree is stripped at this scope); removing it for good is
+        // `gina bundle:remove`'s job.
         if (
             /^project\:(add|import)/.test(cmd.task)
             && typeof(cmd.projects[cmd.projectName]) != 'undefined'
-            && !cmd.bundles.length
         ) {
             var releasesPathObj = new _(cmd.projects[cmd.projectName].path +'/releases', true);
             var _bundleConfigPath = cmd.bundlesLocation;
@@ -1539,18 +1608,35 @@ function CmdHelper(cmd, client, debug) {
                 _bundleConfigPath = releasesPathObj.toString();
                 files = fs.readdirSync(releasesPathObj.toString());
             }
+            var _diskNames = [];
             for (;f < files.length; ++f) {
                 // skip hidden
                 let name = files[f];
                 if ( /^\./.test(name) ) continue;
+                _diskNames.push(name);
+                if ( cmd.bundles.indexOf(name) > -1 ) {
+                    // already declared in the manifest — keep the existing entry untouched
+                    continue;
+                }
                 cmd.bundles.push(name);
-                _bundleConfigPath += '/'+ name;
+                // #B376 — the settings path is derived from the loop-invariant scan root
+                // for every bundle: the previous version mutated the root across
+                // iterations, so every bundle after the first got a path nested under its
+                // predecessors and the settings-consistency pass silently skipped it.
                 cmd.bundlesByProject[cmd.projectName][name] = {
+                    src: 'src/'+ name,
                     configPaths: {
-                        settings: _(_bundleConfigPath +'/config/settings.json', true)
+                        settings: _(_bundleConfigPath +'/'+ name +'/config/settings.json', true)
                     }
                 };
             }
+            // Surface manifest entries whose tree is missing from the scanned location —
+            // once per bundle per command (loadAssets runs several times per command).
+            for (let declared in cmd.bundlesByProject[cmd.projectName]) {
+                if ( _diskNames.indexOf(declared) > -1 || cmd.warnedAbsentBundles[declared] ) continue;
+                cmd.warnedAbsentBundles[declared] = true;
+                console.warn('Bundle `'+ declared +'` is declared in the manifest.json of project `@'+ cmd.projectName +'` but was not found under `'+ _bundleConfigPath +'` — keeping the declaration (it may be restricted to other scopes); if the bundle is gone for good, remove it with `gina bundle:remove '+ declared +' @'+ cmd.projectName +'`.');
+            }
             cmd.bundles.sort()
         }
 
@@ -1783,17 +1869,30 @@ function CmdHelper(cmd, client, debug) {
         }
 
         // getting available all protocols
+        // #B380 — read the SOURCE list by its own index, exactly as the env loop
+        // above does: the previous form indexed the TARGET with the source's index,
+        // so once the contextual list outgrew the project's own, the overshoot read
+        // undefined. #B378 — and merge only values the framework supports: the
+        // contextual list also grows from ports.json keys, which can retain
+        // protocols a framework update removed.
         for (let p in cmd.protocols) {
-            let newProtocol = allProjectProtocols[p];
-            if (allProjectProtocols.indexOf(newProtocol) < 0) {
+            let newProtocol = cmd.protocols[p];
+            if (
+                cmd.protocolsAvailable.indexOf(newProtocol) > -1
+                && allProjectProtocols.indexOf(newProtocol) < 0
+            ) {
                 console.debug('adding new protocol ['+newProtocol+'] VS' + JSON.stringify(cmd.protocols, null, 2));
                 allProjectProtocols.push(newProtocol);
             }
         }
         // getting available all schemes
+        // #B380 / #B378 — same two rules as the protocol loop above.
         for (let p in cmd.schemes) {
-            let newScheme = allProjectSchemes[p];
-            if (allProjectSchemes.indexOf(newScheme) < 0) {
+            let newScheme = cmd.schemes[p];
+            if (
+                cmd.schemesAvailable.indexOf(newScheme) > -1
+                && allProjectSchemes.indexOf(newScheme) < 0
+            ) {
                 console.debug('adding new scheme ['+newScheme+'] VS' + JSON.stringify(cmd.schemes, null, 2));
                 allProjectSchemes.push(newScheme);
             }

package/framework/{v0.6.8 → v0.6.9}/lib/cmd/project/add.js

@@ -390,6 +390,58 @@ function Add(opt, cmd) {
     }
 
 
+    /**
+     * Copies the framework's `_gitignore` template to the project's `.gitignore`,
+     * but only when the project does not already have one (#B258).
+     *
+     * The `_` prefix is the ship-time name: a real `.gitignore` tracked inside
+     * `core/template/` would be read by git as ignore rules for the framework's
+     * own tree. The rename to the dotted form belongs here, at scaffold time —
+     * and until now nothing performed it, so the template shipped in every
+     * tarball with no consumer and scaffolded projects got no `.gitignore` at
+     * all. That left the `.env` / `*.env` globs it carries unable to protect
+     * anything, which is the security-adjacent half of this fix.
+     *
+     * SKIP-IF-EXISTS is deliberate. A project's `.gitignore` is the user's file
+     * and routinely carries rules the framework knows nothing about; filling a
+     * gap is safe, replacing is not. This also makes the step idempotent, so
+     * re-running `project:add` over an existing project cannot clobber it.
+     *
+     * Note this does NOT reuse `lib.generator.createFileFromTemplateSync`, which
+     * is otherwise the right shape: it unlinks the target first, so it cannot
+     * express skip-if-exists, and it chmods 0755 — an executable `.gitignore`.
+     *
+     * Never fatal: a scaffold that produced a complete, working project should
+     * not fail over an ignore file the operator can write by hand.
+     *
+     * @inner
+     * @private
+     * @param {string} target - Absolute path to the project's `.gitignore`
+     * @returns {boolean} true when written, false when one already existed or the write was skipped
+     *
+     * @example
+     * createGitignoreFile('/path/to/project/.gitignore'); // → true on a fresh project
+     * createGitignoreFile('/path/to/project/.gitignore'); // → false the second time
+     */
+    var createGitignoreFile = function(target) {
+        try {
+            if ( fs.existsSync(target) ) {
+                return false
+            }
+            var source = _(getPath('gina').core + '/template/_gitignore', true).toString();
+            if ( !fs.existsSync(source) ) {
+                return false
+            }
+            fs.writeFileSync(target, fs.readFileSync(source));
+            try { fs.chmodSync(target, 0o644) } catch (chmodErr) { /* best effort */ }
+            return true
+        } catch (gitignoreErr) {
+            console.warning('[ project:add ] could not write `.gitignore`: ' + (gitignoreErr.message || gitignoreErr));
+            return false
+        }
+    }
+
+
     /**
      * Creates or updates package.json from the framework template, merging
      * any existing file when isCreatedFromExistingPackage is true.
@@ -430,6 +482,12 @@ function Add(opt, cmd) {
             target
         );
 
+        // #B258 — the project's `.gitignore`, written only when absent. This is
+        // the last scaffold step for both the new-project and the import path:
+        // an imported project without one has exactly the same exposure as a
+        // fresh one, and skip-if-exists keeps the import non-destructive.
+        createGitignoreFile( _(self.projectLocation + '/.gitignore', true).toString() );
+
         end(true)
     }
 
@@ -593,6 +651,10 @@ function Add(opt, cmd) {
      * and writes ports.json and ports.reverse.json when all bundles are done.
      * Also used by the `port:reset` command.
      *
+     * Bundles declared in the manifest but absent from disk (e.g. restricted to
+     * other scopes — #B373) carry no `configPaths`; the settings-consistency
+     * check skips them (#B375) while their port entries are still processed.
+     *
      * @inner
      * @private
      * @param {number} b - Current bundle index into self.bundles
@@ -677,20 +739,29 @@ function Add(opt, cmd) {
                             // bundle settings inconsistency check @ fix
                             bundleName              = local.bundle;
                             bundleConfig            = self.bundlesByProject[self.projectName][bundleName];
-                            settingsPath            = _(bundleConfig.configPaths.settings, true);
+                            // #B375 — a bundle declared in the manifest but absent from disk
+                            // (e.g. restricted to other scopes) carries no `configPaths`: skip
+                            // its settings-consistency check instead of throwing; the ports
+                            // handling below is unaffected.
+                            settingsPath            = ( bundleConfig && bundleConfig.configPaths ) ? _(bundleConfig.configPaths.settings, true) : null;
                             bundleSettingsUpdate    = false;
 
-                            if ( fs.existsSync(settingsPath) ) {
+                            if ( settingsPath && fs.existsSync(settingsPath) ) {
 
                                 bundleSettings  = requireJSON(settingsPath);
                                 //console.debug('found [ '+ bundleName +' ] settings ');
                                 if ( typeof(bundleSettings.server) != 'undefined' ) {
+                                    // #B378 — this heal is what makes an invalid declaration
+                                    // bootable again, but a user file must never be rewritten
+                                    // silently: every change is collected and reported by name.
+                                    var _settingsChanges = [];
                                     // update only if given bundle protocol setting not in project protocols list
                                     // use project def_protocol by default in that case
                                     if (
                                         typeof(bundleSettings.server.protocol) != 'undefined'
                                         && protocols.indexOf(bundleSettings.server.protocol) < 0
                                     ) {
+                                        _settingsChanges.push('server.protocol "'+ bundleSettings.server.protocol +'" -> "'+ self.defaultProtocol +'"');
                                         bundleSettings.server.protocol = self.defaultProtocol;
                                         bundleSettingsUpdate = true
                                     }
@@ -701,13 +772,14 @@ function Add(opt, cmd) {
                                         typeof(bundleSettings.server.scheme) != 'undefined'
                                         && schemes.indexOf(bundleSettings.server.scheme) < 0
                                     ) {
+                                        _settingsChanges.push('server.scheme "'+ bundleSettings.server.scheme +'" -> "'+ self.defaultScheme +'"');
                                         bundleSettings.server.scheme = self.defaultScheme;
                                         bundleSettingsUpdate = true
                                     }
 
                                     if (bundleSettingsUpdate) {
                                         lib.generator.createFileFromDataSync(bundleSettings, settingsPath);
-                                        console.debug('updated [ '+ bundleName +' ] settings');
+                                        console.warn('Updated [ '+ bundleName +' ] settings: '+ _settingsChanges.join('; ') +' — the declared value is not in the project protocols/schemes list.');
                                     }
                                 }
                             }

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

@@ -130,6 +130,22 @@ function Build(opt, cmd) {
 
         var bundle = self.bundles[b];
 
+        // #B373 — per-scope deployment. This is the BULK verb: it walks every bundle
+        // in the project, so a bundle not deployed in the scope being built is skipped
+        // with a notice rather than refused — refusing would make one parked bundle
+        // block the whole project build. (The single-target `bundle:build` refuses
+        // instead, because there the exclusion is what the operator explicitly asked
+        // for.) A malformed `scopes` is still a hard error: it is a manifest defect,
+        // not an opt-out.
+        var _entry = local.manifest.bundles[bundle];
+        if ( _entry && typeof(_entry.scopes) != 'undefined' && _entry.scopes !== null && !Array.isArray(_entry.scopes) ) {
+            return end( new Error('[ manifest ] `bundles.'+ bundle +'.scopes` must be an array of scope names (got '+ typeof(_entry.scopes) +'). Remove the key to deploy `'+ bundle +'` in every scope, or list the scopes it belongs to.') );
+        }
+        if ( _entry && Array.isArray(_entry.scopes) && _entry.scopes.indexOf(process.env.NODE_SCOPE) < 0 ) {
+            console.info('[ BUILD ] Skipping bundle [ '+ bundle +' ]: not deployed in scope `'+ process.env.NODE_SCOPE +'` (declared scopes: '+ ( _entry.scopes.length ? '`'+ _entry.scopes.join('`, `') +'`' : 'none' ) +').');
+            return buildBundle(b+1);
+        }
+
         local.envs          = self.envs.slice();
         local.scopes        = self.scopes.slice();
         // var releasesPathObj = new _(self.projects[self.projectName].path +'/releases', true);
@@ -137,6 +153,14 @@ function Build(opt, cmd) {
             // per scope
             for (let i = 0, len = local.scopes.length; i < len; i++) {
                 let scope = local.scopes[i]
+                // #B373 — do not seed a scope the bundle opts out of; this loop walks
+                // EVERY project scope, so unfiltered it regrows the opted-out entries.
+                if (
+                    Array.isArray(local.manifest.bundles[bundle].scopes)
+                    && local.manifest.bundles[bundle].scopes.indexOf(scope) < 0
+                ) {
+                    continue;
+                }
                 if ( typeof(local.manifest.bundles[bundle].releases[scope]) == 'undefined' ) {
                     local.manifest.bundles[bundle].releases[scope] = {}
                 }

package/framework/{v0.6.8 → v0.6.9}/lib/index.js

@@ -140,6 +140,14 @@ function Lib() {
         // module, discarding the live registry and orphaning the sweep timer on
         // each request. Plain require = cache hit = the singleton survives.
         job             : require('./job'),
+        // #B366 — out-of-request push primitive, behind the gina.pushToSession()
+        // global. Stateless (the caller hands it the live server instance), but a
+        // PLAIN require (NOT _require) for the authzGate/authn reason: gna.js is
+        // load-once and captures this binding at boot, so a _require'd copy would
+        // be evicted and re-required out from under that gen-0 capture on every
+        // dev-mode request — the #B32-residual leak class. It also keeps the
+        // primitive that chooses a push recipient out of the hot-reload path.
+        push            : require('./push'),
         // #INS10 — toggleable instrumentation window primitive. Owns the
         // time-boxed Inspector capture window (process.gina._inspectorWindowUntil)
         // and its unref'd expiry timer. PLAIN require (like job / State / logger):

package/framework/v0.6.9/lib/push/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "gina-lib-push",
+  "version": "1.0.0",
+  "description": "Out-of-request push primitive (#B366) — deliver a payload to ONE named session's engine.io sockets from code with no live request (job handlers, cron, boot hooks). Recipient is a required argument with no fallback and no reachable broadcast; reports how many sockets were written. Backs the gina.pushToSession() global.",
+  "author": {
+    "name": "Martin-Luther ETOUMAN",
+    "email": "contact@gina.io"
+  },
+  "copyright": "Copyright (c) 2009-2026 Rhinostone <contact@gina.io>",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "main": "src/main",
+  "scripts": {
+    "test": "node --test test"
+  },
+  "license": "MIT",
+  "readmeFilename": "README.md"
+}

package/framework/v0.6.9/lib/push/src/main.js

@@ -0,0 +1,144 @@
+/**
+ * Out-of-request push primitive (#B366).
+ *
+ * `SuperController.push()` is reachable only from a live request-bound
+ * controller — it returns early once the request is released (#B38) — and the
+ * engine.io socket set has exactly one other reader in the whole framework.
+ * So code with no request in hand (a `lib/job` handler, a cron tick, a boot
+ * hook) has had no sanctioned way to reach a user's socket. This module is it.
+ *
+ * Design notes (full record: the #B366 design):
+ *
+ *   - The recipient is a REQUIRED argument with no fallback, and there is no
+ *     broadcast reachable from this API at all. #B364 shipped because a
+ *     primitive whose blast radius is "everyone connected" inferred the wide
+ *     case from a MISSING value; an absent recipient here is an error, never a
+ *     fan-out. Deliberate all-clients sends stay in-request
+ *     (`self.push(payload, { broadcast: true })`).
+ *
+ *   - The caller is trusted to name any session, exactly as the in-request
+ *     `option.sessionID` branch already trusts server-side code. What must
+ *     never happen is a recipient sourced from client input: capture the id
+ *     server-side (at job creation, say) and keep it there. Round-tripping a
+ *     recipient id — or a token naming one — through the browser hands the
+ *     choice back to the caller and re-opens #B364 one layer up.
+ *
+ *   - Delivery is REPORTED, not assumed. `callback(err, { delivered })` gives
+ *     the number of sockets written, because the shape this replaces was
+ *     fire-and-forget and blind: a consumer measured ~41% of their progress
+ *     pushes never sending, and nothing surfaced it. `delivered: 0` is a
+ *     normal outcome (the user has no socket open), not an error.
+ *
+ *   - Receiver identity is a SEPARATE axis (#B365): this decides who a sender
+ *     may aim at, never how a receiver proves who it is.
+ *
+ * @module lib/push
+ */
+
+/**
+ * Push a payload to every engine.io socket bound to one session.
+ *
+ * @param {object}          instance            - The live server instance (`process.gina._serverInstance`).
+ * @param {string}          sessionID           - REQUIRED recipient session id; empty/non-string is an error, never a broadcast.
+ * @param {object|string}   payload             - Object (JSON-stringified) or a pre-serialized string.
+ * @param {object}          [option]            - Forwarded to the transport (e.g. `{ compress: true }`).
+ * @param {string}          [option.section]    - Stamped onto an object payload when it carries no `section`.
+ * @param {function}        [callback]          - `callback(err, { delivered })`, called exactly ONCE.
+ * @returns {void}
+ *
+ * @example
+ * // from a job handler, with the session id captured at job creation
+ * var push = require('gina').lib.push;
+ * push.toSession(process.gina._serverInstance, job.sessionID, { event: 'ready', pct: 100 }, null, function(err, res) {
+ *     if (err) { return console.error(err.code, err.message); }
+ *     if (!res.delivered) { console.debug('user has no socket open'); }
+ * });
+ */
+var toSession = function(instance, sessionID, payload, option, callback) {
+
+    if ( typeof(option) == 'function' ) {
+        callback = option;
+        option   = null;
+    }
+    var cb = ( typeof(callback) == 'function' ) ? callback : function() {};
+
+    // Fail CLOSED on an unusable recipient. This is the #B364 invariant in the
+    // signature: no recipient means nothing is sent — never everyone.
+    if ( typeof(sessionID) != 'string' || sessionID === '' ) {
+        return cb(_err('PUSH_INVALID_RECIPIENT',
+            '`sessionID` is required and must be a non-empty string. This API never broadcasts: '
+            + 'use the in-request `self.push(payload, { broadcast: true })` to reach every client.'));
+    }
+
+    if ( payload == null ) {
+        return cb(_err('PUSH_INVALID_PAYLOAD',
+            '`payload` is required. There is no request to fall back to outside a controller.'));
+    }
+
+    if ( instance == null || instance.eio == null || instance.eio.clients == null ) {
+        return cb(_err('PUSH_CHANNEL_NOT_CONFIGURED',
+            'no engine.io channel on this server instance. The push channel needs the isaac engine with '
+            + '`settings.json > server.ioServer.integrationMode: "attach"`; the express engine has no `eio`.'));
+    }
+
+    // Section stamping mirrors the in-request path, minus every request-sourced
+    // default — there is no request here, so an explicit option is the only source.
+    var section = ( option != null && typeof(option.section) != 'undefined' ) ? option.section : null;
+    var body    = payload;
+    if ( typeof(body) == 'object' ) {
+        if ( section && typeof(body.section) == 'undefined' ) {
+            body.section = section;
+        }
+        try {
+            body = JSON.stringify(body);
+        } catch (serializeErr) {
+            return cb(_err('PUSH_PAYLOAD_SERIALIZE_FAILED', serializeErr.message || String(serializeErr)));
+        }
+    }
+
+    var clients   = instance.eio.clients;
+    var delivered = 0;
+    try {
+        for (let s in clients) {
+            // #B364 — the guard this replaces read `!clients[s].constructor.name == 'Socket'`,
+            // which parses as `(!name) == 'Socket'` and so never once skipped anything.
+            if ( clients[s].constructor.name !== 'Socket' ) {
+                continue;
+            }
+            if (
+                typeof(clients[s].sessionId) != 'undefined'
+                && clients[s].sessionId == sessionID
+            ) {
+                // The caller's callback is NOT threaded into sendPacket: it fires
+                // per socket, and this API promises exactly one callback carrying a
+                // total. Transport-level acks stay the transport's business.
+                clients[s].sendPacket('message', body, option || {});
+                ++delivered;
+            }
+        }
+    } catch (sendErr) {
+        return cb(sendErr);
+    }
+
+    return cb(null, { delivered: delivered });
+};
+
+/**
+ * Build a coded Error — same shape as the storage verbs, so callers can branch
+ * on `err.code` instead of matching message text.
+ *
+ * @inner
+ * @private
+ * @param {string} code    - Machine-readable code.
+ * @param {string} message - Human-readable detail.
+ * @returns {Error} The error, with `code` attached.
+ */
+var _err = function(code, message) {
+    var e = new Error('[ push ] ' + message);
+    e.code = code;
+    return e;
+};
+
+module.exports = {
+    toSession: toSession
+};