symfonic.agent.fastapi.transport.http

http

The HTTP edge of the mapper: an ErrorFrame as an HTTPException.

This is the only module in the transport package that imports a web framework, and it does so in one direction: frames in, framework object out. Keeping the conversion here is what lets :mod:error_mapper, :mod:sse, and :mod:codec stay honestly transport-neutral (TRN-3).

http_exception

http_exception(frame: ErrorFrame) -> HTTPException

Render a mapped frame as the framework's error object.

Source code in src/symfonic/agent/fastapi/transport/http.py

def http_exception(frame: ErrorFrame) -> HTTPException:
    """Render a mapped frame as the framework's error object."""
    return HTTPException(
        status_code=frame.status,
        detail=frame.detail,
        headers=dict(frame.headers) if frame.headers else None,
    )

raise_mapped

raise_mapped(error: BaseException, policy: ErrorPolicy, *, log_message: str | None = None, mapper: HttpErrorMapper = ERROR_MAPPER) -> HTTPException

Map error and return the exception for the handler to raise.

Returned rather than raised so the call site keeps its raise ... from chain: a handler that loses the cause makes the log useless exactly when it matters.

log_message is emitted with a traceback only when the mapped status is a server fault. This is the counterpart of EMAP-7: the detail a developer needs goes to the log, and a client-correctable 400/403/404 is not an incident — logging one with a stack trace is how a log stops being read.

Source code in src/symfonic/agent/fastapi/transport/http.py

def raise_mapped(
    error: BaseException,
    policy: ErrorPolicy,
    *,
    log_message: str | None = None,
    mapper: HttpErrorMapper = ERROR_MAPPER,
) -> HTTPException:
    """Map ``error`` and return the exception for the handler to ``raise``.

    Returned rather than raised so the call site keeps its ``raise ... from``
    chain: a handler that loses the cause makes the log useless exactly when it
    matters.

    ``log_message`` is emitted with a traceback only when the mapped status is
    a server fault. This is the counterpart of EMAP-7: the detail a developer
    needs goes to the log, and a client-correctable 400/403/404 is not an
    incident — logging one with a stack trace is how a log stops being read.
    """
    frame = mapper.map(error, policy)
    if log_message and frame.status >= 500:
        logger.exception(log_message)
    return http_exception(frame)