@traffic-twin/sdk 0.0.0-stage → 0.1.1

package/dist/cjs/worker/sanitizer-worker.js

@@ -0,0 +1,53 @@
+"use strict";
+// Sanitizer worker thread: receives wire exchanges, returns ready-made OTLP logRecords.
+// It runs exactly the code the main thread would run inline (export/pipeline.ts), so the
+// events are byte-identical. It holds the HMAC key like the main thread does and has no
+// network, file or Fleet access of its own: it only reads messages and posts results.
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_worker_threads_1 = require("node:worker_threads");
+const pipeline_js_1 = require("../export/pipeline.js");
+const json_js_1 = require("../sanitizer/json.js");
+const policy_js_1 = require("../sanitizer/policy.js");
+const sanitizer_js_1 = require("../sanitizer/sanitizer.js");
+const MAX_GENS = 16;
+const sans = new Map();
+const port = node_worker_threads_1.parentPort;
+if (port) {
+    const send = (m) => port.postMessage(m);
+    port.on('message', (m) => {
+        try {
+            if (m.t === 'policy') {
+                const p = new policy_js_1.Policy((0, json_js_1.nodeToPlain)((0, json_js_1.parseJson)(m.body), true));
+                p.hash = m.hash;
+                sans.set(m.gen, new sanitizer_js_1.Sanitizer(p, { kid: m.kid, key: Buffer.from(m.key) }, { rateOverrideBp: m.rateOverrideBp }));
+                while (sans.size > MAX_GENS)
+                    sans.delete(sans.keys().next().value);
+            }
+            else if (m.t === 'run') {
+                const recs = [];
+                const errs = [];
+                const now = Date.now();
+                for (const j of m.jobs) {
+                    const san = sans.get(j.gen);
+                    const r = san ? (0, pipeline_js_1.sanitizeToRecord)(san, j.wire, j.decision, j.meta, m.sourceId, now) : { err: 'sanitizer_error' };
+                    if (r === null)
+                        continue;
+                    if ('record' in r)
+                        recs.push(r.record);
+                    else
+                        errs.push(r.err);
+                }
+                send({ t: 'out', epoch: m.epoch, recs, errs });
+            }
+            else if (m.t === 'sync') {
+                send({ t: 'synced', seq: m.seq });
+            }
+        }
+        catch {
+            // A malformed message must not kill the worker; the jobs it carried are lost.
+            if (m.t === 'run')
+                send({ t: 'out', epoch: m.epoch, recs: [], errs: m.jobs.map(() => 'sanitizer_error') });
+        }
+    });
+    send({ t: 'ready' });
+}

package/dist/esm/agent.d.ts

