@webpieces/core-util 0.4.395 → 0.4.396

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/core-util",
-  "version": "0.4.395",
+  "version": "0.4.396",
   "description": "Utility functions for WebPieces - works in browser and Node.js",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/http/ServiceInfo.d.ts

@@ -1,5 +1,6 @@
 /**
- * ServiceInfo - the ONE answer to "what service am I?", for every part of webpieces that needs it.
+ * ServiceInfo - the ONE answer to "what service am I, and which build of it?", for every part of
+ * webpieces that needs it.
  *
  * Configured like {@link HeaderRegistry} / {@link ClientRegistry} / LogManager — populated once at
  * startup, then globally accessible with NO DI wiring. Browser-safe (no `process.env`, no node-only
@@ -7,49 +8,68 @@
  *
  * ```ts
  * // startup, FIRST — before the logger factory is constructed (it reads this):
- * ServiceInfo.setName('my-service');
+ * ServiceInfo.setInfo('my-service', '2.1.0');
  * ```
  *
- * WHY THIS EXISTS. The name used to live on `BunyanFactoryOptions`, which made it an artifact of
- * WHICH LOGGING LIBRARY YOU PICKED rather than a fact about the service:
- * - bunyan REQUIRES a root-logger name (`options.name (string) is required` — bunyan's own
- *   TypeError), so a bunyan app was forced to supply one.
- * - winston has no such concept, so a winston app supplied nothing and shipped its logs UNNAMED.
+ * WHY THIS EXISTS. Both facts used to be artifacts of WHICH LOGGING LIBRARY YOU PICKED rather than
+ * facts about the service:
+ * - the name lived on `BunyanFactoryOptions`, because bunyan REQUIRES a root-logger name
+ *   (`options.name (string) is required` — bunyan's own TypeError). winston has no such concept, so
+ *   a winston app shipped its logs UNNAMED.
+ * - the version lived on `WinstonFactoryOptions` as `svcGitHash`, so a bunyan app could not stamp a
+ *   version AT ALL — and the name presumed a git SHA, which not every project deploys from.
  *
- * Three unrelated readers need the same fact, so it belongs to the framework, not to a backend:
- * - the bunyan backend, to satisfy bunyan's mandatory root-logger `name`;
- * - the winston backend, to stamp `svcName` (which it never had);
+ * Switching backends silently changed which fields your logs carried. Several unrelated readers
+ * need these same two facts, so they belong to the framework, not to a backend:
+ * - the bunyan backend, to satisfy bunyan's mandatory root-logger `name`, and to stamp `version`;
+ * - the winston backend, to stamp `svcName` + `version`;
  * - {@link WebpiecesCoreHeaders.REQUEST_ID_SOURCE}, to record WHO minted a request id.
  *
- * FAIL FAST, AT STARTUP. {@link getName} throws, and the logger factories + `setupRuntime` call it
- * while the process is booting — so a forgotten `setName` kills the deploy (the revision never goes
- * healthy) instead of quietly shipping unnamed logs. Nothing on the REQUEST path may throw over
- * this: a missing log field must never 500 live traffic, so per-request readers use
- * {@link tryGetName} and simply omit the field. See {@link tryGetName}.
+ * VERSION IS OPAQUE. It is whatever string identifies THIS build — a git SHA, a semver tag, a CI
+ * build number. webpieces neither parses nor derives it; the app decides where it comes from (a
+ * generated file, an env var, a Docker build arg) and passes it here.
+ *
+ * FAIL FAST, AT STARTUP. {@link getName} / {@link getVersion} throw, and the logger factories +
+ * `setupRuntime` call them while the process is booting — so a forgotten `setInfo` kills the deploy
+ * (the revision never goes healthy) instead of quietly shipping logs that cannot say which build
+ * emitted them. Nothing on the REQUEST path may throw over this: a missing log field must never 500
+ * live traffic, so per-request readers use {@link tryGetName} / {@link tryGetVersion} and simply
+ * omit the field.
  */
 export declare class ServiceInfo {
     /** This service's name. Process-global; set once at startup. */
     private static svcName;
+    /** This build's version — an opaque app-chosen string. Process-global; set once at startup. */
+    private static svcVersion;
     /**
-     * Name this service. Call it FIRST at startup — before constructing the logger factory, which
-     * reads it during its own constructor.
+     * Identify this service. Call it FIRST at startup — before constructing the logger factory,
+     * which reads both values during its own constructor.
      *
-     * LAST CALL WINS, deliberately. A real deployment names itself once, but an in-process test can
-     * legitimately boot TWO services back-to-back (see the app-example e2e two-server flow), so a
-     * "one process = one name" rule would reject a case that genuinely exists. Since a logger
-     * factory captures the name in its own constructor, each server built that way still keeps the
-     * name that was set when IT was built.
+     * LAST CALL WINS, deliberately. A real deployment identifies itself once, but an in-process test
+     * can legitimately boot TWO services back-to-back (see the app-example e2e two-server flow), so a
+     * "one process = one service" rule would reject a case that genuinely exists. Since a logger
+     * factory captures both values in its own constructor, each server built that way still keeps
+     * what was set when IT was built.
      *
-     * @throws Error on a blank name — that is always a bug, never a use case.
+     * @param name - this service's name, e.g. 'my-service'.
+     * @param version - the opaque identifier of THIS build (git SHA, semver, CI build number).
+     * @throws Error on a blank name or version — that is always a bug, never a use case.
      */
-    static setName(name: string): void;
+    static setInfo(name: string, version: string): void;
     /**
      * This service's name, REQUIRED. For STARTUP callers only (the logger factories, setupRuntime) —
      * they run while booting, so throwing here fails the deploy rather than live traffic.
      *
-     * @throws Error if {@link setName} was never called.
+     * @throws Error if {@link setInfo} was never called.
      */
     static getName(): string;
+    /**
+     * This build's version, REQUIRED. For STARTUP callers only (the logger factories, setupRuntime),
+     * for the same reason as {@link getName}.
+     *
+     * @throws Error if {@link setInfo} was never called.
+     */
+    static getVersion(): string;
     /**
      * This service's name, or undefined when unset. For the REQUEST path, which must NOT throw: a
      * server that booted has already passed the {@link getName} check in `setupRuntime`, so a real
@@ -57,6 +77,18 @@ export declare class ServiceInfo {
      * undefined — and there, omitting a log field beats exploding.
      */
     static tryGetName(): string | undefined;
+    /**
+     * This build's version, or undefined when unset. For the REQUEST path, which must NOT throw —
+     * same reasoning as {@link tryGetName}.
+     */
+    static tryGetVersion(): string | undefined;
     /** Reset — for tests, mirroring {@link ClientRegistry.clear}. */
     static clear(): void;
+    /**
+     * The one actionable "you forgot to call setInfo" message. Shared by {@link getName} and
+     * {@link getVersion}: setInfo sets BOTH, so either being missing has the identical cause and
+     * the identical fix — telling the caller only about the half they happened to read first would
+     * send them back for a second round.
+     */
+    private static notSetMessage;
 }

