dd-trace 5.114.0 → 5.116.0

package/packages/datadog-plugin-graphql/src/execute.js

@@ -5,7 +5,7 @@ const dc = require('dc-polyfill')
 const { storage } = require('../../datadog-core')
 const TracingPlugin = require('../../dd-trace/src/plugins/tracing')
 const GraphQLParsePlugin = require('./parse')
-const { extractErrorIntoSpanEvent, getOperation, getSignature } = require('./utils')
+const { extractErrorIntoSpanEvent, getOperation, getSignature, isApolloHealthCheck } = require('./utils')
 
 const legacyStorage = storage('legacy')
 
@@ -26,12 +26,24 @@ const contexts = new WeakMap()
 const instrumentedArgs = new WeakSet()
 
 const patchedResolvers = new WeakSet()
-const patchedTypes = new WeakSet()
+
+// Visited types per caller-owned schema. The walk reaches union members and
+// interface implementations through the schema (`getTypes`/`getPossibleTypes`),
+// so it differs per schema: a global guard would stop the second schema at any
+// type the first already walked and leave its own implementations unwrapped.
+// `patchedResolvers` keeps wrapping idempotent, so re-walking a shared type is
+// safe and this set only terminates cycles.
+const walkedTypes = new WeakMap()
 
 // Module-level fast path: skip the resolver-side WeakMap lookup entirely
 // when depth=0 disables resolver instrumentation.
 let depthDisabled = false
 
