@spec build_auth_headers(http_method(), String.t(), body(), map(), auth_scheme()) ::
  headers()

Build authentication headers for API requests.

Parameters

• method: HTTP method
• path: API endpoint path
• body: Request body
• credentials: API credentials
• auth_type: Authentication type: :hmac_sha256, :basic, :bearer, or a 4-arity function (method, path, body, credentials -> headers) for a venue's own scheme

Returns

• List of authentication headers. An auth_type that is none of the above raises ArgumentError. It used to yield [], so a typo'd scheme (:hmac_sha_256) sent the request unauthenticated — the opposite of failing closed.

@spec get(String.t(), keyword() | map(), rate_limited_request_options()) ::
  {:ok, any()} | {:error, request_error()}

Convenience function for GET requests with query parameters.

Parameters

• url: Base URL for the request
• params: Query parameters as keyword list or map. nil values are dropped. Keys and values are form-encoded. A list, tuple or plain-map value raises ArgumentError: it has no single spelling, and the venue decides between repeated keys and a comma join.
• opts: Additional options

Returns

• {:ok, parsed_json} on success. With decode_body: false the bytes are decoded here with Jason's floats: :decimals, so a JSON number is a Decimal and keeps its digits.
• {:error, reason} on failure

@spec parse_rate_limit_headers(headers() | map()) :: map() | nil

Parses rate-limit information from response headers, for the conventional x-ratelimit-limit / x-ratelimit-remaining / x-ratelimit-reset shape only.

Returns nil when the headers do not carry it. nil means "this response did not say", never "there is no limit" — a caller must not read an absent header as headroom.

This used to take a provider name and dispatch on it, with branches for two venues' bespoke headers. Those branches are venue knowledge and moved into the venue packages (D-C); a venue whose headers differ parses them itself, and does not need this function to have heard of it.

@spec request(
  http_method(),
  String.t(),
  signed_headers(),
  body(),
  rate_limited_request_options()
) ::
  {:ok, http_response()} | {:error, request_error()}

Make an HTTP request with provider-specific and account-aware rate limiting.

Parameters

• method: HTTP method (:get, :post, :put, :delete)
• url: Full URL for the request
• headers: List of HTTP headers, or a zero-arity function returning them (or {:ok, list} / {:error, reason}) that is called again before every attempt, so a signed request is re-signed on retry rather than replayed
• body: Request body (for POST/PUT requests). A :get with a non-empty body raises ArgumentError before anything is sent, because Req 0.7.0-0.7.2 send it as a POST
• opts: Additional options including rate limiting context

Options

• :timeout - Request timeout in milliseconds, or :infinity (default: 30_000). It bounds the whole response, not each chunk, and it applies to each attempt when :retry_attempts retries.
• :retry_attempts - Number of attempts in all; 0 sends once, like 1 (default: 3 for :get, 1 for :post, :put and :delete). A transport failure or 5xx after a write may mean the write took effect, and a retry repeats it. Whether that is safe depends on whether the venue deduplicates the request, which only the venue package knows. So a write is never retried unless the venue says so: one with an idempotency key, such as a client_order_id, passes an explicit retry_attempts. A write without one needs nothing.
• :retry_delay - Base delay between retries in milliseconds (default: 1000). The wait before retry n is retry_delay * n plus up to a quarter of that again at random, so it is never shorter than the configured delay. A delay whose longest wait over the attempts (jitter included) passes 4_294_967_295 ms, the most a process can sleep, is an ArgumentError before anything is sent. What is retried: a transport failure, a 5xx and an unexpected status. What is not: a 4xx (permanent), a 3xx (redirect is off, so the same request gets the same answer), a 429 (the venue's Retry-After holds the bucket and the error returns at once), a body over :max_body_bytes, and a request that could not be signed.
• :log_requests - Whether to log requests (default: true)
• :provider - The venue's identity: echoed in {:exchange_error, provider, _} and in every [:dp_exchange, :request | :rate_limit, _] event's provider:. Also the limiter bucket unless :rate_limit_key names another (no :provider and no :rate_limit_key means no rate limiting). An atom or a non-blank string, or ArgumentError before anything is sent (:rate_limit_key too): both are printed into log lines and bucket names.
• :rate_limit_key - The limiter bucket this request is metered in (default: :provider). Selects ONLY the bucket: a venue that meters order writes apart from its reads passes provider: :venue, rate_limit_key: :venue_orders, and errors and telemetry still say :venue. The limiter is handed the key and, as :telemetry_provider, the identity. The ceiling for the key is configured under the key (DefaultRateLimiter :limits).
• :plug, :adapter, :req_adapter - The transport seam, passed to Req (:req_adapter is this package's name for :adapter and loses to an explicit one). For a transport that never leaves the process, such as a test stub.
• :headers - get/3 only: request headers (default: []).
• :rate_limit_per_endpoint - Also meter this request in a bucket of its own endpoint, keyed "<provider> <path>", beside the provider's (default: false). For a venue that states a per-endpoint limit as well as a global one. The endpoint bucket takes the limiter's :default limits unless the consumer names it.
• :rate_limit_blocking - Wait for the limiter instead of failing when the bucket is empty (default: false). The wait is bounded by :timeout.
• :weight - Tokens this request costs (default: 1)
• :max_retry_after_s - Ceiling, in seconds, on a venue's Retry-After that is honoured (default: 600). A non-negative integer of at most 4_294_967 (the seconds whose milliseconds are the longest hold a limiter can serve), or ArgumentError before anything is sent.
• :account_id, :user_id, :operation - Forwarded to the limiter, which may use them (optional, no defaults). DefaultRateLimiter ignores all three: the ceiling is per venue, never per key.
• :max_body_bytes - The most of a response body that is received (default: 16 MiB, 16_777_216). Counted as the bytes arrive; the transfer is halted the moment the total passes the limit, so an oversized or endless body is never held in memory. The result is {:error, {:response_too_large, limit}} (wrapped in {:exchange_error, provider, _} when :provider is given), is never retried, and is reported on [:dp_exchange, :request, :stop] with result: :error, reason: :response_too_large. A body of exactly the limit is accepted. A positive integer, or ArgumentError. The count is of the bytes on the wire: this pipeline never asks for compression (Req's :compressed is off), so it is also the decoded size.
• :raw_status - Return {:ok, response} for a 4xx instead of an error string (default: false). A venue package needs this to tell a refusal from an error: the contract makes {:refused, reason} permanent and {:error, reason} possibly transient, and the venue states which in the 4xx status and body. Without it that evidence is flattened into a message and the venue has to string-match its way back to it. 5xx is unaffected — a server error is not a venue's considered answer. 429 is unaffected too: it is the venue's rate limit, handled by this pipeline (Retry-After, the held bucket, telemetry), and is always the "Rate limited by the venue" error, whether or not :raw_status is set.
• :decode_body - Passed to Req (default: Req's, which decodes JSON with floats). false returns the body as bytes, for a venue that types money as a JSON number and must decode it without float rounding (Jason.decode(body, floats: :decimals)).

Returns

• {:ok, http_response()} on success, and on a 4xx when raw_status: true
• {:error, reason} on failure