feat: Add custom HTTP Client implementation

Author: rafaeelaudibert

README.md

@@ -13,6 +13,7 @@ A powerful Elixir client for [PostHog](https://posthog.com), providing seamless
 - Custom Properties: Support for user, group, and person properties
 - Flexible Configuration: Customizable JSON library and API version
 - Environment Control: Disable tracking in development/test environments
+- Configurable HTTP Client: Customizable timeouts, retries, and HTTP client implementation
 
 ## Installation
 
@@ -76,7 +77,49 @@ config :posthog,
 # Optional configurations
 config :posthog,
   json_library: Jason,  # Default JSON parser (optional)
-  enabled: true        # Whether to enable PostHog tracking (optional, defaults to true)
+  enabled: true,       # Whether to enable PostHog tracking (optional, defaults to true)
+  http_client: Posthog.HTTPClient.Hackney,  # Default HTTP client (optional)
+  http_client_opts: [  # HTTP client options (optional)
+    timeout: 5_000,    # Request timeout in milliseconds (default: 5_000)
+    retries: 3,        # Number of retries on failure (default: 3)
+    retry_delay: 1_000 # Delay between retries in milliseconds (default: 1_000)
+  ]
+```
+
+### HTTP Client Configuration
+
+The library uses Hackney as the default HTTP client, but you can configure its behavior or even swap it for a different implementation by simply implementing the `Posthog.HTTPClient` behavior:
+
+```elixir
+# config/config.exs
+config :posthog,
+  # Use a different HTTP client implementation
+  http_client: MyCustomHTTPClient,
+
+  # Configure HTTP client options
+  http_client_opts: [
+    timeout: 10_000,   # 10 seconds timeout
+    retries: 5,        # 5 retries
+    retry_delay: 2_000 # 2 seconds between retries
+  ]
+```
+
+For testing, you might want to use a mock HTTP client:
+
+```elixir
+# test/support/mocks.ex
+defmodule Posthog.HTTPClient.Test do
+  @behaviour Posthog.HTTPClient
+
+  def post(url, body, headers, _opts) do
+    # Return mock responses for testing
+    {:ok, %{status: 200, headers: [], body: %{}}}
+  end
+end
+
+# config/test.exs
+config :posthog,
+  http_client: Posthog.HTTPClient.Test
 ```
 
 ### Disabling PostHog capture
@@ -248,7 +291,6 @@ If you encounter WX library issues during Erlang installation:
 ```sh
 # Disable WX during installation
 export KERL_CONFIGURE_OPTIONS="--without-wx"
-asdf install
 ```
 
 To persist this setting, add it to your shell configuration file (`~/.bashrc`, `~/.zshrc`, or `~/.profile`).

lib/posthog/client.ex

@@ -19,8 +19,13 @@ defmodule Posthog.Client do
         api_url: "https://app.posthog.com",  # Required
         api_key: "phc_your_project_api_key", # Required
         json_library: Jason,                 # Optional (default: Jason)
-        enabled_capture: true                # Optional (default: true)
-                                             # Set to false to disable all tracking
+        enabled_capture: true,               # Optional (default: true)
+        http_client: Posthog.HTTPClient.Hackney,  # Optional (default: Posthog.HTTPClient.Hackney)
+        http_client_opts: [                  # Optional
+          timeout: 5_000,    # 5 seconds
+          retries: 3,        # Number of retries
+          retry_delay: 1_000 # 1 second between retries
+        ]
 
   ### Disabling capture
 
@@ -365,35 +370,12 @@ defmodule Posthog.Client do
 
     url = Posthog.Config.api_url() <> path
 
-    :hackney.post(url, headers, body, [])
-    |> handle()
-  end
-
-  @doc false
-  @spec handle(tuple()) :: {:ok, response()} | {:error, response() | term()}
-  defp handle({:ok, status, _headers, _ref} = resp) when div(status, 100) == 2 do
-    {:ok, to_response(resp)}
-  end
-
-  defp handle({:ok, _status, _headers, _ref} = resp) do
-    {:error, to_response(resp)}
-  end
-
-  defp handle({:error, _} = result) do
-    result
-  end
-
-  @doc false
-  @spec to_response({:ok, pos_integer(), headers(), reference()}) :: response()
-  defp to_response({_, status, headers, ref}) do
-    response = %{status: status, headers: headers, body: nil}
-
-    with {:ok, body} <- :hackney.body(ref),
-         {:ok, json} <- Posthog.Config.json_library().decode(body) do
-      %{response | body: json}
-    else
-      _ -> response
-    end
+    Posthog.Config.http_client().post(
+      url,
+      body,
+      headers,
+      Posthog.Config.http_client_opts()
+    )
   end
 
   @doc false

lib/posthog/config.ex

@@ -84,6 +84,31 @@ defmodule Posthog.Config do
     Application.get_env(@app, :json_library, Jason)
   end
 
+  @doc """
+  Returns the HTTP client module to use.
+
+  Defaults to Posthog.HTTPClient.Hackney if not configured.
+  """
+  def http_client do
+    Application.get_env(@app, :http_client, Posthog.HTTPClient.Hackney)
+  end
+
+  @doc """
+  Returns the HTTP client options.
+
+  Defaults to:
+  - timeout: 5_000 (5 seconds)
+  - retries: 3
+  - retry_delay: 1_000 (1 second)
+  """
+  def http_client_opts do
+    Application.get_env(@app, :http_client_opts,
+      timeout: 5_000,
+      retries: 3,
+      retry_delay: 1_000
+    )
+  end
+
   @doc """
   Validates the entire PostHog configuration at compile time.
 
@@ -109,6 +134,20 @@ defmodule Posthog.Config do
       end
     end
 
+    # Validate HTTP client
+    http_client = http_client()
+
+    unless Code.ensure_loaded?(http_client) do
+      raise """
+      Configured HTTP client #{inspect(http_client)} is not available.
+
+      Make sure to add it to your dependencies in mix.exs:
+          defp deps do
+            [{:hackney, "~> x.x"}]
+          end
+      """
+    end
+
     :ok
   end
 end

lib/posthog/http_client.ex

@@ -0,0 +1,68 @@
+defmodule Posthog.HTTPClient do
+  @moduledoc """
+  Behaviour for HTTP client implementations.
+
+  This allows for easy swapping of HTTP clients and better testability.
+  """
+
+  @type headers :: [{binary(), binary()}]
+  @type response :: %{status: pos_integer(), headers: headers(), body: map() | nil}
+  @type body :: iodata() | binary()
+  @type url :: binary()
+
+  @doc """
+  Makes a POST request to the given URL with the specified body and headers.
+
+  Returns `{:ok, response}` on success or `{:error, reason}` on failure.
+  """
+  @callback post(url(), body(), headers(), keyword()) :: {:ok, response()} | {:error, term()}
+end
+
+defmodule Posthog.HTTPClient.Hackney do
+  @moduledoc """
+  Hackney-based implementation of the Posthog.HTTPClient behaviour.
+  """
+
+  @behaviour Posthog.HTTPClient
+
+  @default_timeout 5_000
+  @default_retries 3
+  @default_retry_delay 1_000
+
+  @impl true
+  def post(url, body, headers, opts \\ []) do
+    timeout = Keyword.get(opts, :timeout, @default_timeout)
+    retries = Keyword.get(opts, :retries, @default_retries)
+    retry_delay = Keyword.get(opts, :retry_delay, @default_retry_delay)
+
+    do_post(url, body, headers, timeout, retries, retry_delay)
+  end
+
+  defp do_post(url, body, headers, timeout, retries, retry_delay) do
+    case :hackney.post(url, headers, body, []) do
+      {:ok, status, _headers, _ref} = resp when div(status, 100) == 2 ->
+        {:ok, to_response(resp)}
+
+      {:ok, _status, _headers, _ref} = resp ->
+        {:error, to_response(resp)}
+
+      {:error, _reason} when retries > 0 ->
+        Process.sleep(retry_delay)
+        do_post(url, body, headers, timeout, retries - 1, retry_delay)
+
+      {:error, _reason} = error ->
+        error
+    end
+  end
+
+  defp to_response({_, status, headers, ref}) do
+    response = %{status: status, headers: headers, body: nil}
+
+    with {:ok, body} <- :hackney.body(ref),
+         {:ok, json} <- Posthog.Config.json_library().decode(body) do
+      %{response | body: json}
+    else
+      _ -> response
+    end
+  end
+end