Send the response from inside the handler, as it runs.

A handler normally returns its response and the connection sends it. A handler that returns {send, Headers, Fun} sends it itself instead: the connection calls Fun(Req) and the fun sends the response with this module's functions, then returns the request.

handle(Req) ->
    {{send, [], fun send/1}, Req}.

send(Req0) ->
    ok = roadrunner_send:inform(103, [{~"link", ~"</app.css>; rel=preload"}], Req0),
    {ok, Body, Req} = roadrunner_req:read_body(Req0),
    ok = roadrunner_send:reply(roadrunner_resp:text(200, Body), Req),
    Req.

Use it when the response can only be decided while the handler runs:

• inform/3 sends an interim 1xx response (such as 103 Early Hints) before the final one, as many times as needed
• reply/2 sends a complete response built with roadrunner_resp, and reply/4 one given as its status, headers and body
• stream/3 sends the status and headers and returns the same Send fun a {stream, ...} response gets, to write the body as it goes
• file/4 sends a file, as a {sendfile, ...} response does
• websocket/4 upgrades the connection to a WebSocket session, as a {websocket, Module, State, Opts} response does

The fun sends one final response (reply/2,4, stream/3, file/4 or websocket/4). The calls take the request the fun holds now, so pass the one returned by roadrunner_req:read_body/1,2, and return the last one from the fun, as handle/1 does.

What a call returns and when it raises:

• ok (or {ok, Send} from stream/3) once the response went out.
• {error, Reason} when it could not: the transport failed, a header has CR/LF/NUL (unsafe_header), the headers are over the client's HTTP/2 or HTTP/3 limit, file/4's file is missing or shorter than its range, or an upgrade was refused. A final response that could not go out is answered 500 in its place.
• It raises already_sent for a final response, or an inform/3, after the final response; and not_in_send_fun when called outside the fun's process, such as from a process the fun spawns. The Send fun stream/3 returns is the fun's too: call it from the fun's process.

A fun that exits with {shutdown, Reason} stops the request on purpose, the OTP way: the response ends as far as it went (an open stream is ended, no response at all is answered 500), nothing is logged, and the request reports a normal stop. On HTTP/1.1 the connection then closes, since how much of the body the fun read is unknown; on HTTP/2 and HTTP/3 only the stream ends.

The framework finishes what the fun leaves open. A stream the fun did not end with Send(Data, fin) is ended when the fun returns. A fun that returns without a final response gets a 500 sent for it. A fun that crashes before a final response is answered 500; one that crashes after it closes the connection (HTTP/1.1) or resets the stream (HTTP/2, HTTP/3) when the body was still open. A file that fails to read once its response has started cuts the response the same way.

Headers in the {send, Headers, Fun} tuple is where middlewares add their headers (roadrunner_cors, roadrunner_security_headers). They are added to the final response, unless the call already sets a header with the same name. vary is the exception: both values are kept. Interim responses get only the headers they are given. roadrunner_compress does not compress a response sent this way.

The rules of the other response shapes apply. Header names must be lowercase. A response with a CR, LF or NUL in a header, or (on HTTP/2 and HTTP/3) headers over the client's header size limit, is not sent: the final ones are answered 500 and the call returns an error. A HEAD request gets no body from reply/2,4 or file/4. An interim response to an HTTP/1.0 client is skipped, as RFC 9110 §15.2 asks.