@tallyrow/safesignal 1.0.1 → 1.2.0

package/dist/transport-otlp.d.cts

@@ -0,0 +1,62 @@
+import { j as Transport } from './types-BiRyHi1e.cjs';
+
+/**
+ * `createOtlpTransport` — factory for the `./transport-otlp` subpath.
+ *
+ * Composes the subpath primitives into a `Transport` that delivers
+ * fully-processed `LogEvent`s to an OTLP logs backend as OTLP/HTTP+JSON,
+ * batched, fire-and-forget (no retry), fail-closed.
+ *
+ * Delivery policy (research D6/D7, contracts TO-2..TO-8):
+ *
+ *   send(event)
+ *     ├── if shutdownComplete: no-op
+ *     ├── lazily install the pagehide best-effort flush (first send)
+ *     ├── if serialized record > maxRecordBytes → oversized_event drop
+ *     ├── if buffered >= maxBufferedEvents → buffer_overflow drop
+ *     └── batcher.push(event)            // flush on size / age
+ *
+ *   flush(batch)  // batcher callback
+ *     ├── serialize(batch) (fail-closed: serialize_failed → drop)
+ *     └── deliver(endpoint, headers, body)  // fetch keepalive, never throws
+ *           ├── delivered ─────────────────── done
+ *           ├── unavailable ───────────────── delivery_unavailable notice
+ *           ├── send_failed ───────────────── send_failed notice (+cause)
+ *           └── partial_rejection ─────────── partial_rejection notice
+ *
+ * Every notice is rate-limited to one per failure class per instance per
+ * session and NEVER carries a configured header/secret value (FR-009).
+ * `send`/`flush`/`shutdown` NEVER throw or reject to the caller; only
+ * construction-time validation throws, at the consumer's call site.
+ *
+ * Boundary discipline (TO-7): the only `src/` import is a type-only import
+ * from `'../api/types.js'`. No `@opentelemetry/*` and no
+ * `../internal/telemetry/otel/` import — the payload is hand-serialized.
+ *
+ * Specs: `specs/007-transport-otlp/contracts/*`, `data-model.md`.
+ */
+
+interface OtlpTransportOptions {
+    /** Full OTLP logs endpoint URL (e.g. `https://otlp.example.com/v1/logs`). */
+    endpoint: string;
+    /** Static request headers (e.g. auth). Sent only on the wire. */
+    headers?: Record<string, string>;
+    /** Batch flush triggers. */
+    batching?: {
+        maxBatchSize: number;
+        maxBatchAgeMs?: number;
+    };
+    /** Hard cap on buffered events; over-cap events are dropped. Default 1000. */
+    maxBufferedEvents?: number;
+    /** Per-record size guard in bytes; larger records are dropped. Default 64 KiB. */
+    maxRecordBytes?: number;
+    /** Stable diagnostic identifier (`Transport.name`). Default `'otlp'`. */
+    name?: string;
+    /** Permit `http://` localhost/127.0.0.1/[::1] only. Default false. */
+    allowInsecureLoopback?: boolean;
+    /** Receives rate-limited diagnostic notices. Never carries header values. */
+    onInternalError?: (err: Error) => void;
+}
+declare function createOtlpTransport(options: OtlpTransportOptions): Transport;
+
+export { type OtlpTransportOptions, createOtlpTransport };

package/dist/transport-otlp.d.ts

