@lunora/container 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/index.mjs

@@ -1,2 +1,2 @@
-export { createContainerContext, createContainerTestContext } from './packem_shared/createContainerContext-ChDD53ys.mjs';
-export { containerBindingName, containerBuildTag, containerClassName, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVars } from './packem_shared/containerBindingName-BGdSdFNA.mjs';
+export { createContainerContext, createContainerTestContext } from './packem_shared/createContainerContext-CIVzsY5m.mjs';
+export { containerBindingName, containerBuildTag, containerClassName, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVars } from './packem_shared/containerBindingName-BiTrAF1J.mjs';

package/dist/otel.d.mts

@@ -0,0 +1,95 @@
+/** An attribute value carried on a span or log. */
+type ContainerAttributeValue = boolean | number | string;
+/**
+* A `fetch` implementation — defaults to the runtime global. The exporter passes
+* an abort `signal` (for the per-request timeout) and, once the promise settles,
+* cancels the response `body` so Node/undici can release the socket for
+* keep-alive reuse instead of leaving it occupied by an unread stream. It reads
+* `ok`/`status` to detect a rejected export and nothing else from the response.
+*/
+type OtelFetchLike = (input: string, init: {
+  body: string;
+  headers: Record<string, string>;
+  method: string;
+  signal?: AbortSignal;
+}) => Promise<{
+  body?: {
+    cancel: () => Promise<void>;
+  } | null;
+  ok: boolean;
+  status: number;
+}>;
+/** A single span the container process asks the exporter to record. */
+interface ContainerSpanInput {
+  /** Attributes attached to the span (rendered under the OTLP `attributes` list). */
+  attributes?: Record<string, ContainerAttributeValue>;
+  /** Wall-clock millis when the operation ended. */
+  endMs: number;
+  /** When set, the span is marked errored with this message (and optional `error.type`). */
+  error?: {
+    message: string;
+    type?: string;
+  };
+  /** Span name — the operation being timed, e.g. `"transcode"`. */
+  name: string;
+  /** Wall-clock millis when the operation started. */
+  startMs: number;
+}
+/** A single log line the container process asks the exporter to record. */
+interface ContainerLogInput {
+  /** Attributes attached to the log record. */
+  attributes?: Record<string, ContainerAttributeValue>;
+  /** Severity — defaults to `"info"`. */
+  level?: "debug" | "error" | "info" | "warn";
+  /** The log message body. */
+  message: string;
+  /** Wall-clock millis the line was emitted; defaults to now. */
+  ts?: number;
+}
+/** Options for {@link createContainerTelemetry}. */
+interface ContainerTelemetryOptions {
+  /** Base OTLP collector endpoint; defaults to the `LUNORA_OTLP_ENDPOINT` env var. */
+  endpoint?: string;
+  /** Injectable `fetch` (tests / non-global runtimes). Defaults to `globalThis.fetch`. */
+  fetch?: OtelFetchLike;
+  /** Extra headers merged onto every POST — e.g. deployment/org correlation. `content-type` is set by default. */
+  headers?: Record<string, string>;
+  /** Called with any send failure so the caller can surface it; the export itself always swallows. */
+  onError?: (error: unknown) => void;
+  /** `service.name` resource attribute; defaults to the `LUNORA_SERVICE_NAME` env var then `"lunora-container"`. */
+  serviceName?: string;
+  /** Per-POST timeout in ms; a collector that never responds aborts after this so a stuck send can't stall `flush()`. Defaults to {@link DEFAULT_TIMEOUT_MS} (10s). */
+  timeoutMs?: number;
+  /** Bearer token sent as an `Authorization: Bearer` header; defaults to the `LUNORA_OTLP_TOKEN` env var. */
+  token?: string;
+}
+/** The exporter handle {@link createContainerTelemetry} returns. */
+interface ContainerTelemetry {
+  /** Record one log line (no-op when disabled). */
+  emitLog: (log: ContainerLogInput) => void;
+  /** Record one span (no-op when disabled). */
+  emitSpan: (span: ContainerSpanInput) => void;
+  /** True when an endpoint resolved and exports are actually sent. */
+  readonly enabled: boolean;
+  /** Await all in-flight sends — call before the process exits. */
+  flush: () => Promise<void>;
+  /** Time `run()`, recording a span named `name` (ok, or errored if it throws). Always runs `run()`, even when disabled. */
+  trace: <T>(name: string, run: () => Promise<T>, attributes?: Record<string, ContainerAttributeValue>) => Promise<T>;
+}
+/**
+* Create a zero-config OTLP exporter for the container process.
+*
+* ```ts
+* const telemetry = createContainerTelemetry(); // reads LUNORA_OTLP_ENDPOINT / _TOKEN
+* await telemetry.trace("transcode", () => transcode(job), { jobId: job.id });
+* telemetry.emitLog({ level: "info", message: "done", attributes: { jobId: job.id } });
+* await telemetry.flush(); // before the process exits
+* ```
+*
+* With no endpoint resolvable the returned exporter is disabled (`enabled ===
+* false`): `emitSpan`/`emitLog` no-op and `trace` still runs its work but records
+* nothing — so the same code runs unchanged locally and in the cloud.
+* @param options Exporter options; every field falls back to a `LUNORA_*` env var.
+*/
+declare const createContainerTelemetry: (options?: ContainerTelemetryOptions) => ContainerTelemetry;
+export { type ContainerAttributeValue, type ContainerLogInput, type ContainerSpanInput, type ContainerTelemetry, type ContainerTelemetryOptions, type OtelFetchLike, createContainerTelemetry };

