pipework 0.252.0 → 0.253.0

package/src/request/http/upload.ts

@@ -0,0 +1,284 @@
+import { Readable, Transform } from 'node:stream'
+import type { FastifyRequest } from 'fastify'
+import type { UploadConfig, BinaryUpload, MultipartUpload } from '../di/types.js'
+import { extensionOf, resolveMediaType, SNIFF_BYTES } from './sniff.js'
+import { isPipeworkError, MalformedMultipartError, PayloadTooLargeError, UnsupportedMediaTypeError, ValidationError } from '../../core/errors/index.js'
+
+/** Largest accepted multipart text field, in bytes. */
+export const MULTIPART_FIELD_LIMIT = 64 * 1024
+const MULTIPART_OVERHEAD = 16 * 1024
+
+/** The body size Fastify may let through: the file plus multipart framing and fields. */
+export function uploadBodyLimit(config: UploadConfig): number {
+  if (config.kind === 'binary') return config.maxBytes
+  return config.maxBytes + MULTIPART_OVERHEAD + (config.fields?.length ?? 0) * MULTIPART_FIELD_LIMIT
+}
+
+/** `type/subtype` of a Content-Type value, lowercased and without parameters. */
+export function mediaTypeOf(value: string | undefined): string {
+  if (value === undefined) return ''
+  return (value.split(';')[0] ?? '').trim().toLowerCase()
+}
+
+/** True when `mediaType` matches an allowed entry: exactly, by `type/*`, or by a star on each side of the slash (any non-empty type). */
+export function mediaTypeAllowed(allowed: readonly string[], mediaType: string): boolean {
+  if (mediaType === '') return false
+  for (const entry of allowed) {
+    const a = entry.trim().toLowerCase()
+    if (a === mediaType || a === '*/*') return true
+    if (a.endsWith('/*') && mediaType.startsWith(a.slice(0, -1))) return true
+  }
+  return false
+}
+
+const pipeworkRefusals = new WeakSet<object>()
+
+function refusal<T extends Error>(error: T): T {
+  pipeworkRefusals.add(error)
+  return error
+}
+
+/** True for a 413 or 415 pipework raised for a file, as opposed to one a handler threw. */
+export function isUploadRefusal(error: unknown): error is PayloadTooLargeError | UnsupportedMediaTypeError {
+  return typeof error === 'object' && error !== null && pipeworkRefusals.has(error)
+}
+
+/** What pipework knows of the file at the moment it refuses it. */
+export interface UploadTrack {
+  declaredType: string
+  extension: string | null
+  filename: string | null
+  detectedType: string | null
+  bytesRead: number
+}
+
+export function newUploadTrack(): UploadTrack {
+  return { declaredType: '', extension: null, filename: null, detectedType: null, bytesRead: 0 }
+}
+
+/**
+ * Refuses a multipart route's request that is not `multipart/form-data`, from
+ * its headers alone. A protocol error: no file is involved. Binary routes have
+ * no header check; their type is settled from the bytes.
+ */
+export function checkUploadHeaders(config: UploadConfig, headers: Record<string, string | string[] | undefined>): UnsupportedMediaTypeError | null {
+  if (config.kind === 'binary') return null
+  const contentType = headers['content-type']
+  const mediaType = mediaTypeOf(Array.isArray(contentType) ? contentType[0] : contentType)
+  if (mediaType === 'multipart/form-data') return null
+  return new UnsupportedMediaTypeError(
+    mediaType === ''
+      ? 'This route needs a Content-Type; accepted: multipart/form-data'
+      : `Media type ${mediaType} is not accepted; accepted: multipart/form-data`,
+    { accepted: ['multipart/form-data'] },
+  )
+}
+
+/** 413 when the request declares a length over what the route may receive. */
+function checkDeclaredLength(config: UploadConfig, headers: Record<string, string | string[] | undefined>): PayloadTooLargeError | null {
+  const declared = Number(headers['content-length'])
+  if (headers['content-length'] !== undefined && Number.isFinite(declared) && declared > uploadBodyLimit(config)) {
+    return refusal(new PayloadTooLargeError(`Request body is ${declared} bytes; the limit is ${config.maxBytes}`, { maxBytes: config.maxBytes }))
+  }
+  return null
+}
+
+/**
+ * Passes `source` through, erroring with a 413 once more than `maxBytes` have
+ * passed. A failure of `source` becomes the failure of the returned stream.
+ */
+export function limitStream(
+  source: Readable,
+  maxBytes: number,
+  mapError: (e: unknown) => Error = (e) => e as Error,
+  onUnfinished?: () => Error,
+  track?: UploadTrack,
+): Readable {
+  let seen = 0
+  const counter = new Transform({
+    transform(chunk: Buffer, _enc, cb) {
+      seen += chunk.length
+      if (track !== undefined) track.bytesRead = seen
+      if (seen > maxBytes) {
+        source.unpipe(counter)
+        cb(refusal(new PayloadTooLargeError(`Upload is over the limit of ${maxBytes} bytes`, { maxBytes })))
+        return
+      }
+      cb(null, chunk)
+    },
+  })
+  source.on('error', (e) => counter.destroy(mapError(e)))
+  if (onUnfinished !== undefined) {
+    // The parser may have failed and destroyed the part before this stream
+    // was attached, so its 'error' and 'close' are already past.
+    const unfinished = (): void => {
+      if (!source.readableEnded && !counter.destroyed) counter.destroy(onUnfinished())
+    }
+    if (source.destroyed) unfinished()
+    else source.on('close', unfinished)
+  }
+  source.pipe(counter)
+  return counter
+}
+
+function toUploadError(e: unknown): Error {
+  const code = (e as { code?: unknown } | null)?.code
+  if (code === 'FST_REQ_FILE_TOO_LARGE') return refusal(new PayloadTooLargeError('Uploaded file is over the size limit'))
+  return asMalformedMultipart(e)
+}
+
+/** A parser failure becomes a 400; errors that already carry a status are kept. */
+function asMalformedMultipart(e: unknown): Error {
+  if (isPipeworkError(e)) return e
+  const status = (e as { statusCode?: unknown } | null)?.statusCode
+  if (typeof status === 'number' && status >= 400 && status < 500) return e as Error
+  const message = e instanceof Error ? e.message : String(e)
+  return new MalformedMultipartError(undefined, { cause: message })
+}
+
+/** Lowercase text after the last dot of a filename; null without a filename or a dot. */
+
+/**
+ * Reads up to SNIFF_BYTES from `source`, then returns them with a stream that
+ * yields them again followed by the rest of `source`, byte for byte. Nothing
+ * further is buffered. A failure of `source` while reading the head is thrown.
+ */
+async function withHead(source: Readable): Promise<{ head: Buffer; stream: Readable }> {
+  const it = source[Symbol.asyncIterator]()
+  const chunks: Buffer[] = []
+  let length = 0
+  let ended = false
+  while (length < SNIFF_BYTES) {
+    const next = await it.next() as IteratorResult<Buffer>
+    if (next.done === true) { ended = true; break }
+    chunks.push(next.value)
+    length += next.value.length
+  }
+  const all = Buffer.concat(chunks)
+  async function* rejoin(): AsyncGenerator<Buffer> {
+    try {
+      if (all.length > 0) yield all
+      while (!ended) {
+        const next = await it.next() as IteratorResult<Buffer>
+        if (next.done === true) return
+        yield next.value
+      }
+    } finally {
+      source.destroy()
+    }
+  }
+  const stream = Readable.from(rejoin(), { objectMode: false })
+  stream.on('close', () => source.destroy())
+  return { head: all.subarray(0, SNIFF_BYTES), stream }
+}
+
+interface SniffedFile {
+  readonly stream: Readable
+  readonly mediaType: string
+  readonly detectedType: string | null
+  readonly declaredType: string
+  readonly extension: string | null
+}
+
+/** Reads the head of `limited`, settles the file's type and refuses a type outside the route's list. */
+async function sniffFile(
+  config: UploadConfig,
+  limited: Readable,
+  declaredType: string,
+  filename: string | null,
+  track: UploadTrack,
+): Promise<SniffedFile> {
+  const extension = extensionOf(filename)
+  track.declaredType = declaredType
+  track.filename = filename
+  track.extension = extension
+  const { head, stream } = await withHead(limited)
+  const { detectedType, mediaType } = resolveMediaType({ head, declared: declaredType, extension })
+  track.detectedType = detectedType
+  if (!mediaTypeAllowed(config.mediaTypes, mediaType)) {
+    stream.destroy()
+    throw refusal(new UnsupportedMediaTypeError(
+      `File media type is not accepted (detected ${detectedType ?? 'none'}, declared ${declaredType === '' ? 'none' : declaredType}); accepted: ${config.mediaTypes.join(', ')}`,
+      { accepted: config.mediaTypes, detectedType, declaredType },
+    ))
+  }
+  return { stream, mediaType, detectedType, declaredType, extension }
+}
+
+/**
+ * Starts an upload: refuses a declared length over the limit, builds the size-
+ * limited file stream, reads its first bytes to settle the media type, and
+ * refuses a type outside the route's list. `track` follows what is learned.
+ */
+export async function startUpload(req: FastifyRequest, config: UploadConfig, track: UploadTrack): Promise<BinaryUpload | MultipartUpload> {
+  if (config.kind === 'binary') {
+    track.declaredType = mediaTypeOf(req.headers['content-type'])
+    const tooLarge = checkDeclaredLength(config, req.headers)
+    if (tooLarge !== null) throw tooLarge
+    const body = req.body
+    const source = body instanceof Readable ? body : Readable.from([])
+    const declared = req.headers['content-length']
+    const length = declared === undefined ? null : Number(declared)
+    const file = await sniffFile(config, limitStream(source, config.maxBytes, undefined, undefined, track), track.declaredType, null, track)
+    return { ...file, length: length !== null && Number.isFinite(length) ? length : null }
+  }
+  const tooLarge = checkDeclaredLength(config, req.headers)
+  if (tooLarge !== null) throw tooLarge
+  try {
+    return await readMultipart(req, config, track)
+  } catch (e) {
+    throw asMalformedMultipart(e)
+  }
+}
+
+/**
+ * Reads a multipart body up to its file part: the text fields before it, then
+ * the file as a size-limited stream. Nothing after the file part is read.
+ */
+async function readMultipart(
+  req: FastifyRequest,
+  config: Extract<UploadConfig, { kind: 'multipart' }>,
+  track: UploadTrack,
+): Promise<MultipartUpload> {
+  const allowedFields = new Set(config.fields ?? [])
+  const fields: Record<string, string> = {}
+  for await (const part of req.parts()) {
+    if (part.type === 'field') {
+      if (!allowedFields.has(part.fieldname)) {
+        throw new ValidationError({ [part.fieldname]: ['Unexpected field'] }, `Unexpected form field "${part.fieldname}"`)
+      }
+      if (part.valueTruncated) {
+        throw new PayloadTooLargeError(`Form field "${part.fieldname}" is over ${MULTIPART_FIELD_LIMIT} bytes`)
+      }
+      fields[part.fieldname] = String(part.value)
+      continue
+    }
+    if (part.fieldname !== config.file) {
+      part.file.resume()
+      throw new ValidationError({ [part.fieldname]: ['Unexpected file field'] }, `Unexpected file field "${part.fieldname}"; the file goes in "${config.file}"`)
+    }
+    const filename = part.filename === '' ? null : part.filename
+    const limited = limitStream(part.file, config.maxBytes, toUploadError, () => new MalformedMultipartError(undefined, { cause: 'The body ended before the file part was closed' }), track)
+    try {
+      const file = await sniffFile(config, limited, mediaTypeOf(part.mimetype), filename, track)
+      return { ...file, filename, fields }
+    } catch (e) {
+      part.file.resume()
+      throw e
+    }
+  }
+  throw new ValidationError({ [config.file]: ['Required'] }, `The form has no file part named "${config.file}"`)
+}
+
+/**
+ * Ends an upload after its handler: a stream not read to the end is destroyed.
+ * Returns true when the body was left incomplete, so the caller closes the
+ * connection rather than reading the rest.
+ */
+export function settleUpload(stream: Readable | undefined): boolean {
+  if (stream === undefined) return false
+  if (stream.readableEnded) return false
+  stream.on('error', () => undefined)
+  stream.destroy()
+  return true
+}

