Merge pull request #126 from SophisticaSean/sophisticasean/helpful-checkout-timeout-error-message

Add helpful checkout timeout error

Author: sneako

lib/finch/http1/pool.ex

@@ -54,7 +54,23 @@ defmodule Finch.HTTP1.Pool do
     catch
       :exit, data ->
         Telemetry.exception(:queue, start_time, :exit, data, __STACKTRACE__, metadata)
-        exit(data)
+
+        # Provide helpful error messages for known errors
+        case data do
+          {:timeout, {NimblePool, :checkout, _affected_pids}} ->
+            reraise(
+              """
+              Finch was unable to provide a connection within the timeout due to excess queuing \
+              for connections. Consider adjusting the pool size, count, timeout or reducing the \
+              rate of requests if it is possible that the downstream service is unable to keep up \
+              with the current rate.
+              """,
+              __STACKTRACE__
+            )
+
+          _ ->
+            exit(data)
+        end
     end
   end
 

test/finch/telemetry_test.exs

@@ -230,15 +230,14 @@ defmodule Finch.TelemetryTest do
 
     Bypass.down(bypass)
 
-    try do
-      Finch.build(:get, endpoint(bypass)) |> Finch.request(finch_name, pool_timeout: 0)
-    catch
-      :exit, reason ->
-        assert {:timeout, _} = reason
-    end
+    assert_raise RuntimeError,
+                 ~r/Finch was unable to provide a connection within the timeout/,
+                 fn ->
+                   Finch.build(:get, endpoint(bypass))
+                   |> Finch.request(finch_name, pool_timeout: 0)
+                 end
 
     assert_receive {^ref, :start}
-    assert_receive {^ref, :exception}
 
     :telemetry.detach(to_string(finch_name))
   end
@@ -295,12 +294,12 @@ defmodule Finch.TelemetryTest do
 
     Bypass.down(bypass)
 
-    try do
-      Finch.build(:get, endpoint(bypass)) |> Finch.request(finch_name, pool_timeout: 0)
-    catch
-      :exit, reason ->
-        assert {:timeout, _} = reason
-    end
+    assert_raise RuntimeError,
+                 ~r/Finch was unable to provide a connection within the timeout/,
+                 fn ->
+                   Finch.build(:get, endpoint(bypass))
+                   |> Finch.request(finch_name, pool_timeout: 0)
+                 end
 
     assert_receive {^ref, :start}
     assert_receive {^ref, :exception}

test/finch_test.exs

@@ -516,11 +516,12 @@ defmodule FinchTest do
 
       :sys.suspend(finch_name)
 
-      assert {:timeout, _} =
-               catch_exit(
-                 Finch.build(:get, endpoint(bypass))
-                 |> Finch.request(finch_name, pool_timeout: 0)
-               )
+      assert_raise RuntimeError,
+                   ~r/Finch was unable to provide a connection within the timeout/,
+                   fn ->
+                     Finch.build(:get, endpoint(bypass))
+                     |> Finch.request(finch_name, pool_timeout: 0)
+                   end
 
       :sys.resume(finch_name)