package/dist/otel.d.ts

@@ -0,0 +1,95 @@
+/** An attribute value carried on a span or log. */
+type ContainerAttributeValue = boolean | number | string;
+/**
+* A `fetch` implementation — defaults to the runtime global. The exporter passes
+* an abort `signal` (for the per-request timeout) and, once the promise settles,
+* cancels the response `body` so Node/undici can release the socket for
+* keep-alive reuse instead of leaving it occupied by an unread stream. It reads
+* `ok`/`status` to detect a rejected export and nothing else from the response.
+*/
+type OtelFetchLike = (input: string, init: {
+  body: string;
+  headers: Record<string, string>;
+  method: string;
+  signal?: AbortSignal;
+}) => Promise<{
+  body?: {
+    cancel: () => Promise<void>;
+  } | null;
+  ok: boolean;
+  status: number;
+}>;
+/** A single span the container process asks the exporter to record. */
+interface ContainerSpanInput {
+  /** Attributes attached to the span (rendered under the OTLP `attributes` list). */
+  attributes?: Record<string, ContainerAttributeValue>;
+  /** Wall-clock millis when the operation ended. */
+  endMs: number;
+  /** When set, the span is marked errored with this message (and optional `error.type`). */
+  error?: {
+    message: string;
+    type?: string;
+  };
+  /** Span name — the operation being timed, e.g. `"transcode"`. */
+  name: string;
+  /** Wall-clock millis when the operation started. */
+  startMs: number;
+}
+/** A single log line the container process asks the exporter to record. */
+interface ContainerLogInput {
+  /** Attributes attached to the log record. */
+  attributes?: Record<string, ContainerAttributeValue>;
+  /** Severity — defaults to `"info"`. */
+  level?: "debug" | "error" | "info" | "warn";
+  /** The log message body. */
+  message: string;
+  /** Wall-clock millis the line was emitted; defaults to now. */
+  ts?: number;
+}
+/** Options for {@link createContainerTelemetry}. */
+interface ContainerTelemetryOptions {
+  /** Base OTLP collector endpoint; defaults to the `LUNORA_OTLP_ENDPOINT` env var. */
+  endpoint?: string;
+  /** Injectable `fetch` (tests / non-global runtimes). Defaults to `globalThis.fetch`. */
+  fetch?: OtelFetchLike;
+  /** Extra headers merged onto every POST — e.g. deployment/org correlation. `content-type` is set by default. */
+  headers?: Record<string, string>;
+  /** Called with any send failure so the caller can surface it; the export itself always swallows. */
+  onError?: (error: unknown) => void;
+  /** `service.name` resource attribute; defaults to the `LUNORA_SERVICE_NAME` env var then `"lunora-container"`. */
+  serviceName?: string;
+  /** Per-POST timeout in ms; a collector that never responds aborts after this so a stuck send can't stall `flush()`. Defaults to {@link DEFAULT_TIMEOUT_MS} (10s). */
+  timeoutMs?: number;
+  /** Bearer token sent as an `Authorization: Bearer` header; defaults to the `LUNORA_OTLP_TOKEN` env var. */
+  token?: string;
+}
+/** The exporter handle {@link createContainerTelemetry} returns. */
+interface ContainerTelemetry {
+  /** Record one log line (no-op when disabled). */
+  emitLog: (log: ContainerLogInput) => void;
+  /** Record one span (no-op when disabled). */
+  emitSpan: (span: ContainerSpanInput) => void;
+  /** True when an endpoint resolved and exports are actually sent. */
+  readonly enabled: boolean;
+  /** Await all in-flight sends — call before the process exits. */
+  flush: () => Promise<void>;
+  /** Time `run()`, recording a span named `name` (ok, or errored if it throws). Always runs `run()`, even when disabled. */
+  trace: <T>(name: string, run: () => Promise<T>, attributes?: Record<string, ContainerAttributeValue>) => Promise<T>;
+}
+/**
+* Create a zero-config OTLP exporter for the container process.
+*
+* ```ts
+* const telemetry = createContainerTelemetry(); // reads LUNORA_OTLP_ENDPOINT / _TOKEN
+* await telemetry.trace("transcode", () => transcode(job), { jobId: job.id });
+* telemetry.emitLog({ level: "info", message: "done", attributes: { jobId: job.id } });
+* await telemetry.flush(); // before the process exits
+* ```
+*
+* With no endpoint resolvable the returned exporter is disabled (`enabled ===
+* false`): `emitSpan`/`emitLog` no-op and `trace` still runs its work but records
+* nothing — so the same code runs unchanged locally and in the cloud.
+* @param options Exporter options; every field falls back to a `LUNORA_*` env var.
+*/
+declare const createContainerTelemetry: (options?: ContainerTelemetryOptions) => ContainerTelemetry;
+export { type ContainerAttributeValue, type ContainerLogInput, type ContainerSpanInput, type ContainerTelemetry, type ContainerTelemetryOptions, type OtelFetchLike, createContainerTelemetry };