package/src/request/internal/text.ts

@@ -0,0 +1,6 @@
+export function singularize(s: string): string {
+  if (s.endsWith('ies')) return s.slice(0, -3) + 'y'
+  if (s.endsWith('ses') || s.endsWith('xes')) return s.slice(0, -2)
+  if (s.endsWith('s') && !s.endsWith('ss')) return s.slice(0, -1)
+  return s
+}

package/src/request/openapi/generate.ts

@@ -0,0 +1,205 @@
+import type { RouteRegistration } from '../http/types.js'
+import { toJsonSchema } from '../../data/schema/json-schema.js'
+
+export interface OpenAPIInfo {
+  title: string
+  version: string
+  description?: string
+}
+
+export interface OpenAPIDocument {
+  openapi: '3.0.3'
+  info: OpenAPIInfo
+  paths: Record<string, Record<string, unknown>>
+}
+
+/** The body of a validation 422: `{ error: { code, message, fields? } }`. */
+export const VALIDATION_ERROR_SCHEMA = {
+  type: 'object',
+  properties: {
+    error: {
+      type: 'object',
+      properties: {
+        code: { type: 'string' },
+        message: { type: 'string' },
+        fields: { type: 'object', additionalProperties: { type: 'array', items: { type: 'string' } } },
+      },
+      required: ['code', 'message'],
+    },
+  },
+  required: ['error'],
+} as const
+
+export const TOO_MANY_REQUESTS_SCHEMA = {
+  type: 'object',
+  properties: {
+    error: {
+      type: 'object',
+      properties: {
+        code: { type: 'string' },
+        message: { type: 'string' },
+        retryAfterSeconds: { type: 'integer', minimum: 0 },
+      },
+      required: ['code', 'message', 'retryAfterSeconds'],
+    },
+  },
+  required: ['error'],
+} as const
+
+export function generateOpenAPI(
+  info: OpenAPIInfo,
+  routes: readonly RouteRegistration[],
+  options?: { rateLimited?: boolean },
+): OpenAPIDocument {
+  const paths: Record<string, Record<string, unknown>> = {}
+
+  for (const route of routes) {
+    const { method, path, handler } = route
+    const meta = handler.meta
+
+    const openApiPath = path.replace(/:(\w+)/g, '{$1}')
+
+    let pathItem = paths[openApiPath]
+    if (!pathItem) {
+      pathItem = {}
+      paths[openApiPath] = pathItem
+    }
+
+    const operation: Record<string, unknown> = {}
+
+    const parameters: Record<string, unknown>[] = []
+
+    if (meta.paramsSchema) {
+      const schema = toJsonSchema(meta.paramsSchema)
+      if ('properties' in schema) {
+        const props = schema['properties'] as Record<string, unknown>
+        for (const [name, propSchema] of Object.entries(props)) {
+          parameters.push({
+            name,
+            in: 'path',
+            required: true,
+            schema: propSchema,
+          })
+        }
+      }
+    }
+
+    if (meta.querySchema) {
+      const schema = toJsonSchema(meta.querySchema)
+      if ('properties' in schema) {
+        const props = schema['properties'] as Record<string, unknown>
+        const requiredFields = Array.isArray(schema['required']) ? schema['required'] as string[] : []
+        for (const [name, propSchema] of Object.entries(props)) {
+          parameters.push({
+            name,
+            in: 'query',
+            required: requiredFields.includes(name),
+            schema: propSchema,
+          })
+        }
+      }
+    }
+
+    if (parameters.length > 0) {
+      operation['parameters'] = parameters
+    }
+
+    if (meta.inputSchema) {
+      operation['requestBody'] = {
+        // Mirrors the runtime: a request with no body reaches the input as undefined.
+        required: !meta.inputSchema.safeParse(undefined).success,
+        content: {
+          'application/json': {
+            schema: toJsonSchema(meta.inputSchema),
+          },
+        },
+      }
+    }
+
+    if (meta.upload) {
+      const binary = { type: 'string', format: 'binary' }
+      if (meta.upload.kind === 'binary') {
+        operation['requestBody'] = {
+          required: true,
+          content: Object.fromEntries(meta.upload.mediaTypes.map((type) => [type, { schema: binary }])),
+        }
+      } else {
+        const properties: Record<string, unknown> = { [meta.upload.file]: binary }
+        for (const field of meta.upload.fields ?? []) properties[field] = { type: 'string' }
+        operation['requestBody'] = {
+          required: true,
+          content: {
+            'multipart/form-data': {
+              schema: { type: 'object', properties, required: [meta.upload.file] },
+              encoding: { [meta.upload.file]: { contentType: meta.upload.mediaTypes.join(', ') } },
+            },
+          },
+        }
+      }
+    }
+
+    const responses: Record<string, unknown> = {}
+    if (meta.outputSchemas.size > 0) {
+      for (const [status, outputSchema] of meta.outputSchemas) {
+        responses[String(status)] = {
+          description: status === 200 ? 'Successful response' : `${status} response`,
+          content: {
+            'application/json': {
+              schema: toJsonSchema(outputSchema),
+            },
+          },
+        }
+      }
+    }
+    if (meta.file) {
+      responses[String(meta.file.status)] = {
+        description: meta.file.status === 200 ? 'Successful response' : `${meta.file.status} response`,
+        content: Object.fromEntries(meta.file.mediaTypes.map((type) => [type, { schema: { type: 'string', format: 'binary' } }])),
+      }
+    }
+    if (Object.keys(responses).length === 0) {
+      responses['200'] = { description: 'Successful response' }
+    }
+
+    if (meta.inputSchema || meta.querySchema || meta.paramsSchema) {
+      const declared = meta.outputSchemas.get(422)
+      responses['422'] = {
+        description: declared === undefined ? 'Validation failed' : '422 response',
+        content: {
+          'application/json': {
+            schema: declared === undefined
+              ? VALIDATION_ERROR_SCHEMA
+              : { oneOf: [toJsonSchema(declared), VALIDATION_ERROR_SCHEMA] },
+          },
+        },
+      }
+    }
+
+    if (typeof meta.rateLimit === 'string' || (options?.rateLimited === true && meta.rateLimit !== false)) {
+      const declared = meta.outputSchemas.get(429)
+      responses['429'] = {
+        description: 'Too many requests',
+        content: {
+          'application/json': {
+            schema: declared === undefined
+              ? TOO_MANY_REQUESTS_SCHEMA
+              : { oneOf: [toJsonSchema(declared), TOO_MANY_REQUESTS_SCHEMA] },
+          },
+        },
+      }
+    }
+
+    if (meta.requiresAuth) {
+      responses['401'] = { description: 'Unauthorized' }
+    }
+    if (meta.permission) {
+      responses['403'] = { description: 'Forbidden' }
+    }
+
+    operation['responses'] = responses
+
+    pathItem[method.toLowerCase()] = operation
+  }
+
+  return { openapi: '3.0.3', info, paths }
+}

