@webpieces/http-routing 0.4.413 → 0.4.414

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/http-routing",
-  "version": "0.4.413",
+  "version": "0.4.414",
   "description": "Decorator-based routing with auto-wiring for WebPieces",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -22,9 +22,9 @@
   },
   "dependencies": {
     "@inversifyjs/binding-decorators": "1.1.5",
-    "@webpieces/core-context": "0.4.413",
-    "@webpieces/core-util": "0.4.413",
-    "@webpieces/gcp-identity": "0.4.413",
+    "@webpieces/core-context": "0.4.414",
+    "@webpieces/core-util": "0.4.414",
+    "@webpieces/gcp-identity": "0.4.414",
     "inversify": "7.10.4",
     "jsonwebtoken": "9.0.2",
     "minimatch": "10.0.1"

package/src/setupRuntime.d.ts

@@ -14,6 +14,13 @@ import { ApiFactory } from './ApiFactory';
  * `platformHeaders` is true) plus AppModules.getHeaders() (by convention the company-wide set).
  */
 export declare class RuntimeSetupOptions {
+    /** This service's name — published to ServiceInfo. Names every log line and stamps
+     * `requestIdSource` on request-ids this service mints. Must be non-blank. */
+    readonly svcName: string;
+    /** This build's version — published to ServiceInfo alongside svcName. Opaque to webpieces
+     * (a git SHA, a semver tag, a CI build number); it just has to identify THIS build so a log
+     * line can say which one emitted it. Must be non-blank. */
+    readonly svcVersion: string;
     /** Logging backend to install (LogManager.setFactory). */
     readonly loggerFactory: LoggerFactory;
     /** Include the webpieces platform default headers. */
@@ -21,6 +28,13 @@ export declare class RuntimeSetupOptions {
     /** Optional WebpiecesConfig (e.g. recording flags); defaults to a fresh one. */
     readonly config?: WebpiecesConfig | undefined;
     constructor(
+    /** This service's name — published to ServiceInfo. Names every log line and stamps
+     * `requestIdSource` on request-ids this service mints. Must be non-blank. */
+    svcName: string, 
+    /** This build's version — published to ServiceInfo alongside svcName. Opaque to webpieces
+     * (a git SHA, a semver tag, a CI build number); it just has to identify THIS build so a log
+     * line can say which one emitted it. Must be non-blank. */
+    svcVersion: string, 
     /** Logging backend to install (LogManager.setFactory). */
     loggerFactory: LoggerFactory, 
     /** Include the webpieces platform default headers. */

package/src/setupRuntime.js

@@ -17,16 +17,27 @@ const WebpiecesRouter_1 = require("./WebpiecesRouter");
  * `platformHeaders` is true) plus AppModules.getHeaders() (by convention the company-wide set).
  */
 class RuntimeSetupOptions {
+    svcName;
+    svcVersion;
     loggerFactory;
     platformHeaders;
     config;
     constructor(
+    /** This service's name — published to ServiceInfo. Names every log line and stamps
+     * `requestIdSource` on request-ids this service mints. Must be non-blank. */
+    svcName, 
+    /** This build's version — published to ServiceInfo alongside svcName. Opaque to webpieces
+     * (a git SHA, a semver tag, a CI build number); it just has to identify THIS build so a log
+     * line can say which one emitted it. Must be non-blank. */
+    svcVersion, 
     /** Logging backend to install (LogManager.setFactory). */
     loggerFactory, 
     /** Include the webpieces platform default headers. */
     platformHeaders = true, 
     /** Optional WebpiecesConfig (e.g. recording flags); defaults to a fresh one. */
     config) {
+        this.svcName = svcName;
+        this.svcVersion = svcVersion;
         this.loggerFactory = loggerFactory;
         this.platformHeaders = platformHeaders;
         this.config = config;
@@ -51,12 +62,13 @@ async function setupRuntime(options, appModules,
 /** A single DI module loaded LAST so tests can rebind bindings to mocks.
  * Or special case servers that want to override specific things */
 appOverrides) {
-    // 0. This service must be IDENTIFIED (name + build version). The logging backends and the request
-    // path READ ServiceInfo without throwing (a missing log field must never 500 live traffic, and
-    // logging must work before setInfo). So the "a deployed build must say which build it is"
-    // guarantee is enforced HERE instead — the one startup every server runs — so a forgotten
-    // setInfo kills the deploy (the revision never goes healthy) rather than shipping anonymous logs.
-    core_util_1.ServiceInfo.assertIdentified();
+    // 0. IDENTIFY this service (name + build version) FIRST, before anything logs. Name and version
+    // are REQUIRED inputs to this call, so a build cannot boot anonymously — setInfo throws on a
+    // blank value, which kills the deploy (the revision never goes healthy) rather than shipping logs
+    // that cannot say which build emitted them. Reads of ServiceInfo elsewhere never throw (a missing
+    // log field must never 500 live traffic); the "say which build you are" guarantee lives HERE, the
+    // one startup every server runs.
+    core_util_1.ServiceInfo.setInfo(options.svcName, options.svcVersion);
     // 1. Register the global HeaderRegistry FIRST (this service's own keys come from AppModules).
     core_util_1.HeaderRegistry.configure(appModules.getHeaders(), options.platformHeaders);
     // 2. Install the logging backend ONCE, before anything else logs.

package/src/setupRuntime.js.map

@@ -1 +1 @@
-{"version":3,"file":"setupRuntime.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/setupRuntime.ts"],"names":[],"mappings":";;;AA2CA,oCAqCC;AA/ED,oDAAoH;AACpH,0DAAuE;AACvE,uDAAoD;AACpD,uDAA2D;AAI3D;;;;;;;;;GASG;AACH,MAAa,mBAAmB;IAGR;IAEA;IAEA;IANpB;IACI,0DAA0D;IAC1C,aAA4B;IAC5C,sDAAsD;IACtC,kBAA2B,IAAI;IAC/C,gFAAgF;IAChE,MAAwB;QAJxB,kBAAa,GAAb,aAAa,CAAe;QAE5B,oBAAe,GAAf,eAAe,CAAgB;QAE/B,WAAM,GAAN,MAAM,CAAkB;IACzC,CAAC;CACP;AATD,kDASC;AAED;;;;;;;;;;;;;GAaG;AACI,KAAK,UAAU,YAAY,CAC9B,OAA4B,EAC5B,UAAsB;AACtB;mEACmE;AACnE,YAA8B;IAE9B,kGAAkG;IAClG,+FAA+F;IAC/F,0FAA0F;IAC1F,0FAA0F;IAC1F,kGAAkG;IAClG,uBAAW,CAAC,gBAAgB,EAAE,CAAC;IAE/B,8FAA8F;IAC9F,0BAAc,CAAC,SAAS,CAAC,UAAU,CAAC,UAAU,EAAE,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAE3E,kEAAkE;IAClE,sBAAU,CAAC,UAAU,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IAE7C,kGAAkG;IAClG,8FAA8F;IAC9F,kGAAkG;IAClG,gCAAoB,CAAC,OAAO,CAAC,IAAI,2CAA4B,EAAE,CAAC,CAAC;IAEjE,gDAAgD;IAChD,MAAM,MAAM,GAAG,MAAM,wCAAsB,CAAC,MAAM,CAAC;QAC/C,WAAW,EAAE,CAAC,GAAG,UAAU,CAAC,iBAAiB,EAAE,CAAC;QAChD,YAAY,EAAE,YAAY;QAC1B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI,iCAAe,EAAE;KAClD,CAAC,CAAC;IAEH,6FAA6F;IAC7F,KAAK,MAAM,WAAW,IAAI,UAAU,CAAC,iBAAiB,EAAE,EAAE,CAAC;QACvD,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC","sourcesContent":["import { ContainerModule } from 'inversify';\nimport { ApiCallContextHolder, HeaderRegistry, LoggerFactory, LogManager, ServiceInfo } from '@webpieces/core-util';\nimport { RequestContextApiCallContext } from '@webpieces/core-context';\nimport { WebpiecesConfig } from './WebpiecesConfig';\nimport { WebpiecesRouterFactory } from './WebpiecesRouter';\nimport { AppModules } from './AppModules';\nimport { ApiFactory } from './ApiFactory';\n\n/**\n * RuntimeSetupOptions - the environment/wiring inputs to {@link setupRuntime} (everything NOT\n * declared by the app's {@link AppModules}): the logging backend, whether to include the platform\n * default headers, and config. Data-only structure (a class, per the webpieces guidelines). The\n * app's own binding modules + route groups + headers come from the AppModules passed alongside;\n * the test-override module is the separate `appOverrides` param of {@link setupRuntime}.\n *\n * Headers: {@link HeaderRegistry.configure} registers the platform defaults (when\n * `platformHeaders` is true) plus AppModules.getHeaders() (by convention the company-wide set).\n */\nexport class RuntimeSetupOptions {\n    constructor(\n        /** Logging backend to install (LogManager.setFactory). */\n        public readonly loggerFactory: LoggerFactory,\n        /** Include the webpieces platform default headers. */\n        public readonly platformHeaders: boolean = true,\n        /** Optional WebpiecesConfig (e.g. recording flags); defaults to a fresh one. */\n        public readonly config?: WebpiecesConfig,\n    ) {}\n}\n\n/**\n * setupRuntime - the ONE canonical, TRANSPORT-FREE startup sequence, reusable by any company/app\n * AND any framework adapter (express, fastify, a serverless handler, ...). It runs, in the correct\n * fail-fast order:\n *\n *   1. HeaderRegistry.configure  (filters read it at construction; logging masks off it)\n *   2. LogManager.setFactory     (fails fast unless the registry is configured first)\n *   3. build the router + DI container (from appModules.getBindingModules())\n *   4. configure each appModules.getRoutingModules() onto the router (addRoutes/addFilter)\n *\n * and returns the built {@link ApiFactory} — `apiClients()` for a transport to bind, or\n * `createApiClient()` for in-process tests. There is NO express (or any transport) here; a\n * transport adapter (e.g. WebpiecesExpressRouter in @webpieces/http-server) serves the result.\n */\nexport async function setupRuntime(\n    options: RuntimeSetupOptions,\n    appModules: AppModules,\n    /** A single DI module loaded LAST so tests can rebind bindings to mocks.\n     * Or special case servers that want to override specific things */\n    appOverrides?: ContainerModule,\n): Promise<ApiFactory> {\n    // 0. This service must be IDENTIFIED (name + build version). The logging backends and the request\n    // path READ ServiceInfo without throwing (a missing log field must never 500 live traffic, and\n    // logging must work before setInfo). So the \"a deployed build must say which build it is\"\n    // guarantee is enforced HERE instead — the one startup every server runs — so a forgotten\n    // setInfo kills the deploy (the revision never goes healthy) rather than shipping anonymous logs.\n    ServiceInfo.assertIdentified();\n\n    // 1. Register the global HeaderRegistry FIRST (this service's own keys come from AppModules).\n    HeaderRegistry.configure(appModules.getHeaders(), options.platformHeaders);\n\n    // 2. Install the logging backend ONCE, before anything else logs.\n    LogManager.setFactory(options.loggerFactory);\n\n    // 2b. Bind the SERVER ApiCallContext so LogApiCall (browser-safe core-util) stamps the structured\n    // `api` tag into the real RequestContext. Installed here — the one startup that runs on EVERY\n    // server — so both inbound (LogApiFilter) and outbound (clients) log lines carry jsonPayload.api.\n    ApiCallContextHolder.install(new RequestContextApiCallContext());\n\n    // 3. Build the node-only router + DI container.\n    const router = await WebpiecesRouterFactory.create({\n        appBindings: [...appModules.getBindingModules()],\n        appOverrides: appOverrides,\n        config: options.config ?? new WebpiecesConfig(),\n    });\n\n    // 4. Let each route group declare its routes + filters, then hand back the consumer surface.\n    for (const routeModule of appModules.getRoutingModules()) {\n        routeModule.configure(router);\n    }\n    return router;\n}\n"]}
+{"version":3,"file":"setupRuntime.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/setupRuntime.ts"],"names":[],"mappings":";;;AAkDA,oCAsCC;AAvFD,oDAAoH;AACpH,0DAAuE;AACvE,uDAAoD;AACpD,uDAA2D;AAI3D;;;;;;;;;GASG;AACH,MAAa,mBAAmB;IAIR;IAIA;IAEA;IAEA;IAEA;IAbpB;IACI;iFAC6E;IAC7D,OAAe;IAC/B;;+DAE2D;IAC3C,UAAkB;IAClC,0DAA0D;IAC1C,aAA4B;IAC5C,sDAAsD;IACtC,kBAA2B,IAAI;IAC/C,gFAAgF;IAChE,MAAwB;QAVxB,YAAO,GAAP,OAAO,CAAQ;QAIf,eAAU,GAAV,UAAU,CAAQ;QAElB,kBAAa,GAAb,aAAa,CAAe;QAE5B,oBAAe,GAAf,eAAe,CAAgB;QAE/B,WAAM,GAAN,MAAM,CAAkB;IACzC,CAAC;CACP;AAhBD,kDAgBC;AAED;;;;;;;;;;;;;GAaG;AACI,KAAK,UAAU,YAAY,CAC9B,OAA4B,EAC5B,UAAsB;AACtB;mEACmE;AACnE,YAA8B;IAE9B,gGAAgG;IAChG,6FAA6F;IAC7F,kGAAkG;IAClG,kGAAkG;IAClG,kGAAkG;IAClG,iCAAiC;IACjC,uBAAW,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAEzD,8FAA8F;IAC9F,0BAAc,CAAC,SAAS,CAAC,UAAU,CAAC,UAAU,EAAE,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAE3E,kEAAkE;IAClE,sBAAU,CAAC,UAAU,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IAE7C,kGAAkG;IAClG,8FAA8F;IAC9F,kGAAkG;IAClG,gCAAoB,CAAC,OAAO,CAAC,IAAI,2CAA4B,EAAE,CAAC,CAAC;IAEjE,gDAAgD;IAChD,MAAM,MAAM,GAAG,MAAM,wCAAsB,CAAC,MAAM,CAAC;QAC/C,WAAW,EAAE,CAAC,GAAG,UAAU,CAAC,iBAAiB,EAAE,CAAC;QAChD,YAAY,EAAE,YAAY;QAC1B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI,iCAAe,EAAE;KAClD,CAAC,CAAC;IAEH,6FAA6F;IAC7F,KAAK,MAAM,WAAW,IAAI,UAAU,CAAC,iBAAiB,EAAE,EAAE,CAAC;QACvD,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC","sourcesContent":["import { ContainerModule } from 'inversify';\nimport { ApiCallContextHolder, HeaderRegistry, LoggerFactory, LogManager, ServiceInfo } from '@webpieces/core-util';\nimport { RequestContextApiCallContext } from '@webpieces/core-context';\nimport { WebpiecesConfig } from './WebpiecesConfig';\nimport { WebpiecesRouterFactory } from './WebpiecesRouter';\nimport { AppModules } from './AppModules';\nimport { ApiFactory } from './ApiFactory';\n\n/**\n * RuntimeSetupOptions - the environment/wiring inputs to {@link setupRuntime} (everything NOT\n * declared by the app's {@link AppModules}): the logging backend, whether to include the platform\n * default headers, and config. Data-only structure (a class, per the webpieces guidelines). The\n * app's own binding modules + route groups + headers come from the AppModules passed alongside;\n * the test-override module is the separate `appOverrides` param of {@link setupRuntime}.\n *\n * Headers: {@link HeaderRegistry.configure} registers the platform defaults (when\n * `platformHeaders` is true) plus AppModules.getHeaders() (by convention the company-wide set).\n */\nexport class RuntimeSetupOptions {\n    constructor(\n        /** This service's name — published to ServiceInfo. Names every log line and stamps\n         * `requestIdSource` on request-ids this service mints. Must be non-blank. */\n        public readonly svcName: string,\n        /** This build's version — published to ServiceInfo alongside svcName. Opaque to webpieces\n         * (a git SHA, a semver tag, a CI build number); it just has to identify THIS build so a log\n         * line can say which one emitted it. Must be non-blank. */\n        public readonly svcVersion: string,\n        /** Logging backend to install (LogManager.setFactory). */\n        public readonly loggerFactory: LoggerFactory,\n        /** Include the webpieces platform default headers. */\n        public readonly platformHeaders: boolean = true,\n        /** Optional WebpiecesConfig (e.g. recording flags); defaults to a fresh one. */\n        public readonly config?: WebpiecesConfig,\n    ) {}\n}\n\n/**\n * setupRuntime - the ONE canonical, TRANSPORT-FREE startup sequence, reusable by any company/app\n * AND any framework adapter (express, fastify, a serverless handler, ...). It runs, in the correct\n * fail-fast order:\n *\n *   1. HeaderRegistry.configure  (filters read it at construction; logging masks off it)\n *   2. LogManager.setFactory     (fails fast unless the registry is configured first)\n *   3. build the router + DI container (from appModules.getBindingModules())\n *   4. configure each appModules.getRoutingModules() onto the router (addRoutes/addFilter)\n *\n * and returns the built {@link ApiFactory} — `apiClients()` for a transport to bind, or\n * `createApiClient()` for in-process tests. There is NO express (or any transport) here; a\n * transport adapter (e.g. WebpiecesExpressRouter in @webpieces/http-server) serves the result.\n */\nexport async function setupRuntime(\n    options: RuntimeSetupOptions,\n    appModules: AppModules,\n    /** A single DI module loaded LAST so tests can rebind bindings to mocks.\n     * Or special case servers that want to override specific things */\n    appOverrides?: ContainerModule,\n): Promise<ApiFactory> {\n    // 0. IDENTIFY this service (name + build version) FIRST, before anything logs. Name and version\n    // are REQUIRED inputs to this call, so a build cannot boot anonymously — setInfo throws on a\n    // blank value, which kills the deploy (the revision never goes healthy) rather than shipping logs\n    // that cannot say which build emitted them. Reads of ServiceInfo elsewhere never throw (a missing\n    // log field must never 500 live traffic); the \"say which build you are\" guarantee lives HERE, the\n    // one startup every server runs.\n    ServiceInfo.setInfo(options.svcName, options.svcVersion);\n\n    // 1. Register the global HeaderRegistry FIRST (this service's own keys come from AppModules).\n    HeaderRegistry.configure(appModules.getHeaders(), options.platformHeaders);\n\n    // 2. Install the logging backend ONCE, before anything else logs.\n    LogManager.setFactory(options.loggerFactory);\n\n    // 2b. Bind the SERVER ApiCallContext so LogApiCall (browser-safe core-util) stamps the structured\n    // `api` tag into the real RequestContext. Installed here — the one startup that runs on EVERY\n    // server — so both inbound (LogApiFilter) and outbound (clients) log lines carry jsonPayload.api.\n    ApiCallContextHolder.install(new RequestContextApiCallContext());\n\n    // 3. Build the node-only router + DI container.\n    const router = await WebpiecesRouterFactory.create({\n        appBindings: [...appModules.getBindingModules()],\n        appOverrides: appOverrides,\n        config: options.config ?? new WebpiecesConfig(),\n    });\n\n    // 4. Let each route group declare its routes + filters, then hand back the consumer surface.\n    for (const routeModule of appModules.getRoutingModules()) {\n        routeModule.configure(router);\n    }\n    return router;\n}\n"]}