effect

A sans-IO effect kernel: an Effect(a) is a pure description of the HTTP + DPoP steps a flow needs, interpreted by a per-target runner. Keys never appear here; DpopProof asks the runner for a proof. Fetch carries string bodies (OAuth endpoints), FetchBits binary (the resource path).

Every URL the kernel fetches was parsed by atproto_core/remote first, but the runner’s transport is still part of the trust boundary: it must not follow redirects (a 3xx has to reach the kernel, which rejects it), must cap response size and request time, and on a server must refuse destinations that resolve to private, loopback, link-local or unique-local addresses.

Types

Effect

pub type Effect(a) {
  Fetch(
    request: request.Request(String),
    next: fn(
      Result(response.Response(String), xrpc.TransportError),
    ) -> Effect(a),
  )
  FetchBits(
    request: request.Request(BitArray),
    next: fn(
      Result(response.Response(BitArray), xrpc.TransportError),
    ) -> Effect(a),
  )
  DpopProof(
    method: String,
    url: String,
    nonce: option.Option(String),
    ath: option.Option(String),
    next: fn(Result(String, String)) -> Effect(a),
  )
  Done(a)
}

Constructors

Fetch(
  request: request.Request(String),
  next: fn(Result(response.Response(String), xrpc.TransportError)) -> Effect(
    a,
  ),
)

FetchBits(
  request: request.Request(BitArray),
  next: fn(
    Result(response.Response(BitArray), xrpc.TransportError),
  ) -> Effect(a),
)

DpopProof(
  method: String,
  url: String,
  nonce: option.Option(String),
  ath: option.Option(String),
  next: fn(Result(String, String)) -> Effect(a),
)

```
Done(a)
```

FetchError

Why a get_json lookup failed. Carries the URL and status, never the response body: a body from an arbitrary host is not echoed into errors.

pub type FetchError {
  FetchTransportFailed(url: String, error: xrpc.TransportError)
  FetchBadStatus(url: String, status: Int)
  FetchDecodeFailed(url: String, reason: String)
}

Constructors

FetchTransportFailed(url: String, error: xrpc.TransportError)

FetchBadStatus(url: String, status: Int)

FetchDecodeFailed(url: String, reason: String)

Values

done

pub fn done(value: a) -> Effect(a)

fetch

pub fn fetch(
  request: request.Request(String),
) -> Effect(
  Result(response.Response(String), xrpc.TransportError),
)

A string-bodied HTTP request, yielding the response (or a transport error).

fetch_bits

pub fn fetch_bits(
  request: request.Request(BitArray),
) -> Effect(
  Result(response.Response(BitArray), xrpc.TransportError),
)

A binary HTTP request (the resource path, for blobs), yielding the response.

fetch_error_to_string

pub fn fetch_error_to_string(error: FetchError) -> String

get_checked

pub fn get_checked(
  url: String,
) -> Effect(Result(response.Response(String), xrpc.XrpcError))

GET url and status-check the response: the shared shape of the metadata and resolver lookups.

get_json

pub fn get_json(
  url: remote.Url,
  decoder: decode.Decoder(a),
) -> Effect(Result(a, FetchError))

GET a parsed remote url, require a 2xx, and decode the JSON body.

json_error

pub fn json_error(error: json.DecodeError) -> String

A JSON decode failure described without quoting the input, so a hostile body cannot smuggle its content into an error message.

map

pub fn map(effect: Effect(a), f: fn(a) -> b) -> Effect(b)

map_error

pub fn map_error(
  effect: Effect(Result(a, e1)),
  f: fn(e1) -> e2,
) -> Effect(Result(a, e2))

proof

pub fn proof(
  method method: String,
  url url: String,
  nonce nonce: option.Option(String),
  ath ath: option.Option(String),
) -> Effect(Result(String, String))

Ask the runner for a DPoP proof bound to this method+URL (and optional nonce and access-token hash). The runner signs it with its platform key.

then

pub fn then(
  effect: Effect(a),
  f: fn(a) -> Effect(b),
) -> Effect(b)

Monadic bind, use-syntax friendly: use x <- effect.then(some_effect).

try

pub fn try(
  effect: Effect(Result(a, e)),
  f: fn(a) -> Effect(Result(b, e)),
) -> Effect(Result(b, e))

Short-circuiting bind over Effect(Result(_, e)): use ok <- effect.try(eff) stops at the first Error.