@heystack/otel 0.14.0 → 0.16.0

package/dist/workers-bindings.js

@@ -1,15 +1,15 @@
 // ---------------------------------------------------------------------------
 // Cloudflare binding instrumentation for @heystack/otel/workers.
 //
-// Wraps D1, KV, R2, Vectorize, Workers AI, Queue producers, and Service
-// bindings with OTel child spans so that every binding operation is visible
-// as a child of the active request span.
+// Wraps supported Cloudflare data, AI, messaging, Durable Object, Workflow,
+// and Service binding operations with OTel child spans.
 //
-// WinterCG-safe: no `node:*` imports. Span factory is injected so the logic
+// WinterCG-safe: no Node-builtin imports. Span factory is injected so the logic
 // is pure and unit-testable without a global provider.
 // ---------------------------------------------------------------------------
 import { context, SpanKind, SpanStatusCode } from "@opentelemetry/api";
 import { isTracingSuppressed } from "@opentelemetry/core";
+import { makeTraceparent } from "./traceparent.js";
 // ---------------------------------------------------------------------------
 // Duck-type detectors — conservative; require the distinctive method set
 // exactly as documented in the task brief.
@@ -45,6 +45,17 @@ function isQueueLike(b) {
     return (typeof b?.send === "function" &&
         typeof b?.sendBatch === "function");
 }
