@softize/opus 9.0.9 → 9.1.1

package/src/observability/drivers/opentelemetry.ts

@@ -0,0 +1,165 @@
+/**
+ * @softize/opus/observability/opentelemetry
+ *
+ * Driver fino sobre `@opentelemetry/api`: não cria provider, exporter, collector nem
+ * context manager. O app configura seu SDK OTel e pode injetar um Tracer nos testes.
+ */
+
+import {
+  context,
+  createTraceState,
+  SpanKind,
+  SpanStatusCode,
+  trace,
+  TraceFlags,
+  type Attributes,
+  type Span,
+  type SpanContext,
+  type Tracer,
+} from '@opentelemetry/api'
+import type {
+  ActionResult,
+  HealthStatus,
+  ObservabilityAdapter,
+  ObservabilityOperation,
+  TraceContext,
+} from '../../core/index.ts'
+
+export interface OpenTelemetryObservabilityOptions {
+  /** Tracer injetado; default usa o provider global configurado pelo app. */
+  tracer?: Tracer
+  /** Nome do instrumentation scope. */
+  instrumentationName?: string
+  /** Versão do instrumentation scope. */
+  instrumentationVersion?: string
+  /** Nome do adapter no health agregado. */
+  name?: string
+  /** Shutdown opt-in de recurso possuído pelo caller; nunca desliga provider global sozinho. */
+  shutdown?: () => Promise<void> | void
+  /** Health adicional do wiring/exporter possuído pelo caller. */
+  healthCheck?: () => Promise<HealthStatus> | HealthStatus
+}
+
+export function openTelemetryObservability(
+  options: OpenTelemetryObservabilityOptions = {},
+): ObservabilityAdapter {
+  const {
+    name = 'opentelemetry',
+    instrumentationName = '@softize/opus',
+    instrumentationVersion,
+  } = options
+  const tracer = options.tracer ?? trace.getTracer(instrumentationName, instrumentationVersion)
+
+  return {
+    name,
+    kind: 'observability',
+
+    async runInSpan<T>(
+      operation: ObservabilityOperation,
+      run: (traceContext: TraceContext) => Promise<T>,
+    ): Promise<T> {
+      const parent = parentContext(operation.parent)
+      return tracer.startActiveSpan(
+        spanName(operation),
+        {
+          kind: SpanKind.INTERNAL,
+          attributes: operationAttributes(operation),
+        },
+        parent,
+        async (span) => runOperation(operation, span, run),
+      )
+    },
+
+    async healthCheck(): Promise<HealthStatus> {
+      if (options.healthCheck !== undefined) return options.healthCheck()
+      return { ok: true, details: { api: 'configured' } }
+    },
+
+    async dispose(): Promise<void> {
+      await options.shutdown?.()
+    },
+  }
+}
+
+async function runOperation<T>(
+  operation: ObservabilityOperation,
+  span: Span,
+  run: (traceContext: TraceContext) => Promise<T>,
+): Promise<T> {
+  const spanContext = span.spanContext()
+  if (!trace.isSpanContextValid(spanContext)) {
+    span.end()
+    throw new Error(
+      'OpenTelemetry tracer is not recording valid spans; configure a TracerProvider before the Opus runtime',
+    )
+  }
+  try {
+    const result = await run(fromSpanContext(spanContext))
+    const failed = operation.resultKind === 'action-result' && isFailedActionResult(result)
+    span.setAttribute('opus.outcome', failed ? 'error' : 'success')
+    if (failed) {
+      span.setAttribute('opus.error.category', result.error.category)
+      span.setStatus({ code: SpanStatusCode.ERROR })
+    } else {
+      span.setStatus({ code: SpanStatusCode.OK })
+    }
+    return result
+  } catch (err) {
+    span.setAttribute('opus.outcome', 'error')
+    span.setStatus({ code: SpanStatusCode.ERROR })
+    throw err
+  } finally {
+    span.end()
+  }
+}
+
+function parentContext(parent: TraceContext | undefined) {
+  if (parent === undefined) return context.active()
+  const spanContext = toSpanContext(parent)
+  return trace.isSpanContextValid(spanContext)
+    ? trace.setSpanContext(context.active(), spanContext)
+    : context.active()
+}
+
+function toSpanContext(value: TraceContext): SpanContext {
+  return {
+    traceId: value.traceId,
+    spanId: value.spanId ?? '0000000000000000',
+    traceFlags: value.traceFlags ?? TraceFlags.NONE,
+    ...(value.traceState !== undefined ? { traceState: createTraceState(value.traceState) } : {}),
+    isRemote: true,
+  }
+}
+
+function fromSpanContext(value: SpanContext): TraceContext {
+  const traceState = value.traceState?.serialize()
+  return {
+    traceId: value.traceId,
+    spanId: value.spanId,
+    traceFlags: value.traceFlags,
+    ...(traceState !== undefined && traceState.length > 0 ? { traceState } : {}),
+  }
+}
+
+function spanName(operation: ObservabilityOperation): string {
+  return `opus.${operation.kind} ${operation.name}`
+}
+
+/** Allowlist de baixa cardinalidade; IDs de execução/atores nunca viram atributos. */
+function operationAttributes(operation: ObservabilityOperation): Attributes {
+  const attributes: Attributes = {
+    'opus.operation.kind': operation.kind,
+    'opus.result.kind': operation.resultKind,
+  }
+  const actionKind = operation.attributes?.['opus.action.kind']
+  if (typeof actionKind === 'string') attributes['opus.action.kind'] = actionKind
+  const eventType = operation.attributes?.['opus.event.type']
+  if (typeof eventType === 'string') attributes['opus.event.type'] = eventType
+  return attributes
+}
+
+function isFailedActionResult(value: unknown): value is Extract<ActionResult<unknown>, { ok: false }> {
+  return typeof value === 'object' && value !== null && 'ok' in value && value.ok === false &&
+    'error' in value && typeof value.error === 'object' && value.error !== null &&
+    'category' in value.error && typeof value.error.category === 'string'
+}

