@thenewlabs/entangle-utils 2.11.1 → 2.11.3

package/dist/index.d.ts

@@ -4,5 +4,6 @@ export * from './validation.js';
 export * from './counters.js';
 export * from './stream-counters.js';
 export * from './version.js';
+export * from './user-agent.js';
 export * from './output.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -4,5 +4,6 @@ export * from './validation.js';
 export * from './counters.js';
 export * from './stream-counters.js';
 export * from './version.js';
+export * from './user-agent.js';
 export * from './output.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}

package/dist/user-agent.d.ts

@@ -0,0 +1,27 @@
+/** Project URL appended so an operator seeing the UA in a log can identify it. */
+export declare const USER_AGENT_URL = "https://github.com/thenewlabs/entangle";
+/** Product token for the component making the request. Add a member per new outbound caller. */
+export type UserAgentProduct = 'entangle-serve' | 'entangle-connect' | 'entangle-relay' | 'entangle';
+/**
+ * Build the UA for `product` at the CALLING package's version. Pass the calling module's
+ * `import.meta.url`; as with `packageVersion()`, the manifest is expected one level up, which
+ * holds for any module directly under `src/` (tsx dev) or `dist/` (tsc output).
+ *
+ * In a standalone bundle the runtime manifest lookup CANNOT be trusted: `import.meta.url` is
+ * empty under the CJS output format, and even once a bundler rewrites it, it points at the
+ * bundle — so `../package.json` resolves to whichever package happens to sit above the output
+ * directory rather than to the calling package. That is how a bundled `locus` came to announce
+ * `entangle-serve/0.1.0` (the Locus root manifest) instead of serve's own 2.15.1. The injected
+ * map therefore WINS over the runtime read, which stays as the tsx/tsc-build path.
+ *
+ * e.g. `entangle-serve/2.15.1 (+https://github.com/thenewlabs/entangle)`
+ */
+export declare function buildUserAgent(product: UserAgentProduct, callerModuleUrl: string): string;
+/**
+ * Headers object for a Node `ws` client or `fetch`. Lowercase key: HTTP/1.1 header names are
+ * case-insensitive, and `ws` merges its own defaults case-sensitively.
+ */
+export declare function userAgentHeaders(product: UserAgentProduct, callerModuleUrl: string): {
+    'user-agent': string;
+};
+//# sourceMappingURL=user-agent.d.ts.map

package/dist/user-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-agent.d.ts","sourceRoot":"","sources":["../src/user-agent.ts"],"names":[],"mappings":"AAgBA,kFAAkF;AAClF,eAAO,MAAM,cAAc,2CAA2C,CAAC;AAEvE,gGAAgG;AAChG,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,gBAAgB,GAAG,UAAU,CAAC;AAsCrG;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAGzF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,gBAAgB,EACzB,eAAe,EAAE,MAAM,GACtB;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,CAE1B"}

package/dist/user-agent.js

