feat: introduce pluggable HTTP client behaviour

[klacointe]

Summary

• Follow up of Add pluggable HTTP client behaviour with Hackney and Finch implementations #148
• Adds Waffle.HTTPClient behaviour with a single get/3 callback
• Adds Waffle.HTTPClient.Hackney as the default implementation (existing behaviour, just moved into a dedicated module)
• Refactors Waffle.File to dispatch through the configured :http_client instead of calling hackney directly; retry logic stays client-agnostic
• Documents how to implement a custom HTTP client adapter

Usage

Configure a custom client:

config :waffle, :http_client, MyApp.HTTPClient

Implement the behaviour:

defmodule MyApp.HTTPClient do
  @behaviour Waffle.HTTPClient

  @impl Waffle.HTTPClient
  def get(url, headers, options) do
    # ...
  end
end

Error shape changes

Error case	Before	After
Connect timeout	{:error, :timeout}	{:error, :timeout} — unchanged
Receive timeout	{:error, :recv_timeout}	{:error, :recv_timeout} — unchanged
503 out of retries	{:error, {:waffle_hackney_error, {:ok, 503, headers, ref}}}	{:error, :service_unavailable}
Non-2xx response	{:error, {:waffle_hackney_error, {:ok, status, headers, ref}}}	{:error, {:http_error, status}} e.g. {:error, {:http_error, 404}}

The previous 503 and non-2xx shapes leaked a closed hackney client_ref inside the error tuple.

Notes

• Hackney remains the default and a required dependency — no breaking change for existing users
• This PR intentionally excludes a Finch adapter; that is a separate concern (Add pluggable HTTP client behaviour with Hackney and Finch implementations #148)

#75

[klacointe]

@achempion when you'll be ok with this one I'll propose the Finch adapter.

[achempion]

looking great, left couple of minor comments before merging

[fastjames]

I am excited to see this work going into waffle, and I'm happy to help push it forward if needed.

[klacointe]

I am excited to see this work going into waffle, and I'm happy to help push it forward if needed.

I'm on holidays for the 2 following weeks and will not have time to work on this before 😕

[klacointe]

I am excited to see this work going into waffle, and I'm happy to help push it forward if needed.

I'm on holidays for the 2 following weeks and will not have time to work on this before 😕

I finally found some time.

[achempion]

Looking great, thanks for the PR

I'll publish new minor release soon.