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

package/dist/index.d.mts

@@ -209,12 +209,15 @@ interface ContainerBindingSpec {
 }
 /**
 * Build the `ctx.containers` record from the Worker `env`. Called by the
-* generated ShardDO with the specs codegen derived from
-* `lunora/containers.ts`. A missing binding doesn't throw here — only when the
-* handle is actually used — so one unprovisioned container never breaks
-* unrelated functions.
+* generated ShardDO with the specs codegen derived from `lunora/containers.ts`.
+* A missing binding doesn't throw here — only when the handle is actually used —
+* so one unprovisioned container never breaks unrelated functions.
+*
+* `traceparent` (the inbound RPC's W3C trace context, forwarded by the runtime
+* and read off the request by the DO) is stamped onto every outbound container
+* `fetch`, so the container's own spans stitch under the Worker's trace.
 */
-declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>, jurisdiction?: DurableObjectJurisdiction) => Record<string, ContainerAccessor>;
+declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>, jurisdiction?: DurableObjectJurisdiction, traceparent?: string) => Record<string, ContainerAccessor>;
 /** A test handler: receives the request plus the targeted instance name. */
 type ContainerTestHandler = (request: Request, instance: {
   name: string;

package/dist/index.d.ts

@@ -209,12 +209,15 @@ interface ContainerBindingSpec {
 }
 /**
 * Build the `ctx.containers` record from the Worker `env`. Called by the
-* generated ShardDO with the specs codegen derived from
-* `lunora/containers.ts`. A missing binding doesn't throw here — only when the
-* handle is actually used — so one unprovisioned container never breaks
-* unrelated functions.
+* generated ShardDO with the specs codegen derived from `lunora/containers.ts`.
+* A missing binding doesn't throw here — only when the handle is actually used —
+* so one unprovisioned container never breaks unrelated functions.
+*
+* `traceparent` (the inbound RPC's W3C trace context, forwarded by the runtime
+* and read off the request by the DO) is stamped onto every outbound container
+* `fetch`, so the container's own spans stitch under the Worker's trace.
 */
-declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>, jurisdiction?: DurableObjectJurisdiction) => Record<string, ContainerAccessor>;
+declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>, jurisdiction?: DurableObjectJurisdiction, traceparent?: string) => Record<string, ContainerAccessor>;
 /** A test handler: receives the request plus the targeted instance name. */
 type ContainerTestHandler = (request: Request, instance: {
   name: string;

package/dist/index.mjs

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

package/dist/otel.d.mts

@@ -62,6 +62,29 @@ interface ContainerTelemetryOptions {
   timeoutMs?: number;
   /** Bearer token sent as an `Authorization: Bearer` header; defaults to the `LUNORA_OTLP_TOKEN` env var. */
   token?: string;
+  /**
+  * W3C `traceparent` of the Worker RPC that invoked this container; defaults to
+  * the `LUNORA_TRACEPARENT` env var. When present (and well-formed) every span
+  * inherits its trace id and hangs off its span id, so container spans stitch
+  * under the Worker's trace instead of forming a fresh, disconnected trace.
+  *
+  * `@lunora/container` stamps this trace context as the **`traceparent` request
+  * header** on every proxied fetch (`ctx.containers.<name>.…`), so a container
+  * that serves many requests should read it per request and create a telemetry
+  * instance scoped to that request — the trace context differs each call, so a
+  * single process-lifetime instance can't carry it:
+  *
+  * ```ts
+  * // inside the container's request handler
+  * const telemetry = createContainerTelemetry({ traceparent: request.headers.get("traceparent") ?? undefined });
+  * await telemetry.trace("transcode", () => transcode(job));
+  * await telemetry.flush();
+  * ```
+  *
+  * The `LUNORA_TRACEPARENT` env fallback fits a one-shot container that
+  * processes a single job per start (the value is fixed for the process).
+  */
+  traceparent?: string;
 }
 /** The exporter handle {@link createContainerTelemetry} returns. */
 interface ContainerTelemetry {

package/dist/otel.d.ts

@@ -62,6 +62,29 @@ interface ContainerTelemetryOptions {
   timeoutMs?: number;
   /** Bearer token sent as an `Authorization: Bearer` header; defaults to the `LUNORA_OTLP_TOKEN` env var. */
   token?: string;
+  /**
+  * W3C `traceparent` of the Worker RPC that invoked this container; defaults to
+  * the `LUNORA_TRACEPARENT` env var. When present (and well-formed) every span
+  * inherits its trace id and hangs off its span id, so container spans stitch
+  * under the Worker's trace instead of forming a fresh, disconnected trace.
+  *
+  * `@lunora/container` stamps this trace context as the **`traceparent` request
+  * header** on every proxied fetch (`ctx.containers.<name>.…`), so a container
+  * that serves many requests should read it per request and create a telemetry
+  * instance scoped to that request — the trace context differs each call, so a
+  * single process-lifetime instance can't carry it:
+  *
+  * ```ts
+  * // inside the container's request handler
+  * const telemetry = createContainerTelemetry({ traceparent: request.headers.get("traceparent") ?? undefined });
+  * await telemetry.trace("transcode", () => transcode(job));
+  * await telemetry.flush();
+  * ```
+  *
+  * The `LUNORA_TRACEPARENT` env fallback fits a one-shot container that
+  * processes a single job per start (the value is fixed for the process).
+  */
+  traceparent?: string;
 }
 /** The exporter handle {@link createContainerTelemetry} returns. */
 interface ContainerTelemetry {

package/dist/otel.mjs

@@ -20,6 +20,19 @@ const otlpRandomHex = (bytes) => {
   }
   return hex;
 };
+const HEX_ONLY = /^[0-9a-f]+$/;
+const parseTraceparent = (header) => {
+  if (header === null || header === void 0) {
+    return void 0;
+  }
+  const parts = header.trim().toLowerCase().split("-");
+  const [version, traceId, parentSpanId, flags] = parts;
+  if (parts.length < 4 || version === void 0 || version.length !== 2 || !HEX_ONLY.test(version) || version === "ff" || // Version 00 forbids trailing fields; only a future version may carry them.
+  version === "00" && parts.length !== 4 || traceId === void 0 || parentSpanId === void 0 || flags === void 0 || flags.length !== 2 || !HEX_ONLY.test(flags) || traceId.length !== 32 || parentSpanId.length !== 16 || !HEX_ONLY.test(traceId) || !HEX_ONLY.test(parentSpanId) || traceId === "00000000000000000000000000000000" || parentSpanId === "0000000000000000") {
+    return void 0;
+  }
+  return { parentSpanId, traceId };
+};
 const encodeAttribute = (key, value) => {
   if (typeof value === "boolean") {
     return { key, value: { boolValue: value } };
@@ -96,7 +109,7 @@ const resolveFetch = (injected) => {
   }
   return void 0;
 };
-const traceBody = (span, serviceName) => {
+const traceBody = (span, serviceName, parent) => {
   const attributes = encodeAttributes(span.attributes);
   if (span.error?.type !== void 0) {
     attributes.push(encodeAttribute("error.type", span.error.type));
@@ -107,11 +120,14 @@ const traceBody = (span, serviceName) => {
     // SPAN_KIND_INTERNAL — the container's own work, not a server/client edge.
     kind: 1,
     name: span.name,
+    // Always the span's own (child) id; with a parent, hang it off the parent
+    // span and inherit the parent's trace id so the spans stitch into one trace.
+    ...parent === void 0 ? {} : { parentSpanId: parent.parentSpanId },
     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)
+    traceId: parent?.traceId ?? otlpRandomHex(16)
   };
   return wrapResourceSpans(otlpSpan, "@lunora/container", serviceName);
 };
@@ -131,6 +147,7 @@ const createContainerTelemetry = (options = {}) => {
   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 parent = parseTraceparent(options.traceparent ?? readEnv("LUNORA_TRACEPARENT"));
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const fetchImpl = resolveFetch(options.fetch);
   const headers = mergeHeaders({ "content-type": "application/json" }, options.headers, token);
@@ -169,7 +186,7 @@ const createContainerTelemetry = (options = {}) => {
     if (!enabled) {
       return;
     }
-    send(tracesUrl, traceBody(span, serviceName));
+    send(tracesUrl, traceBody(span, serviceName, parent));
   };
   const emitLog = (log) => {
     if (!enabled) {

package/dist/packem_shared/{createContainerContext-CIVzsY5m.mjs → createContainerContext-Cg53QGdf.mjs}

@@ -7,11 +7,14 @@ const DEFAULT_MAX_BACKOFF_MS = 3e4;
 const DEFAULT_COLD_START_ATTEMPTS = 3;
 const DEFAULT_COLD_START_BACKOFF_MS = 500;
 const TARGET_PORT_HEADER = "cf-container-target-port";
-const toRequest = (input, init, port) => {
+const toRequest = (input, init, port, traceparent) => {
   const request = typeof input === "string" && input.startsWith("/") ? new Request(`http://container${input}`, init) : new Request(input, init);
   if (port !== void 0) {
     request.headers.set(TARGET_PORT_HEADER, String(port));
   }
+  if (traceparent !== void 0) {
+    request.headers.set("traceparent", traceparent);
+  }
   return request;
 };
 const sleep = async (ms) => {
@@ -62,7 +65,7 @@ const isColdStartTransient = async (response) => {
     return false;
   }
 };
-const coldStartRetryingHandle = (send, options = {}, port) => {
+const coldStartRetryingHandle = (send, options = {}, port, traceparent) => {
   const attempts = Math.max(1, options.attempts ?? DEFAULT_COLD_START_ATTEMPTS);
   const baseBackoff = options.backoffMs ?? DEFAULT_COLD_START_BACKOFF_MS;
   const maxBackoff = options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
@@ -76,7 +79,7 @@ const coldStartRetryingHandle = (send, options = {}, port) => {
           await sleep(Math.min(baseBackoff * 2 ** (attempt - 1), maxBackoff));
         }
         try {
-          const response = await send(toRequest(input, init, port));
+          const response = await send(toRequest(input, init, port, traceparent));
           if (isLastAttempt || !await isColdStartTransient(response)) {
             return response;
           }
@@ -89,10 +92,10 @@ const coldStartRetryingHandle = (send, options = {}, port) => {
       }
       throw lastError instanceof Error ? lastError : new Error("ctx.containers: cold-start retry exhausted");
     },
-    port: (targetPort) => coldStartRetryingHandle(send, options, targetPort)
+    port: (targetPort) => coldStartRetryingHandle(send, options, targetPort, traceparent)
   };
 };
-const handleFor = (namespace, instanceName, options) => coldStartRetryingHandle(async (request) => namespace.get(namespace.idFromName(instanceName)).fetch(request), options);
+const handleFor = (namespace, instanceName, options, traceparent) => coldStartRetryingHandle(async (request) => namespace.get(namespace.idFromName(instanceName)).fetch(request), options, void 0, traceparent);
 const lifecycleCall = async (stub, method, binding, argument) => {
   const rpc = stub[method];
   if (typeof rpc !== "function") {
@@ -110,10 +113,10 @@ const egressControlsFor = (stub, binding) => {
     setDenied: async (hosts) => lifecycleCall(stub(), "setDeniedHosts", binding, [...hosts])
   };
 };
-const instanceHandleFor = (namespace, spec, instanceName, options) => {
+const instanceHandleFor = (namespace, spec, instanceName, options, traceparent) => {
   const stub = () => namespace.get(namespace.idFromName(instanceName));
   return {
-    ...coldStartRetryingHandle(async (request) => stub().fetch(request), options),
+    ...coldStartRetryingHandle(async (request) => stub().fetch(request), options, void 0, traceparent),
     destroy: async () => lifecycleCall(stub(), "destroy", spec.binding),
     egress: egressControlsFor(stub, spec.binding),
     getState: async () => lifecycleCall(stub(), "getState", spec.binding),
@@ -127,7 +130,7 @@ const randomPoolName = (size) => (
   `pool-${String(Math.floor(Math.random() * size))}`
 );
 const retryOnServerError = (response) => response.status >= 500;
-const poolHandleFor = (namespace, spec, options = {}, port) => {
+const poolHandleFor = (namespace, spec, options = {}, port, traceparent) => {
   const size = options.size ?? spec.maxInstances ?? DEFAULT_POOL_SIZE;
   const attempts = Math.max(1, options.attempts ?? 3);
   const baseBackoff = options.backoffMs ?? 100;
@@ -141,7 +144,7 @@ const poolHandleFor = (namespace, spec, options = {}, port) => {
         if (attempt > 0) {
           await sleep(Math.min(baseBackoff * 2 ** (attempt - 1), maxBackoff));
         }
-        const request = toRequest(input, init, port);
+        const request = toRequest(input, init, port, traceparent);
         try {
           const response = await namespace.get(namespace.idFromName(randomPoolName(size))).fetch(request);
           if (attempt === totalAttempts - 1 || !shouldRetry(response)) {
@@ -153,14 +156,14 @@ const poolHandleFor = (namespace, spec, options = {}, port) => {
       }
       throw lastError instanceof Error ? lastError : new Error(`ctx.containers.${spec.exportName}.pool(): all ${String(totalAttempts)} attempts failed`);
     },
-    port: (targetPort) => poolHandleFor(namespace, spec, options, targetPort)
+    port: (targetPort) => poolHandleFor(namespace, spec, options, targetPort, traceparent)
   };
 };
-const accessorFor = (namespace, spec) => {
+const accessorFor = (namespace, spec, traceparent) => {
   return {
-    any: (count, options) => handleFor(namespace, randomPoolName(count ?? spec.maxInstances ?? DEFAULT_POOL_SIZE), options),
-    get: (name, options) => instanceHandleFor(namespace, spec, name, options),
-    pool: (options) => poolHandleFor(namespace, spec, options)
+    any: (count, options) => handleFor(namespace, randomPoolName(count ?? spec.maxInstances ?? DEFAULT_POOL_SIZE), options, traceparent),
+    get: (name, options) => instanceHandleFor(namespace, spec, name, options, traceparent),
+    pool: (options) => poolHandleFor(namespace, spec, options, void 0, traceparent)
   };
 };
 const missingBindingAccessor = (spec) => {
@@ -172,11 +175,11 @@ const missingBindingAccessor = (spec) => {
   };
   return { any: fail, get: fail, pool: fail };
 };
-const createContainerContext = (env, specs, jurisdiction) => {
+const createContainerContext = (env, specs, jurisdiction, traceparent) => {
   const containers = {};
   for (const spec of specs) {
     const binding = env[spec.binding];
-    containers[spec.exportName] = binding && typeof binding.idFromName === "function" && typeof binding.get === "function" ? accessorFor(applyJurisdiction(binding, jurisdiction), spec) : missingBindingAccessor(spec);
+    containers[spec.exportName] = binding && typeof binding.idFromName === "function" && typeof binding.get === "function" ? accessorFor(applyJurisdiction(binding, jurisdiction), spec, traceparent) : missingBindingAccessor(spec);
   }
   return containers;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/container",
-  "version": "1.0.0-alpha.10",
+  "version": "1.0.0-alpha.11",
   "description": "Cloudflare Containers for Lunora: defineContainer, generated Container DO classes, and the ctx.containers action surface",
   "keywords": [
     "cloudflare",