package/src/http/ServiceInfo.js

@@ -2,7 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ServiceInfo = void 0;
 /**
- * ServiceInfo - the ONE answer to "what service am I?", for every part of webpieces that needs it.
+ * ServiceInfo - the ONE answer to "what service am I, and which build of it?", for every part of
+ * webpieces that needs it.
  *
  * Configured like {@link HeaderRegistry} / {@link ClientRegistry} / LogManager — populated once at
  * startup, then globally accessible with NO DI wiring. Browser-safe (no `process.env`, no node-only
@@ -10,65 +11,92 @@ exports.ServiceInfo = void 0;
  *
  * ```ts
  * // startup, FIRST — before the logger factory is constructed (it reads this):
- * ServiceInfo.setName('my-service');
+ * ServiceInfo.setInfo('my-service', '2.1.0');
  * ```
  *
- * WHY THIS EXISTS. The name used to live on `BunyanFactoryOptions`, which made it an artifact of
- * WHICH LOGGING LIBRARY YOU PICKED rather than a fact about the service:
- * - bunyan REQUIRES a root-logger name (`options.name (string) is required` — bunyan's own
- *   TypeError), so a bunyan app was forced to supply one.
- * - winston has no such concept, so a winston app supplied nothing and shipped its logs UNNAMED.
+ * WHY THIS EXISTS. Both facts used to be artifacts of WHICH LOGGING LIBRARY YOU PICKED rather than
+ * facts about the service:
+ * - the name lived on `BunyanFactoryOptions`, because bunyan REQUIRES a root-logger name
+ *   (`options.name (string) is required` — bunyan's own TypeError). winston has no such concept, so
+ *   a winston app shipped its logs UNNAMED.
+ * - the version lived on `WinstonFactoryOptions` as `svcGitHash`, so a bunyan app could not stamp a
+ *   version AT ALL — and the name presumed a git SHA, which not every project deploys from.
  *
- * Three unrelated readers need the same fact, so it belongs to the framework, not to a backend:
- * - the bunyan backend, to satisfy bunyan's mandatory root-logger `name`;
- * - the winston backend, to stamp `svcName` (which it never had);
+ * Switching backends silently changed which fields your logs carried. Several unrelated readers
+ * need these same two facts, so they belong to the framework, not to a backend:
+ * - the bunyan backend, to satisfy bunyan's mandatory root-logger `name`, and to stamp `version`;
+ * - the winston backend, to stamp `svcName` + `version`;
  * - {@link WebpiecesCoreHeaders.REQUEST_ID_SOURCE}, to record WHO minted a request id.
  *
- * FAIL FAST, AT STARTUP. {@link getName} throws, and the logger factories + `setupRuntime` call it
- * while the process is booting — so a forgotten `setName` kills the deploy (the revision never goes
- * healthy) instead of quietly shipping unnamed logs. Nothing on the REQUEST path may throw over
- * this: a missing log field must never 500 live traffic, so per-request readers use
- * {@link tryGetName} and simply omit the field. See {@link tryGetName}.
+ * VERSION IS OPAQUE. It is whatever string identifies THIS build — a git SHA, a semver tag, a CI
+ * build number. webpieces neither parses nor derives it; the app decides where it comes from (a
+ * generated file, an env var, a Docker build arg) and passes it here.
+ *
+ * FAIL FAST, AT STARTUP. {@link getName} / {@link getVersion} throw, and the logger factories +
+ * `setupRuntime` call them while the process is booting — so a forgotten `setInfo` kills the deploy
+ * (the revision never goes healthy) instead of quietly shipping logs that cannot say which build
+ * emitted them. Nothing on the REQUEST path may throw over this: a missing log field must never 500
+ * live traffic, so per-request readers use {@link tryGetName} / {@link tryGetVersion} and simply
+ * omit the field.
  */
 class ServiceInfo {
     /** This service's name. Process-global; set once at startup. */
     static svcName;
+    /** This build's version — an opaque app-chosen string. Process-global; set once at startup. */
+    static svcVersion;
     /**
-     * Name this service. Call it FIRST at startup — before constructing the logger factory, which
-     * reads it during its own constructor.
+     * Identify this service. Call it FIRST at startup — before constructing the logger factory,
+     * which reads both values during its own constructor.
      *
-     * LAST CALL WINS, deliberately. A real deployment names itself once, but an in-process test can
-     * legitimately boot TWO services back-to-back (see the app-example e2e two-server flow), so a
-     * "one process = one name" rule would reject a case that genuinely exists. Since a logger
-     * factory captures the name in its own constructor, each server built that way still keeps the
-     * name that was set when IT was built.
+     * LAST CALL WINS, deliberately. A real deployment identifies itself once, but an in-process test
+     * can legitimately boot TWO services back-to-back (see the app-example e2e two-server flow), so a
+     * "one process = one service" rule would reject a case that genuinely exists. Since a logger
+     * factory captures both values in its own constructor, each server built that way still keeps
+     * what was set when IT was built.
      *
-     * @throws Error on a blank name — that is always a bug, never a use case.
+     * @param name - this service's name, e.g. 'my-service'.
+     * @param version - the opaque identifier of THIS build (git SHA, semver, CI build number).
+     * @throws Error on a blank name or version — that is always a bug, never a use case.
      */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected
-    static setName(name) {
+    static setInfo(name, version) {
         if (!name || !name.trim()) {
-            throw new Error('ServiceInfo.setName(...) requires a non-blank service name.');
+            throw new Error('ServiceInfo.setInfo(...) requires a non-blank service name.');
+        }
+        if (!version || !version.trim()) {
+            throw new Error('ServiceInfo.setInfo(...) requires a non-blank version. It is opaque to webpieces — ' +
+                'a git SHA, a semver tag, a CI build number — but every deployed build must be able ' +
+                'to say which build it is.');
         }
         ServiceInfo.svcName = name;
+        ServiceInfo.svcVersion = version;
     }
     /**
      * This service's name, REQUIRED. For STARTUP callers only (the logger factories, setupRuntime) —
      * they run while booting, so throwing here fails the deploy rather than live traffic.
      *
-     * @throws Error if {@link setName} was never called.
+     * @throws Error if {@link setInfo} was never called.
      */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected
     static getName() {
         if (!ServiceInfo.svcName) {
-            throw new Error('ServiceInfo.setName(...) has not been called. Name this service at startup, ' +
-                'BEFORE constructing the logger factory (it reads the name in its constructor):\n' +
-                "    ServiceInfo.setName('my-service');\n" +
-                'It names every log line and records which service minted a request id ' +
-                '(requestIdSource).');
+            throw new Error(ServiceInfo.notSetMessage());
         }
         return ServiceInfo.svcName;
     }
+    /**
+     * This build's version, REQUIRED. For STARTUP callers only (the logger factories, setupRuntime),
+     * for the same reason as {@link getName}.
+     *
+     * @throws Error if {@link setInfo} was never called.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected
+    static getVersion() {
+        if (!ServiceInfo.svcVersion) {
+            throw new Error(ServiceInfo.notSetMessage());
+        }
+        return ServiceInfo.svcVersion;
+    }
     /**
      * This service's name, or undefined when unset. For the REQUEST path, which must NOT throw: a
      * server that booted has already passed the {@link getName} check in `setupRuntime`, so a real
@@ -79,10 +107,34 @@ class ServiceInfo {
     static tryGetName() {
         return ServiceInfo.svcName;
     }
+    /**
+     * This build's version, or undefined when unset. For the REQUEST path, which must NOT throw —
+     * same reasoning as {@link tryGetName}.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected
+    static tryGetVersion() {
+        return ServiceInfo.svcVersion;
+    }
     /** Reset — for tests, mirroring {@link ClientRegistry.clear}. */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected
     static clear() {
         ServiceInfo.svcName = undefined;
+        ServiceInfo.svcVersion = undefined;
+    }
+    /**
+     * The one actionable "you forgot to call setInfo" message. Shared by {@link getName} and
+     * {@link getVersion}: setInfo sets BOTH, so either being missing has the identical cause and
+     * the identical fix — telling the caller only about the half they happened to read first would
+     * send them back for a second round.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected
+    static notSetMessage() {
+        return ('ServiceInfo.setInfo(...) has not been called. Identify this service at startup, ' +
+            'BEFORE constructing the logger factory (it reads name+version in its constructor):\n' +
+            "    ServiceInfo.setInfo('my-service', '2.1.0');\n" +
+            'The name+version stamp every log line (so you can tell WHICH BUILD emitted a line), ' +
+            'and the name records which service minted a request id (requestIdSource). The version ' +
+            'is opaque — a git SHA, a semver tag, a CI build number, whatever identifies your build.');
     }
 }
 exports.ServiceInfo = ServiceInfo;

package/src/http/ServiceInfo.js.map

@@ -1 +1 @@
-{"version":3,"file":"ServiceInfo.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ServiceInfo.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAa,WAAW;IACpB,gEAAgE;IACxD,MAAM,CAAC,OAAO,CAAqB;IAE3C;;;;;;;;;;;OAWG;IACH,4JAA4J;IAC5J,MAAM,CAAC,OAAO,CAAC,IAAY;QACvB,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;QACnF,CAAC;QACD,WAAW,CAAC,OAAO,GAAG,IAAI,CAAC;IAC/B,CAAC;IAED;;;;;OAKG;IACH,4JAA4J;IAC5J,MAAM,CAAC,OAAO;QACV,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACX,8EAA8E;gBAC9E,kFAAkF;gBAClF,0CAA0C;gBAC1C,wEAAwE;gBACxE,oBAAoB,CACvB,CAAC;QACN,CAAC;QACD,OAAO,WAAW,CAAC,OAAO,CAAC;IAC/B,CAAC;IAED;;;;;OAKG;IACH,4JAA4J;IAC5J,MAAM,CAAC,UAAU;QACb,OAAO,WAAW,CAAC,OAAO,CAAC;IAC/B,CAAC;IAED,iEAAiE;IACjE,4JAA4J;IAC5J,MAAM,CAAC,KAAK;QACR,WAAW,CAAC,OAAO,GAAG,SAAS,CAAC;IACpC,CAAC;CACJ;AA5DD,kCA4DC","sourcesContent":["/**\n * ServiceInfo - the ONE answer to \"what service am I?\", for every part of webpieces that needs it.\n *\n * Configured like {@link HeaderRegistry} / {@link ClientRegistry} / LogManager — populated once at\n * startup, then globally accessible with NO DI wiring. Browser-safe (no `process.env`, no node-only\n * deps), which is why it lives in core-util beside {@link ClientRegistry}.\n *\n * ```ts\n * // startup, FIRST — before the logger factory is constructed (it reads this):\n * ServiceInfo.setName('my-service');\n * ```\n *\n * WHY THIS EXISTS. The name used to live on `BunyanFactoryOptions`, which made it an artifact of\n * WHICH LOGGING LIBRARY YOU PICKED rather than a fact about the service:\n * - bunyan REQUIRES a root-logger name (`options.name (string) is required` — bunyan's own\n *   TypeError), so a bunyan app was forced to supply one.\n * - winston has no such concept, so a winston app supplied nothing and shipped its logs UNNAMED.\n *\n * Three unrelated readers need the same fact, so it belongs to the framework, not to a backend:\n * - the bunyan backend, to satisfy bunyan's mandatory root-logger `name`;\n * - the winston backend, to stamp `svcName` (which it never had);\n * - {@link WebpiecesCoreHeaders.REQUEST_ID_SOURCE}, to record WHO minted a request id.\n *\n * FAIL FAST, AT STARTUP. {@link getName} throws, and the logger factories + `setupRuntime` call it\n * while the process is booting — so a forgotten `setName` kills the deploy (the revision never goes\n * healthy) instead of quietly shipping unnamed logs. Nothing on the REQUEST path may throw over\n * this: a missing log field must never 500 live traffic, so per-request readers use\n * {@link tryGetName} and simply omit the field. See {@link tryGetName}.\n */\nexport class ServiceInfo {\n    /** This service's name. Process-global; set once at startup. */\n    private static svcName: string | undefined;\n\n    /**\n     * Name this service. Call it FIRST at startup — before constructing the logger factory, which\n     * reads it during its own constructor.\n     *\n     * LAST CALL WINS, deliberately. A real deployment names itself once, but an in-process test can\n     * legitimately boot TWO services back-to-back (see the app-example e2e two-server flow), so a\n     * \"one process = one name\" rule would reject a case that genuinely exists. Since a logger\n     * factory captures the name in its own constructor, each server built that way still keeps the\n     * name that was set when IT was built.\n     *\n     * @throws Error on a blank name — that is always a bug, never a use case.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected\n    static setName(name: string): void {\n        if (!name || !name.trim()) {\n            throw new Error('ServiceInfo.setName(...) requires a non-blank service name.');\n        }\n        ServiceInfo.svcName = name;\n    }\n\n    /**\n     * This service's name, REQUIRED. For STARTUP callers only (the logger factories, setupRuntime) —\n     * they run while booting, so throwing here fails the deploy rather than live traffic.\n     *\n     * @throws Error if {@link setName} was never called.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected\n    static getName(): string {\n        if (!ServiceInfo.svcName) {\n            throw new Error(\n                'ServiceInfo.setName(...) has not been called. Name this service at startup, ' +\n                'BEFORE constructing the logger factory (it reads the name in its constructor):\\n' +\n                \"    ServiceInfo.setName('my-service');\\n\" +\n                'It names every log line and records which service minted a request id ' +\n                '(requestIdSource).',\n            );\n        }\n        return ServiceInfo.svcName;\n    }\n\n    /**\n     * This service's name, or undefined when unset. For the REQUEST path, which must NOT throw: a\n     * server that booted has already passed the {@link getName} check in `setupRuntime`, so a real\n     * request always finds a name here. Only a unit test driving the context directly can see\n     * undefined — and there, omitting a log field beats exploding.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected\n    static tryGetName(): string | undefined {\n        return ServiceInfo.svcName;\n    }\n\n    /** Reset — for tests, mirroring {@link ClientRegistry.clear}. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected\n    static clear(): void {\n        ServiceInfo.svcName = undefined;\n    }\n}\n"]}
+{"version":3,"file":"ServiceInfo.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ServiceInfo.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAa,WAAW;IACpB,gEAAgE;IACxD,MAAM,CAAC,OAAO,CAAqB;IAE3C,+FAA+F;IACvF,MAAM,CAAC,UAAU,CAAqB;IAE9C;;;;;;;;;;;;;OAaG;IACH,4JAA4J;IAC5J,MAAM,CAAC,OAAO,CAAC,IAAY,EAAE,OAAe;QACxC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;QACnF,CAAC;QACD,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACX,qFAAqF;gBACrF,qFAAqF;gBACrF,2BAA2B,CAC9B,CAAC;QACN,CAAC;QACD,WAAW,CAAC,OAAO,GAAG,IAAI,CAAC;QAC3B,WAAW,CAAC,UAAU,GAAG,OAAO,CAAC;IACrC,CAAC;IAED;;;;;OAKG;IACH,4JAA4J;IAC5J,MAAM,CAAC,OAAO;QACV,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,WAAW,CAAC,aAAa,EAAE,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,WAAW,CAAC,OAAO,CAAC;IAC/B,CAAC;IAED;;;;;OAKG;IACH,4JAA4J;IAC5J,MAAM,CAAC,UAAU;QACb,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,WAAW,CAAC,aAAa,EAAE,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,WAAW,CAAC,UAAU,CAAC;IAClC,CAAC;IAED;;;;;OAKG;IACH,4JAA4J;IAC5J,MAAM,CAAC,UAAU;QACb,OAAO,WAAW,CAAC,OAAO,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACH,4JAA4J;IAC5J,MAAM,CAAC,aAAa;QAChB,OAAO,WAAW,CAAC,UAAU,CAAC;IAClC,CAAC;IAED,iEAAiE;IACjE,4JAA4J;IAC5J,MAAM,CAAC,KAAK;QACR,WAAW,CAAC,OAAO,GAAG,SAAS,CAAC;QAChC,WAAW,CAAC,UAAU,GAAG,SAAS,CAAC;IACvC,CAAC;IAED;;;;;OAKG;IACH,4JAA4J;IACpJ,MAAM,CAAC,aAAa;QACxB,OAAO,CACH,kFAAkF;YAClF,sFAAsF;YACtF,mDAAmD;YACnD,sFAAsF;YACtF,wFAAwF;YACxF,yFAAyF,CAC5F,CAAC;IACN,CAAC;CACJ;AA7GD,kCA6GC","sourcesContent":["/**\n * ServiceInfo - the ONE answer to \"what service am I, and which build of it?\", for every part of\n * webpieces that needs it.\n *\n * Configured like {@link HeaderRegistry} / {@link ClientRegistry} / LogManager — populated once at\n * startup, then globally accessible with NO DI wiring. Browser-safe (no `process.env`, no node-only\n * deps), which is why it lives in core-util beside {@link ClientRegistry}.\n *\n * ```ts\n * // startup, FIRST — before the logger factory is constructed (it reads this):\n * ServiceInfo.setInfo('my-service', '2.1.0');\n * ```\n *\n * WHY THIS EXISTS. Both facts used to be artifacts of WHICH LOGGING LIBRARY YOU PICKED rather than\n * facts about the service:\n * - the name lived on `BunyanFactoryOptions`, because bunyan REQUIRES a root-logger name\n *   (`options.name (string) is required` — bunyan's own TypeError). winston has no such concept, so\n *   a winston app shipped its logs UNNAMED.\n * - the version lived on `WinstonFactoryOptions` as `svcGitHash`, so a bunyan app could not stamp a\n *   version AT ALL — and the name presumed a git SHA, which not every project deploys from.\n *\n * Switching backends silently changed which fields your logs carried. Several unrelated readers\n * need these same two facts, so they belong to the framework, not to a backend:\n * - the bunyan backend, to satisfy bunyan's mandatory root-logger `name`, and to stamp `version`;\n * - the winston backend, to stamp `svcName` + `version`;\n * - {@link WebpiecesCoreHeaders.REQUEST_ID_SOURCE}, to record WHO minted a request id.\n *\n * VERSION IS OPAQUE. It is whatever string identifies THIS build — a git SHA, a semver tag, a CI\n * build number. webpieces neither parses nor derives it; the app decides where it comes from (a\n * generated file, an env var, a Docker build arg) and passes it here.\n *\n * FAIL FAST, AT STARTUP. {@link getName} / {@link getVersion} throw, and the logger factories +\n * `setupRuntime` call them while the process is booting — so a forgotten `setInfo` kills the deploy\n * (the revision never goes healthy) instead of quietly shipping logs that cannot say which build\n * emitted them. Nothing on the REQUEST path may throw over this: a missing log field must never 500\n * live traffic, so per-request readers use {@link tryGetName} / {@link tryGetVersion} and simply\n * omit the field.\n */\nexport class ServiceInfo {\n    /** This service's name. Process-global; set once at startup. */\n    private static svcName: string | undefined;\n\n    /** This build's version — an opaque app-chosen string. Process-global; set once at startup. */\n    private static svcVersion: string | undefined;\n\n    /**\n     * Identify this service. Call it FIRST at startup — before constructing the logger factory,\n     * which reads both values during its own constructor.\n     *\n     * LAST CALL WINS, deliberately. A real deployment identifies itself once, but an in-process test\n     * can legitimately boot TWO services back-to-back (see the app-example e2e two-server flow), so a\n     * \"one process = one service\" rule would reject a case that genuinely exists. Since a logger\n     * factory captures both values in its own constructor, each server built that way still keeps\n     * what was set when IT was built.\n     *\n     * @param name - this service's name, e.g. 'my-service'.\n     * @param version - the opaque identifier of THIS build (git SHA, semver, CI build number).\n     * @throws Error on a blank name or version — that is always a bug, never a use case.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected\n    static setInfo(name: string, version: string): void {\n        if (!name || !name.trim()) {\n            throw new Error('ServiceInfo.setInfo(...) requires a non-blank service name.');\n        }\n        if (!version || !version.trim()) {\n            throw new Error(\n                'ServiceInfo.setInfo(...) requires a non-blank version. It is opaque to webpieces — ' +\n                'a git SHA, a semver tag, a CI build number — but every deployed build must be able ' +\n                'to say which build it is.',\n            );\n        }\n        ServiceInfo.svcName = name;\n        ServiceInfo.svcVersion = version;\n    }\n\n    /**\n     * This service's name, REQUIRED. For STARTUP callers only (the logger factories, setupRuntime) —\n     * they run while booting, so throwing here fails the deploy rather than live traffic.\n     *\n     * @throws Error if {@link setInfo} was never called.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected\n    static getName(): string {\n        if (!ServiceInfo.svcName) {\n            throw new Error(ServiceInfo.notSetMessage());\n        }\n        return ServiceInfo.svcName;\n    }\n\n    /**\n     * This build's version, REQUIRED. For STARTUP callers only (the logger factories, setupRuntime),\n     * for the same reason as {@link getName}.\n     *\n     * @throws Error if {@link setInfo} was never called.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected\n    static getVersion(): string {\n        if (!ServiceInfo.svcVersion) {\n            throw new Error(ServiceInfo.notSetMessage());\n        }\n        return ServiceInfo.svcVersion;\n    }\n\n    /**\n     * This service's name, or undefined when unset. For the REQUEST path, which must NOT throw: a\n     * server that booted has already passed the {@link getName} check in `setupRuntime`, so a real\n     * request always finds a name here. Only a unit test driving the context directly can see\n     * undefined — and there, omitting a log field beats exploding.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected\n    static tryGetName(): string | undefined {\n        return ServiceInfo.svcName;\n    }\n\n    /**\n     * This build's version, or undefined when unset. For the REQUEST path, which must NOT throw —\n     * same reasoning as {@link tryGetName}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected\n    static tryGetVersion(): string | undefined {\n        return ServiceInfo.svcVersion;\n    }\n\n    /** Reset — for tests, mirroring {@link ClientRegistry.clear}. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected\n    static clear(): void {\n        ServiceInfo.svcName = undefined;\n        ServiceInfo.svcVersion = undefined;\n    }\n\n    /**\n     * The one actionable \"you forgot to call setInfo\" message. Shared by {@link getName} and\n     * {@link getVersion}: setInfo sets BOTH, so either being missing has the identical cause and\n     * the identical fix — telling the caller only about the half they happened to read first would\n     * send them back for a second round.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/ClientRegistry); populated once at startup, never DI-injected\n    private static notSetMessage(): string {\n        return (\n            'ServiceInfo.setInfo(...) has not been called. Identify this service at startup, ' +\n            'BEFORE constructing the logger factory (it reads name+version in its constructor):\\n' +\n            \"    ServiceInfo.setInfo('my-service', '2.1.0');\\n\" +\n            'The name+version stamp every log line (so you can tell WHICH BUILD emitted a line), ' +\n            'and the name records which service minted a request id (requestIdSource). The version ' +\n            'is opaque — a git SHA, a semver tag, a CI build number, whatever identifies your build.'\n        );\n    }\n}\n"]}