gina 0.6.8 → 0.6.9

package/schema/settings.json

@@ -192,7 +192,8 @@
           "type": ["string", "array", "null"],
           "items": { "type": "string", "minLength": 1 },
           "minLength": 1,
-          "description": "One `.env`-style file path, or an array of them, layered UNDERNEATH the environment. Written with the ordinary config tokens, e.g. [\"${homedir}/secrets.env\", \"${homedir}/${scope}/secrets.env\"]. A NON-EMPTY environment value always wins: every production delivery mechanism (a Kubernetes envFrom secretRef, an ECS task secret, `sops exec-env`, a CI export) arrives through the environment, so a file that won could let a stale plaintext copy baked into an image silently shadow the credential the platform injected while the bundle looked healthy. As a fallback it can only ever fill a gap. A variable that is SET but EMPTY counts as absent, so the file tier fills it — that is what keeps the common `environment: [\"X=${X}\"]` passthrough working when the outer variable is unset — but because the same shape also arises when an entrypoint's `export X=\"$(fetch …)\"` fails, the fallback emits a warning naming the key so the dangerous case is visible without the benign one becoming fatal. Within the array, LATER entries win over earlier ones, so a shared base file and a per-scope file combine. A declared file that does not exist contributes nothing and is not an error — a project may ship a base file and add the per-scope one only on some targets. A declared file that EXISTS but cannot be read (wrong permissions or ownership) IS an error and boot refuses, naming the path: skipping it silently would drop the chain onto the shared base file and run the bundle on the wrong credential with no signal. Resolution stays fail-closed when a key is in neither tier. Boot refuses on a non-string or empty entry, on a `${secret:…}` placeholder (the backend that would resolve it is the one being built), and on any `${…}` token the substitution pass did not know — unknown tokens are preserved verbatim by design, so a typo would otherwise become a silent lookup for a literally-named file that never exists. NOT a secrets-management integration: it does not decrypt, and pointed at ciphertext it yields ciphertext silently. For SOPS, Vault or a KMS keep decrypting at the container entrypoint so values land in the environment, which this tier already prefers. Files are layered once per config-load cycle, so editing one after the bundle has started changes nothing until a restart.",
+          "minItems": 1,
+          "description": "One `.env`-style file path, or an array of them, layered UNDERNEATH the environment. Written with the ordinary config tokens, e.g. [\"${homedir}/secrets.env\", \"${homedir}/${scope}/secrets.env\"]. A NON-EMPTY environment value always wins: every production delivery mechanism (a Kubernetes envFrom secretRef, an ECS task secret, `sops exec-env`, a CI export) arrives through the environment, so a file that won could let a stale plaintext copy baked into an image silently shadow the credential the platform injected while the bundle looked healthy. As a fallback it can only ever fill a gap. A variable that is SET but EMPTY counts as absent, so the file tier fills it — that is what keeps the common `environment: [\"X=${X}\"]` passthrough working when the outer variable is unset — but because the same shape also arises when an entrypoint's `export X=\"$(fetch …)\"` fails, the fallback emits a warning naming the key so the dangerous case is visible without the benign one becoming fatal. Within the array, LATER entries win over earlier ones, so a shared base file and a per-scope file combine. A declared file that does not exist contributes nothing and is not an error — a project may ship a base file and add the per-scope one only on some targets. A declared file that EXISTS but cannot be read (wrong permissions or ownership) IS an error and boot refuses, naming the path: skipping it silently would drop the chain onto the shared base file and run the bundle on the wrong credential with no signal. Resolution stays fail-closed when a key is in neither tier. Boot refuses on a non-string, empty or whitespace-only entry, on a `${secret:…}` placeholder (the backend that would resolve it is the one being built), on any `${…}` token the substitution pass did not know — unknown tokens are preserved verbatim by design, so a typo would otherwise become a silent lookup for a literally-named file that never exists — and on a path containing an empty segment (`//`), because such a path does not name the file it appears to — POSIX reads `<a>//<b>` as `<a>/<b>`. The dangerous cause is a `${…}` token that resolved to an EMPTY value: `${homedir}/${scope}/secrets.env` with an empty scope collapses to a read of the file one directory up, silently, with no token left for the check above to catch. The benign cause is a token carrying a trailing slash (e.g. `GINA_HOMEDIR=/opt/gina/`), which resolves to the intended file; the two are indistinguishable by the time the path is assembled, so boot refuses on both rather than risk running on the wrong credential. Removing the doubled separator, or the trailing slash from the token, resolves either. An empty ARRAY is accepted and disables the file tier exactly like `null`, but it warns, because emptying the array to drop one layer drops the whole tier; prefer `null` when opting out deliberately. NOT a secrets-management integration: it does not decrypt, and pointed at ciphertext it yields ciphertext silently. For SOPS, Vault or a KMS keep decrypting at the container entrypoint so values land in the environment, which this tier already prefers. Files are layered once per config-load cycle, so editing one after the bundle has started changes nothing until a restart.",
           "default": null
         }
       }
