GitHub

web_handler

API reference for web_handler.

HTTP apps as asyncio handlers, and asyncio handlers as apps (Effect's HttpEffect.toWebHandler family, fromWebHandler and the Web conversions of HttpServerRequest / HttpServerResponse).

A handler is async (WebRequest, context=None) -> WebResponse. Each request runs the app on its own fiber (http_effect.to_handled); the request's signal interrupts it as a client abort (499). A streamed body owns the request's scope: it closes when the body ends, when the reader stops, or when the signal fires.

Re-exports

Types

TypeDefinitionDescription
Forktype Fork = Callable[[Effect[None, Never, Any], Context[Any]], Fiber[None, Never]]

Starts a request's fiber: the handled app and the request's services.

Classes

Functions

request_from_web

request_from_web(request) -> ServerRequest

A server request reading request (Effect's HttpServerRequest.fromWeb); its source is request.

ParameterTypeDescription
requestWebRequest

Returns ServerRequest

def request_from_web(request: WebRequest) -> ServerRequest:
    """A server request reading ``request`` (Effect's
    ``HttpServerRequest.fromWeb``); its ``source`` is ``request``."""
    body = request.body

    def open_body() -> Stream[bytes, object]:
        chunks = request.chunks()
        if isinstance(body, bytes):
            return stream_succeed(body)
        return from_async_iterable(chunks, lambda error: error)

    def read_body() -> Stream[bytes, object]:
        # A whole read stops at the size limit without waiting for the
        # body's cleanup, which may never settle (as Effect's).
        if isinstance(body, bytes):
            return stream_succeed(body)
        return from_async_iterable(_DetachedClose(request.chunks()), lambda error: error)

    return SourceRequest(
        request.method,
        request.url,
        request.headers,
        None if body is None else open_body,
        source=request,
        remote_address=request.remote_address,
        read_body=None if body is None else read_body,
    )

request_to_web

request_to_web(request, *, signal=None, context=None) -> Result[WebRequest, RequestParseError]

request as a WebRequest (its source, if it is one); the body is read when the Web body is read. A path with a dot segment fails: the router matched it literally, and the handler may resolve it.

ParameterTypeDescription
requestServerRequest
signalAbortSignal | None = None
contextContext[Any] | None = None

Returns Result[WebRequest, RequestParseError]

def request_to_web(
    request: ServerRequest,
    *,
    signal: AbortSignal | None = None,
    context: Context[Any] | None = None,
) -> Result[WebRequest, RequestParseError]:
    """``request`` as a ``WebRequest`` (its source, if it is one); the body
    is read when the Web body is read. A path with a dot segment fails: the
    router matched it literally, and the handler may resolve it."""
    parts = split_url(request.original_url)
    if parts is None:
        return Err(RequestParseError(request, "Invalid URL"))
    if has_dot_segment(parts.path):
        return Err(RequestParseError(request, "Dot segment in the request path"))
    if isinstance(request.source, WebRequest):
        return Ok(request.source)
    url = to_url(request)
    if url is None:
        return Err(RequestParseError(request, "Invalid URL"))
    body: AsyncIterable[bytes] | None = None
    if request.method not in ("GET", "HEAD", "OPTIONS", "TRACE"):
        body = _StreamBody(request.stream, context or Context.empty(), None, signal)
    return Ok(
        WebRequest(
            url.href,
            method=request.method,
            headers=request.headers,
            body=body,
            signal=signal,
            remote_address=request.remote_address,
        )
    )

response_to_web

response_to_web(response, *, without_body=False, context=None, signal=None, scope=None) -> WebResponse

response as a WebResponse (Effect's HttpServerResponse.toWeb): a streamed body runs with context when read, and stops when signal fires; scope closes with it.

ParameterTypeDescription
responseHttpServerResponse
without_bodybool = False
contextContext[Any] | None = None
signalAbortSignal | None = None
scopeCloseableScope | None = None

Returns WebResponse

def response_to_web(
    response: HttpServerResponse,
    *,
    without_body: bool = False,
    context: Context[Any] | None = None,
    signal: AbortSignal | None = None,
    scope: CloseableScope | None = None,
) -> WebResponse:
    """``response`` as a ``WebResponse`` (Effect's
    ``HttpServerResponse.toWeb``): a streamed body runs with ``context``
    when read, and stops when ``signal`` fires; ``scope`` closes with it."""
    if scope is None or not isinstance(response.body, _body.Stream):
        return _to_web(response, without_body, context, signal, None)
    closing = response.body.stream.on_exit(scope.close)
    streamed = response.set_body_keep_headers(
        _body.Stream(closing, response.body.content_type, response.body.content_length)
    )
    return _to_web(streamed, without_body, context, signal, scope.close)

response_from_web

response_from_web(response) -> HttpServerResponse

A server response sending response (Effect's HttpServerResponse.fromWeb): its cookies parsed from set-cookie, its body streamed.

ParameterTypeDescription
responseWebResponse

Returns HttpServerResponse

def response_from_web(response: WebResponse) -> HttpServerResponse:
    """A server response sending ``response`` (Effect's
    ``HttpServerResponse.fromWeb``): its cookies parsed from
    ``set-cookie``, its body streamed."""
    body = response.body
    wire_body: bytes | Stream[bytes, object] | None
    if body is None or isinstance(body, bytes):
        wire_body = body
    else:
        wire_body = from_async_iterable(response.chunks(), lambda error: error)
    return from_wire(
        WireResponse(response.status, response.status_text, response.header_lines, wire_body)
    )

to_web_handler_with

to_web_handler_with(context, *, fork=_run_fork) -> Callable[[Effect[HttpServerResponse, Any, Any], HttpMiddleware | None], WebHandler]

to_web_handler for an app needing the services of context (each request may add more). fork starts each request's fiber (a root fiber by default).

ParameterTypeDescription
contextContext[Any]
forkFork = _run_fork

Returns Callable[[Effect[HttpServerResponse, Any, Any], HttpMiddleware | None], WebHandler]

def to_web_handler_with(
    context: Context[Any], *, fork: Fork = _run_fork
) -> Callable[[Effect[HttpServerResponse, Any, Any], HttpMiddleware | None], WebHandler]:
    """``to_web_handler`` for an app needing the services of ``context``
    (each request may add more). ``fork`` starts each request's fiber (a
    root fiber by default)."""

    def make(
        app: Effect[HttpServerResponse, Any, Any], middleware: HttpMiddleware | None = None
    ) -> WebHandler:
        def handler(
            request: WebRequest, extra: Context[Any] | None = None
        ) -> Awaitable[WebResponse]:
            return _handle(app, middleware, context, request, extra, fork=fork)

        return handler

    return make

to_web_handler

to_web_handler[E](app, middleware=None) -> WebHandler

app as an asyncio handler. HEAD responses have no body; a streamed body closes the request's scope when it ends.

ParameterTypeDescription
appEffect[HttpServerResponse, E, HttpServerRequest | Scope]
middlewareHttpMiddleware | None = None

Returns WebHandler

def to_web_handler[E](
    app: Effect[HttpServerResponse, E, HttpServerRequest | Scope],
    middleware: HttpMiddleware | None = None,
) -> WebHandler:
    """``app`` as an asyncio handler. ``HEAD`` responses have no body; a
    streamed body closes the request's scope when it ends."""
    require_effect(app, "app")
    return to_web_handler_with(Context.empty())(app, middleware)

to_web_handler_layer_with

to_web_handler_layer_with[E, LE](layer, to_handler, middleware=None, *, memo_map=None) -> WebHandlerLayer

Build layer now (on the running loop), then handle requests with the app to_handler makes of its services. If the build fails, every request raises its error. Handlers built with one memo_map share the layers they have in common.

ParameterTypeDescription
layerLayer[Any, LE]
to_handlerCallable[[Context[Any]], Effect[Effect[HttpServerResponse, E, Any], LE]]
middlewareHttpMiddleware | None = None
memo_mapMemoMap | None = None

Returns WebHandlerLayer

def to_web_handler_layer_with[E, LE](
    layer: Layer[Any, LE],
    to_handler: Callable[[Context[Any]], Effect[Effect[HttpServerResponse, E, Any], LE]],
    middleware: HttpMiddleware | None = None,
    *,
    memo_map: MemoMap | None = None,
) -> WebHandlerLayer:
    """Build ``layer`` now (on the running loop), then handle requests with
    the app ``to_handler`` makes of its services. If the build fails, every
    request raises its error. Handlers built with one ``memo_map`` share
    the layers they have in common."""
    require_layer(layer, "layer")
    scope = CloseableScope()

    def build(context: Context[Any]) -> Effect[WebHandler, LE]:
        return to_handler(context).map(lambda app: to_web_handler_with(context)(app, middleware))

    # Started now, as Effect's runPromise: the build runs up to its first wait.
    building_layer = (
        layer.build_with_scope(scope)
        if memo_map is None
        else layer.build_with_memo_map(memo_map, scope)
    )
    built = run_fork(building_layer.flat_map(build))
    building = asyncio.ensure_future(await_fiber(built))
    disposing: list[asyncio.Future[None]] = []

    async def handler(request: WebRequest, extra: Context[Any] | None = None) -> WebResponse:
        exit = await asyncio.shield(building)
        if not isinstance(exit, Success):
            raise exit.cause.raisable()
        return await exit.value(request, extra)

    def dispose() -> asyncio.Future[None]:
        if not disposing:
            closing = asyncio.ensure_future(run_async_exit(scope.close(Success(None))))
            disposing.append(asyncio.ensure_future(_settled(closing)))
        return disposing[0]

    return WebHandlerLayer(handler, dispose)

to_web_handler_layer

to_web_handler_layer[E, LE](app, layer, middleware=None, *, memo_map=None) -> WebHandlerLayer

to_web_handler for an app needing the services layer builds.

ParameterTypeDescription
appEffect[HttpServerResponse, E, Any]
layerLayer[Any, LE]
middlewareHttpMiddleware | None = None
memo_mapMemoMap | None = None

Returns WebHandlerLayer

def to_web_handler_layer[E, LE](
    app: Effect[HttpServerResponse, E, Any],
    layer: Layer[Any, LE],
    middleware: HttpMiddleware | None = None,
    *,
    memo_map: MemoMap | None = None,
) -> WebHandlerLayer:
    """``to_web_handler`` for an app needing the services ``layer``
    builds."""
    require_effect(app, "app")
    require_layer(layer, "layer")
    return to_web_handler_layer_with(
        layer, lambda _context: succeed(app), middleware, memo_map=memo_map
    )

from_web_handler

from_web_handler(handler) -> Effect[HttpServerResponse, HttpServerError, HttpServerRequest]

An app answering with handler (Effect's fromWebHandler); interrupting it fires the Web request's signal. Needs an asyncio run.

ParameterTypeDescription
handlerCallable[[WebRequest], Awaitable[WebResponse]]

Returns Effect[HttpServerResponse, HttpServerError, HttpServerRequest]

def from_web_handler(
    handler: Callable[[WebRequest], Awaitable[WebResponse]],
) -> Effect[HttpServerResponse, HttpServerError, HttpServerRequest]:
    """An app answering with ``handler`` (Effect's ``fromWebHandler``);
    interrupting it fires the Web request's signal. Needs an asyncio run."""

    def run(fiber: Fiber[Any, Any]) -> Effect[HttpServerResponse, HttpServerError]:
        request = fiber._context.get_unsafe(HttpServerRequest)
        controller = AbortController()
        match request_to_web(request, signal=controller.signal, context=fiber._context):
            case Err(reason):
                return fail(HttpServerError(reason))
            case Ok(web):
                pass

        async def call() -> WebResponse:
            try:
                return await handler(web)
            except asyncio.CancelledError:
                controller.abort()
                raise

        def on_error(cause: Exception) -> HttpServerError:
            return HttpServerError(
                InternalError(request, "HttpApp.fromWebHandler: Error in handler", cause)
            )

        return try_async(call, on_error).map(response_from_web)

    return _WithFiber(run)