Dowser.Client (Dowser.Client v0.1.1)

View Source

Low-level entry point for querying a search backend over HTTP.

request/4 resolves every option into a Dowser.Client.Request, performs it against the resolved config's HTTP adapter, and decodes the response body according to :format, returning {:ok, %Dowser.Client.Response{}} or {:error, exception}.

All option resolution — header merging, URL/query building, adapter selection and body encoding — happens in Dowser.Client.Request.new/5 before the adapter is called; response decoding uses the same :format/JSON adapter.

Errors

Errors are always Dowser exceptions, never a dependency's own exception type:

Options

Every option below can be set globally (config :dowser_client, ...), per config (Dowser.Client.Config), or per request — most specific wins, except the three _opts keyword lists (:codec_opts, :json_opts, :http_opts), which merge across all three (most specific wins per key).

  • :config — the config to query (see Dowser.Client.Config); absent resolves the :default entry from config :dowser_client, configs: [...] (there is no other built-in fallback).
  • :params — query-string parameters appended to the URL.
  • :format — :json (default), :ndjson or :raw; selects the codec used to encode the request body and decode the response body (:raw leaves both untouched). Mutually exclusive with :req_format/:resp_format.
  • :req_format / :resp_format — set the request and response formats independently; each falls back to :format (so :json) when omitted.
  • :codec_adapter — a module implementing Dowser.Client.Codec, used to cast a decoded response body via decode/2, and a request body via encode/2, beyond plain JSON. Defaults to Dowser.Client.Codec.Default, which only applies :keys casting below; see Dowser.Client.Codec for the full contract.
  • :codec_opts — options forwarded to :codec_adapter's decode/2/ encode/2 (e.g. an index mapping); default [].
  • :keys — :strings (default), :atoms or :atoms!; how object keys in the response body are cast. Applied by the default :codec_adapter; a custom one is responsible for applying opts[:key_fn] itself if it wants the same behavior.
  • :http_adapter / :json_adapter — the HTTP/JSON adapter modules.
  • :json_opts — options forwarded to the JSON adapter's encode/2/decode/2.
  • :http_opts — options forwarded to the HTTP adapter's request/5, including :headers (a map or list of {name, value} pairs, merged over global and config headers plus a derived content-type).
  • :retry — retry policy for transient failures; see Dowser.Client.Retry.

Summary

Types

method()
result()

Functions

delete(path, body \\ nil, opts \\ [])
get(path, opts \\ [])
patch(path, body \\ nil, opts \\ [])
post(path, body \\ nil, opts \\ [])
put(path, body \\ nil, opts \\ [])
request(method, path, body \\ nil, opts \\ [])

Runs an HTTP request against the config given in opts[:config].

Types

method()

@type method() :: Dowser.Client.HTTP.Adapter.method()

result()

@type result() :: {:ok, Dowser.Client.Response.t()} | {:error, Exception.t()}

Functions

delete(path, body \\ nil, opts \\ [])

get(path, opts \\ [])

patch(path, body \\ nil, opts \\ [])

post(path, body \\ nil, opts \\ [])

put(path, body \\ nil, opts \\ [])

request(method, path, body \\ nil, opts \\ [])

@spec request(method(), String.t(), term(), keyword()) :: result()

Runs an HTTP request against the config given in opts[:config].

Returns {:ok, %Dowser.Client.Response{}} on a completed exchange (any HTTP status), or {:error, exception} when the config cannot be resolved, the body cannot be encoded/decoded, or the transport fails.