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#
| Type | Definition | Description |
|---|---|---|
Fork | type 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) -> ServerRequestA server request reading request (Effect's
HttpServerRequest.fromWeb); its source is request.
| Parameter | Type | Description |
|---|---|---|
request | WebRequest |
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.
| Parameter | Type | Description |
|---|---|---|
request | ServerRequest | |
signal | AbortSignal | None = None | |
context | Context[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) -> WebResponseresponse as a WebResponse (Effect's
HttpServerResponse.toWeb): a streamed body runs with context
when read, and stops when signal fires; scope closes with it.
| Parameter | Type | Description |
|---|---|---|
response | HttpServerResponse | |
without_body | bool = False | |
context | Context[Any] | None = None | |
signal | AbortSignal | None = None | |
scope | CloseableScope | 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) -> HttpServerResponseA server response sending response (Effect's
HttpServerResponse.fromWeb): its cookies parsed from
set-cookie, its body streamed.
| Parameter | Type | Description |
|---|---|---|
response | WebResponse |
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).
| Parameter | Type | Description |
|---|---|---|
context | Context[Any] | |
fork | Fork = _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 maketo_web_handler#
to_web_handler[E](app, middleware=None) -> WebHandlerapp as an asyncio handler. HEAD responses have no body; a
streamed body closes the request's scope when it ends.
| Parameter | Type | Description |
|---|---|---|
app | Effect[HttpServerResponse, E, HttpServerRequest | Scope] | |
middleware | HttpMiddleware | 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) -> WebHandlerLayerBuild 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.
| Parameter | Type | Description |
|---|---|---|
layer | Layer[Any, LE] | |
to_handler | Callable[[Context[Any]], Effect[Effect[HttpServerResponse, E, Any], LE]] | |
middleware | HttpMiddleware | None = None | |
memo_map | MemoMap | 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) -> WebHandlerLayerto_web_handler for an app needing the services layer
builds.
| Parameter | Type | Description |
|---|---|---|
app | Effect[HttpServerResponse, E, Any] | |
layer | Layer[Any, LE] | |
middleware | HttpMiddleware | None = None | |
memo_map | MemoMap | 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.
| Parameter | Type | Description |
|---|---|---|
handler | Callable[[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)