tadpole/rest/execute

The REST executor: turns RestRequests into responses over an injected transport. Tests run against canned gleam/http values; the Erlang target ships gleam_httpc. Rate-limit behaviour is learned from response headers and 429 bodies only (see tadpole/rest/rate_limit) and applied as best-effort waits before sending.

Transport failures surface as RestStatus with the synthetic status 0 and a “no HTTP response: …” body. No variant in error.gleam describes a REST transport failure honestly — GatewayConnectFailed means gateway reconnects — and status 0 reads as “no HTTP happened” anywhere a status is printed.

When you reach for this

Behind tadpole/rest/endpoints for the known calls; directly when you need a Discord route the endpoint helpers do not wrap, or when one run of calls should share rate-limit state (send_in_session). Tests reach for it constantly: Transport is one function.

Transport injection

Transport is fn(Request(String)) -> Result(Response(String), TransportError) — the executor knows nothing else about HTTP. httpc_transport wraps gleam_httpc for production; tests hand in a closure returning canned responses; a future JS target would hand in fetch. The TransportError shapes mirror gleam_httpc 5.x’s HttpError one-to-one, so nothing is lost in translation and other transports map onto the same three cases.

The status-0 convention

When the transport fails — no connection, timeout, non-UTF-8 body — no HTTP response exists to report. Rather than stretch a variant, the failure becomes error.RestStatus with status: 0, discord_code: None, and the transport’s own description in the body: "no HTTP response: failed to connect (ipv4: ..., ipv6: ...)". Matching RestStatus(_, 0, _, _) catches every “Discord never saw this request” case.

send, send_with_sleep, send_in_session

• send — one request, throwaway rate-limit state: waits learned during this call throttle only this call’s own 429 retries, and nothing carries to the next call. What the endpoint helpers use.
• send_with_sleep — send with the sleep function injected; tests pass a recorder instead of waiting real milliseconds.
• send_in_session — the request runs inside a RestSession, so a wait learned from one response gates the next call on the same route. Returns the updated session; thread it through your loop.

429 retry flow

On a 429: fold the response into the session, then, if the client has retry_on_429 and attempts remain, sleep the window the response asked for — the Retry-After header (whole seconds, to ms) first, else the body’s fractional retry_after — and try again. When retries run out, the error is error.RateLimited carrying the route, the last window in ms, the global flag, and the bucket id. Zero-window 429s retry immediately. Sleeps are real process.sleep: the calling process waits.

RestSession ownership honesty

A RestSession is a plain value, not a process. Passing it to two processes gives each an independent copy — no cross-process coordination, and no corruption either. The executor owns no clock: a wait is measured as time elapsed since the response that produced it, so a session reused long after real time passed waits slightly long. That errs safe.

Concurrency

• send and send_with_sleep share nothing between calls: safe from as many processes as you like.
• A session threaded through one process serializes that route’s calls — that is the point. Sent across processes, it is copied and learned waits diverge silently (see above).
• Every sleep blocks the calling process: pre-send waits, 429 windows, and the HTTP round trip (bounded by the client timeout).

Failure modes

RestStatus for any non-2xx and RateLimited when 429s outlast the retries — nothing else. The body is returned raw, so no DecodeFailed here; decoding is the endpoint’s job. Never panics, and the token never appears in an error.

See also

• tadpole/rest/rate_limit — the pure state behind the waits
• tadpole/rest — request builders and header parsing
• tadpole/rest/endpoints — the endpoint helpers on top

pub type ConnectError {
  Posix(code: String)
  TlsAlert(code: String, detail: String)
}

pub type RestSession {
  RestSession(
    client: rest.RestClient,
    buckets: dict.Dict(String, rate_limit.BucketState),
    routes: dict.Dict(String, error.BucketId),
  )
}

pub type Transport =
  fn(request.Request(String)) -> Result(
    response.Response(String),
    TransportError,
  )

pub type TransportError {
  InvalidUtf8Response
  FailedToConnect(ip4: ConnectError, ip6: ConnectError)
  ResponseTimeout
}

pub fn httpc_transport(
  timeout_ms: Int,
) -> fn(request.Request(String)) -> Result(
  response.Response(String),
  TransportError,
)

pub fn new_session(client: rest.RestClient) -> RestSession

pub fn send(
  client: rest.RestClient,
  request: rest.RestRequest,
  transport: fn(request.Request(String)) -> Result(
    response.Response(String),
    TransportError,
  ),
) -> Result(rest.RestResponse, error.TadpoleError)

pub fn send_in_session(
  session: RestSession,
  request: rest.RestRequest,
  transport: fn(request.Request(String)) -> Result(
    response.Response(String),
    TransportError,
  ),
  sleep_fn: fn(Int) -> Nil,
) -> #(Result(rest.RestResponse, error.TadpoleError), RestSession)

pub fn send_with_sleep(
  client: rest.RestClient,
  request: rest.RestRequest,
  transport: fn(request.Request(String)) -> Result(
    response.Response(String),
    TransportError,
  ),
  sleep_fn: fn(Int) -> Nil,
) -> Result(rest.RestResponse, error.TadpoleError)

pub fn transport_error_to_string(
  transport_error: TransportError,
) -> String