Tesla.Env (tesla v1.18.0)

Copy Markdown View Source

This module defines a Tesla.Env.t/0 struct that stores all data related to request/response.

Summary

Types

assigns()
body()
client()
headers()
method()
opts()
param()
private()
query()

Structured query params as a list or map, including nested maps.

query_key()
query_list()
query_pair()
query_scalar()
query_scalar_list()
query_string()
result()
runtime()
stack()
status()
t()

Request/response state carried through the middleware pipeline.

url()

Request URL or request target.

Types

assigns()

@type assigns() :: %{optional(atom()) => any()}

body()

@type body() :: any()

client()

@type client() :: Tesla.Client.t()

headers()

@type headers() :: [{binary(), binary()}]

method()

@type method() :: :head | :get | :delete | :trace | :options | :post | :put | :patch

opts()

@type opts() :: keyword()

param()

@type param() ::
  query_scalar()
  | query_scalar_list()
  | query_list()
  | %{optional(query_key()) => param()}

private()

@type private() :: %{optional(atom()) => any()}

query()

@type query() :: query_list() | query_string() | %{optional(query_key()) => param()}

Structured query params as a list or map, including nested maps.

Examples

  • [{"param", "value"}] will be translated to ?param=value.
  • %{filters: %{page: 1}} will be translated to ?filters%5Bpage%5D=1 (that is, filters[page] with brackets percent-encoded by default).

Map query params do not guarantee encoded parameter order when Tesla's default URL builder encodes them directly. In Tesla.Middleware.Query :modern mode, values matching Tesla.OpenAPI.QueryParams definitions are encoded in definition order.

A Tesla.OpenAPI.QueryString.t/0 value represents the entire URL query string and must not be mixed with normal query params.

query_key()

@type query_key() :: binary() | atom()

query_list()

@type query_list() :: [query_pair()]

query_pair()

@type query_pair() :: {query_key(), param()}

query_scalar()

@type query_scalar() :: String.Chars.t()

query_scalar_list()

@type query_scalar_list() :: [query_scalar()]

query_string()

@type query_string() :: Tesla.OpenAPI.QueryString.t()

result()

@type result() :: {:ok, t()} | {:error, any()}

runtime()

@type runtime() ::
  {atom(), atom(), any()}
  | {atom(), atom()}
  | {:fn, (t() -> t())}
  | {:fn, (t(), stack() -> t())}

stack()

@type stack() :: [runtime()]

status()

@type status() :: integer() | nil

t()

@type t() :: %Tesla.Env{
  __client__: client() | nil,
  __module__: atom() | nil,
  assigns: assigns(),
  body: body(),
  headers: headers(),
  method: method(),
  opts: opts(),
  private: private(),
  query: query(),
  status: status(),
  url: url()
}

Request/response state carried through the middleware pipeline.

Fields

  • :method - method of request. Example: :get.
  • :url - request URL. Example: "https://www.google.com".
  • :query - structured query params. See query/0. Query params passed in the URL, such as "/get?param=value", are not parsed to the :query field.
  • :headers - list of request/response headers. Example: [{"content-type", "application/json"}]. Request headers are overridden by response headers when the adapter is called.
  • :body - request/response body. Request body is overridden by response body when the adapter is called.
  • :status - response status. Example: 200.
  • :opts - list of options. Example: [adapter: [recv_timeout: 30_000]].
  • :assigns - user data as a map for application-specific metadata.
  • :private - data reserved for libraries and middleware. Keys must be atoms. Prefix keys with the name of your project to avoid conflicts. The tesla_ prefix is reserved for Tesla.

url()

@type url() :: binary()

Request URL or request target.

Examples:

Callers are expected to pass a valid, already-encoded URL or request target. Tesla does not automatically validate, normalize, or percent-encode the URL path. Some middleware may rewrite env.url.