Mint Documentation

Mint uses a process-less architecture where the HTTP connection is represented as a functional and immutable data structure called a connection.

Key characteristics:

• Immutability: Every operation performed on a connection (such as sending a request) returns a new, updated connection struct. You must always use the returned connection for subsequent operations.
• Socket Management: A connection wraps a socket in active: :once mode. Messages from the socket are delivered to the process that created the connection.
• Parsing: You must manually pass messages received from the socket to Mint to parse them into HTTP responses.
• Composability: Because connections are simple data structures and not tied to a specific process, they can be stored inside any Elixir process (e.g., GenServer, GenStage) or even managed by a single process managing multiple connections simultaneously.

Mint is a low-level client and does not provide built-in support for decompression. To handle compressed payloads (e.g., gzip, br, zstd), you must manually inspect the content-encoding or transfer-encoding headers and decompress the :data field of the response map.

To implement this, you should:

1. Extract the compression algorithms from the content-encoding header.
2. Reverse the list of algorithms to ensure they are applied in the correct order (from the last applied to the first).
3. Use an appropriate decompression library (like Erlang's built-in :zlib for gzip) to transform the data.

Note: This implementation assumes you are decompressing the entire response body at once rather than streaming chunks.

defp process_response({:done, request_ref}, state) do
  {%{response: response, from: from}, state} = pop_in(state.requests[request_ref])

  # Handle compression here.
  compression_algorithms = get_content_encoding_header(response.headers)
  response = %{response | data: decompress_data(response.data, compression_algorithms)}

  GenServer.reply(from, {:ok, response})

  state
end

To manage a connection within a long-running process, you can wrap a Mint connection in a GenServer. This pattern is useful for maintaining a persistent connection to a host or managing multiple connections within a single process.

Implementation Details:

1. Initialization: Call Mint.HTTP.connect(scheme, host, port) in the init/1 callback to create the initial connection.
2. Request Handling: In handle_call/3, use Mint.HTTP.request/5. Since the connection is immutable, you must update the conn in your GenServer state with the returned connection. Store the request_ref and the caller's from pid to facilitate asynchronous replies.
3. Response Processing: Use handle_info/2 to receive messages from the socket. Pass these messages to Mint.HTTP.stream/2.
4. Asynchronous Reply: As Mint.HTTP.stream/2 parses messages (status, headers, data, and :done), update your state. When the :done message for a specific request_ref is received, use GenServer.reply(from, {:ok, response}) to unblock the original caller.

Concurrency Note:

• HTTP/1: Requests will be pipelined (sent sequentially without waiting for responses).
• HTTP/2: Requests will be truly concurrent.
• To avoid pipelining in HTTP/1, you must manually queue or reject requests if one is already in progress.

defmodule ConnectionProcess do
  use GenServer

  require Logger

  defstruct [:conn, requests: %{}]

  def start_link({scheme, host, port}) do
    GenServer.start_link(__MODULE__, {scheme, host, port})
  end

  def request(pid, method, path, headers, body) do
    GenServer.call(pid, {:request, method, path, headers, body})
  end

  @impl true
  def init({scheme, host, port}) do
    case Mint.HTTP.connect(scheme, host, port) do
      {:ok, conn} ->
        state = %__MODULE__{conn: conn}
        {:ok, state}

      {:error, reason} ->
        {:stop, reason}
    end
  end

  @impl true
  def handle_call({:request, method, path, headers, body}, from, state) do
    case Mint.HTTP.request(state.conn, method, path, headers, body) do
      {:ok, conn, request_ref} ->
        state = put_in(state.conn, conn)
        state = put_in(state.requests[request_ref], %{from: from, response: %{}})
        {:noreply, state}

      {:error, conn, reason} ->
        state = put_in(state.conn, conn)
        {:reply, {:error, reason}, state}
    end
  end

  @impl true
  def handle_info(message, state) do
    case Mint.HTTP.stream(state.conn, message) do
      :unknown ->
        _ = Logger.error(fn -> "Received unknown message: " <> inspect(message) end)
        {:noreply, state}

      {:ok, conn, responses} ->
        state = put_in(state.conn, conn)
        state = Enum.reduce(responses, state, &process_response/2)
        {:noreply, state}
    end
  end

  defp process_response({:status, request_ref, status}, state) do
    put_in(state.requests[request_ref].response[:status], status)
  end

  defp process_response({:headers, request_ref, headers}, state) do
    put_in(state.requests[request_ref].response[:headers], headers)
  end

  defp process_response({:data, request_ref, new_data}, state) do
    update_in(state.requests[request_ref].response[:data], fn data -> (data || "") <> new_data end)
  end

  defp process_response({:done, request_ref}, state) do
    {%{response: response, from: from}, state} = pop_in(state.requests[request_ref])
    GenServer.reply(from, {:ok, response})
    state
  end
end