package/src/request/openapi/index.ts

@@ -0,0 +1,2 @@
+export { generateOpenAPI } from './generate.js'
+export type { OpenAPIDocument, OpenAPIInfo } from './generate.js'

package/src/request/openapi/namespace.ts

@@ -0,0 +1,7 @@
+import { generateOpenAPI } from './generate.js'
+
+/** OpenAPI spec generation namespace. */
+export const openapi = {
+  /** Generates an OpenAPI 3.1 document from route registrations — schemas derived from fitting() input/output. */
+  generate: generateOpenAPI,
+}

package/src/test/auth.ts

@@ -0,0 +1,13 @@
+import type { BaseAuth } from '../auth/auth/types.js'
+
+export function mockAuth<TAuth extends BaseAuth>(overrides: Partial<TAuth> & { userId?: string; tenantId?: string } = {}): TAuth {
+  return {
+    userId: 'test-user',
+    tenantId: 'test-tenant',
+    ...overrides,
+  } as TAuth
+}
+
+export function asTenant<TAuth extends BaseAuth>(tenantId: string, overrides: Partial<TAuth> = {}): TAuth {
+  return mockAuth<TAuth>({ tenantId, ...overrides } as Partial<TAuth> & { userId?: string; tenantId?: string })
+}

package/src/test/auto-setup.ts

