effect-app 4.0.0-beta.25 → 4.0.0-beta.251

package/src/rpc/MiddlewareMaker.ts

@@ -1,14 +1,15 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { Effect, Layer, type Schema, Schema as S, type Scope, ServiceMap } from "effect"
 import { type NonEmptyArray, type NonEmptyReadonlyArray } from "effect/Array"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as S from "effect/Schema"
+import type * as Scope from "effect/Scope"
 import { type Simplify } from "effect/Types"
 import { Rpc, type RpcGroup, type RpcSchema } from "effect/unstable/rpc"
 import { type HandlersFrom } from "effect/unstable/rpc/RpcGroup"
-import { type RequestId } from "effect/unstable/rpc/RpcMessage"
-import { type HttpHeaders } from "../http.js"
+import * as Context from "../Context.js"
 import { PreludeLogger } from "../logger.js"
 import { type TypeTestId } from "../TypeTest.js"
-import { typedValuesOf } from "../utils.js"
 import { type GetContextConfig, type RequestContextMapTagAny, type RpcContextMap } from "./RpcContextMap.js"
 import { type AddMiddleware, type AnyDynamic, type RpcDynamic, type RpcMiddlewareV4, type TagClassAny } from "./RpcMiddleware.js"
 import * as RpcMiddlewareX from "./RpcMiddleware.js"
@@ -61,13 +62,13 @@ export interface MiddlewareMaker<
     }
   >
 {
-  readonly layer: Layer.Layer<Self, never, ServiceMap.Service.Identifier<MiddlewareProviders[number]>>
+  readonly layer: Layer.Layer<Self, never, Context.Service.Identifier<MiddlewareProviders[number]>>
   readonly requestContext: RequestContextTag<RequestContextMap>
   readonly requestContextMap: RequestContextMap
 }
 
 export interface RequestContextTag<RequestContextMap extends Record<string, RpcContextMap.Any>>