@@ -204,7 +205,7 @@
       "properties": {
         "engine": {
           "type": "string",
-          "description": "HTTP server engine. Defaults to \"isaac\" (built-in HTTP/2 server).",
+          "description": "HTTP server engine. Defaults to \"isaac\" (built-in HTTP/2 server). \"express\" uses the project's own express install (the framework deliberately ships no express dependency) — supported range >= 4 < 6, Express 4 and 5 both verified (#B211); an out-of-range major logs a warning at boot.",
           "enum": ["isaac", "express"]
         },
         "protocol": {

package/types/index.d.ts

@@ -798,6 +798,21 @@ declare namespace gina {
         JobStore: any;
         Model: any;
         Proc: any;
+        /**
+         * Out-of-request push primitive (#B366) — deliver to ONE named session
+         * from code with no live request. The recipient is required and this
+         * API never broadcasts; `self.push(payload, { broadcast: true })` is
+         * the deliberate all-clients path, and it stays in-request.
+         */
+        push: {
+            toSession(
+                instance: any,
+                sessionID: string,
+                payload: object | string,
+                option?: { section?: string; [key: string]: any } | null,
+                callback?: (err: Error | null, result?: { delivered: number }) => void
+            ): void;
+        };
         /** Render/output cache backing `routing.json > cache`. */
         RenderCache: any;
         /** Connector-backed render-cache L2 store dispatcher (`cache.type=redis`). */
@@ -1007,6 +1022,30 @@ declare namespace gina {
     /** Get a configured object-storage driver; omit `name` for `storage.default`. Throws when storage is unconfigured or the name is unknown (#STO1). */
     function storage(name?: string): any;
 
+    /**
+     * Push a payload to ONE named session from outside a request (#B366) — for
+     * code with no live controller (job handlers, cron, boot hooks).
+     *
+     * `sessionID` is required: an absent recipient is an error, never a
+     * fan-out. This API cannot broadcast at all — the deliberate all-clients
+     * send stays in-request as `self.push(payload, { broadcast: true })`.
+     * Source the recipient from server-held state, never from client input.
+     *
+     * `delivered` counts the sockets written; `0` is a normal outcome.
+     * Needs the isaac engine with `server.ioServer` attached.
+     */
+    function pushToSession(
+        sessionID: string,
+        payload: object | string,
+        option?: { section?: string; [key: string]: any } | null,
+        callback?: (err: Error | null, result?: { delivered: number }) => void
+    ): void;
+    function pushToSession(
+        sessionID: string,
+        payload: object | string,
+        callback: (err: Error | null, result?: { delivered: number }) => void
+    ): void;
+
     // -- global-helper re-exports (same functions the framework injects on
     //    the global scope; see types/globals.d.ts) --
 

package/framework/v0.6.8/VERSION

@@ -1 +0,0 @@
-0.6.8