package/src/observability/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @softize/opus/observability — superfície dos drivers de observabilidade.
+ *
+ * A porta vendor-neutral (`ObservabilityAdapter`, `TraceContext`) permanece no core.
+ * Drivers concretos vivem em subpaths, como `./opentelemetry`.
+ */
+
+export {}

package/src/queue/drivers/bullmq.ts

@@ -6,8 +6,8 @@
  *
  * Worker (consumer-side) é responsabilidade do consumer — esse adapter
  * só **enfileira** e **consulta**. Pra processar, o consumer registra
- * um `new Worker(queueName, processor, { connection })` que chama
- * `runtime.execute()` no callback.
+ * um `new Worker(queueName, processor, { connection })`, reidrata auth e chama
+ * `runtime.executeJob()` no callback.
  *
  * Uso:
  *   import { Queue } from 'bullmq'
@@ -23,6 +23,7 @@ import type {
   JobStatus,
   QueueAdapter,
 } from '../../core/index.ts'
+import { normalizeTraceContext } from '../../core/index.ts'
 
 // =============================================================================
 // BullMQ-compatible interfaces (zero direct dep no tipo público)
@@ -58,11 +59,18 @@ export interface BullMQQueue {
   add(
     name: string,
     data: unknown,
-    opts?: { jobId?: string },
+    opts?: BullMQAddOptions,
   ): Promise<BullMQJob>
   getJob(jobId: string): Promise<BullMQJob | undefined | null>
 }
 
+export interface BullMQAddOptions {
+  jobId?: string
+  attempts?: number
+  priority?: number
+  backoff?: { type: 'fixed' | 'exponential'; delay: number }
+}
+
 // =============================================================================
 // Adapter factory
 // =============================================================================