@@ -0,0 +1,45 @@
+import { beforeAll, afterAll, beforeEach, afterEach } from 'vitest'
+import { loadEnvFiles } from '../core/config/env.js'
+import { discoverForTestFork } from './discover-fork.js'
+import { setupTestDatabases } from './setup.js'
+import { beginTestIsolation, endTestIsolation, type TestContext } from './plugin.js'
+import { _setTestState, teardownAfterAll, useTestDb } from './vitest.js'
+import { logSlowPhases, SETUP_HOOK_TIMEOUT_MS } from './progress.js'
+import { TEARDOWN_HOOK_TIMEOUT_MS } from '../trace/runtime/pending-writes.js'
+
+loadEnvFiles()
+
+let _testContext: TestContext | null = null
+
+const instance = await discoverForTestFork()
+
+_setTestState(instance)
+
+const dbNames = instance.config.databaseNames()
+if (dbNames.length === 1) {
+  ;(globalThis as Record<string, unknown>)['db'] = useTestDb()
+}
+
+// Setup narrates: any phase that holds long enough to explain a late hook gets
+// a line, and setup fails by name when a phase stops advancing — never merely
+// because a fixed wall clock elapsed while it queued behind peer forks (#380).
+beforeAll(async () => {
+  await setupTestDatabases(instance, { onProgress: logSlowPhases() })
+}, SETUP_HOOK_TIMEOUT_MS)
+
+afterAll(async () => {
+  await teardownAfterAll(instance)
+}, TEARDOWN_HOOK_TIMEOUT_MS)
+
+beforeEach(async ({ task }) => {
+  _testContext = await beginTestIsolation(instance, task)
+  _setTestState(instance, _testContext)
+})
+
+afterEach(async () => {
+  if (_testContext) {
+    await endTestIsolation(instance, _testContext)
+    _testContext = null
+    _setTestState(instance, null)
+  }
+}, TEARDOWN_HOOK_TIMEOUT_MS)

