Dowser.Client.Request (Dowser.Client v0.3.0)

View Source

A fully-resolved HTTP request, ready to hand to Dowser.Client.HTTP.

new/5 turns a Dowser.Client.Context plus a method, path, body and per-request options into a %Request{}. All option resolution happens here, so the transport only ever sees a finished request:

  • headers — merge of global (config :dowser_client, :http_opts, headers: ...), context (auth + context http_opts[:headers]) and per-request (opts[:http_opts][:headers]) headers, plus a content-type derived from the request format. Later sources win on name clashes. Each source accepts either a map or a list of {name, value} pairs.
  • url — the context's endpoint joined with the request path and, when given, opts[:params] encoded as a query string. An absolute path is used verbatim.
  • body — a document source in it cast through :encoder when :encode says where (see Casting below), then encoded according to the request format (:json, :ndjson or :raw) by Dowser.Client.JSON/Dowser.Client.NDJSON.
  • http_opts — :http_opts merged global → context → request (minus :headers, kept as its own field — see above), plus the resolved :profile and :profile_opts. Handed straight to Dowser.Client.HTTP.request/5.
  • retry — the resolved retry policy, from opts[:retry] and the method (which decides whether the request is idempotent, and so what may be retried); see Dowser.Client.Retry.

Formats

The request and response bodies each have a format (:json, :ndjson or :raw), resolved from the options:

  • :format — sets both, and is mutually exclusive with :req_format / :resp_format. Defaults to :json.
  • :req_format / :resp_format — set each direction independently; a missing one falls back to :format (so :json).

Casting

A response body always decodes to plain, string-keyed terms. :keys and :decoder — resolved here into the :key_fn and :decoder fields, each falling back to the context's value then to config :dowser_client, ... — configure the optional second pass over it; see Dowser.Client.Decoder. Neither set means no second pass at all.

A request body is encoded as given unless :encode points at a document source in it, in which case :encoder — the encoder and the options it needs — casts that source; a query is never touched. See Dowser.Client.Encoder.

The second pass is skipped when the format is :raw or the body is empty.

Summary

Types

format()
t()

Functions

new(context, method, path, body, opts)

Resolves a context plus a method, path, body and options into a %Request{}.

run(request)

Performs the request over Dowser.Client.HTTP.

Types

format()

@type format() :: :json | :ndjson | :raw

t()

@type t() :: %Dowser.Client.Request{
  body: Dowser.Client.HTTP.body(),
  decoder: Dowser.Client.Decoder.resolved() | nil,
  headers: Dowser.Client.HTTP.headers(),
  http_opts: keyword(),
  key_fn: Dowser.Client.Decoder.key_fun() | nil,
  method: Dowser.Client.HTTP.method(),
  resp_format: format(),
  retry: Dowser.Client.Retry.config(),
  url: String.t()
}

Functions

new(context, method, path, body, opts)

@spec new(
  Dowser.Client.Context.t(),
  Dowser.Client.HTTP.method(),
  String.t() | nil,
  term(),
  keyword()
) ::
  {:ok, t()} | {:error, Exception.t()}

Resolves a context plus a method, path, body and options into a %Request{}.

Returns {:error, exception} for an invalid option, an unsupported body, or a :decoder/:encoder that raised — never raises, whatever those do.

run(request)

@spec run(t()) :: {:ok, Dowser.Client.Response.t()} | {:error, term()}

Performs the request over Dowser.Client.HTTP.