README.md (5854B)
1 # Mint 🌱 2 3 [](https://travis-ci.org/elixir-mint/mint) 4 [](https://hexdocs.pm/mint) 5 [](https://hex.pm/packages/mint) 6 [](https://coveralls.io/github/elixir-mint/mint?branch=main) 7 8 > Functional HTTP client for Elixir with support for HTTP/1 and HTTP/2. 9 10 ## Installation 11 12 To install Mint, add it to your `mix.exs` file. Unless you're using your own SSL certificate store, also add the [CAStore][castore] library to your dependencies. 13 14 ```elixir 15 defp deps do 16 [ 17 {:castore, "~> 0.1.0"}, 18 {:mint, "~> 1.0"} 19 ] 20 end 21 ``` 22 23 Then, run `$ mix deps.get`. 24 25 ## Usage 26 27 Mint is different from most Erlang and Elixir HTTP clients because it provides a process-less architecture. Instead, Mint is based on a functional and immutable data structure that represents an HTTP connection. This data structure wraps a TCP or SSL socket. This allows for more fine-tailored architectures where the developer is responsible for wrapping the connection struct, such as having one process handle multiple connections or having different kinds of processes handle connections. 28 29 Below is an example of a basic interaction with Mint. First, we start a connection through `Mint.HTTP.connect/3`: 30 31 ```elixir 32 iex> {:ok, conn} = Mint.HTTP.connect(:http, "httpbin.org", 80) 33 ``` 34 35 This transparently chooses between HTTP/1 and HTTP/2. Requests are sent with: 36 37 ```elixir 38 iex> {:ok, conn, request_ref} = Mint.HTTP.request(conn, "GET", "/", [], "") 39 ``` 40 41 The connection socket runs in [*active mode*](http://erlang.org/doc/man/inet.html#setopts-2) (with `active: :once`), which means that the user of the library needs to handle [TCP messages](http://erlang.org/doc/man/gen_tcp.html#connect-4) and [SSL messages](http://erlang.org/doc/man/ssl.html#id66002): 42 43 ```elixir 44 iex> flush() 45 {:tcp, #Port<0.8>, 46 "HTTP/1.1 200 OK\r\n" <> _} 47 ``` 48 49 To handle such messages, Mint provides a `stream/2` function that turns messages into HTTP responses. Responses are streamed back to the user in parts through response parts `:status`, `:headers`, `:data`, and finally `:done`. 50 51 52 ```elixir 53 iex> {:ok, conn} = Mint.HTTP.connect(:http, "httpbin.org", 80) 54 iex> {:ok, conn, request_ref} = Mint.HTTP.request(conn, "GET", "/", [], "") 55 iex> receive do 56 ...> message -> 57 ...> {:ok, conn, responses} = Mint.HTTP.stream(conn, message) 58 ...> IO.inspect responses 59 ...> end 60 [ 61 {:status, #Reference<...>, 200}, 62 {:headers, #Reference<...>, [{"connection", "keep-alive"}, ...}, 63 {:data, #Reference<...>, "<!DOCTYPE html>..."}, 64 {:done, #Reference<...>} 65 ] 66 ``` 67 68 The connection API is stateless, this means that you need to make sure to always save the returned `conn`: 69 70 ```elixir 71 # Wrong 72 {:ok, _conn, ref} = Mint.HTTP.request(conn, "GET", "/foo", [], "") 73 {:ok, conn, ref} = Mint.HTTP.request(conn, "GET", "/bar", [], "") 74 75 # Correct 76 {:ok, conn, ref} = Mint.HTTP.request(conn, "GET", "/foo", [], "") 77 {:ok, conn, ref} = Mint.HTTP.request(conn, "GET", "/bar", [], "") 78 ``` 79 80 For more information, see [the documentation][documentation]. 81 82 ### SSL certificates 83 84 When using SSL, you can pass in your own CA certificate store or use one provided by Mint. Mint doesn't ship with the certificate store itself, but it has an optional dependency on [CAStore][castore], which provides an up-to-date certificate store. If you don't want to use your own certificate store, just add `:castore` to your dependencies. 85 86 ```elixir 87 def deps do 88 [ 89 {:castore, "~> 0.1.0"}, 90 {:mint, "~> 0.4.0"} 91 ] 92 end 93 ``` 94 95 ### WebSocket Support 96 97 Mint itself does not support the WebSocket protocol, but it can be used as the foundation to build a WebSocket client on top of. If you need WebSocket support, you can use [mint_web_socket]. 98 99 ### Connection Management and Pooling 100 101 Mint is a low-level client. If you need higher-level features such as connection management, pooling, metrics, and more, check out [Finch], a project built on top of Mint that provides those things. 102 103 ## Contributing 104 105 If you wish to contribute check out the [issue list](https://github.com/elixir-mint/mint/issues) and let us know what you want to work on so we can discuss it and reduce duplicate work. 106 107 Tests are organized with tags. Integration tests that hit real websites over the internet are tagged with `:requires_internet_connection`. Proxy tests are tagged with `:proxy` and require that you run `docker-compose up` from the Mint root directory in order to run (they are excluded by default when you run `$ mix test`). A few examples of running tests: 108 109 * `$ mix test` to run the test suite without caring about Docker and `docker-compose up`. 110 111 * `$ mix test --exclude integration` to only run local tests (for example, you don't have an internet connection available). 112 113 * `$ mix test --include proxy` to run all tests, including proxy tests. 114 115 ## License 116 117 Copyright 2018 Eric Meadows-Jönsson and Andrea Leopardi 118 119 Licensed under the Apache License, Version 2.0 (the "License"); 120 you may not use this file except in compliance with the License. 121 You may obtain a copy of the License at 122 123 http://www.apache.org/licenses/LICENSE-2.0 124 125 Unless required by applicable law or agreed to in writing, software 126 distributed under the License is distributed on an "AS IS" BASIS, 127 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 128 See the License for the specific language governing permissions and 129 limitations under the License. 130 131 [castore]: https://github.com/elixir-mint/castore 132 [documentation]: https://hexdocs.pm/mint 133 [mint_web_socket]: https://github.com/elixir-mint/mint_web_socket 134 [Finch]: https://github.com/sneako/finch