An HTTP client implementation of the :mint library. Requires :mint to be
added as a dependency.
Speaks HTTP/1.1 and HTTP/2 over TCP, TLS (Transport Layer Security) and unix domain sockets.
Options
:client_opts is a keyword list, passed to Mint.HTTP.connect/4.
Mint takes its socket settings under its own :transport_opts key, which
is not an Arangox.start_link/1 option. This client builds that key from
:tcp_opts or :ssl_opts — whichever the endpoint's scheme selects —
plus the connect timeout and the socket write bounds. A :transport_opts
given inside :client_opts is merged over that per key, so setting one
socket option does not discard the others, and trust material configured
through :ssl_opts survives.
Which protocol gets used
This client speaks HTTP/1.1 by default on both schemes. HTTP/2 is opt-in:
Arangox.start_link(client_opts: [protocols: [:http2]])On TLS that offer is settled by ALPN (Application-Layer Protocol Negotiation); on cleartext it is prior knowledge, and it fails at connect time if the server does not speak HTTP/2.
Why HTTP/2 is not the default
request/3 hands the entire encoded body to Mint.request/5 rather than
streaming it, and HTTP/2 applies flow control to a request body: one
larger than the peer's current window is refused outright with
:exceeds_window_size instead of waiting for a WINDOW_UPDATE. ArangoDB
advertises about 64 KiB, so a bulk insert or a large document sits above
it while the same request succeeds over HTTP/1.1, which has no flow
control.
Until request bodies are streamed in window-sized chunks — work that
belongs with the transport rework, since it means interleaving writes with
WINDOW_UPDATE reads under the request deadline — HTTP/2 costs a size
bound and buys header compression on a driver whose headers are four
small fields. It is offered rather than assumed.
Conforms to the Arangox.Client error contract: every failure is an
Arangox.Error carrying a :reason atom, and neither connect/2 nor
request/3 raises or exits, whatever the transport does with the options it
is given.
Headers on the wire
The merged header list is delivered to :mint as given — order kept,
duplicates kept — and :mint lowercases header names on the wire
(HTTP/2 requires lowercase; it applies the same to HTTP/1.1). Values are
untouched. Response headers come back as the parsed list on
Arangox.Response — names lowercased, order and repeats as received.
Header values never reach an error
:mint reports a rejected header value as
{:invalid_header_value, name, value}, with the whole value. For an
authorization header that value is the credential. This module reports the
header name and drops the value.