@rootcat/node 0.0.0-stage → 0.1.0

package/dist/intake.js

@@ -0,0 +1,164 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.procFiles = void 0;
+exports.defaultGateway = defaultGateway;
+exports.inContainer = inContainer;
+exports.hostNetwork = hostNetwork;
+exports.privateAddress = privateAddress;
+exports.discoverIntake = discoverIntake;
+// Intake discovery: where the host agent's OTLP listener is from where the
+// process runs. Inside a container the agent listens on the IPv4 address
+// of the container's bridge, which is the container's default gateway; on
+// the host it listens on loopback. Both come from /proc, read once,
+// bounded.
+const fs = __importStar(require("node:fs"));
+const config_js_1 = require("./config.js");
+/** Bounds on the /proc reads. */
+const maxRouteBytes = 64 * 1024;
+const maxCgroupBytes = 16 * 1024;
+/** procFiles reads the real /proc, /sys and root. */
+exports.procFiles = {
+    exists(file) {
+        try {
+            return fs.existsSync(file);
+        }
+        catch {
+            return false;
+        }
+    },
+    list(dir) {
+        try {
+            return fs.readdirSync(dir).slice(0, 4096);
+        }
+        catch {
+            return [];
+        }
+    },
+    read(file, maxBytes) {
+        let fd;
+        try {
+            fd = fs.openSync(file, 'r');
+            const buffer = Buffer.alloc(maxBytes);
+            const n = fs.readSync(fd, buffer, 0, maxBytes, 0);
+            return buffer.toString('utf8', 0, n);
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            if (fd !== undefined) {
+                fs.closeSync(fd);
+            }
+        }
+    },
+};
+/**
+ * defaultGateway parses /proc/net/route and returns the IPv4 gateway of
+ * the default route (destination 0.0.0.0 with the gateway flag set), or
+ * undefined when there is none.
+ */
+function defaultGateway(routeTable) {
+    const lines = routeTable.split('\n');
+    for (const line of lines.slice(1)) {
+        const fields = line.trim().split(/\s+/);
+        if (fields.length < 4) {
+            continue;
+        }
+        const [, destination, gateway, flags] = fields;
+        if (destination !== '00000000' || !/^[0-9a-fA-F]{8}$/.test(gateway)) {
+            continue;
+        }
+        const flagBits = Number.parseInt(flags, 16);
+        if (Number.isNaN(flagBits) || (flagBits & 0x2) === 0) {
+            continue; // RTF_GATEWAY not set
+        }
+        const value = Number.parseInt(gateway, 16);
+        if (value === 0) {
+            continue;
+        }
+        // The kernel writes the address in host byte order, little-endian on
+        // every platform Rootcat runs on.
+        const address = [value & 0xff, (value >>> 8) & 0xff, (value >>> 16) & 0xff, (value >>> 24) & 0xff].join('.');
+        return address;
+    }
+    return undefined;
+}
+/**
+ * inContainer reports whether the process runs in a container: Docker's
+ * /.dockerenv, podman's /run/.containerenv, or a cgroup path naming a
+ * container runtime.
+ */
+function inContainer(files) {
+    if (files.exists('/.dockerenv') || files.exists('/run/.containerenv')) {
+        return true;
+    }
+    const cgroup = files.read('/proc/1/cgroup', maxCgroupBytes) ?? '';
+    return /\/(docker|containerd|kubepods|libpod|lxc|podman)[/-]/.test(cgroup) || /:\/docker\//.test(cgroup);
+}
+/**
+ * hostNetwork reports whether the process sees the host's own network:
+ * a Docker bridge (docker0, docker_gwbridge, br-*) among the interfaces
+ * in /sys/class/net, which in a container's own network namespace lists
+ * only that namespace's interfaces. A container started with
+ * network_mode: host has /.dockerenv and the host's routing table, whose
+ * default gateway is the LAN's or the provider's router.
+ */
+function hostNetwork(files) {
+    return files.list('/sys/class/net').some((name) => name === 'docker0' || name === 'docker_gwbridge' || name.startsWith('br-'));
+}
+/** privateAddress reports whether an IPv4 address is in a private or shared range. */
+function privateAddress(address) {
+    const [a, b] = address.split('.').map(Number);
+    return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 100 && b >= 64 && b <= 127);
+}
+/**
+ * discoverIntake returns the agent intake's origin: the default gateway
+ * inside a container on a bridge (the bridge address the agent listens
+ * on), else loopback. A container on the host's network, or a gateway
+ * outside the private ranges, gets loopback: spans are never sent off
+ * the host by discovery.
+ */
+function discoverIntake(files = exports.procFiles) {
+    if (inContainer(files) && !hostNetwork(files)) {
+        const route = files.read('/proc/net/route', maxRouteBytes);
+        const gateway = route ? defaultGateway(route) : undefined;
+        if (gateway && privateAddress(gateway)) {
+            return `http://${gateway}:${config_js_1.otlpPort}`;
+        }
+    }
+    return `http://127.0.0.1:${config_js_1.otlpPort}`;
+}
+//# sourceMappingURL=intake.js.map

