@effect-app/infra 4.0.0-beta.30 → 4.0.0-beta.301

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.ts"
 
 // 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,7 +1,9 @@
-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"
+import { getRequestContextFromFiber } from "./shared.ts"
 
 export const jsonLogger = Logger.make<unknown, void>(
   ({ cause, date, fiber, logLevel, message }) => {

package/src/logger/logFmtLogger.ts

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

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 { storeId } from "../Store/Memory.js"
+import { storeId } from "effect-app/Store"
+import type * as Fiber from "effect/Fiber"
 
 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/middlewares.ts

@@ -0,0 +1,10 @@
+/**
+ * Mechanism for extendning behaviour of all handlers on the server.
+ *
+ * @since 1.0.0
+ */
+
+export * from "./internal/auth.ts"
+export * from "./internal/events.ts"
+export * from "./internal/health.ts"
+export * from "./internal/RequestContextMiddleware.ts"

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

package/src/rateLimit.ts

@@ -20,8 +20,13 @@
 //   }
 // }
 
-import { Array, type Duration, Effect, type NonEmptyArray } from "effect-app"
+import * as Array from "effect-app/Array"
+import type { NonEmptyArray } from "effect-app/Array"
+import * as Effect from "effect-app/Effect"
+import { dual } from "effect-app/Function"
+import type * as Duration from "effect/Duration"
 import type { Semaphore } from "effect/Semaphore"
+import type { Concurrency } from "effect/Types"
 
 /**
  * Executes the specified effect, acquiring the specified number of permits
@@ -45,36 +50,42 @@ export function SEM_withPermitsDuration(permits: number, duration: Duration.Dura
   }
 }
 
-export function batchPar<R, E, A, R2, E2, A2, T>(
-  n: number,
-  forEachItem: (item: T, iWithinBatch: number, batchI: number) => Effect.Effect<A, E, R>,
-  forEachBatch: (a: NonEmptyArray<A>, i: number) => Effect.Effect<A2, E2, R2>
-) {
-  return (items: Iterable<T>) =>
-    Effect.forEach(
-      Array.chunksOf(items, n),
-      (_, i) =>
-        Effect
-          .forEach(_, (_, j) => forEachItem(_, j, i), { concurrency: "inherit" })
-          .pipe(Effect.flatMap((_) => forEachBatch(_, i))),
-      { concurrency: "inherit" }
-    )
+export interface BatchOptions {
+  readonly concurrency?: Concurrency | undefined
 }
 
-export function batch<R, E, A, R2, E2, A2, T>(
-  n: number,
-  forEachItem: (item: T, iWithinBatch: number, batchI: number) => Effect.Effect<A, E, R>,
-  forEachBatch: (a: NonEmptyArray<A>, i: number) => Effect.Effect<A2, E2, R2>
-) {
-  return (items: Iterable<T>) =>
+export const batch: {
+  <T, A, E, R, A2, E2, R2>(
+    n: number,
+    forEachItem: (item: T, iWithinBatch: number, batchI: number) => Effect.Effect<A, E, R>,
+    forEachBatch: (a: NonEmptyArray<A>, i: number) => Effect.Effect<A2, E2, R2>,
+    options?: BatchOptions
+  ): (items: Iterable<T>) => Effect.Effect<Array<A2>, E | E2, R | R2>
+  <T, A, E, R, A2, E2, R2>(
+    items: Iterable<T>,
+    n: number,
+    forEachItem: (item: T, iWithinBatch: number, batchI: number) => Effect.Effect<A, E, R>,
+    forEachBatch: (a: NonEmptyArray<A>, i: number) => Effect.Effect<A2, E2, R2>,
+    options?: BatchOptions
+  ): Effect.Effect<Array<A2>, E | E2, R | R2>
+} = dual(
+  (args) => typeof args[0] !== "number",
+  <T, A, E, R, A2, E2, R2>(
+    items: Iterable<T>,
+    n: number,
+    forEachItem: (item: T, iWithinBatch: number, batchI: number) => Effect.Effect<A, E, R>,
+    forEachBatch: (a: NonEmptyArray<A>, i: number) => Effect.Effect<A2, E2, R2>,
+    options?: BatchOptions
+  ) =>
     Effect.forEach(
       Array.chunksOf(items, n),
       (_, i) =>
         Effect
           .forEach(_, (_, j) => forEachItem(_, j, i), { concurrency: "inherit" })
-          .pipe(Effect.flatMap((_) => forEachBatch(_, i)))
+          .pipe(Effect.flatMap((_) => forEachBatch(_, i))),
+      { concurrency: options?.concurrency }
     )
-}
+)
 
 // export function rateLimit(
 //   n: number,

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

@@ -1,10 +1,14 @@
-import { Data, Effect, Layer, Option, 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 * as Option from "effect-app/Option"
+import * as Data from "effect/Data"
 import type { RedisClient as Client } from "redis"
 import Redlock from "redlock"
 
 export class ConnectionException extends Data.TaggedError("ConnectionException")<{ cause: Error; message: string }> {
   constructor(cause: Error) {
-    super({ message: "A connection error ocurred", cause })
+    super({ message: "A connection error occurred", cause })
   }
 }
 
@@ -90,7 +94,7 @@ export const makeRedisClient = (makeClient: () => Client) =>
         .pipe(Effect.uninterruptible, Effect.orDie)
   )
 
-export class RedisClient extends ServiceMap.Service<RedisClient, {
+export class RedisClient extends Context.Service<RedisClient, {
   readonly client: Client
   readonly lock: Redlock
   readonly get: (key: string) => Effect.Effect<Option.Option<string>, ConnectionException>

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

@@ -1,5 +1,6 @@
-import { Cause, Effect } from "effect-app"
-import { logError, reportError } from "../errorReporter.js"
+import * as Effect from "effect-app/Effect"
+import * as Cause from "effect/Cause"
+import { logError, reportError } from "./errorReporter.ts"
 
 // const onExitReportError = (name: string, unknownOnly?: boolean) => {
 //   const report = reportError(name)

package/src/{api/routing → routing}/middleware/RouterMiddleware.ts

@@ -1,13 +1,14 @@
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
 /* eslint-disable @typescript-eslint/no-unsafe-return */
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { type Layer, type ServiceMap } from "effect-app"
+import type * as Context from "effect-app/Context"
+import type * as Layer from "effect-app/Layer"
 import { type GetContextConfig, type RpcContextMap } from "effect-app/rpc/RpcContextMap"
 import { type RpcMiddlewareV4 } from "effect-app/rpc/RpcMiddleware"
 // module:
 //
 
-// v4: middleware tags are ServiceMap.Service (not Effect) — they carry the RpcMiddlewareV4 as their service Shape
+// v4: middleware tags are Context.Service (not Effect) — they carry the RpcMiddlewareV4 as their service Shape
 export type RouterMiddleware<
   Self,
   RequestContextMap extends Record<string, RpcContextMap.Any>, // what services will the middlware provide dynamically to the next, or raise errors.
@@ -18,9 +19,9 @@ export type RouterMiddleware<
   _ContextProviderR, // what the context provider requires
   RequestContextId
 > =
-  & ServiceMap.Service<Self, RpcMiddlewareV4<ContextProviderA, ContextProviderE, never>>
+  & Context.Service<Self, RpcMiddlewareV4<ContextProviderA, ContextProviderE, never>>
   & {
     readonly Default: Layer.Layer<Self, MakeMiddlewareE, MakeMiddlewareR>
-    readonly requestContext: ServiceMap.Service<RequestContextId, GetContextConfig<RequestContextMap>>
+    readonly requestContext: Context.Service<RequestContextId, GetContextConfig<RequestContextMap>>
     readonly requestContextMap: RequestContextMap
   }

package/src/routing/middleware/middleware.ts

@@ -0,0 +1,196 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { ConfigureInterruptibilityMiddleware, DevMode, DevModeMiddleware, LoggerMiddleware, RequestCacheMiddleware } from "effect-app/middleware"
+import { RpcContextMap, type RpcMiddleware } from "effect-app/rpc"
+import { pretty } from "effect-app/utils"
+import * as Array from "effect/Array"
+import * as Cause from "effect/Cause"
+import * as Config from "effect/Config"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+import { type Rpc } from "effect/unstable/rpc"
+import { logError, reportError } from "../../errorReporter.ts"
+import { InfraLogger } from "../../logger.ts"
+import { WithNsTransaction } from "../../Store/SQL.ts"
+
+const logRequestError = logError("Request")
+const reportRequestError = reportError("Request")
+
+// Summarize an rpc payload for the `rpc.request.payload` span attribute.
+// Scalars are kept (long strings snipped), nested objects are recursed into up
+// to `PAYLOAD_MAX_DEPTH` so useful inputs (carrier, packageType, dimensions, ids,
+// …) are captured. Arrays are sampled to the first `PAYLOAD_ARRAY_HEAD` elements
+// (with a `…N more` marker when longer) so pack/pick item arrays — one entry per
+// article, quantity folded into `amount` — are diagnosable without dumping the
+// whole tail on every (high-frequency) SaveItems.
+const PAYLOAD_MAX_DEPTH = 4
+const PAYLOAD_ARRAY_HEAD = 20
+const REDACTED_KEYS = new Set(["password", "secret", "token"])
+
+const summarizePayloadValue = (key: string, value: unknown, depth: number): unknown => {
+  if (REDACTED_KEYS.has(key)) return "<redacted>"
+  if (typeof value === "string") return value.length > 256 ? value.substring(0, 253) + "..." : value
+  if (typeof value === "number" || typeof value === "boolean") return value
+  if (value === null || value === undefined) return `${value}`
+  if (Array.isArray(value)) {
+    if (depth >= PAYLOAD_MAX_DEPTH) return `Array[${value.length}]`
+    const head = value.slice(0, PAYLOAD_ARRAY_HEAD).map((v) => summarizePayloadValue(key, v, depth + 1))
+    return value.length > PAYLOAD_ARRAY_HEAD ? [...head, `…${value.length - PAYLOAD_ARRAY_HEAD} more`] : head
+  }
+  if (typeof value === "object") {
+    return depth >= PAYLOAD_MAX_DEPTH
+      ? `Object[${Object.keys(value).length}]`
+      : Object.entries(value).reduce((prev, [k, v]) => {
+        prev[k] = summarizePayloadValue(k, v, depth + 1)
+        return prev
+      }, {} as Record<string, unknown>)
+  }
+  return typeof value
+}
+
+const summarizePayload = (payload: unknown): unknown =>
+  typeof payload === "object" && payload !== null
+    ? Object.entries(payload).reduce((prev, [key, value]) => {
+      prev[key] = summarizePayloadValue(key, value, 1)
+      return prev
+    }, {} as Record<string, unknown>)
+    : payload
+
+// TODO: do we need this as middleware or just as layer?
+export const DevModeLive = Layer.effect(
+  DevMode,
+  Effect.gen(function*() {
+    const env = yield* Config.string("env").pipe(Config.withDefault("local-dev"))
+    return env !== "prod"
+  })
+)
+
+export const RequestCacheMiddlewareLive = Layer.succeed(
+  RequestCacheMiddleware,
+  (effect) => effect
+)
+
+const isOptimisticConcurrencyException = (input: unknown) =>
+  typeof input === "object" && input !== null && "_tag" in input && input._tag === "OptimisticConcurrencyException"
+
+export const RequestType = Context.Reference<"command" | "query">(
+  "@effect-app/infra/routing/RequestType",
+  { defaultValue: () => "query" }
+)
+
+export const ConfigureInterruptibilityMiddlewareLive = Layer.effect(
+  ConfigureInterruptibilityMiddleware,
+  Effect.gen(function*() {
+    return (effect, { rpc }) => {
+      const requestType = Context.get(rpc.annotations, RequestType)
+      const isCommand = requestType === "command"
+
+      effect = isCommand
+        ? Effect.retry(effect, { times: 1, while: isOptimisticConcurrencyException })
+        : Effect.interruptible(effect)
+
+      return effect
+    }
+  })
+)
+
+export const LoggerMiddlewareLive = Layer
+  .effect(
+    LoggerMiddleware,
+    Effect.gen(function*() {
+      const devMode = yield* DevMode
+      return (effect, { headers, payload, rpc }) =>
+        Effect
+          .annotateCurrentSpan({
+            "rpc.method": rpc._tag,
+            "rpc.request.payload": summarizePayload(payload)
+          })
+          .pipe(
+            Effect.andThen(effect),
+            // TODO: support SchemaError if the error channel of the request allows it.. but who would want that?
+            Effect.catch((_) => Schema.isSchemaError(_) ? Effect.die(_) : Effect.fail(_)),
+            Effect.tapCause((cause) => Cause.hasFails(cause) ? logRequestError(cause) : Effect.void),
+            Effect.tapCauseIf(Cause.hasDies, (cause) =>
+              Effect
+                .all([
+                  reportRequestError(cause, {
+                    action: rpc._tag
+                  }),
+                  InfraLogger
+                    .logError("Finished request", cause)
+                    .pipe(Effect.annotateLogs({
+                      action: rpc._tag,
+                      req: pretty(payload),
+                      headers: pretty(headers)
+                      // resHeaders: pretty(
+                      //   Object
+                      //     .entries(headers)
+                      //     .reduce((prev, [key, value]) => {
+                      //       prev[key] = value && typeof value === "string" ? snipString(value) : value
+                      //       return prev
+                      //     }, {} as Record<string, any>)
+                      // )
+                    }))
+                ])),
+            devMode ? (_) => _ : Effect.catchDefect(() => Effect.die("Internal Server Error"))
+          )
+    })
+  )
+  .pipe(Layer.provide(DevModeLive))
+
+export const DevModeMiddlewareLive = Layer
+  .effect(
+    DevModeMiddleware,
+    Effect.gen(function*() {
+      const devMode = yield* DevMode
+      return (effect) => Effect.provideService(effect, DevMode, devMode)
+    })
+  )
+  .pipe(Layer.provide(DevModeLive))
+
+export const DefaultGenericMiddlewaresLive = Layer.mergeAll(
+  RequestCacheMiddlewareLive,
+  ConfigureInterruptibilityMiddlewareLive,
+  LoggerMiddlewareLive,
+  DevModeMiddlewareLive
+)
+
+/**
+ * Config entry for `RequestContextMap` that controls per-RPC transaction wrapping.
+ * Defaults to `false` (no transaction). Set `requiresTransaction: true` on a route to enable.
+ *
+ * @example
+ * ```ts
+ * class RequestContextMap extends RpcContextMap.makeMap({
+ *   requiresTransaction: requiresTransactionConfig,
+ *   // ...
+ * }) {}
+ * ```
+ */
+export const requiresTransactionConfig = RpcContextMap.makeCustom()(Schema.Never, false)
+
+/**
+ * Creates the middleware Effect for SQL transaction wrapping.
+ * Requires `WithNsTransaction` service.
+ * Reads `requiresTransaction` from the RPC config; defaults to `false`.
+ *
+ * @example
+ * ```ts
+ * const SqlTransactionMiddlewareLive = Layer.effect(
+ *   SqlTransactionMiddleware,
+ *   makeSqlTransactionMiddleware(RequestContextMap)
+ * )
+ * ```
+ */
+export const makeSqlTransactionMiddleware = Effect.fnUntraced(function*(
+  rcm: { getConfig: (rpc: Rpc.AnyWithProps) => { readonly requiresTransaction?: boolean } }
+) {
+  const withTx = yield* WithNsTransaction
+  const mw: RpcMiddleware.RpcMiddlewareV4<never, never, never> = (effect, { rpc }) => {
+    const { requiresTransaction } = rcm.getConfig(rpc)
+    if (requiresTransaction !== true) return effect
+    return withTx(effect)
+  }
+  return mw
+})

package/src/routing/middleware.ts

@@ -0,0 +1,4 @@
+// codegen:start {preset: barrel, include: ./middleware/*.ts, nodir: false }
+export * from "./middleware/middleware.ts"
+export * from "./middleware/RouterMiddleware.ts"
+// codegen:end

package/src/{api/routing → routing}/schema/jwt.ts

@@ -1,7 +1,8 @@
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { Effect, Option } from "effect"
 import * as S from "effect-app/Schema"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
 import { jwtDecode, type JwtDecodeOptions } from "jwt-decode"
 
 export const parseJwt = <Sch extends S.Top>(

package/src/{api/routing → routing}/utils.ts

@@ -1,5 +1,6 @@
-import { S, SchemaAST } from "effect-app"
+import * as S from "effect-app/Schema"
 import type { AST } from "effect-app/Schema"
+import * as SchemaAST from "effect-app/SchemaAST"
 
 const get = ["Get", "Index", "List", "All", "Find", "Search"]
 const del = ["Delete", "Remove", "Destroy"]