HttpTransport

HttpTransport: low-level HTTP transport layer.

Sends raw HTTP/1.1 requests over TCP sockets. This is Layer 2 of March's HTTP library — it handles connection management and raw request/response exchange.

Most users should use HttpClient (Layer 3) instead. Use this directly only when you need low-level control over connections.

HTTPS requests use the certificate-verifying TLS client. The fd-oriented APIs deliberately remain plain HTTP only: a raw fd carries no TLS context, so accepting an HTTPS request there could leak a request in plaintext.

Types

typeTransportErrorTransportError =#

Functions

fnconnectconnect(req)#

Open a TCP connection to the request's host and port (80 when the request has none). Returns Ok(fd), or Err(ConnectionRefused(msg)) if the connection fails. The caller owns the fd and must tcp_close it.

Refuses https:// requests with SchemeNotSupported — use the Tls module for TLS-enabled connections.

Examples

let req = Result.unwrap(Http.get("http://example.com/"))
match HttpTransport.connect(req) do
  Ok(fd) -> HttpTransport.request_on(fd, Http.set_body(req, ""))
  Err(e) -> Err(e)
end

march> let sreq = Http.set_body(Result.unwrap(Http.get("https://example.com/")), "")
march> HttpTransport.connect(sreq)
Err(SchemeNotSupported("https:// not supported by HttpTransport; use the Tls module"))

fnrequestrequest(req)#

Send an HTTP or HTTPS request and receive the response. Opens a TCP connection, sends the request with Connection: close, receives and parses the response, then closes the connection.

HTTPS uses the certificate-verifying TLS client with SNI. connect, request_on, and stream_request_on remain plain-HTTP fd APIs and refuse HTTPS because they cannot safely construct or receive a TLS connection.

In js_of_ocaml builds (where http_fetch_available() is true) the request is routed through a synchronous XHR instead, which handles both http and https; the socket path below is skipped.

Default ports are 80 / 443. The response is read with a 1 MiB limit (plain HTTP also uses a 30 s receive timeout). Errors: ConnectionRefused for a failed TCP connect or TLS setup/handshake, SendError, RecvError, and ConnParseError for an unparseable response.

Examples

let req = Result.unwrap(Http.get("https://example.com/"))
match HttpTransport.request(Http.set_body(req, "")) do
  Ok(resp) -> Http.response_status_code(resp)
  Err(_) -> 0
end

fnrequest_onrequest_on(fd, req)#

Send a request and receive the response on an existing fd. Does NOT close the connection — caller manages the fd lifetime. Suitable for keep-alive connection reuse. No Connection: close header is added. The response is read with a 1 MiB limit.

Returns Ok(Response(...)), or SendError / RecvError / ConnParseError for a failed send, receive or unparseable response.

Refuses https:// requests with SchemeNotSupported even when an fd is provided, because this module uses plain tcp_send_all that would bypass TLS on a TLS-wrapped fd. Use the Tls module for HTTPS.

Examples

let r1 = HttpTransport.request_on(fd, users_req)
let r2 = HttpTransport.request_on(fd, posts_req)
tcp_close(fd)

fnsimple_getsimple_get(url)#

Convenience wrapper: parse a URL and send a GET request (empty body) with request. A URL that does not parse gives Err(ConnParseError(...)) without touching the network; otherwise the result of request.

Examples

HttpTransport.simple_get("http://example.com/")

march> HttpTransport.simple_get("ftp://example.com/")
Err(ConnParseError("invalid scheme: ftp://example.com/"))

fnstream_fixed_bodystream_fixed_body(fd, remaining, on_chunk, status_code, resp_headers)#

Read a Content-Length body of remaining bytes from fd, calling on_chunk on each piece received. Stops when remaining reaches 0 or the peer closes early (both give Ok((status_code, resp_headers, ()))), or returns Err(RecvError(msg)). Used by stream_request_on.

fnstream_request_onstream_request_on(fd, req, on_chunk)#

Send a request on an existing fd and stream the response body. Calls on_chunk(chunk_string) for each body chunk as it arrives (chunked transfer-encoding frames, or reads of a Content-Length body). Returns Ok((status_code, headers, ())): the values returned by on_chunk are discarded. Errors are SendError / RecvError / ConnParseError. Does NOT close the connection.

Examples

HttpTransport.stream_request_on(fd, req, fn chunk -> println(chunk))

Refuses https:// requests with SchemeNotSupported. Use the Tls module for streaming over TLS.