{"_id":"@arnaude/source-tag","_rev":"4-3c88e02aa1d5a4c8887bcf6aa8612c9d","name":"@arnaude/source-tag","dist-tags":{"latest":"1.0.0"},"versions":{"0.4.0":{"name":"@arnaude/source-tag","version":"0.4.0","keywords":["http","https","http2","fetch","undici","header","headers","service-identity","observability","preload"],"author":{"name":"Arnav Sen"},"license":"MIT","_id":"@arnaude/source-tag@0.4.0","maintainers":[{"name":"arnaude","email":"arnavsen999@gmail.com"}],"dist":{"shasum":"21e57c97b8c76659087062b36b6b8ecb9624d4c5","tarball":"https://registry.npmjs.org/@arnaude/source-tag/-/source-tag-0.4.0.tgz","fileCount":3,"integrity":"sha512-LsQdu11KQuOODU5BxrnoXeKi31dMGDSBMEjJQAj9ZnFZJFgDR9XVCmBw0PzHWa9cAWZs6B6VvMPyRKDziZNgPw==","signatures":[{"sig":"MEUCIQCxH0y14EP+92Khb0tqCwZxBJ+ImcZFgLmvC6AjheHEIQIgVS8Ja8Z70BG83+vtfoxBC3nOZrJIjrj7qYzlFS5XVy8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":55407},"main":"index.js","engines":{"node":">=14.0.0"},"gitHead":"03d1636adb8b292904bd23c8e681ddcfefec7eaa","scripts":{"test":"node test/run-tests.js"},"_npmUser":{"name":"arnaude","email":"arnavsen999@gmail.com"},"_npmVersion":"10.8.2","description":"Zero-touch outbound service-identity headers for Node HTTP clients.","directories":{"test":"test"},"sideEffects":true,"_nodeVersion":"20.20.2","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/source-tag_0.4.0_1781507167004_0.8361908182521942","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@arnaude/source-tag","version":"1.0.0","description":"Preload-based source-service tagging and trace propagation for Node.js HTTP clients and servers","main":"source-tag.js","exports":{".":"./source-tag.js"},"type":"commonjs","sideEffects":true,"scripts":{"test":"node test/run.js","pack:check":"npm pack --dry-run --json","prepublishOnly":"npm test"},"engines":{"node":">=14"},"keywords":["observability","tracing","correlation-id","http","http2","fetch","undici","preload"],"license":"MIT","publishConfig":{"access":"public"},"_id":"@arnaude/source-tag@1.0.0","_integrity":"sha512-UOAC0ncmgOGGOh+urW/1XT5IcuGVkpkmiXum3dP0QnSAYQUE7codDHk2LG39TWSxMK0kNQvml/aM04ngw0VSsA==","_resolved":"/home/user/Desktop/work/source-tag-package/arnaude-source-tag-1.0.0.tgz","_from":"file:arnaude-source-tag-1.0.0.tgz","_nodeVersion":"20.10.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-UOAC0ncmgOGGOh+urW/1XT5IcuGVkpkmiXum3dP0QnSAYQUE7codDHk2LG39TWSxMK0kNQvml/aM04ngw0VSsA==","shasum":"4a36a1b78a64686d73277282fb02f68ad8ebb996","tarball":"https://registry.npmjs.org/@arnaude/source-tag/-/source-tag-1.0.0.tgz","fileCount":6,"unpackedSize":165673,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQChblG6sl9Pbg8jWJZ56CN7E9st0+ru6OOGeHee2REYWAIhANRfV5YVegbIW7oOg8ShQtjHQOnQ1Kz4synDI2n2ygrY"}]},"_npmUser":{"name":"arnaude","email":"arnavsen999@gmail.com"},"directories":{},"maintainers":[{"name":"arnaude","email":"arnavsen999@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/source-tag_1.0.0_1786104229355_0.12241161957742164"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-15T07:06:06.791Z","modified":"2026-08-07T12:03:49.672Z","0.4.0":"2026-06-15T07:06:07.141Z","0.4.1":"2026-07-02T11:13:22.947Z","1.0.0":"2026-08-07T12:03:49.504Z"},"license":"MIT","keywords":["observability","tracing","correlation-id","http","http2","fetch","undici","preload"],"description":"Preload-based source-service tagging and trace propagation for Node.js HTTP clients and servers","maintainers":[{"name":"arnaude","email":"arnavsen999@gmail.com"}],"readme":"# @arnaude/source-tag\n\nDependency-free source-service tagging and trace propagation for Node.js services.\n\nThe package is loaded before an application starts. It instruments supported Node.js\nHTTP client and server paths without requiring every request call to be changed.\n\n## What it adds\n\nFor supported outbound requests:\n\n```http\nX-Source-Service: orders-api\nX-Source-Trace-Id: 2e7ba9f5-90d8-4df2-8e1d-81c04773ab0f\n```\n\n`X-Source-Service` identifies the immediate caller and normally changes at every\nservice boundary. `X-Source-Trace-Id` identifies the request journey and is propagated\nacross service boundaries.\n\nThese headers are observability metadata. They are not authentication or authorization.\n\n## Install\n\n```bash\nnpm install @arnaude/source-tag\n```\n\n## Start a service\n\nSet a meaningful service name and preload the package:\n\n```bash\nSERVICE_NAME=orders-api node -r @arnaude/source-tag app.js\n```\n\nIf the service relies on `dotenv` to provide `SERVICE_NAME`, load it first:\n\n```bash\nnode -r dotenv/config -r @arnaude/source-tag app.js\n```\n\nIt can also be configured through `NODE_OPTIONS`:\n\n```bash\nSERVICE_NAME=orders-api \\\nNODE_OPTIONS=\"--require=@arnaude/source-tag\" \\\nnode app.js\n```\n\nPreloading must occur in the process that actually runs the application. Child\nprocesses need their own preload configuration.\n\n## Normal behavior\n\n- A valid incoming UUIDv4 `X-Source-Trace-Id` is accepted.\n- A missing or invalid incoming trace ID is replaced with a new UUIDv4.\n- The active trace ID is returned on compatible HTTP responses.\n- Supported outbound calls receive the active trace ID.\n- Supported outbound calls receive `X-Source-Service` from `SERVICE_NAME`.\n- An explicitly supplied source header is preserved, using a case-insensitive check.\n- An outbound trace ID that conflicts with the active context is replaced by the\n  active trace ID.\n- An outbound call made outside a trace context receives the source header but does\n  not automatically create a trace ID.\n\nTrace context is isolated per request with `AsyncLocalStorage`.\n\n## Supported transports\n\nVersion 1.0 instruments supported paths for:\n\n- Node `http` and `https`\n- inbound Node HTTP/HTTPS servers\n- Node `http2`\n- built-in `fetch` when present\n- installed `undici` when resolvable\n- clients such as Axios that use the patched Node transports\n\nInstrumentation is fail-open by default: an optional transport failure is logged and\nthe host service continues.\n\n## Configuration\n\nConfiguration is read during preload. Restart the process after changing it.\n\n| Variable | Purpose |\n| --- | --- |\n| `SERVICE_NAME` | Value used for `X-Source-Service`. |\n| `SOURCE_HEADER` | Overrides the source header name. Default: `X-Source-Service`. |\n| `SOURCE_TAG_STRICT=1` | Treats critical source-tag initialization failures as fatal. |\n| `SOURCE_TAG_ALLOW_HOSTS` | Comma-separated destination allowlist for source tagging. |\n| `TRACE_ID_ALLOW_HOSTS` | Comma-separated destination allowlist for trace propagation. |\n| `DISABLE_SOURCE_TAG=1` | Disables automatic source tagging only. |\n| `DISABLE_TRACE_CONTEXT=1` | Disables automatic trace context and propagation only. |\n| `DISABLE_TRACE_ID=1` | Alias for disabling trace behavior. |\n| `DISABLE_ALL_PROPAGATION=1` | Emergency switch that disables both systems. |\n| `SOURCE_TAG_LOG_TRACE_EVENTS=1` | Enables optional trace-event diagnostics. |\n\nTransport-specific source switches are `SOURCE_TAG_DISABLE_HTTP`,\n`SOURCE_TAG_DISABLE_FETCH`, `SOURCE_TAG_DISABLE_HTTP2`, and\n`SOURCE_TAG_DISABLE_UNDICI`.\n\nTransport-specific trace switches use the `TRACE_ID_DISABLE_*` names. The shorter\n`TRACE_DISABLE_*` aliases are also accepted. Set `TRACE_ID_DISABLE_INBOUND=1` to\ndisable automatic inbound trace capture.\n\nBoolean switches are enabled with the exact value `1` unless otherwise documented.\n\n## Host allowlists\n\nWhen an allowlist is configured, propagation occurs only to matching destinations.\nEntries are comma-separated hostnames. Use allowlists when headers must not be sent to\narbitrary third-party hosts.\n\n```bash\nSOURCE_TAG_ALLOW_HOSTS=api.internal.example,localhost \\\nTRACE_ID_ALLOW_HOSTS=api.internal.example,localhost \\\nSERVICE_NAME=orders-api \\\nnode -r @arnaude/source-tag app.js\n```\n\n## Programmatic trace API\n\nPreloading is still required for automatic transport instrumentation.\n\n```js\nconst sourceTag = require('@arnaude/source-tag');\n\nsourceTag.runWithTrace(function () {\n  // Supported outbound calls made here use this trace context.\n});\n\nconsole.log(sourceTag.getTraceId());\n```\n\nExports:\n\n- `traceMiddleware` / `correlationTraceMiddleware`\n- `getTraceId` / `getCorrelationTraceId`\n- `getTraceContext`\n- `runWithTrace`\n- `generateTraceId`\n- `isValidTraceId`\n- `normalizeTraceId`\n\n## Express middleware\n\nAutomatic inbound instrumentation normally establishes context before Express handles\nthe request. The exported middleware is available as an explicit integration path:\n\n```js\nconst sourceTag = require('@arnaude/source-tag');\n\napp.use(sourceTag.traceMiddleware);\n```\n\nUsing both paths does not intentionally create a second trace for an already marked\nrequest.\n\n## Upgrade from 0.4.0\n\nVersion 1.0 enables trace context by default in addition to source tagging. See\n[`MIGRATION.md`](MIGRATION.md) for rollout controls and compatibility notes.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}