@@ -80,8 +88,8 @@ export function bullmqQueue(options: BullmqQueueOptions): QueueAdapter {
     kind: 'queue',
 
     async enqueue(spec: JobSpec): Promise<JobHandle> {
-      const job = await queue.add(spec.action, spec, { jobId: spec.jobId })
-      return jobToHandle(spec.action, job, 'queued')
+      const job = await queue.add(spec.action, spec, bullmqOptions(spec))
+      return jobToHandle(spec.action, job, 'queued', normalizeTraceContext(spec.ctx.trace))
     },
 
     async status(jobId: string): Promise<JobHandle | null> {
@@ -101,6 +109,31 @@ export function bullmqQueue(options: BullmqQueueOptions): QueueAdapter {
   }
 }
 
+function bullmqOptions(spec: JobSpec): BullMQAddOptions {
+  const options: BullMQAddOptions = { jobId: spec.jobId }
+  if (spec.config.priority !== undefined) {
+    options.priority = { high: 1, normal: 5, low: 10 }[spec.config.priority]
+  }
+  const retry = spec.config.retry
+  if (retry !== undefined) {
+    options.attempts = retry.attempts
+    if (retry.backoff?.kind === 'fixed') {
+      options.backoff = { type: 'fixed', delay: retry.backoff.delayMs }
+    } else if (retry.backoff?.kind === 'exponential') {
+      if (
+        (retry.backoff.multiplier !== undefined && retry.backoff.multiplier !== 2) ||
+        retry.backoff.maxMs !== undefined
+      ) {
+        throw new Error(
+          'BullMQ native exponential backoff supports multiplier 2 without maxMs; configure a worker backoffStrategy for custom behavior',
+        )
+      }
+      options.backoff = { type: 'exponential', delay: retry.backoff.initialMs }
+    }
+  }
+  return options
+}
+
 // =============================================================================
 // Mapping
 // =============================================================================
@@ -136,6 +169,7 @@ function jobToHandle(
   action: string,
   job: BullMQJob,
   status: JobStatus,
+  trace = readTrace(job),
 ): JobHandle {
   const handle: JobHandle = {
     jobId: job.id ?? '',
@@ -144,6 +178,7 @@ function jobToHandle(
     enqueuedAt: toIso(job.timestamp),
     attempts: job.attemptsMade,
   }
+  if (trace !== undefined) handle.trace = trace
   if (job.processedOn !== undefined) handle.startedAt = toIso(job.processedOn)
   if (job.finishedOn !== undefined) handle.finishedAt = toIso(job.finishedOn)
   if (status === 'done' && job.returnvalue !== undefined) handle.data = job.returnvalue
@@ -161,6 +196,13 @@ function jobToHandle(
   return handle
 }
 
+function readTrace(job: BullMQJob): JobHandle['trace'] | undefined {
+  if (typeof job.data !== 'object' || job.data === null || !('ctx' in job.data)) return undefined
+  const ctx = (job.data as { ctx?: unknown }).ctx
+  if (typeof ctx !== 'object' || ctx === null || !('trace' in ctx)) return undefined
+  return normalizeTraceContext((ctx as { trace?: unknown }).trace)
+}
+
 function readAction(job: BullMQJob): string {
   if (
     typeof job.data === 'object' &&

package/src/server/drivers/fastify.ts

@@ -35,12 +35,14 @@ import {
 } from '../../schema/openapi.ts'
 import {
   httpStatusFor,
+  extractW3CTraceContext,
   inputSourceFor,
   methodFor,
   pathFor,
   serializeResult,
   shouldMountPublicly,
   successStatusFor,
+  w3cTraceResponseHeaders,
 } from '../index.ts'
 
 // =============================================================================
@@ -62,6 +64,9 @@ export interface FastifyServerOptions {
 
   /** Servers do OpenAPI document. */
   openapiServers?: OpenAPIServer[]
+
+  /** Propagação HTTP opt-in. `'w3c'` extrai/injeta traceparent + tracestate. */
+  traceContext?: false | 'w3c'
 }
 
 // =============================================================================
@@ -74,6 +79,7 @@ export function fastifyServer(options: FastifyServerOptions): ServerAdapter {
     apiPrefix = '/api',
     openapiInfo = { title: 'tbdlib API', version: '0.0.0' },
     openapiServers,
+    traceContext = false,
   } = options
   let runtime: RuntimeRef | undefined
   const mountedActions: ActionDef[] = []
@@ -104,7 +110,7 @@ export function fastifyServer(options: FastifyServerOptions): ServerAdapter {
 
       const handler = async (req: FastifyRequest, reply: FastifyReply) => {
         const rt = requireRuntime()
-        const ctx = await resolveCtx(rt, req)
+        const ctx = await resolveCtx(rt, req, traceContext)
         const input = source === 'body' ? req.body : req.query
 
         const result = await rt.execute(action.name, input, ctx)
@@ -112,6 +118,11 @@ export function fastifyServer(options: FastifyServerOptions): ServerAdapter {
           ? successStatusFor(action)
           : httpStatusFor(result.error)
 
+        if (traceContext === 'w3c') {
+          for (const [key, value] of Object.entries(w3cTraceResponseHeaders(result.meta.trace))) {
+            reply.header(key, value)
+          }
+        }
         reply.code(status).send(serializeResult(result))
       }
 
@@ -138,11 +149,15 @@ export function fastifyServer(options: FastifyServerOptions): ServerAdapter {
 async function resolveCtx(
   rt: RuntimeRef,
   req: FastifyRequest,
+  traceContext: false | 'w3c',
 ): Promise<ContextBase> {
   const base = await resolveAuthBase(rt, req)
   // Fastify sempre popula req.id (auto-gen ou via genReqId opt). Não é optional.
   return {
     ...base,
+    ...(traceContext === 'w3c'
+      ? { trace: extractW3CTraceContext(req.headers as Record<string, string | string[] | undefined>) }
+      : {}),
     requestId: req.id,
     provenance: {
       kind: 'http',

package/src/server/drivers/node.ts

@@ -42,12 +42,14 @@ import {
 } from '../../schema/openapi.ts'
 import {
   httpStatusFor,
+  extractW3CTraceContext,
   inputSourceFor,
   methodFor,
   pathFor,
   serializeResult,
   shouldMountPublicly,
   successStatusFor,
+  w3cTraceResponseHeaders,
 } from '../index.ts'
 
 // =============================================================================
@@ -72,6 +74,9 @@ export interface NodeServerOptions {
 
   /** Servers do OpenAPI document. */
   openapiServers?: OpenAPIServer[]
+
+  /** Propagação HTTP opt-in. `'w3c'` extrai/injeta traceparent + tracestate. */
+  traceContext?: false | 'w3c'
 }
 
 export interface NodeServerHandle {
@@ -98,6 +103,7 @@ export function nodeServer(options: NodeServerOptions = {}): NodeServerHandle {
     endpoints,
     openapiInfo = { title: 'tbdlib API', version: '0.0.0' },
     openapiServers,
+    traceContext = false,
   } = options
 
   let runtime: RuntimeRef | undefined
@@ -142,7 +148,7 @@ export function nodeServer(options: NodeServerOptions = {}): NodeServerHandle {
       routes.set(`${method} ${path}`, async (req, res, url) => {
         const rt = requireRuntime()
         const requestId = crypto.randomUUID()
-        const ctx = await resolveCtx(rt, req, requestId)
+        const ctx = await resolveCtx(rt, req, requestId, traceContext)
 
         let input: unknown
         if (source === 'body') {
@@ -177,7 +183,7 @@ export function nodeServer(options: NodeServerOptions = {}): NodeServerHandle {
           ? successStatusFor(action)
           : httpStatusFor(result.error)
 
-        sendResult(res, status, result)
+        sendResult(res, status, result, traceContext === 'w3c')
       })
     },
 
@@ -235,10 +241,14 @@ async function resolveCtx(
   rt: RuntimeRef,
   req: IncomingMessage,
   requestId: string,
+  traceContext: false | 'w3c',
 ): Promise<ContextBase> {
   const base = await resolveAuthBase(rt, req)
   return {
     ...base,
+    ...(traceContext === 'w3c'
+      ? { trace: extractW3CTraceContext(req.headers) }
+      : {}),
     requestId,
     provenance: {
       kind: 'http',
@@ -275,9 +285,19 @@ async function readBody(req: IncomingMessage): Promise<string> {
   return body
 }
 
-function sendResult(res: ServerResponse, status: number, result: ActionResult<unknown>): void {
+function sendResult(
+  res: ServerResponse,
+  status: number,
+  result: ActionResult<unknown>,
+  injectTrace = false,
+): void {
   res.statusCode = status
   res.setHeader('content-type', 'application/json; charset=utf-8')
+  if (injectTrace) {
+    for (const [key, value] of Object.entries(w3cTraceResponseHeaders(result.meta.trace))) {
+      res.setHeader(key, value)
+    }
+  }
   res.end(JSON.stringify(serializeResult(result)))
 }
 

package/src/server/index.ts

@@ -15,8 +15,65 @@ import type {
   ActionError,
   ActionResult,
   ErrorCategory,
+  TraceContext,
 } from '../core/index.ts'
 
+// =============================================================================
+// W3C trace context
+// =============================================================================
+
+export type HttpHeaderValue = string | string[] | undefined
+
+/** Extrai somente traceparent v00 válido; tracestate é opcional e limitado a 512 bytes. */
+export function extractW3CTraceContext(
+  headers: Record<string, HttpHeaderValue>,
+): TraceContext | undefined {
+  const raw = firstHeader(headers['traceparent'])
+  if (raw === undefined) return undefined
+  const match = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i.exec(raw.trim())
+  if (match === null) return undefined
+  const traceId = match[1]?.toLowerCase()
+  const spanId = match[2]?.toLowerCase()
+  const flags = match[3]
+  if (traceId === undefined || spanId === undefined || flags === undefined) return undefined
+  if (/^0+$/.test(traceId) || /^0+$/.test(spanId)) return undefined
+  const traceState = validTraceState(firstHeader(headers['tracestate']))
+  return {
+    traceId,
+    spanId,
+    traceFlags: Number.parseInt(flags, 16),
+    ...(traceState !== undefined ? { traceState } : {}),
+  }
+}
+
+export function w3cTraceResponseHeaders(
+  traceContext: TraceContext | undefined,
+): Record<string, string> {
+  if (traceContext === undefined || !validTraceIds(traceContext)) return {}
+  const flags = (traceContext.traceFlags ?? 0) & 0xff
+  return {
+    traceparent: `00-${traceContext.traceId}-${traceContext.spanId}-${flags.toString(16).padStart(2, '0')}`,
+    ...(validTraceState(traceContext.traceState) !== undefined
+      ? { tracestate: traceContext.traceState as string }
+      : {}),
+  }
+}
+
+function firstHeader(value: HttpHeaderValue): string | undefined {
+  return Array.isArray(value) ? (value.length === 1 ? value[0] : undefined) : value
+}
+
+function validTraceState(value: string | undefined): string | undefined {
+  if (value === undefined || value.length === 0 || value.length > 512) return undefined
+  return /[^\x20-\x7e]/.test(value) ? undefined : value
+}
+
+function validTraceIds(value: TraceContext): value is TraceContext & { spanId: string } {
+  return /^[0-9a-f]{32}$/i.test(value.traceId) && !/^0+$/.test(value.traceId) &&
+    typeof value.spanId === 'string' && /^[0-9a-f]{16}$/i.test(value.spanId) &&
+    !/^0+$/.test(value.spanId)
+}
+
 // =============================================================================
 // HTTP status mapping
 // =============================================================================

package/src/testing/index.ts

@@ -46,6 +46,7 @@ import type {
   StorageObject,
   StoragePutOptions,
   User,
+  TraceContext,
 } from '../core/index.ts'
 
 // =============================================================================
@@ -73,6 +74,7 @@ export interface TestContextOptions {
   storage?: StorageAdapter | null
   ai?: AiAdapter | null
   meta?: Record<string, unknown>
+  trace?: TraceContext
 }
 
 export interface TestContext {
@@ -133,6 +135,7 @@ export function testContext(options: TestContextOptions = {}): TestContext {
     storage: options.storage ?? null,
     ai: options.ai ? toBoundAi(options.ai) : null,
     provenance: { kind: 'system', source: 'test' },
+    ...(options.trace !== undefined ? { trace: options.trace } : {}),
     meta: options.meta ?? {},
   }
   return { ctx, emitted, logged }