Confusion around when to use timeout vs recv_timeout

[Cohen-Carlisle]

Getting {:error, %HTTPoison.Error{id: nil, reason: :timeout}} in about 6 seconds with my options set as [timeout: 30_000]. After much digging and confusion, it seems that the timeout is stemming from recv_timeout being too low. I found this confusing for 2 reasons:

1. reason: :timeout is reported, which suggests that the timeout is the appropriate option to adjust.
2. The docs around timeout vs recv_timeout are pretty vague... I'm still not sure exactly what each one does and how they are different.

[edgurgel]

Yeah the struggle is real: #211

The only way to solve this issue is to patch hackney so that it will provide the correct timeout error.

[jschneider1207]

@edgurgel hackney returns {:error, :connect_timeout} when the connect_timeout is reached, and {:error, :timeout} when the recv_timeout is reached.

iex(2)> :hackney.request(:get, 'http://google.com', [], [], [{:connect_timeout, 1}])
{:error, :connect_timeout}
iex(3)> :hackney.request(:get, 'http://google.com', [], [], [{:recv_timeout, 1}])
{:error, :timeout}

so this should be doable.

Edit: I'm guessing the confusion is because the HTTPoison option :timeout (which corresponds to hackney :connect_timeout) returns a :connect_timeout error, whereas the HTTPoison :recv_timeout returns the :timeout hackney error. So if you get a :timeout error from :recv_timeout occuring, you would probably think to increase the :timeout option, which goes to the wrong option.

[Cohen-Carlisle]

Any plans to do anything further with this? I think the new(-ish) docs around setting :timeout and :recv_timeout in request options are great, but there is still a lot of potential for confusion around getting back :timeout | :connect_timeout error reasons and trying to set the corresponding request options. (As an anecdote, I showed my team the behavior around the timeouts and they were very confused 😄.) I see a few approaches:

1. Change the request options to match the error reasons, or vice versa. Unfortunately, it would be backwards incompatible.
2. Introduce a :connect_timeout option that is an alias of :timeout. Doesn't solve the problem of getting a :timeout reason and setting the (incorrect) :timeout option.
3. Add more docs around the specific timeout reasons and which request option to set. This would be helpful no matter what else was done.

I might be able to carve out some time to do number 3.