+// Initial key for the per-operation variables-filter cache. A unique sentinel
+// so the first #filterVariables call never falsely matches, even when the
+// operation's variableValues is undefined.
+const NO_VARIABLES_CACHED = Symbol('noVariablesCached')
+
 class AbortError extends Error {
   constructor (message) {
     super(message)
@@ -111,6 +123,16 @@ class GraphQLExecutePlugin extends TracingPlugin {
     const name = operation?.name?.value
     const source = this.config.source && docSource
 
+    // Apollo Server may execute a cached document without parsing it first.
+    // Match the full gateway operation here so caller-owned AST transformations
+    // cannot suppress execute/resolver AppSec and IAST channels.
+    if (name === '__ApolloServiceHealthCheck__' &&
+        document.definitions.length === 1 &&
+        isApolloHealthCheck(operation)) {
+      ctx.ddSkipped = true
+      return ctx.currentStore
+    }
+
     ctx.collapse = this.config.collapse
 
     const signature = getSignature(document, name, type, this.config.signature)
@@ -165,9 +187,9 @@ class GraphQLExecutePlugin extends TracingPlugin {
 
     const schema = args.schema
     if (schema) {
-      wrapFields(schema._queryType)
-      wrapFields(schema._mutationType)
-      wrapFields(schema._subscriptionType)
+      wrapFields(schema._queryType, schema)
+      wrapFields(schema._mutationType, schema)
+      wrapFields(schema._subscriptionType, schema)
     }
 
     const rootCtx = {
@@ -175,10 +197,13 @@ class GraphQLExecutePlugin extends TracingPlugin {
       config: this.config,
       fields: new Map(),
       pathCache: new Map(),
-      collapsedPathCache: this.config.collapse ? { byPath: new Map(), byParent: new Map() } : undefined,
       abortController,
       executeSpan: span,
       plugin: this,
+      // graphql.resolve variable tags: memoize the filtered result for the
+      // last-seen variableValues object (see #filterVariables).
+      filteredVariablesKey: NO_VARIABLES_CACHED,
+      filteredVariables: undefined,
     }
     ctx.ddRootCtx = rootCtx
     if (isWeakMapKey(contextValue)) {
@@ -202,9 +227,13 @@ class GraphQLExecutePlugin extends TracingPlugin {
     if (!span) return
 
     // Synchronous execute() throw (e.g. execute(null, doc)) — error handler
-    // already tagged the span, just finish it.
+    // already tagged the span.
     if (ctx.error) {
-      this.#drain(ctx, span)
+      if (ctx.ddAborted) {
+        span.finish()
+      } else {
+        this.#finishSpan(ctx, span)
+      }
       return ctx.parentStore
     }
 
@@ -213,10 +242,7 @@ class GraphQLExecutePlugin extends TracingPlugin {
     if (typeof result?.then === 'function') {
       result.then(
         (res) => this.#finishSpan(ctx, span, res),
-        (err) => {
-          span.setTag('error', err)
-          this.#drain(ctx, span)
-        }
+        (err) => this.#finishSpan(ctx, span, undefined, err)
       )
     } else {
       this.#finishSpan(ctx, span, result)
@@ -235,8 +261,16 @@ class GraphQLExecutePlugin extends TracingPlugin {
     }
   }
 
-  #finishSpan (ctx, span, res) {
-    this.config.hooks.execute(span, ctx.ddArgs, res)
+  /**
+   * @param {object} ctx
+   * @param {import('../../dd-trace/src/opentracing/span')} span
+   * @param {import('graphql').ExecutionResult} [res]
+   * @param {unknown} [error]
+   */
+  #finishSpan (ctx, span, res, error) {
+    if (error !== undefined) {
+      span.setTag('error', error)
+    }
 
     if (res?.errors?.length) {
       span.setTag('error', res.errors[0])
@@ -245,17 +279,16 @@ class GraphQLExecutePlugin extends TracingPlugin {
       }
     }
 
-    this.#drain(ctx, span)
-  }
-
-  #drain (ctx, span) {
-    span.finish()
     if (ctx.ddContextValue) {
       contexts.delete(ctx.ddContextValue)
     }
     if (ctx.ddInstrumentedArgs) {
       instrumentedArgs.delete(ctx.ddInstrumentedArgs)
     }
+
+    this.config.hooks.execute(span, ctx.ddArgs, res)
+
+    span.finish()
   }
 
   // Public — called from wrapResolve (free function, crosses class boundary).
@@ -281,6 +314,7 @@ class GraphQLExecutePlugin extends TracingPlugin {
       type: 'graphql',
       startTime,
       meta: {
+        'graphql.field.coordinates': `${field.parentTypeName}.${fieldName}`,
         'graphql.field.name': fieldName,
         'graphql.field.path': collapsedKey,
         'graphql.field.type': baseTypeName,
@@ -291,7 +325,7 @@ class GraphQLExecutePlugin extends TracingPlugin {
     field.span = span
 
     if (fieldNode && this.config.variables && fieldNode.arguments) {
-      const variables = this.config.variables(variableValues)
+      const variables = this.#filterVariables(rootCtx, variableValues)
       for (const arg of fieldNode.arguments) {
         if (arg.value?.name && arg.value.kind === 'Variable' && variables[arg.value.name.value]) {
           const name = arg.value.name.value
@@ -303,6 +337,27 @@ class GraphQLExecutePlugin extends TracingPlugin {
     return span
   }
 
+  // Memoize the user variables filter against the last-seen variableValues
+  // object. graphql hands every resolver in one execute the same coerced
+  // variableValues object, so all arg-bearing fields hit the identity fast
+  // path and the filter runs once per operation. A nested execute() sharing
+  // the same object contextValue reuses the outer rootCtx but carries its own
+  // variableValues; comparing by identity recomputes for it (and any later
+  // fields on that inner object reuse the slot), so each field's tags stay
+  // correct. A single slot beats a WeakMap here: no per-operation allocation,
+  // and the common single-object case is a bare `===` (see the microbenchmark
+  // numbers in the commit body).
+  #filterVariables (rootCtx, variableValues) {
+    if (rootCtx.filteredVariablesKey === variableValues) {
+      return rootCtx.filteredVariables
+    }
+
+    const filtered = this.config.variables(variableValues)
+    rootCtx.filteredVariablesKey = variableValues
+    rootCtx.filteredVariables = filtered
+    return filtered
+  }
+
   // Public — called from wrapResolve. endTime reflects when the resolver
   // actually completed, not when the field record was created.
   finishResolveSpan (span, field, error, result, endTime) {
@@ -376,20 +431,35 @@ function wrapResolve (resolve) {
       return resolve.apply(this, arguments)
     }
 
-    const fieldKey = config.collapse ? buildCachedCollapsedPath(infoPath, rootCtx.collapsedPathCache) : infoPath
+    const fieldKey = config.collapse ? pathString : infoPath
+    const parentTypeName = info.parentType.name
     let field = rootCtx.fields.get(fieldKey)
+    const collapsedField = field
+    if (config.collapse && field !== undefined && field.parentTypeName !== parentTypeName) {
+      const parentTypeFields = field.parentTypeFields
+      if (parentTypeFields?.parentTypeName === undefined) {
+        field = parentTypeFields?.get(parentTypeName)
+      } else if (parentTypeFields.parentTypeName === parentTypeName) {
+        field = parentTypeFields
+      } else {
+        field = undefined
+      }
+      if (field && infoPath.typename === undefined) {
+        cacheFieldByPath(rootCtx, infoPath, field)
+      }
+    }
     const isFirst = !field
 
     if (isFirst) {
       field = {
         fieldNode: info.fieldNodes?.[0],
         fieldName: info.fieldName,
+        parentTypeName,
         returnType: info.returnType,
         baseTypeName: getBaseTypeName(info.returnType),
         variableValues: info.variableValues,
         args,
         infoPath,
-        fieldKey,
         pathString,
         collapsedKey: collapsedKey ?? pathString,
         span: null,
@@ -398,7 +468,25 @@ function wrapResolve (resolve) {
         parentStore: null,
         currentStore: null,
       }
-      rootCtx.fields.set(fieldKey, field)
+      if (config.collapse && collapsedField) {
+        const parentTypeFields = collapsedField.parentTypeFields
+        if (parentTypeFields === undefined) {
+          collapsedField.parentTypeFields = field
+        } else if (parentTypeFields.parentTypeName === undefined) {
+          parentTypeFields.set(parentTypeName, field)
+        } else {
+          const fieldsByParentType = new Map()
+            .set(collapsedField.parentTypeName, collapsedField)
+            .set(parentTypeFields.parentTypeName, parentTypeFields)
+            .set(parentTypeName, field)
+          collapsedField.parentTypeFields = fieldsByParentType
+        }
+        if (infoPath.typename === undefined) {
+          cacheFieldByPath(rootCtx, infoPath, field)
+        }
+      } else {
+        rootCtx.fields.set(fieldKey, field)
+      }
     }
 
     // Collapsed siblings still publish updateField (master's contract: one
@@ -432,15 +520,44 @@ function wrapResolve (resolve) {
   return resolveAsync
 }
 
-function wrapFields (type) {
-  if (!type?._fields || patchedTypes.has(type)) return
+function wrapFields (type, schema) {
+  if (!type || !markWalked(schema, type)) return
+
+  const tag = type[Symbol.toStringTag]
+
+  // Union types (e.g. Apollo Federation's `_Entity`) hold their members on
+  // `_types`, not `_fields`. Their member object types are reachable only here,
+  // so descend into each to wrap the entity resolvers a `_entities` query runs.
+  if (tag === 'GraphQLUnionType') {
+    for (const member of type.getTypes()) wrapFields(member, schema)
+    return
+  }
+
+  if (type._fields) {
+    for (const field of Object.values(type._fields)) {
+      wrapFieldResolve(field)
+      wrapFieldType(field, schema)
+    }
+  }
 
-  patchedTypes.add(type)
+  // Interface implementations carry their own resolvers and are reachable only
+  // through `getPossibleTypes`; an interface return type alone never wraps them.
+  if (schema && tag === 'GraphQLInterfaceType') {
+    for (const impl of schema.getPossibleTypes(type)) wrapFields(impl, schema)
+  }
+}
 
-  for (const field of Object.values(type._fields)) {
-    wrapFieldResolve(field)
-    wrapFieldType(field)
+// Marks the guard on entry so recursive types (a field looping back to its own
+// type, an interface an implementation returns) terminate the walk.
+function markWalked (schema, type) {
+  let walked = walkedTypes.get(schema)
+  if (walked === undefined) {
+    walked = new WeakSet()
+    walkedTypes.set(schema, walked)
   }
+  if (walked.has(type)) return false
+  walked.add(type)
+  return true
 }
 
 function wrapFieldResolve (field) {
@@ -448,13 +565,13 @@ function wrapFieldResolve (field) {
   field.resolve = wrapResolve(field.resolve)
 }
 
-function wrapFieldType (field) {
+function wrapFieldType (field, schema) {
   if (!field?.type) return
 
   let unwrapped = field.type
   while (unwrapped.ofType) unwrapped = unwrapped.ofType
 
-  wrapFields(unwrapped)
+  wrapFields(unwrapped, schema)
 }
 
 // Runs the resolver inside `store`, including any code after an internal
@@ -516,31 +633,18 @@ function buildCachedPathString (path, cache, collapse) {
   return pathString
 }
 
-function buildCachedCollapsedPath (path, cache) {
-  if (!path) return
-
-  const cached = cache.byPath.get(path)
-  if (cached !== undefined) return cached
-
-  const segment = typeof path.key === 'string' ? path.key : '*'
-  const prev = path.prev === undefined
-    ? undefined
-    : buildCachedCollapsedPath(path.prev, cache)
-
-  let siblings = cache.byParent.get(prev)
-  if (siblings === undefined) {
-    siblings = new Map()
-    cache.byParent.set(prev, siblings)
-  }
-
-  let collapsedPath = siblings.get(segment)
-  if (collapsedPath === undefined) {
-    collapsedPath = { key: segment, prev }
-    siblings.set(segment, collapsedPath)
-  }
-
-  cache.byPath.set(path, collapsedPath)
-  return collapsedPath
+/**
+ * @param {{ hasFieldsByPath?: boolean, fields: Map<string|object, object> }} rootCtx
+ * @param {object} path
+ * @param {object} field
+ */
+function cacheFieldByPath (rootCtx, path, field) {
+  // Leaf fields cannot parent resolver spans, so their concrete paths are never read.
+  if (field.fieldNode?.selectionSet === undefined) return
+
+  // Concrete info path objects cannot collide with collapsed path string keys.
+  rootCtx.hasFieldsByPath = true
+  rootCtx.fields.set(path, field)
 }
 
 // Depth filtering directly on the linked-list node — no array allocation needed.
@@ -564,9 +668,23 @@ function shouldInstrumentNode (config, path) {
 }
 
 function getParentField (rootCtx, field) {
-  for (let curr = field.fieldKey?.prev; curr; curr = curr.prev) {
-    const innerField = rootCtx.fields.get(curr)
-    if (innerField) return innerField
+  for (let curr = field.infoPath?.prev; curr; curr = curr.prev) {
+    const fieldKey = rootCtx.config.collapse ? rootCtx.pathCache.get(curr) : curr
+    const innerField = rootCtx.fields.get(fieldKey)
+    if (innerField) {
+      if (curr.typename === undefined) {
+        if (rootCtx.hasFieldsByPath) {
+          const fieldByPath = rootCtx.fields.get(curr)
+          if (fieldByPath) return fieldByPath
+        }
+        return innerField
+      }
+      if (innerField.parentTypeName === curr.typename) return innerField
+
+      const parentTypeFields = innerField.parentTypeFields
+      if (parentTypeFields.parentTypeName === undefined) return parentTypeFields.get(curr.typename)
+      return parentTypeFields
+    }
   }
 
   return null

package/packages/datadog-plugin-graphql/src/parse.js

@@ -1,9 +1,15 @@
 'use strict'
 
 const TracingPlugin = require('../../dd-trace/src/plugins/tracing')
+const { isApolloHealthCheckSource } = require('./utils')
 
 const documentSources = new WeakMap()
 
+// Documents produced by parsing an Apollo Gateway health-check poll. Populated
+// here (parse owns the document lifecycle, like documentSources) and read by the
+// validate plugin. Execute independently verifies the operation for cached docs.
+const healthCheckDocuments = new WeakSet()
+
 class GraphQLParsePlugin extends TracingPlugin {
   static id = 'graphql'
   static operation = 'parser'
@@ -12,6 +18,14 @@ class GraphQLParsePlugin extends TracingPlugin {
   bindStart (ctx) {
     const source = ctx.arguments?.[0]
 
+    // Apollo Gateway polls every subgraph with a fixed health-check query.
+    // Mark its document after parsing so validation can skip the same poll.
+    if (isApolloHealthCheckSource(source?.body ?? source)) {
+      ctx.ddHealthCheck = true
+      ctx.ddSkipped = true
+      return ctx.currentStore
+    }
+
     this.startSpan('graphql.parse', {
       service: this.config.service,
       type: 'graphql',
@@ -24,8 +38,14 @@ class GraphQLParsePlugin extends TracingPlugin {
   }
 
   end (ctx) {
-    const source = ctx.ddSource
     const document = ctx.result
+
+    if (ctx.ddHealthCheck) {
+      if (document) healthCheckDocuments.add(document)
+      return ctx.parentStore
+    }
+
+    const source = ctx.ddSource
     const span = ctx?.currentStore?.span || this.activeSpan
 
     let docSource
@@ -51,5 +71,6 @@ class GraphQLParsePlugin extends TracingPlugin {
 }
 
 GraphQLParsePlugin.documentSources = documentSources
+GraphQLParsePlugin.healthCheckDocuments = healthCheckDocuments
 
 module.exports = GraphQLParsePlugin

package/packages/datadog-plugin-graphql/src/request.js

@@ -1,7 +1,24 @@
 'use strict'
 
 const TracingPlugin = require('../../dd-trace/src/plugins/tracing')
-const { extractErrorIntoSpanEvent, getCachedRequestOperation } = require('./utils')
+const { extractErrorIntoSpanEvent, getCachedRequestOperation, isApolloHealthCheckSource } = require('./utils')
+
+/**
+ * @typedef {object} GraphQLRequestStore
+ * @property {import('../../dd-trace/src/opentracing/span')} [span]
+ * @property {import('../../dd-trace/src/opentracing/span')} [graphqlRequestSpan]
+ * @property {string} [graphqlRequestOperationName]
+ * @property {unknown} [graphqlRequestSource]
+ */
+
+/**
+ * @typedef {object} GraphQLRequestContext
+ * @property {unknown[]} [arguments]
+ * @property {GraphQLRequestStore} [currentStore]
+ * @property {GraphQLRequestStore} [parentStore]
+ * @property {boolean} [ddSkipped]
+ * @property {{ errors?: import('graphql').GraphQLError[] }} [result]
+ */
 
 // Top-level GraphQL request span for drivers that funnel every operation
 // through a single entry point but parse/validate/execute internally (mercurius
@@ -25,9 +42,18 @@ class GraphQLRequestPlugin extends TracingPlugin {
   static kind = 'server'
   static prefix = 'tracing:orchestrion:mercurius:apm:graphql:request'
 
+  /**
+   * @param {GraphQLRequestContext} ctx
+   */
   bindStart (ctx) {
     // fastifyGraphQl(source, context, variables, operationName)
     const source = ctx.arguments?.[0]
+
+    if (isApolloHealthCheckSource(source)) {
+      ctx.ddSkipped = true
+      return ctx.currentStore
+    }
+
     const operationName = ctx.arguments?.[3]
 
     // `source` is the request text on the common path, but mercurius also
@@ -72,7 +98,12 @@ class GraphQLRequestPlugin extends TracingPlugin {
     return ctx.currentStore
   }
 
+  /**
+   * @param {GraphQLRequestContext} ctx
+   */
   asyncEnd (ctx) {
+    if (ctx.ddSkipped) return ctx.parentStore
+
     /* istanbul ignore next: currentStore is populated for the request lifecycle; activeSpan is base-plugin fallback. */
     const span = ctx?.currentStore?.span || this.activeSpan
     /* istanbul ignore if: startSpan always populates currentStore for the request lifecycle. */

package/packages/datadog-plugin-graphql/src/utils.js

@@ -228,6 +228,46 @@ function extractErrorIntoSpanEvent (config, span, exc) {
   span.addEvent('dd.graphql.query.error', attributes, Date.now())
 }
 
+// Apollo Gateway's fixed subgraph health-check query, sent verbatim on every
+// poll interval. See https://github.com/apollographql/federation
+// `HEALTH_CHECK_QUERY`.
+const HEALTH_CHECK_QUERY = 'query __ApolloServiceHealthCheck__ { __typename }'
+
+/**
+ * Matches the raw query string before it is parsed (the only input parse has).
+ *
+ * @param {unknown} source Raw query string or a graphql `Source` body.
+ * @returns {boolean}
+ */
+function isApolloHealthCheckSource (source) {
+  return source === HEALTH_CHECK_QUERY
+}
+
+/**
+ * Matches Apollo's parsed health-check operation exactly for cached documents.
+ *
+ * @param {import('graphql').OperationDefinitionNode | undefined} operation
+ * @returns {boolean}
+ */
+function isApolloHealthCheck (operation) {
+  const selections = operation?.selectionSet?.selections
+  if (operation?.operation !== 'query' ||
+      operation.name?.value !== '__ApolloServiceHealthCheck__' ||
+      operation.variableDefinitions?.length ||
+      operation.directives?.length ||
+      selections?.length !== 1) {
+    return false
+  }
+
+  const selection = selections[0]
+  return selection.kind === 'Field' &&
+    selection.name?.value === '__typename' &&
+    selection.alias === undefined &&
+    selection.selectionSet === undefined &&
+    selection.arguments?.length === 0 &&
+    selection.directives?.length === 0
+}
+
 let tools
 
 function getSignature (document, operationName, operationType, calculate) {
@@ -261,5 +301,7 @@ module.exports = {
   getCachedRequestOperation,
   getOperation,
   getSignature,
+  isApolloHealthCheck,
+  isApolloHealthCheckSource,
   refineRequestSpan,
 }

package/packages/datadog-plugin-graphql/src/validate.js

@@ -3,7 +3,7 @@
 const { storage } = require('../../datadog-core')
 const TracingPlugin = require('../../dd-trace/src/plugins/tracing')
 const GraphQLParsePlugin = require('./parse')
-const { extractErrorIntoSpanEvent, refineRequestSpan } = require('./utils')
+const { extractErrorIntoSpanEvent, isApolloHealthCheck, refineRequestSpan } = require('./utils')
 
 const legacyStorage = storage('legacy')
 
@@ -15,6 +15,16 @@ class GraphQLValidatePlugin extends TracingPlugin {
   bindStart (ctx) {
     // validate(schema, documentAST, rules, options, typeInfo)
     const document = ctx.arguments?.[1]
+
+    // Verify the marked document in case the caller transformed its AST after parsing.
+    if (document &&
+        GraphQLParsePlugin.healthCheckDocuments.has(document) &&
+        document.definitions?.length === 1 &&
+        isApolloHealthCheck(document.definitions[0])) {
+      ctx.ddSkipped = true
+      return ctx.currentStore
+    }
+
     const docSource = document ? GraphQLParsePlugin.documentSources.get(document) : undefined
     const source = this.config.source && document && docSource
 
@@ -52,12 +62,12 @@ class GraphQLValidatePlugin extends TracingPlugin {
   }
 
   end (ctx) {
+    if (ctx.ddSkipped) return ctx.parentStore
+
     const document = ctx.ddDocument
     const errors = ctx.result
     const span = ctx?.currentStore?.span || this.activeSpan
 
-    this.config.hooks.validate(span, document, errors)
-
     if (errors?.length) {
       span.setTag('error', errors[0])
       for (const err of errors) {
@@ -65,6 +75,8 @@ class GraphQLValidatePlugin extends TracingPlugin {
       }
     }
 
+    this.config.hooks.validate(span, document, errors)
+
     span.finish()
 
     return ctx.parentStore

package/packages/datadog-plugin-http2/src/client.js

@@ -32,7 +32,7 @@ class Http2ClientPlugin extends ClientPlugin {
     const { authority, options, headers = {} } = message
     const sessionDetails = extractSessionDetails(authority, options)
     const path = headers[HTTP2_HEADER_PATH] || '/'
-    const pathname = path.split(/[?#]/)[0]
+    const pathname = path.split(/[?#]/, 1)[0]
     const method = headers[HTTP2_HEADER_METHOD] || HTTP2_METHOD_GET
     const base = `${sessionDetails.protocol}//${sessionDetails.host}:${sessionDetails.port}`
     const uri = `${base}${pathname}`

package/packages/datadog-plugin-http2/src/server.js

@@ -1,7 +1,5 @@
 'use strict'
 
-// Plugin temporarily disabled. See https://github.com/DataDog/dd-trace-js/issues/312
-
 const ServerPlugin = require('../../dd-trace/src/plugins/server')
 const web = require('../../dd-trace/src/plugins/util/web')
 const { COMPONENT, SVC_SRC_KEY } = require('../../dd-trace/src/constants')
@@ -10,6 +8,7 @@ class Http2ServerPlugin extends ServerPlugin {
   constructor (tracer, config) {
     super(tracer, config)
     this.addBind('apm:http2:server:response:emit', this.bindEmit)
+    this.addSub('apm:http2:server:request:adopt', this.adopt)
   }
 
   static id = 'http2'
@@ -47,15 +46,35 @@ class Http2ServerPlugin extends ServerPlugin {
 
     const context = web.getContext(req)
 
-    if (!context.instrumented) {
-      context.res.writeHead = web.wrapWriteHead(context)
-      context.instrumented = true
-    }
+    // A mixed server adopts the real request off this stream later; key the
+    // context on the stream now so that lookup resolves. Skipped for the common
+    // single-listener request, which never adopts.
+    if (ctx.adoptable) web.linkContextToStream(req.stream, context)
+
+    instrumentWriteHead(context)
 
     return ctx.currentStore
   }
 
+  // A mixed server (raw-stream + 'request' listeners) creates the span from the
+  // 'stream' event with a throwaway adapter. When the compatibility layer then
+  // synthesizes the real request/response off the same stream, point the shared
+  // context at them so `web.setFramework`/`web.setRoute` from the user's
+  // 'request' handler resolve to this span and the finish `hooks.request`
+  // receives the real objects instead of the adapter.
+  adopt (ctx) {
+    const context = web.patch(ctx.req)
+    context.req = ctx.req
+    context.res = ctx.res
+    instrumentWriteHead(context)
+  }
+
   bindEmit (ctx) {
+    // Both the compatibility response and the core-API stream emit 'close'
+    // exactly once, so the span is finished from a single source. `web.js`
+    // bypasses its `finished` idempotency guard for stream-backed requests
+    // (`!req.stream`); that bypass is harmless here only because of this
+    // single-finish property.
     if (ctx.eventName !== 'close') return ctx.currentStore
 
     const { req } = ctx
@@ -78,4 +97,17 @@ class Http2ServerPlugin extends ServerPlugin {
   }
 }
 
+// The core stream API has no `res.writeHead`; CORS preflight tagging only
+// applies to the compatibility response that exposes it. Runs once per context:
+// the mixed path calls it again from `adopt` once the real response is in place.
+/**
+ * @param {{ res: { writeHead?: Function }, instrumented?: boolean }} context
+ */
+function instrumentWriteHead (context) {
+  if (!context.instrumented && typeof context.res.writeHead === 'function') {
+    context.res.writeHead = web.wrapWriteHead(context)
+    context.instrumented = true
+  }
+}
+
 module.exports = Http2ServerPlugin