package/dist/otel.mjs

@@ -0,0 +1,203 @@
+const OTLP_SEVERITY = {
+  debug: 5,
+  // DEBUG
+  error: 17,
+  // ERROR
+  info: 9,
+  // INFO
+  log: 9,
+  // INFO
+  warn: 13
+  // WARN
+};
+const otlpUnixNano = (ms) => `${String(Math.round(ms))}000000`;
+const otlpRandomHex = (bytes) => {
+  const buffer = new Uint8Array(bytes);
+  crypto.getRandomValues(buffer);
+  let hex = "";
+  for (const byte of buffer) {
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  return hex;
+};
+const encodeAttribute = (key, value) => {
+  if (typeof value === "boolean") {
+    return { key, value: { boolValue: value } };
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      return { key, value: { stringValue: String(value) } };
+    }
+    return Number.isSafeInteger(value) ? { key, value: { intValue: String(value) } } : { key, value: { doubleValue: value } };
+  }
+  return { key, value: { stringValue: value } };
+};
+const encodeAttributes = (attributes) => {
+  if (attributes === void 0) {
+    return [];
+  }
+  return Object.entries(attributes).map(([key, value]) => encodeAttribute(key, value));
+};
+const mergeHeaders = (defaults, overrides, token) => {
+  const merged = {};
+  const seen = /* @__PURE__ */ new Map();
+  const put = (name, value) => {
+    const lower = name.toLowerCase();
+    const existing = seen.get(lower);
+    if (existing === void 0) {
+      seen.set(lower, name);
+      merged[name] = value;
+    } else {
+      merged[existing] = value;
+    }
+  };
+  for (const [name, value] of Object.entries(defaults)) {
+    put(name, value);
+  }
+  for (const [name, value] of Object.entries(overrides ?? {})) {
+    put(name, value);
+  }
+  if (token !== void 0 && token.length > 0) {
+    put("authorization", `Bearer ${token}`);
+  }
+  return merged;
+};
+const wrapResourceSpans = (span, scopeName, serviceName) => {
+  return {
+    resourceSpans: [
+      {
+        resource: { attributes: [encodeAttribute("service.name", serviceName)] },
+        scopeSpans: [{ scope: { name: scopeName }, spans: [span] }]
+      }
+    ]
+  };
+};
+const wrapResourceLogs = (logRecord, scopeName, serviceName) => {
+  return {
+    resourceLogs: [
+      {
+        resource: { attributes: [encodeAttribute("service.name", serviceName)] },
+        scopeLogs: [{ logRecords: [logRecord], scope: { name: scopeName } }]
+      }
+    ]
+  };
+};
+
+const DEFAULT_TIMEOUT_MS = 1e4;
+const readEnv = (name) => {
+  return process.env[name];
+};
+const resolveFetch = (injected) => {
+  if (injected !== void 0) {
+    return injected;
+  }
+  if (typeof globalThis.fetch === "function") {
+    return globalThis.fetch;
+  }
+  return void 0;
+};
+const traceBody = (span, serviceName) => {
+  const attributes = encodeAttributes(span.attributes);
+  if (span.error?.type !== void 0) {
+    attributes.push(encodeAttribute("error.type", span.error.type));
+  }
+  const otlpSpan = {
+    attributes,
+    endTimeUnixNano: otlpUnixNano(span.endMs),
+    // SPAN_KIND_INTERNAL — the container's own work, not a server/client edge.
+    kind: 1,
+    name: span.name,
+    spanId: otlpRandomHex(8),
+    startTimeUnixNano: otlpUnixNano(span.startMs),
+    // STATUS_CODE_OK (1) / STATUS_CODE_ERROR (2).
+    status: span.error === void 0 ? { code: 1 } : { code: 2, message: span.error.message },
+    traceId: otlpRandomHex(16)
+  };
+  return wrapResourceSpans(otlpSpan, "@lunora/container", serviceName);
+};
+const logBody = (log, serviceName, nowMs) => {
+  const level = log.level ?? "info";
+  const record = {
+    attributes: encodeAttributes(log.attributes),
+    body: { stringValue: log.message },
+    severityNumber: OTLP_SEVERITY[level],
+    severityText: level.toUpperCase(),
+    timeUnixNano: otlpUnixNano(log.ts ?? nowMs)
+  };
+  return wrapResourceLogs(record, "@lunora/container", serviceName);
+};
+const createContainerTelemetry = (options = {}) => {
+  const endpoint = options.endpoint ?? readEnv("LUNORA_OTLP_ENDPOINT");
+  const enabled = endpoint !== void 0 && endpoint.length > 0;
+  const token = options.token ?? readEnv("LUNORA_OTLP_TOKEN");
+  const serviceName = options.serviceName ?? readEnv("LUNORA_SERVICE_NAME") ?? "lunora-container";
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const fetchImpl = resolveFetch(options.fetch);
+  const headers = mergeHeaders({ "content-type": "application/json" }, options.headers, token);
+  let base = endpoint ?? "";
+  while (base.endsWith("/")) {
+    base = base.slice(0, -1);
+  }
+  const tracesUrl = `${base}/v1/traces`;
+  const logsUrl = `${base}/v1/logs`;
+  const inflight = /* @__PURE__ */ new Set();
+  const send = (url, body) => {
+    if (fetchImpl === void 0) {
+      options.onError?.(new TypeError("createContainerTelemetry: no `fetch` available — pass `fetch` in options for this runtime."));
+      return;
+    }
+    const dispatch = async () => {
+      try {
+        const response = await fetchImpl(url, { body: JSON.stringify(body), headers, method: "POST", signal: AbortSignal.timeout(timeoutMs) });
+        if (!response.ok) {
+          options.onError?.(new Error(`createContainerTelemetry: OTLP export to ${url} failed with status ${String(response.status)}.`));
+        }
+        try {
+          await response.body?.cancel();
+        } catch {
+        }
+      } catch (error) {
+        options.onError?.(error);
+      }
+    };
+    const settled = dispatch().finally(() => {
+      inflight.delete(settled);
+    });
+    inflight.add(settled);
+  };
+  const emitSpan = (span) => {
+    if (!enabled) {
+      return;
+    }
+    send(tracesUrl, traceBody(span, serviceName));
+  };
+  const emitLog = (log) => {
+    if (!enabled) {
+      return;
+    }
+    send(logsUrl, logBody(log, serviceName, Date.now()));
+  };
+  const trace = async (name, run, attributes) => {
+    const startMs = Date.now();
+    try {
+      const result = await run();
+      emitSpan({ attributes, endMs: Date.now(), name, startMs });
+      return result;
+    } catch (error) {
+      emitSpan({
+        attributes,
+        endMs: Date.now(),
+        error: { message: error instanceof Error ? error.message : String(error), type: error instanceof Error ? error.name : void 0 },
+        name,
+        startMs
+      });
+      throw error;
+    }
+  };
+  const flush = async () => {
+    await Promise.allSettled(inflight);
+  };
+  return { emitLog, emitSpan, enabled, flush, trace };
+};
+
+export { createContainerTelemetry };