@@ -0,0 +1,62 @@
+import { j as Transport } from './types-BiRyHi1e.js';
+
+/**
+ * `createOtlpTransport` — factory for the `./transport-otlp` subpath.
+ *
+ * Composes the subpath primitives into a `Transport` that delivers
+ * fully-processed `LogEvent`s to an OTLP logs backend as OTLP/HTTP+JSON,
+ * batched, fire-and-forget (no retry), fail-closed.
+ *
+ * Delivery policy (research D6/D7, contracts TO-2..TO-8):
+ *
+ *   send(event)
+ *     ├── if shutdownComplete: no-op
+ *     ├── lazily install the pagehide best-effort flush (first send)
+ *     ├── if serialized record > maxRecordBytes → oversized_event drop
+ *     ├── if buffered >= maxBufferedEvents → buffer_overflow drop
+ *     └── batcher.push(event)            // flush on size / age
+ *
+ *   flush(batch)  // batcher callback
+ *     ├── serialize(batch) (fail-closed: serialize_failed → drop)
+ *     └── deliver(endpoint, headers, body)  // fetch keepalive, never throws
+ *           ├── delivered ─────────────────── done
+ *           ├── unavailable ───────────────── delivery_unavailable notice
+ *           ├── send_failed ───────────────── send_failed notice (+cause)
+ *           └── partial_rejection ─────────── partial_rejection notice
+ *
+ * Every notice is rate-limited to one per failure class per instance per
+ * session and NEVER carries a configured header/secret value (FR-009).
+ * `send`/`flush`/`shutdown` NEVER throw or reject to the caller; only
+ * construction-time validation throws, at the consumer's call site.
+ *
+ * Boundary discipline (TO-7): the only `src/` import is a type-only import
+ * from `'../api/types.js'`. No `@opentelemetry/*` and no
+ * `../internal/telemetry/otel/` import — the payload is hand-serialized.
+ *
+ * Specs: `specs/007-transport-otlp/contracts/*`, `data-model.md`.
+ */
+
+interface OtlpTransportOptions {
+    /** Full OTLP logs endpoint URL (e.g. `https://otlp.example.com/v1/logs`). */
+    endpoint: string;
+    /** Static request headers (e.g. auth). Sent only on the wire. */
+    headers?: Record<string, string>;
+    /** Batch flush triggers. */
+    batching?: {
+        maxBatchSize: number;
+        maxBatchAgeMs?: number;
+    };
+    /** Hard cap on buffered events; over-cap events are dropped. Default 1000. */
+    maxBufferedEvents?: number;
+    /** Per-record size guard in bytes; larger records are dropped. Default 64 KiB. */
+    maxRecordBytes?: number;
+    /** Stable diagnostic identifier (`Transport.name`). Default `'otlp'`. */
+    name?: string;
+    /** Permit `http://` localhost/127.0.0.1/[::1] only. Default false. */
+    allowInsecureLoopback?: boolean;
+    /** Receives rate-limited diagnostic notices. Never carries header values. */
+    onInternalError?: (err: Error) => void;
+}
+declare function createOtlpTransport(options: OtlpTransportOptions): Transport;
+
+export { type OtlpTransportOptions, createOtlpTransport };

package/dist/transport-otlp.mjs