-  extends ServiceMap.Service<"RequestContextConfig", GetContextConfig<RequestContextMap>>
+  extends Context.Service<"RequestContextConfig", GetContextConfig<RequestContextMap>>
 {}
 
 export namespace MiddlewareMaker {
@@ -93,7 +94,7 @@ export namespace MiddlewareMaker {
     : never
     : never
 
-  export type Errors<T> = T extends TagClassAny ? T extends { error: S.Top } ? S.Schema.Type<T["error"]>
+  export type Errors<T> = T extends TagClassAny ? T extends { error: S.Top } ? T["error"]["Type"]
     : never
     : never
 
@@ -169,9 +170,9 @@ export interface BuildingMiddleware<
 > {
   rpc: <
     const Tag extends string,
-    Payload extends Schema.Top | Schema.Struct.Fields = typeof Schema.Void,
-    Success extends Schema.Top = typeof Schema.Void,
-    Error extends Schema.Top = typeof Schema.Never,
+    Payload extends S.Top | S.Struct.Fields = typeof S.Void,
+    Success extends S.Top = typeof S.Void,
+    Error extends S.Top = typeof S.Never,
     const Stream extends boolean = false,
     Config extends GetContextConfig<RequestContextMap> = {}
   >(tag: Tag, options?: {
@@ -180,16 +181,16 @@ export interface BuildingMiddleware<
     readonly error?: Error
     readonly stream?: Stream
     readonly config?: Config
-    readonly primaryKey?: [Payload] extends [Schema.Struct.Fields] ? ((
-        payload: Payload extends Schema.Struct.Fields ? Simplify<Schema.Struct<Payload>["Type"]> : Payload["Type"]
+    readonly primaryKey?: [Payload] extends [S.Struct.Fields] ? ((
+        payload: Payload extends S.Struct.Fields ? Simplify<S.Struct<Payload>["Type"]> : Payload["Type"]
       ) => string)
       : never
   }) =>
     & Rpc.Rpc<
       Tag,
-      Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload,
+      Payload extends S.Struct.Fields ? S.Struct<Payload> : Payload,
       Stream extends true ? RpcSchema.Stream<Success, Error> : Success,
-      Stream extends true ? typeof Schema.Never : Error
+      Stream extends true ? typeof S.Never : Error
     >
     & { readonly config: Config }
 
@@ -258,10 +259,10 @@ export type MiddlewaresBuilder<
     : { new(_: never): {} }
     : { new(_: never): {} })
 
-const middlewareMaker = <
+const middlewareMaker = Effect.fnUntraced(function*<
   MiddlewareProviders extends ReadonlyArray<MiddlewareMaker.Any>
->(middlewares: MiddlewareProviders): Effect.Effect<
-  RpcMiddlewareV4<
+>(middlewares: MiddlewareProviders) {
+  type Middleware = RpcMiddlewareV4<
     MiddlewareMaker.ManyProvided<MiddlewareProviders>,
     MiddlewareMaker.ManyErrors<MiddlewareProviders>,
     Exclude<
@@ -270,42 +271,32 @@ const middlewareMaker = <
     > extends never ? never
       : Exclude<MiddlewareMaker.ManyRequired<MiddlewareProviders>, MiddlewareMaker.ManyProvided<MiddlewareProviders>>
   >
-> => {
+  type Next = Parameters<Middleware>[0]
+  type Options = Parameters<Middleware>[1]
+
   // we want to run them in reverse order because latter middlewares will provide context to former ones
-  middlewares = middlewares.toReversed() as any
-
-  return Effect.gen(function*() {
-    const context = yield* Effect.services()
-
-    // returns a Effect/RpcMiddlewareV4 with Scope.Scope in requirements
-    // v4: wrap middleware takes (effect, options) as two params instead of a single options bag
-    return (
-      next: Effect.Effect<any, any, any>,
-      options: {
-        readonly clientId: number
-        readonly requestId: RequestId
-        readonly rpc: Rpc.AnyWithProps
-        readonly payload: unknown
-        readonly headers: HttpHeaders.Headers
-      }
-    ) => {
-      // we start with the actual handler
-      let handler = next
-
-      // inspired from Effect/RpcMiddleware
-      for (const tag of middlewares) {
-        // use the tag to get the middleware from context
-        const middleware = ServiceMap.getUnsafe(context, tag)
-
-        // wrap the current handler, allowing the middleware to run before and after it
-        handler = PreludeLogger.logDebug("Applying middleware wrap " + tag.key).pipe(
-          Effect.andThen(middleware(handler, options))
-        ) as any
-      }
-      return handler
+  const reversed = middlewares.toReversed()
+  const context = yield* Effect.context()
+
+  // returns a Effect/RpcMiddlewareV4 with Scope.Scope in requirements
+  // v4: wrap middleware takes (effect, options) as two params instead of a single options bag
+  return (next: Next, options: Options) => {
+    // we start with the actual handler
+    let handler = next
+
+    // inspired from Effect/RpcMiddleware
+    for (const tag of reversed) {
+      // use the tag to get the middleware from context
+      const middleware = Context.getUnsafe(context, tag)
+
+      // wrap the current handler, allowing the middleware to run before and after it
+      handler = PreludeLogger.logDebug("Applying middleware wrap " + tag.key).pipe(
+        Effect.andThen(middleware(handler, options))
+      ) as any
     }
-  }) as any
-}
+    return handler
+  }
+})
 
 const makeMiddlewareBasic = <Self>() =>
 // by setting RequestContextMap beforehand, execute contextual typing does not fuck up itself to anys
@@ -321,7 +312,26 @@ const makeMiddlewareBasic = <Self>() =>
   // reverse middlewares and wrap one after the other
   const middleware = middlewareMaker(make)
 
-  const failures = make.map((_) => _.error).filter(Boolean)
+  // Per-middleware error: union of the static `error` on the tag (if any) AND
+  // the rcm config entry pointed at by the middleware's `dynamic.key` (if any).
+  // Reason: middlewares declared with `dynamic: RequestContextMap.get("foo")`
+  // don't set a static `error` field — at runtime their `.error` defaults to
+  // `S.Never`. Without pulling from rcm, the composite middleware's
+  // `.error` collapses to `Never`, and `Rpc.exitSchema` (which walks
+  // `rpc.middlewares[*].error` to build the wire failure union) can't decode
+  // the actual middleware-thrown error type. Critical for stream rpcs whose
+  // top-level `errorSchema` is force-set to `Never` by effect-rpc.
+  const isMeaningfulError = (e: S.Top | undefined): e is S.Top => e !== undefined && e !== null && e !== S.Never
+  const rcmRecord = rcm as Record<string, RpcContextMap.Any>
+  const failures: Array<S.Top> = make.flatMap((_) => {
+    const out: Array<S.Top> = []
+    if (isMeaningfulError(_.error)) out.push(_.error)
+    const key = _.dynamic?.key as string | undefined
+    if (key && rcmRecord[key] && isMeaningfulError(rcmRecord[key].error)) {
+      out.push(rcmRecord[key].error)
+    }
+    return out
+  })
   const provides = make.flatMap((_) => !_.provides ? [] : Array.isArray(_.provides) ? _.provides : [_.provides])
   const requires = make
     .flatMap((_) => !_.requires ? [] : Array.isArray(_.requires) ? _.requires : [_.requires])
@@ -357,17 +367,18 @@ const makeMiddlewareBasic = <Self>() =>
     .effect(
       MiddlewareMaker,
       middleware as Effect.Effect<
-        any,
-        Effect.Error<typeof middleware>,
-        Effect.Services<typeof middleware>
+        any
       >
+      // todo; they dont change the type..
+      //  Effect.Error<typeof middleware>,
+      //  Effect.Services<typeof middleware>
     )
 
   // add to the tag a default implementation
   return Object.assign(MiddlewareMaker, {
     layer,
     // tag to be used to retrieve the RequestContextConfig from Rpc annotations
-    requestContext: ServiceMap.Service<"RequestContextConfig", GetContextConfig<RequestContextMap>>(
+    requestContext: Context.Service<"RequestContextConfig", GetContextConfig<RequestContextMap>>(
       "RequestContextConfig"
     ),
     requestContextMap: rcm
@@ -379,8 +390,8 @@ export const Tag = <Self>() =>
   const Id extends string,
   RequestContextMap extends RequestContextMapTagAny
 >(id: Id, rcm: RequestContextMap): MiddlewaresBuilder<Self, Id, RequestContextMap["config"]> => {
-  let allMiddleware: MiddlewareMaker.Any[] = []
-  const requestContext = ServiceMap.Service<"RequestContextConfig", GetContextConfig<RequestContextMap["config"]>>(
+  const allMiddleware: MiddlewareMaker.Any[] = []
+  const requestContext = Context.Service<"RequestContextConfig", GetContextConfig<RequestContextMap["config"]>>(
     "RequestContextConfig"
   )
   const it = {
@@ -388,9 +399,9 @@ export const Tag = <Self>() =>
     // rpc with config
     rpc: <
       const Tag extends string,
-      Payload extends Schema.Top | Schema.Struct.Fields = typeof Schema.Void,
-      Success extends Schema.Top = typeof Schema.Void,
-      Error extends Schema.Top = typeof Schema.Never,
+      Payload extends S.Top | S.Struct.Fields = typeof S.Void,
+      Success extends S.Top = typeof S.Void,
+      Error extends S.Top = typeof S.Never,
       const Stream extends boolean = false,
       Config extends GetContextConfig<RequestContextMap["config"]> = {}
     >(tag: Tag, options?: {
@@ -399,35 +410,32 @@ export const Tag = <Self>() =>
       readonly error?: Error
       readonly stream?: Stream
       readonly config?: Config
-      readonly primaryKey?: [Payload] extends [Schema.Struct.Fields] ? ((
-          payload: Payload extends Schema.Struct.Fields ? Simplify<Schema.Struct<Payload>["Type"]> : Payload["Type"]
+      readonly primaryKey?: [Payload] extends [S.Struct.Fields] ? ((
+          payload: Payload extends S.Struct.Fields ? Simplify<S.Struct<Payload>["Type"]> : Payload["Type"]
         ) => string)
         : never
     }):
       & Rpc.Rpc<
         Tag,
-        Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload,
+        Payload extends S.Struct.Fields ? S.Struct<Payload> : Payload,
         // TODO: enhance `Error`. type based on middleware config.
         Stream extends true ? RpcSchema.Stream<Success, Error> : Success,
-        Stream extends true ? typeof Schema.Never : Error
+        Stream extends true ? typeof S.Never : Error
       >
       & { config: Config } =>
     {
       const config = options?.config ?? {} as Config
 
-      // based on the config, we must enhance (union) or set failures.
-      // TODO: we should only include errors that are relevant based on the middleware config.ks
-      const error = options?.error
-      const errors = typedValuesOf(rcm.config).map((_) => _.error).filter((_) => _ && _ !== S.Never) // TODO: only the errors relevant based on config
-      const allErrors = error ? [error, ...errors] : errors
-      const [firstError, ...restErrors] = allErrors
-      const newError = firstError ? S.Union([firstError, ...restErrors]) : S.Never
-
+      // The rpc's `error` schema carries ONLY the request's own declared errors.
+      // Middleware errors (rcm-derived) reach the wire via the middleware tag
+      // attached to the rpc group later (`RpcGroup.middleware(...)` at the
+      // routing/client level), and are unioned into the failure schema by
+      // `Rpc.exitSchema`'s `rpc.middlewares[*].error` walk.
       // @ts-expect-error — TypeScript can't prove Simplify<T> ≡ { [K in keyof T]: T[K] } for unresolved generics (primaryKey)
       const rpc = Rpc.make(tag, {
         ...options?.payload !== undefined ? { payload: options.payload } : {},
         ...options?.success !== undefined ? { success: options.success } : {},
-        error: newError,
+        ...options?.error !== undefined ? { error: options.error } : {},
         ...options?.stream !== undefined ? { stream: options.stream } : {},
         ...options?.primaryKey !== undefined ? { primaryKey: options.primaryKey } : {}
       }) as any
@@ -437,7 +445,7 @@ export const Tag = <Self>() =>
     middleware: (...middlewares: any[]) => {
       for (const mw of middlewares) {
         // recall that we run middlewares in reverse order
-        allMiddleware = [mw, ...allMiddleware]
+        allMiddleware.unshift(mw)
       }
       return allMiddleware.filter((m) => !!m.dynamic).length !== Object.keys(rcm.config).length
         // for sure, until all the dynamic middlewares are provided it's non sensical to call makeMiddlewareBasic

package/src/rpc/README.md

@@ -3,7 +3,7 @@
 The extensions use V4 format of RPC middleware:
 
 - supports `requires` besides `provides`
-- `requires` and `provides`  should be set as second generic argument: `Tag<Self, Config>`.
+- `requires` and `provides` should be set as second generic argument: `Tag<Self, Config>`.
 - `wrap: true` is the default, there is no classic `provides: Tag`
 
 ## Features
@@ -34,7 +34,7 @@ NOTE: perhaps not as useful anymore if support for dynamic middleware gets integ
 
 ## Examples
 
-See  [tests](../../../infra/test/rpc-multi-middleware.test.ts)
+See [tests](../../../infra/test/rpc-multi-middleware.test.ts)
 
 ## Future
 

package/src/rpc/RpcContextMap.ts

@@ -2,14 +2,15 @@
 /* eslint-disable @typescript-eslint/no-unsafe-return */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
-import { type Schema as S, ServiceMap } from "effect"
+import type * as S from "effect/Schema"
 import { type AnyWithProps } from "effect/unstable/rpc/Rpc"
+import * as Context from "../Context.js"
 import { type RpcDynamic } from "./RpcMiddleware.js"
 
 type Values<T extends Record<any, any>> = T[keyof T]
 
 /**
- * Middleware is inactivate by default, the Key is optional in route context, and the service is optionally provided as Effect ServiceMap.
+ * Middleware is inactivate by default, the Key is optional in route context, and the service is optionally provided as Effect Context.
  * Unless explicitly configured as `true`.
  */
 export type RpcContextMap<Service, E> = {
@@ -22,7 +23,7 @@ export type RpcContextMap<Service, E> = {
 
 export declare namespace RpcContextMap {
   /**
-   * Middleware is active by default, and provides the Service at Key in route context, and the Service is provided as Effect ServiceMap.
+   * Middleware is active by default, and provides the Service at Key in route context, and the Service is provided as Effect Context.
    * Unless explicitly omitted.
    */
   export type Inverted<Service, E> = {
@@ -97,7 +98,7 @@ export type GetEffectError<RequestContextMap extends Record<string, RpcContextMa
   }
 >
 
-const tag = ServiceMap.Service("RequestContextConfig")
+const tag = Context.Service("RequestContextConfig")
 
 export const makeMap = <const Config extends Record<string, RpcContextMap.Any>>(config: Config) => {
   const cls = class {
@@ -109,7 +110,7 @@ export const makeMap = <const Config extends Record<string, RpcContextMap.Any>>(
   return Object.assign(cls, {
     config, /** Retrieves RequestContextConfig out of the Rpc annotations */
     getConfig: (rpc: AnyWithProps): GetContextConfig<Config> => {
-      return ServiceMap.getOrElse(rpc.annotations, tag as any, () => ({}))
+      return Context.getOrElse(rpc.annotations, tag as any, () => ({}))
     },
     /** Adapter used when setting the dynamic prop on a middleware implementation */
     get: <

package/src/rpc/RpcMiddleware.ts

@@ -1,17 +1,21 @@
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
 /* eslint-disable @typescript-eslint/no-unsafe-return */
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { type Effect, type Schema, type Schema as S, type Scope, type ServiceMap, type Stream } from "effect"
 import { type NonEmptyReadonlyArray } from "effect/Array"
+import type * as Effect from "effect/Effect"
+import type * as S from "effect/Schema"
+import type * as Scope from "effect/Scope"
+import type * as Stream from "effect/Stream"
 import { type Rpc, RpcMiddleware } from "effect/unstable/rpc"
 import { type TypeId } from "effect/unstable/rpc/RpcMiddleware"
+import type * as Context from "../Context.js"
 import { type GetEffectContext, type RpcContextMap } from "./RpcContextMap.js"
 
 export type RpcMiddlewareV4<Provides, E, Requires> = RpcMiddleware.RpcMiddleware<Provides, E, Requires>
 
 export type RpcOptionsOriginal = {
   readonly optional?: boolean
-  readonly error?: Schema.Top
+  readonly error?: S.Top
   readonly requiredForClient?: boolean
 }
 
@@ -39,7 +43,7 @@ export interface TagClassAny extends RpcMiddleware.AnyService {
   readonly optional: boolean
   readonly provides: any
   readonly requires: any
-  readonly error: Schema.Top
+  readonly error: S.Top
   readonly dynamic?: RpcDynamic<any, any> | undefined
   readonly dependsOn?: NonEmptyReadonlyArray<AnyDynamic> | undefined
 }
@@ -49,27 +53,29 @@ export declare namespace TagClass {
    * @since 1.0.0
    * @category models
    */
-  export type FailureSchema<Options> = Options extends { readonly error: Schema.Top; readonly optional?: false }
+  export type FailureSchema<Options> = Options extends { readonly error: S.Top; readonly optional?: false }
     ? Options["error"]
     // actually not, the Failure depends on Dynamic Middleware Configuration!
     // : Options extends { readonly dynamic: RpcDynamic<any, infer A> } ? A["error"]
-    : typeof Schema.Never
+    : typeof S.Never
 
   /**
    * @since 1.0.0
    * @category models
    */
-  export type Failure<Options> = Options extends { readonly error: Schema.Codec<infer _A>; readonly optional?: false }
-    ? _A
+  export type Failure<Options> = Options extends { readonly error: S.Codec<infer _A>; readonly optional?: false } ? _A
     // actually not, the Failure depends on Dynamic Middleware Configuration!
-    : Options extends { readonly dynamic: RpcDynamic<any, infer A> } ? S.Schema.Type<A["error"]>
+    : Options extends { readonly dynamic: RpcDynamic<any, infer A> } ? A["error"]["Type"]
     : never
 
   /**
    * @since 1.0.0
    * @category models
    */
-  export type FailureContext<Options> = Schema.Codec.DecodingServices<FailureSchema<Options>>
+  // Avoid `S.Codec.DecodingServices<X> = X extends Top ? X["DecodingServices"] : never`:
+  // tsgo fails to reduce it here and leaves `unknown`. `FailureSchema<Options>` is
+  // always `S.Top` (either `Options["error"]` or `typeof S.Never`), so read directly.
+  export type FailureContext<Options> = FailureSchema<Options>["DecodingServices"]
 
   /**
    * @since 1.0.0
@@ -102,8 +108,8 @@ export declare namespace TagClass {
       requires?: any
       provides?: any
     }
-  > extends ServiceMap.Service<Self, Service> {
-    new(_: never): ServiceMap.ServiceClass.Shape<Name, Service>
+  > extends Context.Service<Self, Service> {
+    new(_: never): Context.ServiceClass.Shape<Name, Service>
     readonly [TypeId]: TypeId
     readonly optional: Optional<Options>
     readonly error: FailureSchema<Options>
@@ -226,7 +232,7 @@ export type ExtractProvides<R extends Rpc.Any, Tag extends string> = R extends
   Rpc.Rpc<Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires> ? _Middleware extends {
     readonly provides: infer _P
   } ? [_P] extends [never] ? never
-    : _P /*_P extends ServiceMap.Service<infer _I, infer _S> ? _I
+    : _P /*_P extends Context.Service<infer _I, infer _S> ? _I
     : never */
   : never
   : never

package/src/rpc.ts

@@ -1,4 +1,4 @@
-export * as RpcX from "./rpc.js"
+export * as Invalidation from "./rpc/Invalidation.js"
 export * as MiddlewareMaker from "./rpc/MiddlewareMaker.js"
 export * as RpcContextMap from "./rpc/RpcContextMap.js"
 export * as RpcMiddleware from "./rpc/RpcMiddleware.js"

package/src/runtime.ts

@@ -0,0 +1,56 @@
+import * as Exit from "effect/Exit"
+import { flow } from "effect/Function"
+import * as Logger from "effect/Logger"
+import * as ManagedRuntime from "effect/ManagedRuntime"
+import { CauseException } from "./client/errors.js"
+import { type Context } from "./Context.js"
+import * as Effect from "./Effect.js"
+import * as Layer from "./Layer.js"
+
+export const makeAppRuntime = Effect.fnUntraced(function*<A, E>(layer: Layer.Layer<A, E>) {
+  const l = layer.pipe(
+    Layer.provide(Logger.layer([Logger.consolePretty()]))
+  ) as Layer.Layer<A>
+  const mrt = ManagedRuntime.make(l)
+  yield* mrt.contextEffect
+  return Object.assign(mrt, {
+    [Symbol.dispose]() {
+      return Effect.runSync(mrt.disposeEffect)
+    },
+
+    [Symbol.asyncDispose]() {
+      return mrt.dispose()
+    }
+  }) // as we initialise here, there is no more error left.
+})
+
+export function initializeSync<A, E>(layer: Layer.Layer<A, E>) {
+  const runtime = Effect.runSync(makeAppRuntime(layer))
+  return runtime
+}
+
+export function initializeAsync<A, E>(layer: Layer.Layer<A, E>) {
+  return Effect
+    .runPromise(makeAppRuntime(layer))
+}
+
+// we wrap into CauseException because we want to keep the full cause of the failure.
+export const makeRunPromise = <T>(services: Context<T>) =>
+  flow(Effect.runPromiseExitWith(services), (_) =>
+    _.then(
+      Exit.match({
+        onFailure: (cause) => Promise.reject(new CauseException(cause, "runPromise")),
+        onSuccess: (value) => Promise.resolve(value)
+      })
+    ))
+
+export const makeRunSync = <T>(services: Context<T>) =>
+  flow(
+    Effect.runSyncExitWith(services),
+    Exit.match({
+      onFailure: (cause) => {
+        throw new CauseException(cause, "runSync")
+      },
+      onSuccess: (value) => value
+    })
+  )

package/src/setupRequest.ts

@@ -0,0 +1,134 @@
+import * as Tracer from "effect/Tracer"
+import { SqlClient } from "effect/unstable/sql"
+import * as Effect from "./Effect.js"
+import * as Layer from "./Layer.js"
+import * as Option from "./Option.js"
+import { LocaleRef, RequestContext, spanAttributes } from "./RequestContext.js"
+import { NonEmptyString255 } from "./Schema.js"
+import { ContextMapContainer, storeId } from "./Store.js"
+
+const withSqlTransaction = <R, E, A>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  Effect.serviceOption(SqlClient.SqlClient).pipe(
+    Effect.flatMap(Option.match({
+      onNone: () => self,
+      onSome: (sql) => sql.withTransaction(self).pipe(Effect.orDie)
+    }))
+  )
+
+export const getRequestContext = Effect
+  .all({
+    span: Effect.currentSpan.pipe(Effect.orDie),
+    locale: LocaleRef,
+    namespace: storeId
+  })
+  .pipe(
+    Effect.map(({ locale, namespace, span }) =>
+      RequestContext.make({
+        span: Tracer.externalSpan(span),
+        locale,
+        namespace,
+        name: NonEmptyString255(span.name)
+      })
+    )
+  )
+
+export const getRC = Effect.all({
+  locale: LocaleRef,
+  namespace: storeId
+})
+
+const withRequestSpan = (name = "request", options?: Tracer.SpanOptions) => <R, E, A>(f: Effect.Effect<A, E, R>) =>
+  Effect.andThen(
+    getRC,
+    (ctx) =>
+      f.pipe(
+        Effect.withSpan(name, {
+          ...options,
+          attributes: { ...spanAttributes({ ...ctx, name: NonEmptyString255(name) }), ...options?.attributes }
+        }, {
+          captureStackTrace: options?.captureStackTrace ?? false
+        }),
+        // TODO: false
+        // request context info is picked up directly in the logger for annotations.
+        Effect.withLogSpan(name)
+      )
+  )
+
+export interface SetupRequestOptions {
+  readonly withTransaction?: boolean
+}
+
+// Build `layer` against the ambient (request) scope rather than a sub-scope of the
+// returned Effect. Required when the returned value is a streaming HttpServerResponse:
+// the response body keeps producing chunks (and using layer-provided state) after the
+// Effect returns, so a sub-scope would close too early and run finalizers mid-stream.
+export const provideOnRequestScope =
+  <ROut, E2, RIn>(layer: Layer.Layer<ROut, E2, RIn>) => <A, E, R>(self: Effect.Effect<A, E, R>) =>
+    Effect.gen(function*() {
+      const requestScope = yield* Effect.scope
+      // Fresh MemoMap per request: `Layer.buildWithScope` would otherwise reuse
+      // the ambient MemoMap living on the HTTP server fiber, sharing the built
+      // value (e.g. ContextMap) across every request handled by that server.
+      const memoMap = yield* Layer.makeMemoMap
+      const ctx = yield* Layer.buildWithMemoMap(layer, memoMap, requestScope)
+      return yield* Effect.provide(self, ctx)
+    })
+
+export const setupRequestContextFromCurrent =
+  (name = "request", options?: Tracer.SpanOptions & SetupRequestOptions) => <R, E, A>(self: Effect.Effect<A, E, R>) =>
+    self
+      .pipe(
+        options?.withTransaction === true ? withSqlTransaction : (_) => _,
+        withRequestSpan(name, options),
+        Effect.provide(ContextMapContainer.layer, { local: true })
+      )
+
+// Streaming variant: binds ContextMapContainer to the ambient (request) scope so its
+// finalizer (clear()) runs only after the response body is fully drained, not when the
+// outer Effect returns its HttpServerResponse value. Use for handlers that return a
+// streaming HttpServerResponse (e.g. SSE) — see RequestContextMiddleware for context.
+export const setupStreamingRequestContextFromCurrent =
+  (name = "request", options?: Tracer.SpanOptions & SetupRequestOptions) => <R, E, A>(self: Effect.Effect<A, E, R>) =>
+    self.pipe(
+      options?.withTransaction === true ? withSqlTransaction : (_) => _,
+      withRequestSpan(name, options),
+      provideOnRequestScope(ContextMapContainer.layer)
+    )
+
+// TODO: consider integrating Effect.withParentSpan
+export function setupRequestContext<R, E, A>(
+  self: Effect.Effect<A, E, R>,
+  requestContext: RequestContext,
+  options?: SetupRequestOptions
+) {
+  const layer = Layer.mergeAll(
+    ContextMapContainer.layer,
+    Layer.succeed(LocaleRef, requestContext.locale),
+    Layer.succeed(storeId, requestContext.namespace)
+  )
+  return self
+    .pipe(
+      options?.withTransaction === true ? withSqlTransaction : (_) => _,
+      withRequestSpan(requestContext.name),
+      Effect.provide(layer, { local: true })
+    )
+}
+
+export function setupRequestContextWithCustomSpan<R, E, A>(
+  self: Effect.Effect<A, E, R>,
+  requestContext: RequestContext,
+  name: string,
+  options?: Tracer.SpanOptions & SetupRequestOptions
+) {
+  const layer = Layer.mergeAll(
+    ContextMapContainer.layer,
+    Layer.succeed(LocaleRef, requestContext.locale),
+    Layer.succeed(storeId, requestContext.namespace)
+  )
+  return self
+    .pipe(
+      options?.withTransaction === true ? withSqlTransaction : (_) => _,
+      withRequestSpan(name, options),
+      Effect.provide(layer, { local: true })
+    )
+}