Add custom HTTP client instructions (#10)

Author: jaeyson

.github/workflows/ci.yml

@@ -67,7 +67,7 @@ jobs:
 
       - name: Start Typesense
         run: |
-          docker run -d \
+          docker run -id \
           -p 8108:8108 \
           --name typesense \
           -v /tmp/typesense-data:/data \
@@ -81,8 +81,24 @@ jobs:
           --analytics-minute-rate-limit=100 \
           --enable-cors
 
-      - name: Curl Typesense
-        run: sleep 1 && curl http://localhost:8108/health
+      - name: Wait for Typesense to be healthy
+        shell: bash
+        run: |
+          start_time=$(date +%s)
+          timeout=30
+          counter=0
+          until curl -s http://localhost:8108/health | grep -q '"ok":true'; do
+            if [ $counter -eq $timeout ]; then
+              echo "Timed out waiting for Typesense to be healthy"
+              exit 1
+            fi
+            echo "Waiting for Typesense to be healthy..."
+            sleep 1
+            counter=$((counter + 1))
+          done
+          end_time=$(date +%s)
+          elapsed=$((end_time - start_time))
+          echo "Typesense healthcheck elapsed: ${elapsed}s"
 
       - name: Setup Elixir/OTP
         uses: erlef/setup-beam@v1
@@ -106,9 +122,6 @@ jobs:
           mix local.hex --if-missing
           mix deps.get
 
-      - name: Compile
-        run: mix compile
-
       - name: Find unused dependencies
         run: mix deps.unlock --check-unused
         if: ${{ matrix.lint }}

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## major.minor.patch (yyyy.mm.dd)
 
+## 0.5.0 (2025.01.08)
+
+### Added
+
+* User(s) can use another HTTP client instead of default ([Req](https://hexdocs.pm/req)).
+
+### Changed
+
+* Update docs
+* Static to Dynamic fetching of application name for connection defaults.
+* Update docs and include few anchor links.
+* Update specific test where async is disabled when using [`Application.put_env/4`](https://elixirforum.com/t/using-application-get-env-application-put-env-in-exunit-tests/8019/2)
+
 ## 0.4.3 (2024.12.27)
 
 ### Changed

README.md

@@ -10,9 +10,6 @@ Restful client for Typesense with adherence to Open API spec 3 (formerly Swagger
 [![Coverage Status](https://coveralls.io/repos/github/jaeyson/open_api_typesense/badge.svg?branch=main)](https://coveralls.io/github/jaeyson/open_api_typesense?branch=main)
 [![CI Status](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jaeyson/open_api_typesense/actions/workflows/ci.yml)
 
-## TODO
-- Custom Http client adapter (currently [`Req`](https://hexdocs.pm/req))
-
 ## Installation
 
 If [available in Hex](https://hex.pm/docs/publish), the package can be installed
@@ -21,7 +18,7 @@ by adding `open_api_typesense` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:open_api_typesense, "~> 0.4"}
+    {:open_api_typesense, "~> 0.5"}
 
     # Or from GitHub repository, if you want the latest greatest from main branch
     {:open_api_typesense, git: "https://github.com/jaeyson/open_api_typesense.git"}
@@ -53,8 +50,7 @@ if config_env() == :prod do # if you'll use this in prod environment
     api_key: "xyz",
     host: "localhost",
     port: 8108,
-    scheme: "http",
-    options: %{}
+    scheme: "http"
   ...
 ```
 
@@ -64,11 +60,106 @@ if config_env() == :prod do # if you'll use this in prod environment
 
 For Cloud hosted, you can generate and obtain the credentials from cluster instance admin interface:
 
+```elixir
+config :open_api_typesense,
+  api_key: "credential", # Admin API key
+  host: "111222333aaabbbcc-9.x9.typesense.net", # Nodes
+  port: 443,
+  scheme: "https"
+```
+
+## Using a another HTTP client
+
+In order to use another HTTP client, OpenApiTypesense has a
+callback function ([Behaviours](https://hexdocs.pm/elixir/typespecs.html#behaviours))
+called `request` that contains 2 args:
+
+1. `conn`: your connection map
+2. `params`: payload, header, and client-related stuffs.
+
+> #### `conn` and `params` {: .info}
+>
+> you can change the name `conn` and/or `params` however you want,
+> since it's just a variable.
+
+Here's a custom client example ([`HTTPoison`](https://hexdocs.pm/httpoison/readme.html))
+in order to match the usage:
+
+```elixir
+defmodule MyApp.CustomClient do
+  def request(conn, params) do
+    url = %URI{
+      scheme: conn.scheme,
+      host: conn.host,
+      port: conn.port,
+      path: params.url,
+      query: URI.encode_query(params[:query] || %{})
+    }
+    |> URI.to_string()
+
+    request = %HTTPoison.Request{method: params.method, url: url}
+
+    request =
+      if params[:request] do
+        [{content_type, _schema}] = params.request
+        
+        headers = [
+          {"X-TYPESENSE-API-KEY", conn.api_key}
+          {"Content-Type", content_type}
+        ]
+
+        %{request | headers: headers}
+      else
+        request
+      end
+
+    request =
+      if params[:body] do
+        %{request | body: Jason.encode!(params.body)}
+      else
+        request
+      end
+
+    HTTPoison.request!(request)
+  end
+end
+```
+
+Then add your client in your config file:
+
 ```elixir
 config :open_api_typesense,
   api_key: "credential", # Admin API key
   host: "111222333aaabbbcc-9.x9.typesense.net", # Nodes
   port: 443,
   scheme: "https",
-  options: %{}
+  client: MyApp.CustomClient # <- add this
 ```
+
+And here's a reference taken from one of functions from [`Collections`](https://hexdocs.pm/open_api_typesense/OpenApiTypesense.Collections.html#create_collection/3), as
+you may want to match the params:
+
+```elixir
+def create_collection(%Connection{} = conn, body, opts) when is_struct(conn) do
+  client = opts[:client] || @default_client
+  query = Keyword.take(opts, [:src_name])
+
+  client.request(conn, %{
+    args: [body: body],
+    call: {OpenApiTypesense.Collections, :create_collection},
+    url: "/collections",
+    body: body,
+    method: :post,
+    query: query,
+    request: [{"application/json", {OpenApiTypesense.CollectionSchema, :t}}],
+    response: [
+      {201, {OpenApiTypesense.CollectionResponse, :t}},
+      {400, {OpenApiTypesense.ApiResponse, :t}},
+      {409, {OpenApiTypesense.ApiResponse, :t}}
+    ],
+    opts: opts
+  })
+end
+```
+
+Check [the examples](./guides/custom_http_client.md) on some HTTP client implementations.

config/config.exs

@@ -8,7 +8,7 @@ if Mix.env() in [:dev, :test] do
     scheme: "http"
 end
 
-if Mix.env() == :dev do
+if config_env() in [:dev] do
   config :oapi_generator,
     default: [
       output: [