@effect-app/infra 2.87.2 → 2.89.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-app/infra",
-  "version": "2.87.2",
+  "version": "2.89.0",
   "license": "MIT",
   "type": "module",
   "dependencies": {
@@ -13,7 +13,7 @@
     "proper-lockfile": "^4.1.2",
     "pure-rand": "7.0.1",
     "query-string": "^9.2.2",
-    "effect-app": "2.52.0"
+    "effect-app": "2.53.0"
   },
   "devDependencies": {
     "@azure/cosmos": "^4.5.0",
@@ -278,6 +278,10 @@
       "types": "./dist/adapters/redis-client.d.ts",
       "default": "./dist/adapters/redis-client.js"
     },
+    "./api/ContextProvider": {
+      "types": "./dist/api/ContextProvider.d.ts",
+      "default": "./dist/api/ContextProvider.js"
+    },
     "./api/codec": {
       "types": "./dist/api/codec.d.ts",
       "default": "./dist/api/codec.js"
@@ -302,10 +306,6 @@
       "types": "./dist/api/routing/middleware.d.ts",
       "default": "./dist/api/routing/middleware.js"
     },
-    "./api/routing/middleware/ContextProvider": {
-      "types": "./dist/api/routing/middleware/ContextProvider.d.ts",
-      "default": "./dist/api/routing/middleware/ContextProvider.js"
-    },
     "./api/routing/middleware/RouterMiddleware": {
       "types": "./dist/api/routing/middleware/RouterMiddleware.d.ts",
       "default": "./dist/api/routing/middleware/RouterMiddleware.js"

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

@@ -4,7 +4,7 @@ import { Context, Effect, Layer, type NonEmptyReadonlyArray, pipe, type Scope }
 import { type HttpRouter } from "effect-app/http"
 import { type Tag } from "effect/Context"
 import { type YieldWrap } from "effect/Utils"
-import { type ContextTagWithDefault, type GetContext, type LayerUtils, mergeContexts } from "../../layerUtils.js"
+import { type ContextTagWithDefault, type GetContext, type LayerUtils, mergeContexts } from "./layerUtils.js"
 
 export namespace EffectGenUtils {
   export type Success<EG> = EG extends Effect<infer A, infer _E, infer _R> ? A

package/src/api/routing/middleware/RouterMiddleware.ts

@@ -1,149 +1,37 @@
 /* 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 Request, type S, type Scope } from "effect-app"
-import type { GetEffectContext, RPCContextMap } from "effect-app/client/req"
-import type * as EffectRequest from "effect/Request"
-import { type ContextTagWithDefault } from "../../layerUtils.js"
-import { type ContextWithLayer } from "./dynamic-middleware.js"
+import { type Context, type Layer, type S } from "effect-app"
+import type { GetContextConfig, RPCContextMap } from "effect-app/client/req"
+import { type MiddlewareMakerId } from "./middleware-api.js"
+import { type TagClass } from "./RpcMiddleware.js"
 
 // module:
 //
-export type MakeRPCHandlerFactory<
-  RequestContextMap extends Record<string, RPCContextMap.Any>,
-  MiddlewareR
-> = <
-  T extends {
-    config?: Partial<Record<keyof RequestContextMap, any>>
-  },
-  Req extends S.TaggedRequest.All,
-  HandlerR
->(
-  schema: T & S.Schema<Req, any, never>,
-  next: (
-    request: Req,
-    headers: any
-  ) => Effect.Effect<
-    EffectRequest.Request.Success<Req>,
-    EffectRequest.Request.Error<Req>,
-    // dynamic middlewares removes the dynamic context from HandlerR
-    Exclude<HandlerR, GetEffectContext<RequestContextMap, (T & S.Schema<Req, any, never>)["config"]>>
-  >,
-  moduleName: string
-) => (
-  req: Req,
-  headers: any
-) => Effect.Effect<
-  Request.Request.Success<Req>,
-  Request.Request.Error<Req> | RequestContextMapErrors<RequestContextMap>,
-  // the middleware will remove from HandlerR the dynamic context, but will also add some requirements
-  | MiddlewareR
-  // & S.Schema<Req, any, never> is useless here but useful when creating the middleware
-  | Exclude<HandlerR, GetEffectContext<RequestContextMap, (T & S.Schema<Req, any, never>)["config"]>>
->
-
-export type RPCHandlerFactory<
-  RequestContextMap extends Record<string, RPCContextMap.Any>,
-  ContextProviderA
-> = <
-  T extends {
-    config?: Partial<Record<keyof RequestContextMap, any>>
-  },
-  Req extends S.TaggedRequest.All,
-  HandlerR
->(
-  schema: T & S.Schema<Req, any, never>,
-  next: (
-    request: Req,
-    headers: any
-  ) => Effect.Effect<
-    EffectRequest.Request.Success<Req>,
-    EffectRequest.Request.Error<Req>,
-    HandlerR
-  >,
-  moduleName: string
-) => (
-  req: Req,
-  headers: any
-) => Effect.Effect<
-  Request.Request.Success<Req>,
-  Request.Request.Error<Req> | RequestContextMapErrors<RequestContextMap>,
-  | Scope.Scope // because of the context provider and the middleware (Middleware)
-  | Exclude<
-    // the middleware will remove from HandlerR the dynamic context
-    // & S.Schema<Req, any, never> is useless here but useful when creating the middleware
-    Exclude<HandlerR, GetEffectContext<RequestContextMap, (T & S.Schema<Req, any, never>)["config"]>>,
-    // the context provider provides additional stuff both to the middleware and the next
-    ContextProviderA
-  >
->
-
-export type RequestContextMapProvider<RequestContextMap extends Record<string, RPCContextMap.Any>> = {
-  [K in keyof RequestContextMap]: ContextWithLayer.Base<
-    { [K in keyof RequestContextMap]?: RequestContextMap[K]["contextActivation"] },
-    RequestContextMap[K]["service"],
-    S.Schema.Type<RequestContextMap[K]["error"]>
-  >
-}
-
-export interface MiddlewareMakerId {
-  _tag: "MiddlewareMaker"
-}
 
 export type RouterMiddleware<
   RequestContextMap extends Record<string, RPCContextMap.Any>, // what services will the middlware provide dynamically to the next, or raise errors.
   MakeMiddlewareE, // what the middleware construction can fail with
   MakeMiddlewareR, // what the middlware requires to be constructed
-  ContextProviderA // what the context provider provides
-> = ContextTagWithDefault<
-  MiddlewareMakerId,
-  {
-    _tag: "MiddlewareMaker"
-    effect: RPCHandlerFactory<RequestContextMap, ContextProviderA>
-  },
-  MakeMiddlewareE,
-  MakeMiddlewareR
->
+  ContextProviderA, // what the context provider provides
+  ContextProviderE, // what the context provider may fail with
+  ContextProviderR // what the context provider may error with
+> =
+  & TagClass<
+    MiddlewareMakerId,
+    "MiddlewareMaker",
+    {
+      wrap: true
+      provides: [Context.Tag<ContextProviderA, ContextProviderA>] // ContextProviderA extends never ? never : [Context.Tag<ContextProviderA, ContextProviderA>] // TODO: Tag<A>, Tag<B>
+      requires: [Context.Tag<ContextProviderR, ContextProviderR>] // ContextProviderE extends never ? never : [Context.Tag<ContextProviderR, ContextProviderR>] // TODO: Tag<A>, Tag<B>
+      failure: ContextProviderE
+    }
+  >
+  & {
+    Default: Layer.Layer<MiddlewareMakerId, MakeMiddlewareE, MakeMiddlewareR>
+    requestContext: Context.Tag<"RequestContextConfig", GetContextConfig<RequestContextMap>>
+  }
 
 export type RequestContextMapErrors<RequestContextMap extends Record<string, RPCContextMap.Any>> = S.Schema.Type<
   RequestContextMap[keyof RequestContextMap]["error"]
 >
-
-// it just provides the right types without cluttering the implementation with them
-export function makeRpcEffect<
-  RequestContextMap extends Record<string, RPCContextMap.Any>,
-  ContextProviderA
->() {
-  return (
-    cb: <
-      T extends {
-        config?: Partial<Record<keyof RequestContextMap, any>>
-      },
-      Req extends S.TaggedRequest.All,
-      HandlerR
-    >(
-      schema: T & S.Schema<Req, any, never>,
-      next: (
-        request: Req,
-        headers: any
-      ) => Effect.Effect<
-        EffectRequest.Request.Success<Req>,
-        EffectRequest.Request.Error<Req>,
-        HandlerR
-      >,
-      moduleName: string
-    ) => (
-      req: Req,
-      headers: any
-    ) => Effect.Effect<
-      Request.Request.Success<Req>,
-      Request.Request.Error<Req> | RequestContextMapErrors<RequestContextMap>,
-      | Scope.Scope // the context provider may require Scope to run
-      | Exclude<
-        // it can also be removed from HandlerR
-        Exclude<HandlerR, GetEffectContext<RequestContextMap, (T & S.Schema<Req, any, never>)["config"]>>,
-        ContextProviderA
-      >
-    >
-  ) => cb
-}

package/src/api/routing/middleware/RpcMiddleware.ts

@@ -4,12 +4,12 @@
 import { type Rpc, RpcMiddleware } from "@effect/rpc"
 import { type SuccessValue, type TypeId } from "@effect/rpc/RpcMiddleware"
 import { type Context, type Effect, Layer, type NonEmptyReadonlyArray, type Option, type S, type Schema, type Scope, Unify } from "effect-app"
-import type { AnyService, ContextRepr, RPCContextMap } from "effect-app/client/req"
+import type { AnyService, ContextTagArray, RPCContextMap } from "effect-app/client/req"
 import { type HttpHeaders } from "effect-app/http"
 import { type TagUnify, type TagUnifyIgnore } from "effect/Context"
 import { type LayerUtils } from "../../layerUtils.js"
 
-// updated to support Scope.Scope
+// updated to support Scope.Scope and Requires
 export interface RpcMiddleware<Provides, E, Requires> {
   (options: {
     readonly clientId: number
@@ -47,19 +47,18 @@ export type DependsOn = {
   readonly dependsOn: NonEmptyReadonlyArray<AnyDynamic> | undefined
 }
 
-type RpcOptionsDynamic<Key extends string, A extends RPCContextMap.Any> = RpcOptionsOriginal & {
+interface RpcOptionsDynamic<Key extends string, A extends RPCContextMap.Any> extends RpcOptionsOriginal {
   readonly dynamic: RpcDynamic<Key, A>
   readonly dependsOn?: NonEmptyReadonlyArray<AnyDynamic> | undefined
 }
 
 export type Dynamic<Options> = Options extends RpcOptionsDynamic<any, any> ? true : false
 
-export interface RpcMiddlewareDynamicWrap<E, R, Config> {
+export interface RpcMiddlewareDynamicWrap<E, R, _Config> {
   (options: {
     readonly next: Effect.Effect<SuccessValue, E, Scope.Scope | R>
-    readonly config: Config // todo
     readonly clientId: number
-    readonly rpc: Rpc.AnyWithProps
+    readonly rpc: Rpc.AnyWithProps // TODO & { annotations: Context.Context<RequestContextMap<Config>> }
     readonly payload: unknown
     readonly headers: HttpHeaders.Headers
   }): Effect.Effect<
@@ -69,11 +68,10 @@ export interface RpcMiddlewareDynamicWrap<E, R, Config> {
   >
 }
 
-export interface RpcMiddlewareDynamicNormal<A, E, R, Config> {
+export interface RpcMiddlewareDynamicNormal<A, E, R, _Config> {
   (options: {
-    readonly config: Config // todo
     readonly clientId: number
-    readonly rpc: Rpc.AnyWithProps
+    readonly rpc: Rpc.AnyWithProps // TODO & { annotations: Context.Context<RequestContextMap<Config>> }
     readonly payload: unknown
     readonly headers: HttpHeaders.Headers
   }): Effect.Effect<
@@ -86,8 +84,8 @@ export interface RpcMiddlewareDynamicNormal<A, E, R, Config> {
 export interface TagClassAny extends Context.Tag<any, any> {
   readonly [TypeId]: TypeId
   readonly optional: boolean
-  readonly provides?: Context.Tag<any, any> | ContextRepr | undefined
-  readonly requires?: Context.Tag<any, any> | ContextRepr | undefined
+  readonly provides?: Context.Tag<any, any> | ContextTagArray | undefined
+  readonly requires?: Context.Tag<any, any> | ContextTagArray | undefined
   readonly failure: Schema.Schema.All
   readonly requiredForClient: boolean
   readonly wrap: boolean
@@ -105,9 +103,9 @@ export declare namespace TagClass {
     readonly optional?: false
   } ? Context.Tag.Identifier<Options["provides"]>
     : Options extends {
-      readonly provides: ContextRepr
+      readonly provides: ContextTagArray
       readonly optional?: false
-    } ? ContextRepr.Identifier<Options["provides"]>
+    } ? ContextTagArray.Identifier<Options["provides"]>
     : never
 
   /**
@@ -118,8 +116,8 @@ export declare namespace TagClass {
     readonly requires: Context.Tag<any, any>
   } ? Context.Tag.Identifier<Options["requires"]>
     : Options extends {
-      readonly requires: ContextRepr
-    } ? ContextRepr.Identifier<Options["requires"]>
+      readonly requires: ContextTagArray
+    } ? ContextTagArray.Identifier<Options["requires"]>
     : never
 
   /**
@@ -130,7 +128,8 @@ export declare namespace TagClass {
     ? Context.Tag.Service<Options["provides"]>
     : Options extends { readonly dynamic: RpcDynamic<any, infer A> }
       ? Options extends { wrap: true } ? void : AnyService.Bla<A["service"]>
-    : Options extends { readonly provides: ContextRepr } ? Context.Context<ContextRepr.Identifier<Options["provides"]>>
+    : Options extends { readonly provides: ContextTagArray }
+      ? Context.Context<ContextTagArray.Identifier<Options["provides"]>>
     : void
 
   /**
@@ -139,7 +138,8 @@ export declare namespace TagClass {
    */
   export type FailureSchema<Options> = Options extends
     { readonly failure: Schema.Schema.All; readonly optional?: false } ? Options["failure"]
-    : Options extends { readonly dynamic: RpcDynamic<any, infer A> } ? A["error"]
+    // actually not, the Failure depends on Dynamic Middleware Configuration!
+    // : Options extends { readonly dynamic: RpcDynamic<any, infer A> } ? A["error"]
     : typeof Schema.Never
 
   /**
@@ -148,6 +148,7 @@ export declare namespace TagClass {
    */
   export type Failure<Options> = Options extends
     { readonly failure: Schema.Schema<infer _A, infer _I, infer _R>; 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"]>
     : never
 
@@ -191,10 +192,10 @@ export declare namespace TagClass {
     readonly optional: Optional<Options>
     readonly failure: FailureSchema<Options>
     readonly provides: Options extends { readonly provides: Context.Tag<any, any> } ? Options["provides"]
-      : Options extends { readonly provides: ContextRepr } ? Options["provides"]
+      : Options extends { readonly provides: ContextTagArray } ? Options["provides"]
       : undefined
     readonly requires: Options extends { readonly requires: Context.Tag<any, any> } ? Options["requires"]
-      : Options extends { readonly requires: ContextRepr } ? Options["requires"]
+      : Options extends { readonly requires: ContextTagArray } ? Options["requires"]
       : undefined
     readonly dynamic: Options extends RpcOptionsDynamic<any, any> ? Options["dynamic"]
       : undefined
@@ -226,8 +227,8 @@ export interface TagClass<
       >
       : TagClass.Wrap<Options> extends true ? RpcMiddlewareWrap<
           TagClass.Provides<Options>,
-          TagClass.Requires<Options>,
-          TagClass.Failure<Options>
+          TagClass.Failure<Options>,
+          TagClass.Requires<Options>
         >
       : RpcMiddleware<
         TagClass.Service<Options>,
@@ -245,7 +246,7 @@ export const Tag = <Self>() =>
   id: Name,
   options?: Options | undefined
 ) =>
-<E, R, L extends NonEmptyReadonlyArray<Layer.Layer.Any>>(opts: {
+<E, R, L extends ReadonlyArray<Layer.Layer.Any>>(opts: {
   effect: Effect.Effect<
     Options extends RpcOptionsDynamic<any, any> ? TagClass.Wrap<Options> extends true ? RpcMiddlewareDynamicWrap<
           TagClass.FailureService<Options>,
@@ -273,7 +274,11 @@ export const Tag = <Self>() =>
   >
   dependencies?: L
 }): TagClass<Self, Name, Options> & {
-  Default: Layer.Layer<Self, E | LayerUtils.GetLayersError<L>, Exclude<R, LayerUtils.GetLayersSuccess<L>>>
+  Default: Layer.Layer<
+    Self,
+    E | LayerUtils.GetLayersError<L>,
+    Exclude<R, LayerUtils.GetLayersSuccess<L>> | LayerUtils.GetLayersContext<L>
+  >
 } =>
   class extends RpcMiddleware.Tag<Self>()(id, options as any) {
     static readonly dynamic = options && "dynamic" in options ? options.dynamic : undefined

package/src/api/routing/middleware/dynamic-middleware.ts

@@ -1,47 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { type ContextTagWithDefault } from "../../layerUtils.js"
-import { type RpcMiddlewareDynamicNormal, type RpcMiddlewareDynamicWrap } from "./RpcMiddleware.js"
-
-export type RpcMiddlewareDynamic<A, E, R, Config> = [A] extends [void] ? RpcMiddlewareDynamicWrap<E, R, Config>
-  : RpcMiddlewareDynamicNormal<A, E, R, Config>
-
-export type ContextWithLayer<
-  Config,
-  Service,
-  Error,
-  Dependencies,
-  Id,
-  LayerE,
-  LayerR
-> =
-  & (
-    | ContextTagWithDefault<
-      Id,
-      // todo
-      RpcMiddlewareDynamic<Service, Error, any, Config>,
-      LayerE,
-      LayerR
-    >
-    | ContextTagWithDefault<
-      Id,
-      // todo
-      RpcMiddlewareDynamic<Service, Error, never, Config>,
-      LayerE,
-      LayerR
-    >
-  )
-  & {
-    dependsOn?: Dependencies
-  }
-
-export namespace ContextWithLayer {
-  export type Base<Config, Service, Error> = ContextWithLayer<
-    Config,
-    Service,
-    Error,
-    any,
-    any,
-    any,
-    any
-  >
-}

package/src/api/routing/middleware/generic-middleware.ts

@@ -1,67 +1,105 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { type Rpc, type RpcMiddleware } from "@effect/rpc"
-import { type SuccessValue } from "@effect/rpc/RpcMiddleware"
-import { type Array, Context, Effect, type Layer, type NonEmptyReadonlyArray, Option, type Scope } from "effect-app"
-import { type ContextRepr } from "effect-app/client"
-import { type HttpHeaders } from "effect-app/http"
+import { type RpcMiddleware } from "@effect/rpc"
+import { Context, Effect, type Layer, type NonEmptyReadonlyArray, Option, type S, type Scope } from "effect-app"
+import { type ContextTagArray } from "effect-app/client"
 import { InfraLogger } from "../../../logger.js"
-import { type TagClassAny } from "./RpcMiddleware.js"
-
-export interface GenericMiddlewareOptions<E> {
-  // Effect rpc middleware does not support changing payload or headers, but we do..
-  readonly next: Effect.Effect<SuccessValue, E, Scope.Scope>
-  readonly payload: unknown
-  readonly headers: HttpHeaders.Headers
-  readonly clientId: number
-  readonly rpc: Rpc.AnyWithProps
-}
+import { type RpcMiddlewareWrap, type TagClassAny } from "./RpcMiddleware.js"
+
+// Effect rpc middleware does not support changing payload or headers, but we do..
 
-export type GenericMiddlewareMaker = TagClassAny & { Default: Layer.Layer.Any } // todo; and Layer..
+export type MiddlewareMaker = TagClassAny & { Default: Layer.Layer.Any } // todo; and Layer..
 
-export namespace GenericMiddlewareMaker {
+export namespace MiddlewareMaker {
   export type ApplyServices<A extends TagClassAny, R> = Exclude<R, Provided<A>> | Required<A>
+
   export type ApplyManyServices<A extends NonEmptyReadonlyArray<TagClassAny>, R> =
     | Exclude<R, { [K in keyof A]: Provided<A[K]> }[number]>
     | { [K in keyof A]: Required<A[K]> }[number]
+
+  export type ManyProvided<A extends ReadonlyArray<TagClassAny>> = A extends NonEmptyReadonlyArray<TagClassAny>
+    ? { [K in keyof A]: Provided<A[K]> }[number]
+    : Provided<A[number]>
+  export type ManyRequired<A extends ReadonlyArray<TagClassAny>> = A extends NonEmptyReadonlyArray<TagClassAny>
+    ? { [K in keyof A]: Required<A[K]> }[number]
+    : Required<A[number]>
+  export type ManyErrors<A extends ReadonlyArray<TagClassAny>> = A extends NonEmptyReadonlyArray<TagClassAny>
+    ? { [K in keyof A]: Errors<A[K]> }[number]
+    : Errors<A[number]>
+
   export type Provided<T> = T extends TagClassAny
     ? T extends { provides: Context.Tag<any, any> } ? Context.Tag.Identifier<T["provides"]>
-    : T extends { provides: ContextRepr } ? ContextRepr.Identifier<T["provides"]>
+    : T extends { provides: ContextTagArray } ? ContextTagArray.Identifier<T["provides"]>
+    : never
+    : never
+
+  export type Errors<T> = T extends TagClassAny ? T extends { failure: S.Schema.Any } ? S.Schema.Type<T["failure"]>
     : never
     : never
 
   export type Required<T> = T extends TagClassAny
     ? T extends { requires: Context.Tag<any, any> } ? Context.Tag.Identifier<T["requires"]>
-    : T extends { requires: ContextRepr } ? ContextRepr.Identifier<T["requires"]>
+    : T extends { requires: ContextTagArray } ? ContextTagArray.Identifier<T["requires"]>
     : never
     : never
 }
 
-export const genericMiddlewareMaker = <
-  T extends Array<GenericMiddlewareMaker>
->(...middlewares: T): {
-  dependencies: { [K in keyof T]: T[K]["Default"] }
-  effect: Effect.Effect<RpcMiddleware.RpcMiddlewareWrap<any, any>>
+export const middlewareMaker = <
+  MiddlewareProviders extends ReadonlyArray<MiddlewareMaker>
+>(middlewares: MiddlewareProviders): {
+  dependencies: { [K in keyof MiddlewareProviders]: MiddlewareProviders[K]["Default"] }
+  effect: Effect.Effect<
+    RpcMiddlewareWrap<
+      MiddlewareMaker.ManyProvided<MiddlewareProviders>,
+      MiddlewareMaker.ManyErrors<MiddlewareProviders>,
+      Exclude<
+        MiddlewareMaker.ManyRequired<MiddlewareProviders>,
+        MiddlewareMaker.ManyProvided<MiddlewareProviders>
+      > extends never ? never
+        : Exclude<MiddlewareMaker.ManyRequired<MiddlewareProviders>, MiddlewareMaker.ManyProvided<MiddlewareProviders>>
+    >
+  >
 } => {
-  // we want to run them in reverse order
+  // we want to run them in reverse order because latter middlewares will provide context to former ones
   middlewares = middlewares.toReversed() as any
+
   return {
     dependencies: middlewares.map((_) => _.Default),
     effect: Effect.gen(function*() {
       const context = yield* Effect.context()
-      return <E>(
-        options: GenericMiddlewareOptions<E>
+
+      // returns a Effect/RpcMiddlewareWrap with Scope in requirements
+      return (
+        options: Parameters<
+          RpcMiddlewareWrap<
+            MiddlewareMaker.ManyProvided<MiddlewareProviders>,
+            never,
+            Scope.Scope
+          >
+        >[0]
       ) => {
+        // we start with the actual handler
         let handler = options.next
-        // copied from RpcMiddleare
+
+        // inspired from Effect/RpcMiddleware
         for (const tag of middlewares) {
           if (tag.wrap) {
+            // use the tag to get the middleware from context
             const middleware = Context.unsafeGet(context, tag)
+
+            // wrap the current handler, allowing the middleware to run before and after it
             handler = InfraLogger.logDebug("Applying middleware wrap " + tag.key).pipe(
               Effect.zipRight(middleware({ ...options, next: handler }))
             ) as any
           } else if (tag.optional) {
+            // use the tag to get the middleware from context
+            // if the middleware fails to run, we will ignore the error
             const middleware = Context.unsafeGet(context, tag) as RpcMiddleware.RpcMiddleware<any, any>
+
             const previous = handler
+
+            // set the previous handler to run after the middleware
+            // if the middleware is not present, we just return the previous handler
+            // otherwise the middleware will provide some context to be provided to the previous handler
             handler = InfraLogger.logDebug("Applying middleware optional " + tag.key).pipe(
               Effect.zipRight(Effect.matchEffect(middleware(options), {
                 onFailure: () => previous,
@@ -74,24 +112,35 @@ export const genericMiddlewareMaker = <
               }))
             )
           } else if (tag.dynamic) {
+            // use the tag to get the middleware from context
             const middleware = Context.unsafeGet(context, tag) as RpcMiddleware.RpcMiddleware<any, any>
+
             const previous = handler
+
+            // set the previous handler to run after the middleware
+            // we do expect the middleware to be present, but the context might not be available
+            // if it is, we provide it to the previous handler
             handler = InfraLogger.logDebug("Applying middleware dynamic " + tag.key, tag.dynamic).pipe(
               Effect.zipRight(
                 middleware(options).pipe(
-                  Effect.flatMap((value) =>
-                    Option.isSome(value)
-                      ? Context.isContext(value.value)
-                        ? Effect.provide(previous, value.value)
-                        : Effect.provideService(previous, tag.dynamic!.settings.service!, /* TODO */ value.value)
+                  Effect.flatMap((o) =>
+                    Option.isSome(o)
+                      ? Context.isContext(o.value)
+                        ? Effect.provide(previous, o.value)
+                        : Effect.provideService(previous, tag.dynamic!.settings.service!, /* TODO */ o.value)
                       : previous
                   )
                 )
               )
-            )
+            ) as any
           } else {
+            // use the tag to get the middleware from context
             const middleware = Context.unsafeGet(context, tag) as RpcMiddleware.RpcMiddleware<any, any>
+
             const previous = handler
+
+            // set the previous handler to run after the middleware
+            // we do expect both the middleware and the context to be present
             handler = InfraLogger.logDebug("Applying middleware " + tag.key).pipe(
               Effect.zipRight(
                 tag.provides !== undefined
@@ -104,7 +153,7 @@ export const genericMiddlewareMaker = <
                   )
                   : Effect.zipRight(middleware(options), previous)
               )
-            )
+            ) as any
           }
         }
         return handler