package/src/test/context.ts

@@ -0,0 +1,91 @@
+import type { Manifold } from '../core/pipework.js'
+import { runInContext } from '../request/context/store.js'
+import { createRequestContext, createJobContext } from '../request/context/index.js'
+import { isTracingEnabled } from '../trace/entry/tracing-enabled.js'
+import { openTrace } from '../trace/entry/open-trace.js'
+import { parentTraceRef } from '../trace/entry/parent-trace.js'
+import { finalizeTrace } from '../trace/entry/finalize-trace.js'
+import { closeTrace } from '../trace/entry/close-trace.js'
+import { _isInTestIsolation } from './vitest.js'
+
+export interface WithContextOptions {
+  instance: Manifold
+  auth?: unknown
+  tenant?: string | null
+  requestId?: string
+}
+
+export function withContext<T>(options: WithContextOptions, fn: () => T): T {
+  if (_isInTestIsolation()) {
+    throw new Error(
+      '[pipework] withContext() creates a fresh context that bypasses test isolation.\n' +
+      '  Queries will not use the test transaction and will not roll back.\n\n' +
+      '  Use withFlow() instead — it preserves the test transaction:\n\n' +
+      "    import { withFlow, asTenant } from 'pipework/test'\n\n" +
+      "    withFlow({ auth: asTenant('tenant-1'), tenant: 'tenant-1' }, async () => {\n" +
+      '      // test transaction is preserved, rollback works\n' +
+      '    })',
+    )
+  }
+
+  const trace = isTracingEnabled(options.instance)
+    ? openTrace({
+        instance: options.instance,
+        entryKind: 'test',
+        parent: parentTraceRef(),
+        tenant: options.tenant ?? null,
+        auth: options.auth ?? null,
+        requestId: options.requestId ?? null,
+        sessionId: null,
+      })
+    : null
+
+  const ctx = createRequestContext({
+    instance: options.instance,
+    auth: options.auth ?? null,
+    tenant: options.tenant ?? null,
+    trace,
+    metadata: {
+      method: 'TEST',
+      path: '/test',
+      startedAt: Date.now(),
+      traceId: options.requestId ?? 'test-trace',
+      sessionId: null,
+    },
+  })
+
+  try {
+    return finalizeTrace(options.instance, trace, runInContext(ctx, fn))
+  } catch (err) {
+    void closeTrace(options.instance, trace, 'error')
+    throw err
+  }
+}
+
+export function withJobContext<T>(options: WithContextOptions, fn: () => T): T {
+  const trace = isTracingEnabled(options.instance)
+    ? openTrace({
+        instance: options.instance,
+        entryKind: 'test',
+        parent: parentTraceRef(),
+        tenant: options.tenant ?? null,
+        auth: options.auth ?? null,
+        requestId: options.requestId ?? null,
+        sessionId: null,
+      })
+    : null
+
+  const ctx = createJobContext({
+    instance: options.instance,
+    auth: options.auth ?? null,
+    tenant: options.tenant ?? null,
+    trace,
+  })
+
+  try {
+    return finalizeTrace(options.instance, trace, runInContext(ctx, fn))
+  } catch (err) {
+    void closeTrace(options.instance, trace, 'error')
+    throw err
+  }
+}