Add Req.TransportError and Req.Test.transport_error/2

lib/req/checksum_mismatch_error.ex

@@ -1,6 +1,11 @@
 defmodule Req.ChecksumMismatchError do
+  @moduledoc """
+  Represents a checksum mismatch error returned by `Req.Steps.checksum/1`.
+  """
+
   defexception [:expected, :actual]
 
+  @impl true
   def message(%{expected: expected, actual: actual}) do
     """
     checksum mismatch

lib/req/steps.ex

@@ -666,6 +666,9 @@ defmodule Req.Steps do
   ["Adapter" section in the `Req.Request`](Req.Request.html#module-adapter) module documentation
   for more information on adapters.
 
+  Finch returns `Mint.TransportError` exceptions on HTTP connection problems. These are automatically
+  converted to `Req.TransportError` exceptions.
+
   ## HTTP/1 Pools
 
   On HTTP/1 connections, Finch creates a pool per `{scheme, host, port}` tuple. These pools
@@ -757,6 +760,11 @@ defmodule Req.Steps do
 
       iex> Req.get!(url, connect_options: [transport_opts: [cacerts: :public_key.cacerts_get()]])
 
+  Transport errors are represented as `Req.TransportError` exceptions:
+
+      iex> Req.get("https://httpbin.org/delay/1", receive_timeout: 0, retry: false)
+      {:error, %Req.TransportError{reason: :timeout}}
+
   Stream response body using `Finch.stream/5`:
 
       fun = fn request, finch_request, finch_name, finch_options ->
@@ -876,6 +884,9 @@ defmodule Req.Steps do
       {:ok, acc} ->
         acc
 
+      {:error, %Mint.TransportError{reason: reason}} ->
+        {req, %Req.TransportError{reason: reason}}
+
       {:error, exception} ->
         {req, exception}
     end
@@ -909,6 +920,9 @@ defmodule Req.Steps do
         acc = collector.(acc, :done)
         {req, %{resp | body: acc}}
 
+      {:error, %Mint.TransportError{reason: reason}} ->
+        {req, %Req.TransportError{reason: reason}}
+
       {:error, exception} ->
         {req, exception}
     end
@@ -977,8 +991,14 @@ defmodule Req.Steps do
 
   defp run_finch_request(finch_request, finch_name, finch_options) do
     case Finch.request(finch_request, finch_name, finch_options) do
-      {:ok, response} -> Req.Response.new(response)
-      {:error, exception} -> exception
+      {:ok, response} ->
+        Req.Response.new(response)
+
+      {:error, %Mint.TransportError{reason: reason}} ->
+        %Req.TransportError{reason: reason}
+
+      {:error, exception} ->
+        exception
     end
   end
 
@@ -1156,6 +1176,18 @@ defmodule Req.Steps do
 
         assert Req.get!(plug: plug, into: []).body == ["echoecho"]
       end
+
+  You can simulate failure conditions by returning exception structs from your plugs.
+  For network related issues, use `Req.TransportError` exception:
+
+      test "network issues" do
+        plug = fn _conn ->
+          %Req.TransportError{reason: :econnrefused}
+        end
+
+        assert Req.get(plug: plug, retry: false) ==
+                 {:error, %Req.TransportError{reason: :econnrefused}}
+      end
   """
   @doc step: :request
   def put_plug(request) do
@@ -1195,8 +1227,36 @@ defmodule Req.Steps do
       conn = Plug.Test.conn(request.method, request.url, req_body)
 
       conn = put_in(conn.req_headers, req_headers)
-      conn = call_plug(conn, plug)
 
+      case call_plug(conn, plug) do
+        %Plug.Conn{} = conn ->
+          handle_plug_result(conn, request)
+
+        %Req.TransportError{} = exception ->
+          validate_transport_error!(exception.reason)
+          {request, exception}
+
+        %_{__exception__: true} = exception ->
+          {request, exception}
+      end
+    end
+
+    defp validate_transport_error!(:protocol_not_negotiated), do: :ok
+    defp validate_transport_error!({:bad_alpn_protocol, _}), do: :ok
+    defp validate_transport_error!(:closed), do: :ok
+    defp validate_transport_error!(:timeout), do: :ok
+
+    defp validate_transport_error!(reason) do
+      case :ssl.format_error(reason) do
+        ~c"Unexpected error:" ++ _ ->
+          raise ArgumentError, "unexpected Req.Transport reason: #{inspect(reason)}"
+
+        _ ->
+          :ok
+      end
+    end
+
+    defp handle_plug_result(conn, request) do
       # consume messages sent by Plug.Test adapter
       {_, %{ref: ref}} = conn.adapter
 

lib/req/too_many_redirects_error.ex

@@ -1,6 +1,11 @@
 defmodule Req.TooManyRedirectsError do
+  @moduledoc """
+  Represents an error when too many redirects occured, returned by `Req.Steps.redirect/1`.
+  """
+
   defexception [:max_redirects]
 
+  @impl true
   def message(%{max_redirects: max_redirects}) do
     "too many redirects (#{max_redirects})"
   end

lib/req/transport_error.ex

@@ -0,0 +1,17 @@
+defmodule Req.TransportError do
+  @moduledoc """
+  Represents an error with the transport used by an HTTP connection.
+
+  This is a standardised exception that all Req adapters should use for transport layer related
+  errors.
+
+  This exception is based on `Mint.TransportError`.
+  """
+
+  defexception [:reason]
+
+  @impl true
+  def message(%__MODULE__{reason: reason}) do
+    Mint.TransportError.message(%Mint.TransportError{reason: reason})
+  end
+end

test/req/steps_test.exs

@@ -1777,6 +1777,33 @@ defmodule Req.StepsTest do
       assert ["defmodule Req.MixProject do" <> _] = resp.body
       refute_receive _
     end
+
+    test "errors" do
+      req =
+        Req.new(
+          plug: fn _conn ->
+            %Req.TransportError{reason: :timeout}
+          end,
+          retry: false
+        )
+
+      assert Req.request(req) ==
+               {:error, %Req.TransportError{reason: :timeout}}
+    end
+
+    test "validate Req.TransportError reason" do
+      req =
+        Req.new(
+          plug: fn _conn ->
+            %Req.TransportError{reason: :bad}
+          end,
+          retry: false
+        )
+
+      assert_raise ArgumentError, "unexpected Req.Transport reason: :bad", fn ->
+        Req.request(req)
+      end
+    end
   end
 
   describe "run_finch" do
@@ -1849,7 +1876,7 @@ defmodule Req.StepsTest do
         end)
 
       req = Req.new(url: url, receive_timeout: 50, retry: false)
-      assert {:error, %Mint.TransportError{reason: :timeout}} = Req.request(req)
+      assert {:error, %Req.TransportError{reason: :timeout}} = Req.request(req)
       assert_received :ping
     end
 
@@ -2044,7 +2071,7 @@ defmodule Req.StepsTest do
     test "into: fun handle error", %{bypass: bypass, url: url} do
       Bypass.down(bypass)
 
-      assert {:error, %Mint.TransportError{reason: :econnrefused}} =
+      assert {:error, %Req.TransportError{reason: :econnrefused}} =
                Req.get(
                  url: url,
                  retry: false,
@@ -2097,7 +2124,7 @@ defmodule Req.StepsTest do
     test "into: collectable handle error", %{bypass: bypass, url: url} do
       Bypass.down(bypass)
 
-      assert {:error, %Mint.TransportError{reason: :econnrefused}} =
+      assert {:error, %Req.TransportError{reason: :econnrefused}} =
                Req.get(
                  url: url,
                  retry: false,