@@ -0,0 +1,143 @@
+import type { CaptureHost, RawExchange } from './capture/common.js';
+import { Sanitizer } from './sanitizer/sanitizer.js';
+export type SourceState = 'starting' | 'capturing' | 'no_policy' | 'policy_rejected' | 'expired_policy' | 'key_missing' | 'key_mismatch' | 'killed';
+export interface AgentOptions {
+    /** Fleet base URL used for enrollment (TT_ENROLL_URL). */
+    enrollUrl?: string;
+    /** Enrollment token `tte_<secret>.<pin>` (TT_ENROLL_TOKEN). */
+    enrollToken?: string;
+    /** Content of the HMAC key (TT_HMAC_KEY). */
+    hmacKey?: string;
+    /** File holding the HMAC key (TT_HMAC_KEY_FILE). */
+    hmacKeyFile?: string;
+    /** Service name requested at enrollment (TT_SERVICE_NAME, else OTEL_SERVICE_NAME). */
+    serviceName?: string;
+    /** Where certificates, keys and the policy cache are kept (TT_STATE_DIR). */
+    stateDir?: string;
+    /** Informational instance name (TT_INSTANCE, default hostname). */
+    instance?: string;
+    /** Send a CSR at enrollment so the private key never leaves the process (default true). */
+    useCsr?: boolean;
+    debug?: boolean;
+    /** Overrides for tests and benchmarks. */
+    heartbeatIntervalMs?: number;
+    policyPollIntervalMs?: number;
+    exportFlushMs?: number;
+    /** Sanitizer worker threads: 0 = always inline, default min(2, cores - 1) (TT_SANITIZER_THREADS). */
+    sanitizerThreads?: number;
+    /** Sampling rate (basis points) from which sanitization moves to the workers (default 200 = 2%). */
+    workerMinBp?: number;
+}
+export declare function serviceNameFromEnv(env: NodeJS.ProcessEnv): string | undefined;
+export declare function optionsFromEnv(env?: NodeJS.ProcessEnv): AgentOptions;
+export declare class Agent implements CaptureHost {
+    readonly opts: AgentOptions;
+    readonly counters: {
+        exchanges_seen: number;
+        exchanges_sampled: number;
+        events_sent: number;
+        events_dropped_queue: number;
+        events_rejected: number;
+        send_errors: number;
+        sanitizer_errors: number;
+    };
+    state: SourceState;
+    private san;
+    private policy;
+    private policyKid;
+    private rejected;
+    private ring;
+    private keyState;
+    private heartbeatOk;
+    private lastContact;
+    private persisted;
+    private overrideBp;
+    private decisionNames;
+    private readonly overhead;
+    private overheadN;
+    private lastErrors;
+    private pending;
+    private pendingBytes;
+    private drainScheduled;
+    private pool;
+    /** The last drain handed its work to the workers: the next one is batched on a timer. */
+    private workerMode;
+    private inflight;
+    private inflightBytes;
+    private uninstall;
+    private timers;
+    private stopped;
+    private store;
+    private enrollment;
+    private keyPem;
+    private httpsAgent;
+    private fleet;
+    private exporter;
+    private etag;
+    private switching;
+    private acceptedHashes;
+    private polling;
+    private pollAgain;
+    constructor(opts: AgentOptions);
+    active(): Sanitizer | null;
+    serviceName(): string;
+    decisionHeaders(): ReadonlySet<string>;
+    propagates(): boolean;
+    mayPropagate(urlBase: string): boolean;
+    private propMemoFor;
+    private readonly propMemo;
+    private mayPropagateUncached;
+    noteSeen(): void;
+    noteSampled(): void;
+    noteOverhead(ns: number): void;
+    noteError(code: string): void;
+    submit(raw: RawExchange): void;
+    private threads;
+    /** Worker threads pay off only when many exchanges are sampled (high rate). */
+    private wantWorkers;
+    private onWorkerOut;
+    /**
+     * Inline sanitization runs right after the response (setImmediate). With worker threads
+     * the exchanges are collected for a few milliseconds and posted as one batch: one message
+     * and one thread wake-up for many exchanges instead of one each.
+     */
+    private scheduleDrain;
+    private drain;
+    /** Posts up to WORKER_BATCH pending exchanges to a worker. False when none could be posted. */
+    private drainToWorkers;
+    private process;
+    /** Installs the hooks and runs the first Fleet cycle. Never throws. */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Sanitizes what is pending and sends everything queued (tests, graceful shutdown). */
+    flush(): Promise<void>;
+    status(): {
+        state: SourceState;
+        counters: Agent['counters'];
+        queue: {
+            events: number;
+            bytes: number;
+        };
+    };
+    private enrollWithRetry;
+    private connect;
+    private schedule;
+    private loadKeys;
+    /** Said once per cause, whatever TT_DEBUG: without the key nothing is captured. Never prints key material or paths. */
+    private keyWarned;
+    private warnKeyMissing;
+    private signingKeys;
+    private persist;
+    private tryAccept;
+    private pollPolicy;
+    private pollOnce;
+    private overheadUs;
+    private heartbeat;
+    private applyHeartbeat;
+    private addSigningKeys;
+    private renew;
+    private revoke;
+    private dropQueues;
+    /** Recomputes the state and the capture gate. */
+    private recompute;
+}