package/dist/intake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intake.js","sourceRoot":"","sources":["../src/intake.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,wCAyBC;AAOD,kCAMC;AAUD,kCAEC;AAGD,wCAGC;AASD,wCASC;AApID,2EAA2E;AAC3E,yEAAyE;AACzE,0EAA0E;AAC1E,oEAAoE;AACpE,WAAW;AACX,4CAA8B;AAC9B,2CAAuC;AAEvC,iCAAiC;AACjC,MAAM,aAAa,GAAG,EAAE,GAAG,IAAI,CAAC;AAChC,MAAM,cAAc,GAAG,EAAE,GAAG,IAAI,CAAC;AAUjC,qDAAqD;AACxC,QAAA,SAAS,GAAU;IAC9B,MAAM,CAAC,IAAI;QACT,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,IAAI,CAAC,GAAG;QACN,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IACD,IAAI,CAAC,IAAI,EAAE,QAAQ;QACjB,IAAI,EAAsB,CAAC;QAC3B,IAAI,CAAC;YACH,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC5B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YACtC,MAAM,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;YAClD,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;gBAAS,CAAC;YACT,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;gBACrB,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YACnB,CAAC;QACH,CAAC;IACH,CAAC;CACF,CAAC;AAEF;;;;GAIG;AACH,SAAgB,cAAc,CAAC,UAAkB;IAC/C,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,SAAS;QACX,CAAC;QACD,MAAM,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC;QAC/C,IAAI,WAAW,KAAK,UAAU,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACpE,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC5C,IAAI,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACrD,SAAS,CAAC,sBAAsB;QAClC,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC3C,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,SAAS;QACX,CAAC;QACD,qEAAqE;QACrE,kCAAkC;QAClC,MAAM,OAAO,GAAG,CAAC,KAAK,GAAG,IAAI,EAAE,CAAC,KAAK,KAAK,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7G,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,SAAgB,WAAW,CAAC,KAAY;IACtC,IAAI,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,oBAAoB,CAAC,EAAE,CAAC;QACtE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,gBAAgB,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC;IAClE,OAAO,sDAAsD,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC3G,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,WAAW,CAAC,KAAY;IACtC,OAAO,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,iBAAiB,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;AACjI,CAAC;AAED,sFAAsF;AACtF,SAAgB,cAAc,CAAC,OAAe;IAC5C,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9C,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;AACzH,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,cAAc,CAAC,QAAe,iBAAS;IACrD,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,iBAAiB,EAAE,aAAa,CAAC,CAAC;QAC3D,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1D,IAAI,OAAO,IAAI,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC;YACvC,OAAO,UAAU,OAAO,IAAI,oBAAQ,EAAE,CAAC;QACzC,CAAC;IACH,CAAC;IACD,OAAO,oBAAoB,oBAAQ,EAAE,CAAC;AACxC,CAAC"}

package/dist/keys.d.ts

@@ -0,0 +1,9 @@
+/** callSiteContextKey carries a call site through the active context. */
+export declare const callSiteContextKey: symbol;
+/**
+ * rootDecisionKey carries a trace decision an entry wrapper made for an
+ * operation outside any span, so the span the driver starts later is
+ * sampled as the wrapper decided (and the wrapper captured, or not, to
+ * match).
+ */
+export declare const rootDecisionKey: symbol;

package/dist/keys.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rootDecisionKey = exports.callSiteContextKey = void 0;
+// Context keys shared by the processor, the sampler and the entry wrappers.
+const api_1 = require("@opentelemetry/api");
+/** callSiteContextKey carries a call site through the active context. */
+exports.callSiteContextKey = (0, api_1.createContextKey)('rootcat.callsite');
+/**
+ * rootDecisionKey carries a trace decision an entry wrapper made for an
+ * operation outside any span, so the span the driver starts later is
+ * sampled as the wrapper decided (and the wrapper captured, or not, to
+ * match).
+ */
+exports.rootDecisionKey = (0, api_1.createContextKey)('rootcat.root-decision');
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":";;;AAAA,4EAA4E;AAC5E,4CAAsD;AAEtD,yEAAyE;AAC5D,QAAA,kBAAkB,GAAG,IAAA,sBAAgB,EAAC,kBAAkB,CAAC,CAAC;AAEvE;;;;;GAKG;AACU,QAAA,eAAe,GAAG,IAAA,sBAAgB,EAAC,uBAAuB,CAAC,CAAC"}