@@ -0,0 +1,64 @@
+/**
+ * The `User-Agent` every entangle component puts on its OWN outbound requests.
+ *
+ * Node sets no `User-Agent` by default — neither global `fetch` (undici) nor the `ws` client
+ * send one, unlike a browser. Relays and reverse proxies in front of them log the header as
+ * "-", and intrusion-prevention layers (CrowdSec et al.) treat a stream of UA-less requests as
+ * bot traffic and ban the source IP. `serve`'s registration WebSocket reconnects on a backoff
+ * loop, so a single unhappy relay produced exactly that pattern against `/agent/register`.
+ *
+ * The string is product + version only. It MUST NOT carry capIds, tokens, secrets, machine ids
+ * or paths: the relay is blind by design, and the header is the one part of a connection it
+ * always sees in cleartext. Distinguishing the products (`entangle-serve` vs `entangle-connect`)
+ * tells a relay operator which component is calling without telling them anything about who.
+ */
+import { packageVersion } from './version.js';
+/** Project URL appended so an operator seeing the UA in a log can identify it. */
+export const USER_AGENT_URL = 'https://github.com/thenewlabs/entangle';
+function buildTimeVersion(product) {
+    // `typeof` first and short-circuit: the identifier is undeclared outside a bundle, where any
+    // other reference to it would throw a ReferenceError at module load.
+    if (typeof ENTANGLE_BUILD_UA_VERSIONS !== 'object' || ENTANGLE_BUILD_UA_VERSIONS === null) {
+        return undefined;
+    }
+    const version = ENTANGLE_BUILD_UA_VERSIONS[product];
+    return typeof version === 'string' ? version : undefined;
+}
+/**
+ * Coerce a version to a single safe HTTP token, falling back to 'unknown'. Guards the two ways
+ * a bundle can degrade — a missing manifest yields `undefined`, and a lookup against an empty
+ * `import.meta` yields `''` — so the header is never `product/` or `product/undefined`. Also
+ * rejects whitespace and control characters, which would split or inject a header.
+ */
+function safeVersion(raw) {
+    if (typeof raw !== 'string')
+        return 'unknown';
+    const version = raw.trim();
+    return version !== '' && /^[\x21-\x7e]+$/.test(version) ? version : 'unknown';
+}
+/**
+ * Build the UA for `product` at the CALLING package's version. Pass the calling module's
+ * `import.meta.url`; as with `packageVersion()`, the manifest is expected one level up, which
+ * holds for any module directly under `src/` (tsx dev) or `dist/` (tsc output).
+ *
+ * In a standalone bundle the runtime manifest lookup CANNOT be trusted: `import.meta.url` is
+ * empty under the CJS output format, and even once a bundler rewrites it, it points at the
+ * bundle — so `../package.json` resolves to whichever package happens to sit above the output
+ * directory rather than to the calling package. That is how a bundled `locus` came to announce
+ * `entangle-serve/0.1.0` (the Locus root manifest) instead of serve's own 2.15.1. The injected
+ * map therefore WINS over the runtime read, which stays as the tsx/tsc-build path.
+ *
+ * e.g. `entangle-serve/2.15.1 (+https://github.com/thenewlabs/entangle)`
+ */
+export function buildUserAgent(product, callerModuleUrl) {
+    const version = safeVersion(buildTimeVersion(product) ?? packageVersion(callerModuleUrl));
+    return `${product}/${version} (+${USER_AGENT_URL})`;
+}
+/**
+ * Headers object for a Node `ws` client or `fetch`. Lowercase key: HTTP/1.1 header names are
+ * case-insensitive, and `ws` merges its own defaults case-sensitively.
+ */
+export function userAgentHeaders(product, callerModuleUrl) {
+    return { 'user-agent': buildUserAgent(product, callerModuleUrl) };
+}
+//# sourceMappingURL=user-agent.js.map

package/dist/user-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-agent.js","sourceRoot":"","sources":["../src/user-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,kFAAkF;AAClF,MAAM,CAAC,MAAM,cAAc,GAAG,wCAAwC,CAAC;AAmBvE,SAAS,gBAAgB,CAAC,OAAyB;IACjD,6FAA6F;IAC7F,qEAAqE;IACrE,IAAI,OAAO,0BAA0B,KAAK,QAAQ,IAAI,0BAA0B,KAAK,IAAI,EAAE,CAAC;QAC1F,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,OAAO,GAAI,0BAAsD,CAAC,OAAO,CAAC,CAAC;IACjF,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED;;;;;GAKG;AACH,SAAS,WAAW,CAAC,GAAuB;IAC1C,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC9C,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,OAAO,OAAO,KAAK,EAAE,IAAI,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,OAAyB,EAAE,eAAuB;IAC/E,MAAM,OAAO,GAAG,WAAW,CAAC,gBAAgB,CAAC,OAAO,CAAC,IAAI,cAAc,CAAC,eAAe,CAAC,CAAC,CAAC;IAC1F,OAAO,GAAG,OAAO,IAAI,OAAO,MAAM,cAAc,GAAG,CAAC;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAyB,EACzB,eAAuB;IAEvB,OAAO,EAAE,YAAY,EAAE,cAAc,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC;AACpE,CAAC"}

