@effect-app/infra 4.0.0-beta.25 → 4.0.0-beta.250

package/src/internal/auth.ts

@@ -0,0 +1,272 @@
+import * as Effect from "effect-app/Effect"
+import { HttpHeaders, HttpMiddleware, HttpServerRequest, HttpServerResponse } from "effect-app/http"
+import * as Option from "effect-app/Option"
+import * as Data from "effect/Data"
+import { createRemoteJWKSet, jwtVerify } from "jose"
+
+const getHeaders = (error: string, description: string, scopes?: ReadonlyArray<string>) => ({
+  "WWW-Authenticate": `Bearer realm="api", error="${error}", error_description="${description.replace(/"/g, "'")}"${
+    scopes ? `, scope="${scopes.join(" ")}"` : ""
+  }`
+})
+
+export class UnauthorizedError extends Error {
+  readonly status: number = 401
+  readonly statusCode: number = 401
+  headers = { "WWW-Authenticate": "Bearer realm=\"api\"" }
+
+  constructor(message = "Unauthorized") {
+    super(message)
+    this.name = this.constructor.name
+  }
+}
+
+export class InvalidRequestError extends UnauthorizedError {
+  readonly code: string
+  override readonly status = 400
+  override readonly statusCode = 400
+
+  constructor(message = "Invalid Request", useErrorCode = true) {
+    super(message)
+    this.code = useErrorCode ? "invalid_request" : ""
+    if (useErrorCode) {
+      this.headers = getHeaders(this.code, this.message)
+    }
+  }
+}
+
+export class InvalidTokenError extends UnauthorizedError {
+  readonly code = "invalid_token"
+
+  constructor(message = "Invalid Token") {
+    super(message)
+    this.headers = getHeaders(this.code, this.message)
+  }
+}
+
+export class InsufficientScopeError extends UnauthorizedError {
+  readonly code = "insufficient_scope"
+  override readonly status = 403
+  override readonly statusCode = 403
+
+  constructor(scopes?: ReadonlyArray<string>, message = "Insufficient Scope") {
+    super(message)
+    this.headers = getHeaders(this.code, this.message, scopes)
+  }
+}
+
+export interface JwtVerifierOptions {
+  readonly audience?: string | Array<string> | ReadonlyArray<string>
+  readonly clockTolerance?: number
+  readonly issuer?: string
+  readonly issuerBaseURL?: string
+  readonly jwksUri?: string
+  readonly maxTokenAge?: number
+  readonly secret?: string
+  readonly strict?: boolean
+  readonly tokenSigningAlg?: string
+}
+
+export interface AuthOptions extends JwtVerifierOptions {
+  readonly authRequired?: boolean
+}
+
+type Config = AuthOptions
+
+type JwtError = InsufficientScopeError | InvalidRequestError | InvalidTokenError | UnauthorizedError
+
+type ResolvedConfigBase = {
+  readonly audience: string | Array<string> | undefined
+  readonly clockTolerance: number
+  readonly issuer: string | undefined
+  readonly maxTokenAge: number | undefined
+  readonly strict: boolean
+  readonly tokenSigningAlg: string | undefined
+}
+
+type ResolvedConfig =
+  & ResolvedConfigBase
+  & (
+    | {
+      readonly key: ReturnType<typeof createRemoteJWKSet>
+      readonly keyType: "jwks"
+    }
+    | {
+      readonly key: Uint8Array
+      readonly keyType: "secret"
+    }
+  )
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null
+
+const getErrorMessage = (error: unknown) => error instanceof Error ? error.message : String(error)
+
+const normalizeAudience = (audience: Config["audience"]): string | Array<string> | undefined =>
+  Array.isArray(audience) ? Array.from(audience) : audience as string | undefined
+
+const buildDiscoveryUrl = (issuerBaseURL: string) => {
+  const url = new URL(issuerBaseURL)
+  if (!url.pathname.includes("/.well-known/")) {
+    url.pathname = url.pathname.endsWith("/")
+      ? `${url.pathname}.well-known/openid-configuration`
+      : `${url.pathname}/.well-known/openid-configuration`
+  }
+  url.search = ""
+  url.hash = ""
+  return url
+}
+
+const fetchDiscoveryDocumentPromise = async (issuerBaseURL: string) => {
+  const response = await fetch(buildDiscoveryUrl(issuerBaseURL))
+  if (!response.ok) {
+    throw new Error(`Failed to fetch authorization server metadata: ${response.status}`)
+  }
+  const json = await response.json()
+  if (!isRecord(json) || typeof json["issuer"] !== "string" || typeof json["jwks_uri"] !== "string") {
+    throw new Error("Invalid authorization server metadata")
+  }
+  return { issuer: json["issuer"], jwksUri: json["jwks_uri"] }
+}
+
+const getAuthorizationToken = (headers: HttpHeaders.Headers, authRequired: boolean) => {
+  const authorization = HttpHeaders.get(headers, "authorization")
+  if (Option.isNone(authorization)) {
+    return authRequired ? Effect.fail(new UnauthorizedError()) : Effect.succeed(Option.none<string>())
+  }
+
+  const [scheme, token] = authorization.value.split(" ")
+  if (!scheme || !token || scheme.toLowerCase() !== "bearer") {
+    return Effect.fail(new InvalidRequestError("", false))
+  }
+
+  return Effect.succeed(Option.some(token))
+}
+
+const makeResolveConfig = (config: Config) => {
+  let cached: Promise<ResolvedConfig> | undefined
+
+  return Effect.tryPromise({
+    try: () => {
+      if (!cached) {
+        cached = (async (): Promise<ResolvedConfig> => {
+          const discovery = config.issuerBaseURL
+            ? await fetchDiscoveryDocumentPromise(config.issuerBaseURL)
+            : undefined
+
+          const issuer = config.issuer ?? discovery?.issuer
+          const jwksUri = config.jwksUri ?? discovery?.jwksUri
+          const secret = config.secret
+          const base = {
+            audience: normalizeAudience(config.audience),
+            clockTolerance: config.clockTolerance ?? 5,
+            issuer,
+            maxTokenAge: config.maxTokenAge,
+            strict: config.strict ?? false,
+            tokenSigningAlg: config.tokenSigningAlg
+          } satisfies ResolvedConfigBase
+
+          if (!issuer && !secret) {
+            throw new InvalidRequestError("JWT config requires 'issuer', 'issuerBaseURL', or 'secret'")
+          }
+
+          if (!secret) {
+            if (!jwksUri) {
+              throw new InvalidRequestError("JWT config requires 'jwksUri', 'issuerBaseURL', or 'secret'")
+            }
+
+            return {
+              ...base,
+              key: createRemoteJWKSet(new URL(jwksUri)),
+              keyType: "jwks"
+            }
+          }
+
+          return {
+            ...base,
+            key: new TextEncoder().encode(secret),
+            keyType: "secret"
+          }
+        })()
+      }
+
+      return cached
+    },
+    catch: (error) =>
+      error instanceof InvalidRequestError || error instanceof InvalidTokenError
+        ? error
+        : new InvalidTokenError(getErrorMessage(error))
+  })
+}
+
+const verifyToken =
+  (resolveConfig: Effect.Effect<ResolvedConfig, InvalidRequestError | InvalidTokenError>) => (token: string) =>
+    resolveConfig.pipe(
+      Effect.flatMap((config) => {
+        const options = {
+          clockTolerance: config.clockTolerance,
+          ...(config.tokenSigningAlg ? { algorithms: [config.tokenSigningAlg] } : {}),
+          ...(config.audience !== undefined ? { audience: config.audience } : {}),
+          ...(config.issuer !== undefined ? { issuer: config.issuer } : {}),
+          ...(config.maxTokenAge !== undefined ? { maxTokenAge: config.maxTokenAge } : {})
+        }
+        const verified = config.keyType === "jwks"
+          ? Effect.tryPromise({
+            try: () => jwtVerify(token, config.key, options).then(({ protectedHeader }) => ({ protectedHeader })),
+            catch: (error) => new InvalidTokenError(getErrorMessage(error))
+          })
+          : Effect.tryPromise({
+            try: () => jwtVerify(token, config.key, options).then(({ protectedHeader }) => ({ protectedHeader })),
+            catch: (error) => new InvalidTokenError(getErrorMessage(error))
+          })
+
+        return verified.pipe(
+          Effect.flatMap(({ protectedHeader }) => {
+            const typ = protectedHeader.typ?.toLowerCase().replace(/^application\//, "")
+            return config.strict && typ !== "at+jwt"
+              ? Effect.fail(new InvalidTokenError("Unexpected 'typ' value"))
+              : Effect.void
+          })
+        )
+      })
+    )
+
+export const checkJWTI = (config: Config) => {
+  const resolveConfig = makeResolveConfig(config)
+  const verify = verifyToken(resolveConfig)
+
+  return Effect.fnUntraced(function*(headers: HttpHeaders.Headers) {
+    const token = yield* getAuthorizationToken(headers, config.authRequired !== false)
+    if (Option.isNone(token)) {
+      return
+    }
+
+    yield* verify(token.value)
+  })
+}
+
+export const checkJwt = (config: Config) => {
+  const check = checkJWTI(config)
+  return HttpMiddleware.make((app) =>
+    Effect.gen(function*() {
+      const req = yield* HttpServerRequest.HttpServerRequest
+      const response = yield* check(req.headers).pipe(
+        Effect.catch((error: JwtError) =>
+          HttpServerResponse.json({ message: error.message }, {
+            status: error.status,
+            headers: HttpHeaders.fromInput(error.headers)
+          })
+        )
+      )
+
+      if (response) {
+        return response
+      }
+
+      return yield* app
+    })
+  )
+}
+
+export class JWTError extends Data.TaggedClass("JWTError")<{
+  error: JwtError
+}> {}

package/src/{api/internal → internal}/events.ts

@@ -1,7 +1,13 @@
-import { Duration, Effect, pipe, S, Schedule, Stream } from "effect-app"
+import * as Effect from "effect-app/Effect"
 import { HttpHeaders, HttpServerResponse } from "effect-app/http"
-import { reportError } from "../../errorReporter.js"
-import { setupRequestContextFromCurrent } from "../setupRequest.js"
+import * as S from "effect-app/Schema"
+import * as Duration from "effect/Duration"
+import { pipe } from "effect/Function"
+import * as Schedule from "effect/Schedule"
+import * as Stream from "effect/Stream"
+import { reportError } from "../errorReporter.js"
+import { setupStreamingRequestContextFromCurrent } from "../setupRequest.js"
+import { storeId } from "../Store/Memory.js"
 
 // Tell the client to retry every 10 seconds if connectivity is lost
 const setRetry = Stream.succeed("retry: 10000")
@@ -9,29 +15,32 @@ const keepAlive = Stream.fromEffectSchedule(Effect.succeed(":keep-alive"), Sched
 
 let connId = BigInt(0)
 
-export const makeSSE = <A extends { id: any }, SI, SR>(
-  schema: S.Codec<A, SI, SR>
+export const makeSSE = <A extends { id: any }, SI, SRD, SRE>(
+  schema: S.Codec<A, SI, SRD, SRE>
 ) =>
 <E, R>(events: Stream.Stream<{ evt: A; namespace: string }, E, R>) =>
   Effect
     .gen(function*() {
       const id = connId++
-      const ctx = yield* Effect.services<R | SR>()
+      const ctx = yield* Effect.context<R | SRD | SRE>()
       const res = HttpServerResponse.stream(
         // workaround for different scoped behaviour for streams in Bun
         // https://discord.com/channels/795981131316985866/1098177242598756412/1389646879675125861
         Effect
           .gen(function*() {
-            yield* Effect.annotateCurrentSpan({ connectionId: id.toString() })
-            yield* Effect.logInfo("$ start listening to events, id: " + id.toString())
-            yield* Effect.addFinalizer(() => Effect.logInfo("$ end listening to events, id: " + id.toString()))
+            const ns = yield* storeId
+            yield* Effect.annotateCurrentSpan({ "network.connection.id": id.toString() })
+            yield* Effect.logInfo("$ start listening to events, id: " + id.toString() + ", ns: " + ns)
+            yield* Effect.addFinalizer(() =>
+              Effect.logInfo("$ end listening to events, id: " + id.toString() + ", ns: " + ns)
+            )
 
             const enc = new TextEncoder()
 
-            const encode = S.encodeEffect(S.fromJsonString(schema))
+            const encode = S.encodeEffect(S.fromJsonString(S.toCodecJson(schema)))
 
             const eventStream = Stream.mapEffect(
-              events,
+              Stream.filter(events, (_) => _.namespace === ns),
               (_) =>
                 encode(_.evt)
                   .pipe(Effect.map((data) => `id: ${_.evt.id}\ndata: ${data}`))
@@ -42,7 +51,7 @@ export const makeSSE = <A extends { id: any }, SI, SR>(
               Stream.merge(keepAlive),
               // Keep this unary so pipe receives a function, not a Stream value.
               (self) => Stream.merge(self, eventStream, { haltStrategy: "either" }),
-              Stream.tapCause((cause) => Effect.logError("SSE error", cause)),
+              Stream.tapCause((cause) => Effect.logError("SSE error, id: " + id.toString() + ", ns: " + ns, cause)),
               Stream.map((_) => enc.encode(_ + "\n\n"))
             )
 
@@ -65,4 +74,4 @@ export const makeSSE = <A extends { id: any }, SI, SR>(
       )
       return res
     })
-    .pipe(Effect.tapCause(reportError("Request")), setupRequestContextFromCurrent("events"))
+    .pipe(Effect.tapCause(reportError("Request")), setupStreamingRequestContextFromCurrent("events"))

package/src/{api/layerUtils.ts → layerUtils.ts}

@@ -1,6 +1,10 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { Effect, type Layer, type NonEmptyReadonlyArray, Option, ServiceMap } from "effect-app"
-import { InfraLogger } from "../logger.js"
+import type { NonEmptyReadonlyArray } from "effect-app/Array"
+import * as Context from "effect-app/Context"
+import * as Effect from "effect-app/Effect"
+import type * as Layer from "effect-app/Layer"
+import * as Option from "effect-app/Option"
+import { InfraLogger } from "./logger.js"
 
 // TODO: These LayerUtils are flaky, like in dependencies as a readonly array, it breaks when there are two entries
 // we should look at Service.MakeDeps[E/RIn/ROut] etc.
@@ -27,38 +31,38 @@ export namespace LayerUtils {
 }
 
 export type ContextTagWithDefault<Id, A, LayerE, LayerR> =
-  & ServiceMap.Service<Id, A>
+  & Context.Service<Id, A>
   & {
     Default: Layer.Layer<Id, LayerE, LayerR>
   }
 
 export namespace ContextTagWithDefault {
-  export type Base<A> = ContextTagWithDefault<any, A, any, any>
+  export type Base<A> = { readonly Service: A } & { Default: Layer.Layer<any, any, any> }
 }
 
-export type GetContext<T> = T extends ServiceMap.ServiceMap<infer Y> ? Y : never
+export type GetContext<T> = T extends Context.Context<infer Y> ? Y : never
 
 export const mergeContexts = Effect.fnUntraced(
   function*<
     T extends readonly {
       maker: any
-      handle: Effect.Effect<ServiceMap.ServiceMap<any> | Option.Option<ServiceMap.ServiceMap<any>>>
+      handle: Effect.Effect<Context.Context<any> | Option.Option<Context.Context<any>>>
     }[]
   >(
     makers: T
   ) {
-    let context = ServiceMap.empty()
+    let context = Context.empty()
     for (const mw of makers) {
       const ctx = yield* mw.handle.pipe(Effect.provide(context))
-      const moreContext = ServiceMap.isServiceMap(ctx) ? Option.some(ctx) : ctx
+      const moreContext = Context.isContext(ctx) ? Option.some(ctx) : ctx
       yield* InfraLogger.logDebug(
         "Built dynamic context for middleware" + (mw.maker.key ?? mw.maker),
         Option.map(moreContext, (c) => (c as any).toJSON().services)
       )
       if (moreContext.value) {
-        context = ServiceMap.merge(context, moreContext.value)
+        context = Context.merge(context, moreContext.value)
       }
     }
-    return context as ServiceMap.ServiceMap<Effect.Success<T[number]["handle"]>>
+    return context as Context.Context<Effect.Success<T[number]["handle"]>>
   }
 )

package/src/logger/jsonLogger.ts

@@ -1,6 +1,8 @@
-import { Array, Cause, Logger } from "effect-app"
+import * as Array from "effect-app/Array"
+import { spanAttributes } from "effect-app/RequestContext"
+import * as Cause from "effect/Cause"
+import * as Logger from "effect/Logger"
 import { CurrentLogAnnotations, CurrentLogSpans } from "effect/References"
-import { spanAttributes } from "../RequestContext.js"
 import { getRequestContextFromFiber } from "./shared.js"
 
 export const jsonLogger = Logger.make<unknown, void>(

package/src/logger/logFmtLogger.ts

@@ -1,5 +1,5 @@
-import { Logger } from "effect-app"
-import { spanAttributes } from "../RequestContext.js"
+import { spanAttributes } from "effect-app/RequestContext"
+import * as Logger from "effect/Logger"
 import { getRequestContextFromFiber } from "./shared.js"
 
 export const logfmtLogger = Logger.make<unknown, void>(

package/src/logger/shared.ts

@@ -1,13 +1,14 @@
-import { type Fiber, Option } from "effect-app"
+import * as Option from "effect-app/Option"
+import { LocaleRef, RequestContext } from "effect-app/RequestContext"
 import { NonEmptyString255 } from "effect-app/Schema"
-import { LocaleRef, RequestContext } from "../RequestContext.js"
+import type * as Fiber from "effect/Fiber"
 import { storeId } from "../Store/Memory.js"
 
 export function getRequestContextFromFiber(fiber: Fiber.Fiber<unknown, unknown>) {
   const span = Option.fromNullishOr(fiber.currentSpan)
   const locale = fiber.getRef(LocaleRef)
   const namespace = fiber.getRef(storeId)
-  return new RequestContext({
+  return RequestContext.make({
     span: Option.map(span, (s) => ({ spanId: s.spanId, traceId: s.traceId, sampled: s.sampled })).pipe(
       Option.getOrElse(() => ({ spanId: "bogus", sampled: true, traceId: "bogus" }))
     ),

package/src/{adapters/memQueue.ts → memQueue.ts}

@@ -1,5 +1,6 @@
-import { Effect, type Queue, ServiceMap } from "effect-app"
-import * as Q from "effect/Queue"
+import * as Context from "effect-app/Context"
+import * as Effect from "effect-app/Effect"
+import * as Queue from "effect/Queue"
 
 const make = Effect
   .gen(function*() {
@@ -9,13 +10,13 @@ const make = Effect
       getOrCreateQueue: Effect.fnUntraced(function*(k: string) {
         const q = store.get(k)
         if (q) return q
-        const newQ = yield* Q.unbounded<string>()
+        const newQ = yield* Queue.unbounded<string>()
         store.set(k, newQ)
         return newQ
       })
     }
   })
 
-export class MemQueue extends ServiceMap.Opaque<MemQueue>()("effect-app/MemQueue", { make }) {
+export class MemQueue extends Context.Opaque<MemQueue>()("effect-app/MemQueue", { make }) {
   static readonly Live = this.toLayer(this.make)
 }

package/src/{adapters/mongo-client.ts → mongo-client.ts}

@@ -1,4 +1,6 @@
-import { Effect, Layer, ServiceMap } from "effect-app"
+import * as Context from "effect-app/Context"
+import * as Effect from "effect-app/Effect"
+import * as Layer from "effect-app/Layer"
 import { MongoClient as MongoClient_ } from "mongodb"
 
 // TODO: we should probably share a single client...
@@ -15,7 +17,7 @@ const withClient = (url: string) =>
 
 const makeMongoClient = (url: string, dbName?: string) => Effect.map(withClient(url), (x) => ({ db: x.db(dbName) }))
 
-export class MongoClient extends ServiceMap.Service<MongoClient, {
+export class MongoClient extends Context.Service<MongoClient, {
   readonly db: ReturnType<InstanceType<typeof MongoClient_>["db"]>
 }>()("@services/MongoClient") {}
 

package/src/otel.ts

@@ -0,0 +1,152 @@
+/**
+ * OpenTelemetry semantic-convention helpers for span attributes.
+ *
+ * Aligns repository / queue / cache adapters with stable OTel semconv keys so
+ * downstream collectors and dashboards work without per-adapter mappings.
+ *
+ * - Database: https://opentelemetry.io/docs/specs/semconv/database/
+ * - Messaging: https://opentelemetry.io/docs/specs/semconv/messaging/
+ * - Cosmos DB:  https://opentelemetry.io/docs/specs/semconv/database/cosmosdb/
+ */
+
+import * as Effect from "effect-app/Effect"
+
+export type DbSystem =
+  | "postgresql"
+  | "sqlite"
+  | "cosmosdb"
+  | "mongodb"
+  | "redis"
+  | "other_sql"
+  | "memory"
+  | "disk"
+
+export interface DbSpanOptions {
+  /** OTel `db.operation.name` (e.g. `find`, `all`, `filter`, `set`). */
+  readonly operation: string
+  readonly system: DbSystem
+  /** Logical collection / table / container name. */
+  readonly collection: string
+  /** Tenant / namespace / database name. */
+  readonly namespace?: string | undefined
+  /** Application-level entity / model name (custom: `app.entity`). */
+  readonly entity?: string | undefined
+  /** Sanitized / parameterized query text. Never include bound values. */
+  readonly query?: string | undefined
+  /** Optional fragments merged into final attributes (e.g. id, partition). */
+  readonly extra?: Record<string, unknown> | undefined
+}
+
+const dbAttributes = (a: DbSpanOptions): Record<string, unknown> => ({
+  "db.system.name": a.system,
+  "db.operation.name": a.operation,
+  "db.collection.name": a.collection,
+  ...(a.namespace !== undefined && { "db.namespace": a.namespace }),
+  ...(a.query !== undefined && { "db.query.text": a.query }),
+  ...(a.entity !== undefined && { "app.entity": a.entity }),
+  ...a.extra
+})
+
+/**
+ * Wrap an effect with an OTel-semconv database span.
+ *
+ * Span name follows the low-cardinality convention: `<operation> <collection>`.
+ */
+export const withDbSpan = (a: DbSpanOptions) =>
+  Effect.withSpan(
+    `${a.operation} ${a.collection}`,
+    { attributes: dbAttributes(a), kind: "client" as const },
+    { captureStackTrace: false }
+  )
+
+/**
+ * Annotate the current span with OTel-semconv database attributes.
+ *
+ * Use when the caller already owns the span (e.g. a repository) and the
+ * adapter should only contribute db.* semconv attrs without opening a child.
+ * Annotates before running so attrs persist even on failure.
+ * No-op if there is no current span.
+ */
+export const annotateDb = (a: DbSpanOptions) => <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  Effect.flatMap(Effect.annotateCurrentSpan(dbAttributes(a)), () => self)
+
+/** Annotate the current span with response metrics from a DB call. */
+export const annotateDbResponse = (m: {
+  readonly returnedRows?: number | undefined
+  readonly responseBytes?: number | undefined
+}) =>
+  Effect.annotateCurrentSpan({
+    ...(m.returnedRows !== undefined && { "db.response.returned_rows": m.returnedRows }),
+    ...(m.responseBytes !== undefined && { "db.response.body.size": m.responseBytes })
+  })
+
+/** Cosmos-specific response annotations. */
+export const annotateCosmosResponse = (m: {
+  readonly requestCharge?: number | undefined
+  readonly returnedRows?: number | undefined
+  readonly responseBytes?: number | undefined
+  readonly statusCode?: number | undefined
+}) =>
+  Effect.annotateCurrentSpan({
+    ...(m.requestCharge !== undefined && { "azure.cosmosdb.operation.request_charge": m.requestCharge }),
+    ...(m.statusCode !== undefined && { "db.response.status_code": String(m.statusCode) }),
+    ...(m.returnedRows !== undefined && { "db.response.returned_rows": m.returnedRows }),
+    ...(m.responseBytes !== undefined && { "db.response.body.size": m.responseBytes })
+  })
+
+export type MessagingSystem =
+  | "servicebus"
+  | "rabbitmq"
+  | "kafka"
+  | "memory"
+  | "sql"
+
+export type MessagingOperation =
+  | "publish"
+  | "create"
+  | "receive"
+  | "process"
+  | "settle"
+
+export interface MessagingSpanOptions {
+  readonly operation: MessagingOperation
+  readonly system: MessagingSystem
+  /** Queue / topic name. */
+  readonly destination: string
+  readonly messageId?: string | undefined
+  readonly conversationId?: string | undefined
+  readonly bodySize?: number | undefined
+  readonly extra?: Record<string, unknown> | undefined
+}
+
+const messagingAttributes = (a: MessagingSpanOptions): Record<string, unknown> => ({
+  "messaging.system": a.system,
+  "messaging.operation.name": a.operation,
+  "messaging.destination.name": a.destination,
+  ...(a.messageId !== undefined && { "messaging.message.id": a.messageId }),
+  ...(a.conversationId !== undefined && { "messaging.message.conversation_id": a.conversationId }),
+  ...(a.bodySize !== undefined && { "messaging.message.body.size": a.bodySize }),
+  ...a.extra
+})
+
+/** Wrap an effect with an OTel-semconv messaging span. */
+export const withMessagingSpan = (
+  a: MessagingSpanOptions,
+  kind: "producer" | "consumer"
+) =>
+  Effect.withSpan(
+    `${a.operation} ${a.destination}`,
+    { kind, attributes: messagingAttributes(a) },
+    { captureStackTrace: false }
+  )
+
+/** Build messaging span options without wrapping (for Effect.fn / setupRequestContextWithCustomSpan). */
+export const messagingSpanArgs = (
+  a: MessagingSpanOptions,
+  kind: "producer" | "consumer"
+) =>
+  ({
+    name: `${a.operation} ${a.destination}`,
+    kind,
+    attributes: messagingAttributes(a)
+  }) as const