|
| 1 | +/** |
| 2 | + * A workerd-safe `diagnostics_channel` façade for the orchestrion EMIT side, and the |
| 3 | + * `dcModule` target for the Cloudflare orchestrion build (see `vite/index.ts`): orchestrion's |
| 4 | + * transformed code imports `tracingChannel` from here (its default export) instead of |
| 5 | + * `node:diagnostics_channel`. |
| 6 | + * |
| 7 | + * On workerd, `channel.publish()` and `channel.runStores()` throw at module/global scope |
| 8 | + * ("Disallowed operation called within global scope …"); only inside a request handler do they |
| 9 | + * work. `subscribe` and channel creation are fine anywhere. Orchestrion's transformed code emits |
| 10 | + * `start.runStores(...)` / `end.publish(...)` at each wrapped call site, so a library |
| 11 | + * instantiated at module scope (`const app = new Hono()`) throws the moment it is wrapped — or, |
| 12 | + * if no subscriber exists yet, is skipped by the wrapper's `if (!hasSubscribers) return |
| 13 | + * __apm$traced()` short-circuit and never instrumented. |
| 14 | + * |
| 15 | + * This façade delegates to the real `node:diagnostics_channel` singletons — so subscribers, which |
| 16 | + * keep subscribing through `node:diagnostics_channel`, are reached unchanged — and changes two |
| 17 | + * things: |
| 18 | + * |
| 19 | + * 1. `hasSubscribers` always reports `true`, so the wrapper never short-circuits. On Cloudflare a |
| 20 | + * channel is only injected for an integration that is actually bundled, so the short-circuit |
| 21 | + * buys nothing — and disabling it is what lets the wrapper run (and reach us) at module scope, |
| 22 | + * before the per-request cached `init()` has subscribed. |
| 23 | + * 2. When a delegated `publish`/`runStores` throws the global-scope error, the event is queued via |
| 24 | + * {@link deferChannelEvent} instead. {@link flushDeferredChannelEvents}, called at the top of |
| 25 | + * the request handler after `init()`, emits it via the real channel — now inside a request, |
| 26 | + * where publish works. |
| 27 | + * |
| 28 | + * In a request handler nothing throws, so every call is a transparent pass-through to the real |
| 29 | + * channel: lifecycle channels (spans, context binding) behave exactly as on Node. |
| 30 | + */ |
| 31 | +import * as realDc from 'node:diagnostics_channel'; |
| 32 | +import { deferChannelEvent, isGlobalScopeError } from './orchestrion-deferred-channels'; |
| 33 | + |
| 34 | +type Ctx = Record<string, unknown>; |
| 35 | + |
| 36 | +// One façade per channel name (node's `tracingChannel` is itself a per-name singleton), built |
| 37 | +// once when the transformed module declares `const CH = tracingChannel(name)`. |
| 38 | +const cache = new Map<string, realDc.TracingChannel>(); |
| 39 | + |
| 40 | +// `Channel.hasSubscribers` is a getter on Node but a method on workerd — normalize both to a |
| 41 | +// boolean. (This shape difference is also why the emit wrapper never short-circuits on workerd: |
| 42 | +// its `if (!ch.start.hasSubscribers)` guard reads a truthy method reference.) |
| 43 | +function channelHasSubscribers(ch: realDc.Channel): boolean { |
| 44 | + const value = (ch as { hasSubscribers: unknown }).hasSubscribers; |
| 45 | + return typeof value === 'function' ? Boolean((value as () => unknown).call(ch)) : Boolean(value); |
| 46 | +} |
| 47 | + |
| 48 | +function wrapSubChannel(tracing: realDc.TracingChannel, real: realDc.Channel): realDc.Channel { |
| 49 | + return { |
| 50 | + name: real.name, |
| 51 | + // A method (not a getter) so it reads truthy as a property in the emit guard *and* is callable, |
| 52 | + // matching workerd's native shape. Forced `true`: on Cloudflare a channel is only injected for a |
| 53 | + // bundled integration, so the wrapper's no-subscriber short-circuit buys nothing — and disabling |
| 54 | + // it is what lets the wrapper run (and reach us) at module scope before `init()` has subscribed. |
| 55 | + hasSubscribers(): boolean { |
| 56 | + return true; |
| 57 | + }, |
| 58 | + publish(ctx: Ctx): void { |
| 59 | + // Decide deferral by whether anyone is subscribed *now*, not by whether publish throws: |
| 60 | + // - With subscribers, workerd delivers to them before throwing the global-scope error (or, |
| 61 | + // in a request, doesn't throw at all) — so they get it exactly once; don't defer. |
| 62 | + // - With none — the common per-request cached-init case — nobody received it, so defer for a |
| 63 | + // subscriber that registers later (at `init()`), which then gets it exactly once. |
| 64 | + const hadSubscribers = channelHasSubscribers(real); |
| 65 | + try { |
| 66 | + real.publish(ctx); |
| 67 | + } catch (error) { |
| 68 | + if (!isGlobalScopeError(error)) { |
| 69 | + throw error; |
| 70 | + } |
| 71 | + } |
| 72 | + if (!hadSubscribers) { |
| 73 | + deferChannelEvent(tracing, ctx); |
| 74 | + } |
| 75 | + }, |
| 76 | + runStores(ctx: Ctx, fn: (...args: unknown[]) => unknown, ...rest: unknown[]): unknown { |
| 77 | + try { |
| 78 | + return real.runStores(ctx, fn, ...rest); |
| 79 | + } catch (error) { |
| 80 | + if (!isGlobalScopeError(error)) { |
| 81 | + throw error; |
| 82 | + } |
| 83 | + // publish() is gated too, so the store can't be established — just run the wrapped call |
| 84 | + // so its return value (e.g. the constructed instance) is produced now. Its own |
| 85 | + // `end.publish` runs back through this façade and is deferred. |
| 86 | + return fn(); |
| 87 | + } |
| 88 | + }, |
| 89 | + subscribe: real.subscribe.bind(real), |
| 90 | + unsubscribe: real.unsubscribe.bind(real), |
| 91 | + bindStore: real.bindStore.bind(real), |
| 92 | + unbindStore: real.unbindStore.bind(real), |
| 93 | + } as unknown as realDc.Channel; |
| 94 | +} |
| 95 | + |
| 96 | +export function tracingChannel<T = Ctx>(name: string): realDc.TracingChannel<T> { |
| 97 | + const cached = cache.get(name); |
| 98 | + if (cached) { |
| 99 | + return cached; |
| 100 | + } |
| 101 | + |
| 102 | + const real = realDc.tracingChannel(name); |
| 103 | + const facade = { |
| 104 | + start: wrapSubChannel(real, real.start), |
| 105 | + end: wrapSubChannel(real, real.end), |
| 106 | + asyncStart: wrapSubChannel(real, real.asyncStart), |
| 107 | + asyncEnd: wrapSubChannel(real, real.asyncEnd), |
| 108 | + error: wrapSubChannel(real, real.error), |
| 109 | + // Iterator (`:next`) channels call these on the tracingChannel itself; delegate to the real |
| 110 | + // implementation (they only run in-request, where publish/runStores are allowed). |
| 111 | + traceSync: real.traceSync.bind(real), |
| 112 | + tracePromise: real.tracePromise.bind(real), |
| 113 | + traceCallback: real.traceCallback.bind(real), |
| 114 | + subscribe: real.subscribe.bind(real), |
| 115 | + unsubscribe: real.unsubscribe.bind(real), |
| 116 | + } as unknown as realDc.TracingChannel<T>; |
| 117 | + |
| 118 | + cache.set(name, facade); |
| 119 | + return facade; |
| 120 | +} |
| 121 | + |
| 122 | +export const channel = realDc.channel; |
| 123 | +export const subscribe = realDc.subscribe; |
| 124 | +export const unsubscribe = realDc.unsubscribe; |
| 125 | + |
| 126 | +// Orchestrion's emit imports the default and destructures `tracingChannel`. |
| 127 | +export default { tracingChannel, channel, subscribe, unsubscribe }; |
0 commit comments