@@ -0,0 +1,539 @@
+// src/transport-otlp/batcher.ts
+function createBatcher(opts) {
+  const buffer = [];
+  let maxAgeTimer = null;
+  let flushCallback = opts.flush;
+  const clearTimer = () => {
+    if (maxAgeTimer !== null) {
+      clearTimeout(maxAgeTimer);
+      maxAgeTimer = null;
+    }
+  };
+  const armTimer = () => {
+    if (opts.maxBatchAgeMs === void 0) return;
+    maxAgeTimer = setTimeout(() => {
+      maxAgeTimer = null;
+      doFlush();
+    }, opts.maxBatchAgeMs);
+  };
+  const doFlush = () => {
+    if (buffer.length === 0) return;
+    if (flushCallback === null) {
+      buffer.length = 0;
+      clearTimer();
+      return;
+    }
+    const events = buffer.slice();
+    buffer.length = 0;
+    clearTimer();
+    try {
+      flushCallback(events);
+    } catch {
+    }
+  };
+  return {
+    push(event) {
+      if (flushCallback === null) return;
+      buffer.push(event);
+      if (buffer.length === 1 && opts.maxBatchAgeMs !== void 0) {
+        armTimer();
+      }
+      if (buffer.length >= opts.maxBatchSize) {
+        doFlush();
+      }
+    },
+    flush() {
+      doFlush();
+    },
+    shutdown() {
+      clearTimer();
+      buffer.length = 0;
+      flushCallback = null;
+    },
+    size() {
+      return buffer.length;
+    }
+  };
+}
+
+// src/transport-otlp/delivery.ts
+async function deliver(endpoint, headers, body) {
+  const fetchFn = globalThis.fetch;
+  if (typeof fetchFn !== "function") {
+    return { kind: "unavailable" };
+  }
+  let response;
+  try {
+    response = await fetchFn(endpoint, {
+      method: "POST",
+      body,
+      headers: { "content-type": "application/json", ...headers },
+      keepalive: true,
+      credentials: "same-origin"
+    });
+  } catch (cause) {
+    return { kind: "send_failed", detail: "fetch rejected", cause };
+  }
+  if (!response.ok) {
+    return { kind: "send_failed", detail: `HTTP ${response.status}` };
+  }
+  const rejected = await readRejectedCount(response);
+  if (rejected > 0) {
+    return { kind: "partial_rejection", rejected };
+  }
+  return { kind: "delivered" };
+}
+async function readRejectedCount(response) {
+  try {
+    if (typeof response.json !== "function") return 0;
+    const parsed = await response.json();
+    if (typeof parsed !== "object" || parsed === null) return 0;
+    const partial = parsed.partialSuccess;
+    if (typeof partial !== "object" || partial === null) return 0;
+    const raw = partial.rejectedLogRecords;
+    const n = typeof raw === "string" ? Number(raw) : raw;
+    return typeof n === "number" && Number.isFinite(n) && n > 0 ? n : 0;
+  } catch {
+    return 0;
+  }
+}
+
+// src/transport-otlp/endpoint-validation.ts
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
+  "localhost",
+  "127.0.0.1",
+  "[::1]"
+]);
+function validateEndpoint(endpoint, allowInsecureLoopback) {
+  if (typeof endpoint !== "string") {
+    throw new TypeError(
+      `otlp transport: endpoint must be a string, got ${typeName(endpoint)}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = new URL(endpoint);
+  } catch {
+    throw new TypeError(`otlp transport: invalid endpoint URL: '${endpoint}'`);
+  }
+  if (parsed.protocol === "https:") {
+    return parsed;
+  }
+  if (parsed.protocol === "http:") {
+    if (!allowInsecureLoopback) {
+      throw new Error(
+        `otlp transport refuses non-HTTPS endpoint '${endpoint}'`
+      );
+    }
+    if (!LOOPBACK_HOSTS.has(parsed.hostname)) {
+      throw new Error(
+        `otlp transport: allowInsecureLoopback permits only localhost / 127.0.0.1 / [::1]; got '${parsed.hostname}' in '${endpoint}'`
+      );
+    }
+    return parsed;
+  }
+  throw new Error(
+    `otlp transport refuses non-HTTPS endpoint '${endpoint}' (scheme '${parsed.protocol}' is not permitted)`
+  );
+}
+function typeName(value) {
+  if (value === null) return "null";
+  return typeof value;
+}
+
+// src/transport-otlp/errors.ts
+var OtlpError = class extends Error {
+  constructor(code, transportName, message, cause) {
+    super(message);
+    this.name = "OtlpError";
+    this.code = code;
+    this.transportName = transportName;
+    if (cause !== void 0) {
+      Object.defineProperty(this, "cause", {
+        value: cause,
+        enumerable: true,
+        writable: false,
+        configurable: false
+      });
+    }
+  }
+};
+function notifyOnce(ctx, code, message, cause) {
+  if (ctx.notified[code]) return;
+  ctx.notified[code] = true;
+  const err = new OtlpError(
+    code,
+    ctx.name,
+    `otlp transport '${ctx.name}': ${message}`,
+    cause
+  );
+  try {
+    ctx.onInternalError(err);
+  } catch {
+  }
+}
+function freshNotifiedLedger() {
+  return {
+    oversized_event: false,
+    buffer_overflow: false,
+    delivery_unavailable: false,
+    send_failed: false,
+    partial_rejection: false,
+    serialize_failed: false,
+    shutdown_failed: false
+  };
+}
+
+// src/transport-otlp/attributes.ts
+function toAnyValue(value) {
+  if (value === null) {
+    return {};
+  }
+  switch (typeof value) {
+    case "string":
+      return { stringValue: value };
+    case "boolean":
+      return { boolValue: value };
+    case "number":
+      return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+  }
+  if (Array.isArray(value)) {
+    return { arrayValue: { values: value.map(toAnyValue) } };
+  }
+  return { kvlistValue: { values: toKeyValues(value) } };
+}
+function toKeyValues(record, keyPrefix = "") {
+  const out = [];
+  for (const key of Object.keys(record)) {
+    const value = record[key];
+    if (value === void 0) continue;
+    out.push({ key: keyPrefix + key, value: toAnyValue(value) });
+  }
+  return out;
+}
+
+// src/transport-otlp/resource.ts
+function buildResource(context) {
+  const attributes = [];
+  const push = (key, value) => {
+    if (typeof value === "string" && value.length > 0) {
+      attributes.push({ key, value: { stringValue: value } });
+    }
+  };
+  push("service.name", context.application?.name);
+  push("service.version", context.application?.version);
+  push("deployment.environment", context.environment);
+  return { attributes };
+}
+
+// src/transport-otlp/otlp-serializer.ts
+var SCOPE_NAME = "@tallyrow/safesignal";
+var LEVEL_TO_SEVERITY_NUMBER = {
+  debug: 5,
+  info: 9,
+  warn: 13,
+  error: 17
+};
+var LEVEL_TO_SEVERITY_TEXT = {
+  debug: "DEBUG",
+  info: "INFO",
+  warn: "WARN",
+  error: "ERROR"
+};
+function toLogRecord(event, fallbackTimeMs) {
+  const ms = toEpochMs(event.timestamp, fallbackTimeMs);
+  const nano = String(ms * 1e6);
+  const attributes = toKeyValues(event.attributes);
+  const context = event.context;
+  if (context.attributes !== void 0) {
+    attributes.push(...toKeyValues(context.attributes, "context."));
+  }
+  pushModuleIdentity(attributes, context);
+  pushException(attributes, event);
+  const record = {
+    timeUnixNano: nano,
+    observedTimeUnixNano: nano,
+    severityNumber: LEVEL_TO_SEVERITY_NUMBER[event.level],
+    severityText: LEVEL_TO_SEVERITY_TEXT[event.level],
+    body: { stringValue: event.message },
+    attributes
+  };
+  const trace = context.trace;
+  if (trace !== void 0) {
+    record.traceId = trace.traceId;
+    record.spanId = trace.spanId;
+    if (trace.traceFlags !== void 0) {
+      record.flags = trace.traceFlags;
+    }
+  }
+  return record;
+}
+function serializeBatch(batch, fallbackTimeMs) {
+  const first = batch[0];
+  const resource = buildResource(first ? first.context : {});
+  const logRecords = batch.map((e) => toLogRecord(e, fallbackTimeMs));
+  return {
+    resourceLogs: [
+      {
+        resource,
+        scopeLogs: [{ scope: { name: SCOPE_NAME }, logRecords }]
+      }
+    ]
+  };
+}
+function encode(request) {
+  return JSON.stringify(request);
+}
+function toEpochMs(iso, fallbackMs) {
+  const parsed = Date.parse(iso);
+  return Number.isFinite(parsed) ? parsed : fallbackMs;
+}
+function pushModuleIdentity(out, context) {
+  const mod = context.module;
+  if (mod === void 0) return;
+  if (typeof mod.name === "string" && mod.name.length > 0) {
+    out.push({ key: "module.name", value: { stringValue: mod.name } });
+  }
+  if (typeof mod.version === "string" && mod.version.length > 0) {
+    out.push({ key: "module.version", value: { stringValue: mod.version } });
+  }
+}
+function pushException(out, event) {
+  const err = event.error;
+  if (err === void 0) return;
+  out.push({ key: "exception.type", value: { stringValue: err.name } });
+  out.push({ key: "exception.message", value: { stringValue: err.message } });
+  if (typeof err.stack === "string" && err.stack.length > 0) {
+    out.push({
+      key: "exception.stacktrace",
+      value: { stringValue: err.stack }
+    });
+  }
+}
+
+// src/transport-otlp/otlp-transport.ts
+var DEFAULTS = {
+  maxBatchSize: 20,
+  maxBatchAgeMs: 5e3,
+  maxBufferedEvents: 1e3,
+  maxRecordBytes: 65536,
+  name: "otlp"
+};
+function validateOptions(options) {
+  if (typeof options !== "object" || options === null) {
+    throw new TypeError("otlp transport: options must be a non-null object");
+  }
+  const { headers, batching, maxBufferedEvents, maxRecordBytes } = options;
+  if (headers !== void 0) {
+    if (typeof headers !== "object" || headers === null) {
+      throw new TypeError("otlp transport: headers must be an object");
+    }
+    for (const key of Object.keys(headers)) {
+      if (typeof headers[key] !== "string") {
+        throw new TypeError(
+          `otlp transport: header '${key}' must be a string value`
+        );
+      }
+    }
+  }
+  const maxBatchSize = batching?.maxBatchSize ?? DEFAULTS.maxBatchSize;
+  if (!Number.isInteger(maxBatchSize) || maxBatchSize < 1) {
+    throw new RangeError(
+      "otlp transport: batching.maxBatchSize must be an integer >= 1"
+    );
+  }
+  const cap = maxBufferedEvents ?? DEFAULTS.maxBufferedEvents;
+  if (!Number.isInteger(cap) || cap < maxBatchSize) {
+    throw new RangeError(
+      "otlp transport: maxBufferedEvents must be an integer >= maxBatchSize"
+    );
+  }
+  const recBytes = maxRecordBytes ?? DEFAULTS.maxRecordBytes;
+  if (!Number.isInteger(recBytes) || recBytes < 1) {
+    throw new RangeError(
+      "otlp transport: maxRecordBytes must be an integer >= 1"
+    );
+  }
+}
+function createOtlpTransport(options) {
+  validateOptions(options);
+  const allowInsecureLoopback = options.allowInsecureLoopback ?? false;
+  validateEndpoint(options.endpoint, allowInsecureLoopback);
+  const name = options.name ?? DEFAULTS.name;
+  const maxBatchSize = options.batching?.maxBatchSize ?? DEFAULTS.maxBatchSize;
+  const maxBatchAgeMs = options.batching?.maxBatchAgeMs ?? DEFAULTS.maxBatchAgeMs;
+  const state = {
+    endpoint: options.endpoint,
+    // Copy + freeze the headers so later consumer mutation cannot change
+    // what we send, and so nothing outside delivery can read them.
+    headers: Object.freeze({ ...options.headers ?? {} }),
+    name,
+    onInternalError: options.onInternalError ?? (() => void 0),
+    maxBufferedEvents: options.maxBufferedEvents ?? DEFAULTS.maxBufferedEvents,
+    maxRecordBytes: options.maxRecordBytes ?? DEFAULTS.maxRecordBytes,
+    notified: freshNotifiedLedger(),
+    // Placeholder; real batcher assigned below once the flush closure exists.
+    batcher: void 0,
+    pagehideInstalled: false,
+    pagehideUninstall: null,
+    shutdownComplete: false,
+    inFlight: /* @__PURE__ */ new Set(),
+    pending: 0
+  };
+  state.batcher = createBatcher({
+    maxBatchSize,
+    maxBatchAgeMs,
+    flush: (events) => {
+      void flushBatch(state, events);
+    }
+  });
+  return {
+    name,
+    send(event) {
+      if (state.shutdownComplete) return;
+      ensurePagehide(state);
+      try {
+        const record = toLogRecord(event, Date.now());
+        if (byteLength(JSON.stringify(record)) > state.maxRecordBytes) {
+          notifyOnce(
+            state,
+            "oversized_event",
+            `dropped an event whose serialized record exceeds ${state.maxRecordBytes} bytes`
+          );
+          return;
+        }
+      } catch (cause) {
+        notifyOnce(
+          state,
+          "serialize_failed",
+          "dropped an event that failed to serialize",
+          cause
+        );
+        return;
+      }
+      if (state.pending >= state.maxBufferedEvents) {
+        notifyOnce(
+          state,
+          "buffer_overflow",
+          `${state.maxBufferedEvents} events undelivered; dropping event`
+        );
+        return;
+      }
+      state.pending += 1;
+      state.batcher.push(event);
+    },
+    async flush() {
+      state.batcher.flush();
+      await settleInFlight(state);
+    },
+    async shutdown() {
+      if (state.shutdownComplete) {
+        await settleInFlight(state);
+        return;
+      }
+      state.shutdownComplete = true;
+      try {
+        state.batcher.flush();
+        await settleInFlight(state);
+      } catch (cause) {
+        notifyOnce(state, "shutdown_failed", "shutdown flush failed", cause);
+      } finally {
+        teardownPagehide(state);
+        state.batcher.shutdown();
+      }
+    }
+  };
+}
+async function flushBatch(state, events) {
+  const count = events.length;
+  let body;
+  try {
+    body = encode(serializeBatch(events, Date.now()));
+  } catch (cause) {
+    state.pending = Math.max(0, state.pending - count);
+    notifyOnce(
+      state,
+      "serialize_failed",
+      "dropped a batch that failed to serialize",
+      cause
+    );
+    return;
+  }
+  const promise = (async () => {
+    const result = await deliver(
+      state.endpoint,
+      state.headers,
+      body
+    );
+    mapResult(state, result);
+  })().catch(() => {
+  });
+  state.inFlight.add(promise);
+  void promise.finally(() => {
+    state.inFlight.delete(promise);
+    state.pending = Math.max(0, state.pending - count);
+  });
+}
+function mapResult(state, result) {
+  switch (result.kind) {
+    case "delivered":
+      return;
+    case "unavailable":
+      notifyOnce(
+        state,
+        "delivery_unavailable",
+        "fetch is unavailable; dropping batch"
+      );
+      return;
+    case "send_failed":
+      notifyOnce(
+        state,
+        "send_failed",
+        `delivery failed (${result.detail})`,
+        result.cause
+      );
+      return;
+    case "partial_rejection":
+      notifyOnce(
+        state,
+        "partial_rejection",
+        `backend rejected ${result.rejected} record(s)`
+      );
+      return;
+  }
+}
+async function settleInFlight(state) {
+  await Promise.all([...state.inFlight]);
+}
+function ensurePagehide(state) {
+  if (state.pagehideInstalled) return;
+  const target = globalThis;
+  state.pagehideInstalled = true;
+  if (typeof target.addEventListener !== "function") {
+    state.pagehideUninstall = null;
+    return;
+  }
+  const handler = () => {
+    state.batcher.flush();
+  };
+  target.addEventListener("pagehide", handler);
+  state.pagehideUninstall = () => {
+    if (typeof target.removeEventListener === "function") {
+      target.removeEventListener("pagehide", handler);
+    }
+  };
+}
+function teardownPagehide(state) {
+  if (state.pagehideUninstall !== null) {
+    state.pagehideUninstall();
+    state.pagehideUninstall = null;
+  }
+  state.pagehideInstalled = false;
+}
+function byteLength(s) {
+  return new TextEncoder().encode(s).length;
+}
+
+export { createOtlpTransport };
+//# sourceMappingURL=transport-otlp.mjs.map
+//# sourceMappingURL=transport-otlp.mjs.map