GitHub

middleware

API reference for middleware.

RPC middleware (Effect's RpcMiddleware): a service wrapping the handlers of the RPCs it is added to.

Declare one as a tag class over what it provides to the handlers, the error it may fail with and the services it needs, and give the error's schema::

class Auth(RpcMiddleware[CurrentUser, Unauthorized], required_for_client=True):
    error = Unauthorized

AuthLive = layer.succeed(Auth, lambda effect, options: effect.pipe(
    fx.provide_service(CurrentUser, user_of(options.headers))
))

Add it to an RPC with rpc.middleware(Auth). required_for_client makes a client of those RPCs run the middleware's client side, given with layer_client.

Types

TypeDefinitionDescription
MiddlewareFntype MiddlewareFn[P, E, R] = Callable[[Effect[SuccessValue, Unhandled | E, P], MiddlewareOptions], Effect[SuccessValue, Unhandled | E, R | Scope]]

A middleware: gets the handler's effect (which needs what the middleware provides) and returns the effect to run instead.

AnyMiddlewaretype AnyMiddleware = type[RpcMiddleware[Any, Any, Any]]
ClientMiddlewareFntype ClientMiddlewareFn[E, R] = Callable[[ClientMiddlewareOptions], Effect[SuccessValue, Unhandled | E, R]]

Classes

Functions

client_tag

client_tag(middleware) -> type[Tag[Any]]

The tag holding middleware's client function, keyed <key>/Client as Effect keys it.

ParameterTypeDescription
middlewareAnyMiddleware

Returns type[Tag[Any]]

def client_tag(middleware: AnyMiddleware) -> type[Tag[Any]]:
    """The tag holding ``middleware``'s client function, keyed
    ``<key>/Client`` as Effect keys it."""
    key = f"{middleware.key}/Client"
    found = _client_tags.get(key)
    if found is None:
        found = type(f"{middleware.__name__}Client", (Tag,), {}, key=key)
        _client_tags[key] = found
    return found

layer_client

layer_client[M: RpcMiddleware[Any, Any, Any], E, R](middleware, service) -> Layer[ForClient[M], Never, R]

The client side of middleware: runs around each request a client of its RPCs sends (Effect's RpcMiddleware.layerClient).

ParameterTypeDescription
middlewaretype[M]
serviceClientMiddlewareFn[E, R]

Returns Layer[ForClient[M], Never, R]

def layer_client[M: RpcMiddleware[Any, Any, Any], E, R](
    middleware: type[M], service: ClientMiddlewareFn[E, R]
) -> Layer[ForClient[M], Never, R]:
    """The client side of ``middleware``: runs around each request a client
    of its RPCs sends (Effect's ``RpcMiddleware.layerClient``)."""
    return layer_client_effect(middleware, succeed(service))

layer_client_effect

layer_client_effect[M: RpcMiddleware[Any, Any, Any], E, EX, RR = Never](middleware, made) -> Layer[ForClient[M], EX, RR]

layer_client with the client middleware made by an effect; it runs with the services of the layer's context.

ParameterTypeDescription
middlewaretype[M]
madeEffect[ClientMiddlewareFn[E, RR], EX, RR]

Returns Layer[ForClient[M], EX, RR]

def layer_client_effect[M: RpcMiddleware[Any, Any, Any], E, EX, RR = Never](
    middleware: type[M], made: Effect[ClientMiddlewareFn[E, RR], EX, RR]
) -> Layer[ForClient[M], EX, RR]:
    """``layer_client`` with the client middleware made by an effect; it
    runs with the services of the layer's context."""
    require_effect(made, "made")

    def build(fn: ClientMiddlewareFn[E, RR]) -> Effect[Context[Any], Never, Any]:
        def with_services(services: Context[Any]) -> Context[Any]:
            kept = Context({t: s for t, s in services.map_unsafe.items() if t is not Scope})

            def run(options: ClientMiddlewareOptions) -> Effect[SuccessValue, Any, Any]:
                return fn(options).pipe(provide_context(kept))

            return Context({client_tag(middleware): run})

        return context().map(with_services)

    return layer_effect_context(made.flat_map(build))