package/dist/version.d.ts

@@ -1,4 +1,10 @@
-export declare const VERSION = "2.11.1";
-export declare const BUILD_TIME: string;
-export declare function getVersionInfo(): string;
+/**
+ * The CALLING package's version. Pass the entry module's `import.meta.url`; the manifest is
+ * expected one level up (`src/index.ts` and `dist/index.js` both sit directly under the package
+ * root). Returns 'unknown' rather than throwing — a binary that cannot find its manifest should
+ * still start, just visibly unversioned.
+ */
+export declare function packageVersion(entryModuleUrl: string): string;
+/** Human-facing version string for banners and `--version`: `v<package version>`. */
+export declare function getVersionInfo(entryModuleUrl: string): string;
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,WAAW,CAAC;AAChC,eAAO,MAAM,UAAU,QAA2B,CAAC;AAEnD,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAuBA;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAU7D;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAE7D"}

package/dist/version.js

@@ -1,6 +1,40 @@
-export const VERSION = '2.11.1';
-export const BUILD_TIME = new Date().toISOString();
-export function getVersionInfo() {
-    return `v${VERSION} (built: ${BUILD_TIME})`;
+/**
+ * Per-package version reporting with ONE source of truth: the package's own package.json.
+ *
+ * There is deliberately NO version constant in this module. A shared hardcoded string is how
+ * every entangle binary ended up announcing utils' stale version instead of its own (serve
+ * 2.12.0 shipped reporting "v2.11.1"); a drift-guard test can only pin such a constant to
+ * THIS package's manifest, never to the caller's. Instead each CLI entry module calls
+ * `getVersionInfo(import.meta.url)`:
+ *
+ * - workspace / tsc builds: the version is read at runtime from `../package.json` relative to
+ *   the calling entry module — which is that package's OWN manifest for `src/` (tsx dev) and
+ *   `dist/` (tsc output) alike;
+ * - standalone bundles (main/dist/*.js are CJS/IIFE where `import.meta.url` is gone and a
+ *   relative manifest lookup would find the wrong package.json): the bundling script injects
+ *   the right version at build time via esbuild `define` (`ENTANGLE_BUILD_VERSION` — see
+ *   scripts/build-dist.js and locus-server's build.mjs), which wins over the runtime read.
+ */
+import { readFileSync } from 'fs';
+/**
+ * The CALLING package's version. Pass the entry module's `import.meta.url`; the manifest is
+ * expected one level up (`src/index.ts` and `dist/index.js` both sit directly under the package
+ * root). Returns 'unknown' rather than throwing — a binary that cannot find its manifest should
+ * still start, just visibly unversioned.
+ */
+export function packageVersion(entryModuleUrl) {
+    if (typeof ENTANGLE_BUILD_VERSION === 'string')
+        return ENTANGLE_BUILD_VERSION;
+    try {
+        const pkg = JSON.parse(readFileSync(new URL('../package.json', entryModuleUrl), 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Human-facing version string for banners and `--version`: `v<package version>`. */
+export function getVersionInfo(entryModuleUrl) {
+    return `v${packageVersion(entryModuleUrl)}`;
 }
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC;AAChC,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAEnD,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,OAAO,YAAY,UAAU,GAAG,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAMlC;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,cAAsB;IACnD,IAAI,OAAO,sBAAsB,KAAK,QAAQ;QAAE,OAAO,sBAAsB,CAAC;IAC9E,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAEtF,CAAC;QACF,OAAO,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,cAAc,CAAC,cAAsB;IACnD,OAAO,IAAI,cAAc,CAAC,cAAc,CAAC,EAAE,CAAC;AAC9C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thenewlabs/entangle-utils",
-  "version": "2.11.1",
+  "version": "2.11.3",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,7 +20,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@thenewlabs/entangle-protocol": "^2.11.0",
+    "@thenewlabs/entangle-protocol": "^2.12.0",
     "dotenv": "^17.4.2",
     "pino": "^10.3.1"
   },