+function isWorkflowLike(b) {
+    return (typeof b?.get === "function" &&
+        typeof b?.create === "function" &&
+        typeof b?.createBatch === "function");
+}
+function isRateLimitLike(b) {
+    return typeof b?.limit === "function";
+}
+function isAnalyticsEngineLike(b) {
+    return typeof b?.writeDataPoint === "function";
+}
 /** Service binding / Fetcher: last branch — anything with `.fetch`. Prior branches
  *  exclude D1/R2/KV/Vectorize/AI/Queue, so order alone is sufficient. */
 function isServiceLike(b) {
@@ -53,7 +64,12 @@ function isServiceLike(b) {
 // ---------------------------------------------------------------------------
 // Span lifecycle helper
 // ---------------------------------------------------------------------------
-async function runWithSpan(span, fn) {
+/**
+ * Run `fn`, ending `span` in `finally` and recording exceptions + ERROR status
+ * on failure (re-throwing). Internal helper shared with the class-level
+ * wrappers in workers.ts.
+ */
+export async function runWithSpan(span, fn) {
     try {
         return await fn();
     }
@@ -69,12 +85,100 @@ async function runWithSpan(span, fn) {
         span.end();
     }
 }
+function runSyncWithSpan(span, fn) {
+    try {
+        return fn();
+    }
+    catch (err) {
+        span.recordException(err instanceof Error ? err : new Error(String(err)));
+        span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+    finally {
+        span.end();
+    }
+}
+function isPromiseLike(value) {
+    return (((typeof value === "object" && value !== null) || typeof value === "function") &&
+        typeof value.then === "function");
+}
+function recordSpanError(span, error) {
+    span.recordException(error instanceof Error ? error : new Error(String(error)));
+    span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : String(error),
+    });
+}
+/** Trace a call without replacing synchronous, Promise, or custom thenable results. */
+function runWithSpanPreservingReturn(span, fn) {
+    try {
+        const result = fn();
+        if (isPromiseLike(result)) {
+            let settled = false;
+            const finish = (error, failed = false) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (failed) {
+                    try {
+                        recordSpanError(span, error);
+                    }
+                    catch {
+                        // Instrumentation must not alter the observed thenable's behaviour.
+                    }
+                }
+                try {
+                    span.end();
+                }
+                catch {
+                    // Instrumentation must not alter the observed thenable's behaviour.
+                }
+            };
+            try {
+                const observer = result.then(() => finish(), (error) => finish(error, true));
+                // A non-compliant custom thenable may reject the observer despite the
+                // rejection callback above. Consume that rejection without replacing
+                // or awaiting the original RPC/Promise object returned to the caller.
+                if (isPromiseLike(observer)) {
+                    try {
+                        observer.then(undefined, () => undefined);
+                    }
+                    catch {
+                        // Calling then() is best-effort for exotic host thenables.
+                    }
+                }
+            }
+            catch (error) {
+                finish(error, true);
+            }
+            return result;
+        }
+        span.end();
+        return result;
+    }
+    catch (error) {
+        recordSpanError(span, error);
+        span.end();
+        throw error;
+    }
+}
+/** Transform either a synchronous result or a promise without changing its category. */
+function mapReturn(result, map) {
+    return isPromiseLike(result) ? Promise.resolve(result).then(map) : map(result);
+}
 // ---------------------------------------------------------------------------
 // Proxy helper — intercepts listed handlers, falls through to prototype for rest
 // ---------------------------------------------------------------------------
-function makeProxy(target, handlers) {
+const rawTarget = Symbol("heystack.rawBindingTarget");
+/** Internal proxy builder shared with the class-level wrappers in workers.ts. */
+export function makeProxy(target, handlers) {
     return new Proxy(target, {
         get(t, prop, receiver) {
+            if (prop === rawTarget)
+                return t;
             if (typeof prop === "string" && prop in handlers)
                 return handlers[prop];
             const val = Reflect.get(t, prop, receiver);
@@ -82,6 +186,9 @@ function makeProxy(target, handlers) {
         },
     });
 }
+function unwrapTarget(value) {
+    return (value?.[rawTarget] ?? value);
+}
 // ---------------------------------------------------------------------------
 // D1 wrappers
 // ---------------------------------------------------------------------------
@@ -112,6 +219,47 @@ function wrapD1(binding, opts) {
         prepare(sql) {
             return wrapD1Statement(binding.prepare(sql), sql, opts);
         },
+        batch(statements) {
+            if (isTracingSuppressed(context.active())) {
+                return binding.batch(statements.map(unwrapTarget));
+            }
+            const span = opts.startSpan("D1 batch", {
+                "db.system": "d1",
+                "db.operation.name": "batch",
+                "db.operation.batch.size": statements.length,
+            });
+            return runWithSpan(span, () => binding.batch(statements.map(unwrapTarget)));
+        },
+        exec(query) {
+            if (isTracingSuppressed(context.active()))
+                return binding.exec(query);
+            const span = opts.startSpan("D1 exec", {
+                "db.system": "d1",
+                "db.operation.name": "exec",
+            });
+            return runWithSpan(span, () => binding.exec(query));
+        },
+        withSession(...args) {
+            return wrapD1Session(binding.withSession(...args), opts);
+        },
+    });
+}
+function wrapD1Session(session, opts) {
+    return makeProxy(session, {
+        prepare(sql) {
+            return wrapD1Statement(session.prepare(sql), sql, opts);
+        },
+        batch(statements) {
+            if (isTracingSuppressed(context.active())) {
+                return session.batch(statements.map(unwrapTarget));
+            }
+            const span = opts.startSpan("D1 session batch", {
+                "db.system": "d1",
+                "db.operation.name": "batch",
+                "db.operation.batch.size": statements.length,
+            });
+            return runWithSpan(span, () => session.batch(statements.map(unwrapTarget)));
+        },
     });
 }
 // ---------------------------------------------------------------------------
@@ -131,6 +279,7 @@ function wrapKV(binding, opts, namespace) {
     };
     return makeProxy(binding, {
         get: wrapOp("get", (key) => key),
+        getWithMetadata: wrapOp("getWithMetadata", (key) => key),
         put: wrapOp("put", (key) => key),
         list: wrapOp("list"),
         delete: wrapOp("delete", (key) => key),
@@ -151,11 +300,56 @@ function wrapR2(binding, opts, bucket) {
         const span = opts.startSpan(`R2 ${op}`, attrs);
         return runWithSpan(span, () => binding[op](...args));
     };
+    const wrapMultipart = (upload, key) => makeProxy(upload, {
+        uploadPart: async (partNumber, ...args) => {
+            if (isTracingSuppressed(context.active())) {
+                return upload.uploadPart(partNumber, ...args);
+            }
+            const span = opts.startSpan("R2 uploadPart", {
+                "r2.bucket": bucket,
+                "r2.key": key,
+                "r2.multipart.part_number": partNumber,
+            });
+            return runWithSpan(span, () => upload.uploadPart(partNumber, ...args));
+        },
+        abort: wrapMultipartOp("abort", upload, key),
+        complete: wrapMultipartOp("complete", upload, key, (parts) => ({
+            "r2.multipart.part_count": parts.length,
+        })),
+    });
+    function wrapMultipartOp(op, upload, key, extraAttrs) {
+        return async (...args) => {
+            if (isTracingSuppressed(context.active()))
+                return upload[op](...args);
+            const span = opts.startSpan(`R2 ${op}`, {
+                "r2.bucket": bucket,
+                "r2.key": key,
+                ...extraAttrs?.(...args),
+            });
+            return runWithSpan(span, () => upload[op](...args));
+        };
+    }
     return makeProxy(binding, {
         get: wrapOp("get", (key) => key),
         put: wrapOp("put", (key) => key),
         head: wrapOp("head", (key) => key),
         delete: wrapOp("delete", (key) => key),
+        list: wrapOp("list"),
+        async createMultipartUpload(key, ...args) {
+            if (isTracingSuppressed(context.active())) {
+                const upload = await binding.createMultipartUpload(key, ...args);
+                return wrapMultipart(upload, key);
+            }
+            const span = opts.startSpan("R2 createMultipartUpload", {
+                "r2.bucket": bucket,
+                "r2.key": key,
+            });
+            const upload = await runWithSpan(span, () => binding.createMultipartUpload(key, ...args));
+            return wrapMultipart(upload, key);
+        },
+        resumeMultipartUpload(key, uploadId) {
+            return wrapMultipart(binding.resumeMultipartUpload(key, uploadId), key);
+        },
     });
 }
 // ---------------------------------------------------------------------------
@@ -261,6 +455,66 @@ function wrapQueue(binding, opts, name) {
             const span = opts.startSpan("Queue sendBatch", batchAttrs, SpanKind.PRODUCER);
             return runWithSpan(span, () => binding.sendBatch(...args));
         },
+        metrics: async (...args) => {
+            if (isTracingSuppressed(context.active()))
+                return binding.metrics(...args);
+            const span = opts.startSpan("Queue metrics", {
+                ...baseAttrs,
+                "messaging.operation": "metrics",
+            });
+            return runWithSpan(span, () => binding.metrics(...args));
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Workflow, rate-limit, and Analytics Engine bindings
+// ---------------------------------------------------------------------------
+function wrapWorkflow(binding, opts, name) {
+    const wrapOp = (op, kind, getCount) => async (...args) => {
+        if (isTracingSuppressed(context.active()))
+            return binding[op](...args);
+        const attrs = {
+            "cloudflare.binding.type": "workflow",
+            "cloudflare.binding.name": name,
+            "cloudflare.workflow.operation": op,
+        };
+        const count = getCount?.(...args);
+        if (count !== undefined)
+            attrs["cloudflare.workflow.batch.size"] = count;
+        const span = opts.startSpan(`Workflow ${op}`, attrs, kind);
+        return runWithSpan(span, () => binding[op](...args));
+    };
+    return makeProxy(binding, {
+        get: wrapOp("get", SpanKind.CLIENT),
+        create: wrapOp("create", SpanKind.PRODUCER),
+        createBatch: wrapOp("createBatch", SpanKind.PRODUCER, (batch) => batch.length),
+        deleteBatch: wrapOp("deleteBatch", SpanKind.CLIENT, (ids) => ids.length),
+    });
+}
+function wrapRateLimit(binding, opts, name) {
+    return makeProxy(binding, {
+        limit: async (...args) => {
+            if (isTracingSuppressed(context.active()))
+                return binding.limit(...args);
+            const span = opts.startSpan("RateLimit limit", {
+                "cloudflare.binding.type": "rate_limit",
+                "cloudflare.binding.name": name,
+            });
+            return runWithSpan(span, () => binding.limit(...args));
+        },
+    });
+}
+function wrapAnalyticsEngine(binding, opts, name) {
+    return makeProxy(binding, {
+        writeDataPoint(...args) {
+            if (isTracingSuppressed(context.active()))
+                return binding.writeDataPoint(...args);
+            const span = opts.startSpan("AnalyticsEngine writeDataPoint", {
+                "cloudflare.binding.type": "analytics_engine",
+                "cloudflare.binding.name": name,
+            });
+            return runSyncWithSpan(span, () => binding.writeDataPoint(...args));
+        },
     });
 }
 // ---------------------------------------------------------------------------
@@ -276,6 +530,14 @@ function wrapQueue(binding, opts, name) {
 export function injectTraceparentArgs(args, traceparent) {
     const [input, ...rest] = args;
     if (input instanceof Request) {
+        const originalInit = rest[0];
+        if (originalInit?.headers !== undefined) {
+            const init = { ...originalInit };
+            const headers = new Headers(originalInit.headers);
+            headers.set("traceparent", traceparent);
+            init.headers = headers;
+            return [input, init, ...rest.slice(1)];
+        }
         const headers = new Headers(input.headers);
         headers.set("traceparent", traceparent);
         return [new Request(input, { headers }), ...rest];
@@ -295,13 +557,202 @@ function wrapService(binding, opts, name) {
             }
             const span = opts.startSpan(`Service ${name} fetch`, { "peer.service": name }, SpanKind.CLIENT);
             const sc = span.spanContext();
-            const traceparent = `00-${sc.traceId}-${sc.spanId}-01`;
+            const traceparent = makeTraceparent(sc);
             const injectedArgs = injectTraceparentArgs(args, traceparent);
             return runWithSpan(span, () => binding.fetch(...injectedArgs));
         },
     });
 }
 // ---------------------------------------------------------------------------
+// Durable Object namespace binding
+// ---------------------------------------------------------------------------
+/** DO namespace detector using the real synchronous Cloudflare API surface. */
+function isDurableObjectNamespaceLike(b) {
+    return (typeof b?.idFromName === "function" &&
+        typeof b?.get === "function" &&
+        typeof b?.newUniqueId === "function");
+}
+/** Fetcher/DO members that are platform operations or must retain host semantics. */
+const DO_STUB_RPC_EXCLUDED = new Set([
+    "fetch",
+    "connect",
+    "alarm",
+    "webSocketMessage",
+    "webSocketClose",
+    "webSocketError",
+    "id",
+    "name",
+    "dup",
+    "constructor",
+    "then",
+]);
+/** Wrap a DO stub: CLIENT spans on fetch (+ traceparent injection) and RPC calls. */
+function wrapDurableObjectStub(stub, opts, name) {
+    const fetch = (...args) => {
+        if (isTracingSuppressed(context.active()))
+            return stub.fetch(...args);
+        const span = opts.startSpan(`DO ${name} fetch`, { "peer.service": name }, SpanKind.CLIENT);
+        const sc = span.spanContext();
+        // Propagate into the DO so its own spans join this trace.
+        const injectedArgs = injectTraceparentArgs(args, makeTraceparent(sc));
+        return runWithSpanPreservingReturn(span, () => stub.fetch(...injectedArgs));
+    };
+    // workerd exposes RPC methods through a wildcard property hook, so method
+    // names are not enumerable. Resolve and wrap them lazily on first access.
+    const rpcMethods = new Map();
+    return new Proxy(stub, {
+        get(target, property) {
+            if (property === "fetch")
+                return fetch;
+            const value = Reflect.get(target, property, target);
+            if (typeof property !== "string" ||
+                typeof value !== "function" ||
+                DO_STUB_RPC_EXCLUDED.has(property) ||
+                property in Object.prototype) {
+                return typeof value === "function" ? value.bind(target) : value;
+            }
+            const cached = rpcMethods.get(property);
+            if (cached)
+                return cached;
+            // Capture the host callable returned for this property. Calling it with
+            // the original stub as receiver preserves both ordinary and workerd RPC
+            // method semantics; the wrapper itself remains stable across reads.
+            const method = value;
+            const wrapped = (...args) => {
+                if (isTracingSuppressed(context.active())) {
+                    return Reflect.apply(method, target, args);
+                }
+                const span = opts.startSpan(`DO ${name} ${property}`, { "peer.service": name, "rpc.method": property }, SpanKind.CLIENT);
+                return runWithSpanPreservingReturn(span, () => Reflect.apply(method, target, args));
+            };
+            rpcMethods.set(property, wrapped);
+            return wrapped;
+        },
+    });
+}
+function wrapDurableObjectNamespace(ns, opts, name) {
+    const handlers = {
+        // Namespace lookup is local and synchronous. Trace the returned stub's
+        // actual fetch/RPC calls, not get() itself.
+        get: (...args) => wrapDurableObjectStub(ns.get(...args), opts, name),
+    };
+    if (typeof ns.getByName === "function") {
+        handlers.getByName = (...args) => wrapDurableObjectStub(ns.getByName(...args), opts, name);
+    }
+    if (typeof ns.jurisdiction === "function") {
+        handlers.jurisdiction = (...args) => wrapDurableObjectNamespace(ns.jurisdiction(...args), opts, name);
+    }
+    // idFromName/idFromString/newUniqueId are synchronous local operations and
+    // fall through untouched.
+    return makeProxy(ns, handlers);
+}
+// ---------------------------------------------------------------------------
+// Workflows binding wrapper
+// ---------------------------------------------------------------------------
+/** Workflow binding: exposes create/createBatch/get and is not a DO namespace. */
+function isWorkflowBindingLike(b) {
+    return (typeof b?.create === "function" &&
+        typeof b?.createBatch === "function" &&
+        typeof b?.get === "function" &&
+        !isDurableObjectNamespaceLike(b));
+}
+const WORKFLOW_INSTANCE_METHODS = [
+    "pause",
+    "resume",
+    "terminate",
+    "restart",
+    "status",
+    "sendEvent",
+];
+function workflowId(value) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (value && typeof value === "object") {
+        const id = value.id;
+        if (typeof id === "string" && id.length > 0)
+            return id;
+    }
+    return undefined;
+}
+function workflowBatchIds(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map(workflowId).filter((id) => id !== undefined);
+}
+function wrapWorkflowInstance(instance, opts, name) {
+    if (!instance || typeof instance !== "object")
+        return instance;
+    const target = instance;
+    const handlers = {};
+    const instanceId = workflowId(instance);
+    for (const method of WORKFLOW_INSTANCE_METHODS) {
+        if (typeof target[method] !== "function")
+            continue;
+        handlers[method] = (...args) => {
+            const underlying = target[method];
+            if (isTracingSuppressed(context.active())) {
+                return underlying.apply(instance, args);
+            }
+            const attrs = {
+                "cloudflare.workflow.namespace": name,
+            };
+            if (instanceId !== undefined) {
+                attrs["cloudflare.workflow.instance_id"] = instanceId;
+            }
+            const span = opts.startSpan(`Workflow ${method}`, attrs, SpanKind.CLIENT);
+            return runWithSpanPreservingReturn(span, () => underlying.apply(instance, args));
+        };
+    }
+    return makeProxy(instance, handlers);
+}
+function wrapWorkflowBindingResult(value, op, opts, name, span) {
+    if (op === "deleteBatch")
+        return value;
+    if (op === "createBatch") {
+        if (!Array.isArray(value))
+            return value;
+        const returnedIds = workflowBatchIds(value);
+        if (span && returnedIds.length > 0) {
+            span.setAttribute("cloudflare.workflow.instance_ids", returnedIds);
+        }
+        return value.map((item) => wrapWorkflowInstance(item, opts, name));
+    }
+    const returnedId = workflowId(value);
+    if (span && returnedId !== undefined) {
+        span.setAttribute("cloudflare.workflow.instance_id", returnedId);
+    }
+    return wrapWorkflowInstance(value, opts, name);
+}
+function wrapWorkflowBinding(binding, opts, name) {
+    const baseAttrs = {
+        "cloudflare.workflow.namespace": name,
+        "cloudflare.binding.type": "workflow",
+        "cloudflare.binding.name": name,
+    };
+    const ops = ["create", "createBatch", "get", "deleteBatch"];
+    const handlers = {};
+    for (const op of ops) {
+        handlers[op] = (...args) => {
+            if (isTracingSuppressed(context.active())) {
+                return mapReturn(binding[op](...args), (value) => wrapWorkflowBindingResult(value, op, opts, name));
+            }
+            const attrs = { ...baseAttrs };
+            const instanceId = workflowId(args[0]);
+            const batchIds = op === "createBatch" || op === "deleteBatch" ? workflowBatchIds(args[0]) : [];
+            if (instanceId !== undefined) {
+                attrs["cloudflare.workflow.instance_id"] = instanceId;
+            }
+            if (batchIds.length > 0) {
+                attrs["cloudflare.workflow.instance_ids"] = batchIds;
+                attrs["cloudflare.workflow.batch.size"] = batchIds.length;
+            }
+            const span = opts.startSpan(`Workflow ${op}`, attrs, SpanKind.CLIENT);
+            return runWithSpanPreservingReturn(span, () => mapReturn(binding[op](...args), (value) => wrapWorkflowBindingResult(value, op, opts, name, span)));
+        };
+    }
+    return makeProxy(binding, handlers);
+}
+// ---------------------------------------------------------------------------
 // Main export
 // ---------------------------------------------------------------------------
 /**
@@ -315,6 +766,11 @@ function wrapService(binding, opts, name) {
  * - Vectorize: `query`+`upsert`
  * - Workers AI: `run` (without `prepare`)
  * - Queue producer: `send`+`sendBatch`
+ * - Workflow: `get`+`create`+`createBatch`
+ * - Rate limit: `limit`
+ * - Analytics Engine: `writeDataPoint`
+ * - Durable Object namespace: `idFromName`+`get`+`newUniqueId` (stub fetch/RPC spans)
+ * - Workflow binding: `create`+`createBatch`+`get` and not a DO namespace
  * - Service binding / Fetcher: `fetch` (last branch; most generic)
  *
  * Unrecognised bindings are passed through unchanged.
@@ -356,6 +812,21 @@ export function instrumentEnv(env, opts) {
         else if (isQueueLike(binding)) {
             result[key] = wrapQueue(binding, opts, key);
         }
+        else if (isDurableObjectNamespaceLike(binding)) {
+            result[key] = wrapDurableObjectNamespace(binding, opts, key);
+        }
+        else if (isWorkflowBindingLike(binding)) {
+            result[key] = wrapWorkflowBinding(binding, opts, key);
+        }
+        else if (isWorkflowLike(binding)) {
+            result[key] = wrapWorkflow(binding, opts, key);
+        }
+        else if (isRateLimitLike(binding)) {
+            result[key] = wrapRateLimit(binding, opts, key);
+        }
+        else if (isAnalyticsEngineLike(binding)) {
+            result[key] = wrapAnalyticsEngine(binding, opts, key);
+        }
         else if (isServiceLike(binding)) {
             result[key] = wrapService(binding, opts, key);
         }