# `Arangox.MintClient`
[🔗](https://github.com/ArangoDB-Community/arangox/blob/v0.8.0/lib/arangox/client/mint.ex#L2)

An HTTP client implementation of the [`:mint`](https://hexdocs.pm/mint/Mint.HTTP.html "documentation") library. Requires [`:mint`](https://hex.pm/packages/mint "hex.pm") 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.

[__Hex.pm__](https://hex.pm/packages/mint)

[__Documentation__](https://hexdocs.pm/mint/Mint.HTTP.html)

---

*Consult [api-reference.md](api-reference.md) for complete listing*