package/dist/notices.d.ts

@@ -0,0 +1,2 @@
+/** sayOnce writes a line to stderr the first time key is seen. */
+export declare function sayOnce(key: string, message: string): void;

package/dist/notices.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sayOnce = sayOnce;
+// Notices the package prints on stderr, each at most once per process:
+// the exporter's and the SDK's failures never reach the application, but
+// an operator should learn once that spans are being lost, and why.
+const said = new Set();
+/** sayOnce writes a line to stderr the first time key is seen. */
+function sayOnce(key, message) {
+    if (said.has(key)) {
+        return;
+    }
+    said.add(key);
+    try {
+        process.stderr.write(`rootcat: ${message}; this is said once\n`);
+    }
+    catch {
+        // stderr closed: nothing to do
+    }
+}
+//# sourceMappingURL=notices.js.map

package/dist/notices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notices.js","sourceRoot":"","sources":["../src/notices.ts"],"names":[],"mappings":";;AAMA,0BAUC;AAhBD,uEAAuE;AACvE,yEAAyE;AACzE,oEAAoE;AACpE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;AAE/B,kEAAkE;AAClE,SAAgB,OAAO,CAAC,GAAW,EAAE,OAAe;IAClD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QAClB,OAAO;IACT,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACd,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,OAAO,uBAAuB,CAAC,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,+BAA+B;IACjC,CAAC;AACH,CAAC"}

package/dist/otlp.d.ts

@@ -0,0 +1,75 @@
+import type { HrTime } from '@opentelemetry/api';
+import { type ExportResult } from '@opentelemetry/core';
+import type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
+/** Writer appends protobuf fields to a growing buffer. */
+export declare class Writer {
+    buf: Buffer;
+    pos: number;
+    constructor(size?: number);
+    private ensure;
+    varint(value: number): void;
+    tag(field: number, type: number): void;
+    /** begin opens a length-delimited field and returns where its length goes. */
+    begin(field: number): number;
+    /** end closes the field begin opened, widening its length when needed. */
+    end(at: number): void;
+    string(field: number, value: string): void;
+    bytesHex(field: number, hex: string): void;
+    fixed64Time(field: number, time: HrTime): void;
+    double(field: number, value: number): void;
+    int64(field: number, value: number): void;
+    /** finish returns the bytes written (a view of the buffer). */
+    finish(): Buffer;
+}
+/**
+ * encodeTraces writes one ExportTraceServiceRequest for spans that share a
+ * resource (the SDK's one resource), grouped by instrumentation scope.
+ */
+export declare function encodeTraces(spans: readonly ReadableSpan[], w?: Writer): Buffer;
+/**
+ * maxRequestBytes keeps every request under the agent's 1 MiB intake
+ * bound, with room for the transport's own framing.
+ */
+export declare const maxRequestBytes: number;
+/**
+ * encodeWithin encodes spans into requests of at most limit bytes,
+ * halving a batch until each part fits. A single span that does not fit
+ * on its own (which the span limits make all but impossible) is dropped,
+ * and counted in dropped.
+ */
+export declare function encodeWithin(spans: readonly ReadableSpan[], limit?: number): {
+    bodies: Buffer[];
+    dropped: number;
+};
+/** ProtobufExporterOptions bounds the exporter. */
+export interface ProtobufExporterOptions {
+    url: string;
+    timeoutMillis: number;
+    /** concurrency is how many exports may be in flight; past it a batch is dropped. */
+    concurrency: number;
+    /** maxRequestBytes bounds one request (tests lower it). */
+    maxRequestBytes?: number;
+}
+/**
+ * ProtobufExporter posts encoded batches to the intake, split into
+ * requests under maxRequestBytes and sent one after another. A batch that
+ * cannot be sent (the intake is down, slow past the timeout, answers an
+ * error, or two exports are already in flight) is dropped and reported as
+ * failed to the batch processor; nothing is retried. A request the intake
+ * refuses as too large (413) is said once on stderr.
+ */
+export declare class ProtobufExporter implements SpanExporter {
+    private readonly url;
+    private readonly agent;
+    private readonly timeoutMillis;
+    private readonly concurrency;
+    private readonly maxRequestBytes;
+    private inFlight;
+    private stopped;
+    constructor(options: ProtobufExporterOptions);
+    export(spans: ReadableSpan[], done: (result: ExportResult) => void): void;
+    /** post sends one request and settles with its outcome. */
+    private post;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}