mooncakes.io

README

marianoguerra/atproto/xrpc does not have a README file

#
Transport

pub(open) trait Transport {
  async fn send(Self, HttpRequest) -> HttpResponse
  fn describe(Self) -> String
}

A thing that can send an XRPC request and return what came back.

Deliberately dumb. An implementation has exactly three obligations, and all three are things a hand-written one gets wrong:

Lower-case the response header names.
Do not forward content-length; most HTTP clients compute their own, and sending both risks two conflicting headers on the wire.
Do not let the underlying client's errors escape. Translate them, or a caller's catch sees a type from a library it never imported.

#
XrpcError

source

pub(all) suberror XrpcError {
  RequestFailed(String)
  Status(status~ : Int, error~ : String, message~ : String?, headers~ : Map[String, String])
  RateLimited(retry_after_millis~ : Int64?, error~ : String, message~ : String?)
  Decode(@marianoguerra/atproto/data.DecodeError
DecodeError)
  Encode(String)
} derive(@moonbitlang/core/debug.Debug
Debug)

impl Show for XrpcError

#
XrpcError::describe_error

source

fn XrpcError::describe_error(self : XrpcError) -> String

#
XrpcError::error_name

source

fn XrpcError::error_name(self : XrpcError) -> String

The machine-readable name: the error field of the body, or a name derived from the status when the server did not send one.

#
XrpcError::is_expired_token

source

fn XrpcError::is_expired_token(self : XrpcError) -> Bool

The access token has expired and a refresh should be attempted.

The condition is upstream's and it is not just "401": a PDS may answer 400 with ExpiredToken, and a client that only checked the status would log the user out instead of refreshing.

#
XrpcError::message

source

fn XrpcError::message(self : XrpcError) -> String?

#
XrpcError::retry_after_millis

source

fn XrpcError::retry_after_millis(self : XrpcError) -> Int64?

How long to wait before retrying, if the server said.

None means it did not, and the caller should pick its own backoff -- the reference implementation uses min(30s, 500ms * 2^attempt).

#
XrpcError::should_retry

source

fn XrpcError::should_retry(self : XrpcError) -> Bool

Whether the same request is worth sending again.

The status set is the reference implementation's RETRYABLE_HTTP_STATUS_CODES. A transport failure is retryable because it may never have reached the server; a 4xx other than these is not, because sending it again produces the same answer.

#
XrpcError::status

source

fn XrpcError::status(self : XrpcError) -> Int?

#
Body

source

pub(all) enum Body {
  Empty
  Json(@marianoguerra/atproto/data.LexValue
LexValue)
  Blob(bytes~ : Bytes, mime_type~ : String)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

What goes in the request body.

#
Credential

source

pub(all) enum Credential {
  Anonymous
  Bearer(String)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

How the caller proves who it is.

#
HttpRequest

source

pub(all) struct HttpRequest {
  url : String
  http_method : String
  headers : Map[String, String]
  body : Bytes
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

One outbound call, already reduced to bytes.

#
HttpRequest::body_text

source

fn HttpRequest::body_text(self : HttpRequest) -> String

The body as text, for logging and tests. Lossy by design: a blob upload is not text and printing it should not fail.

#
HttpRequest::content_length

source

fn HttpRequest::content_length(self : HttpRequest) -> Int

The UTF-8 byte count, which is what Content-Length must be -- and is not the string length, because MoonBit strings are UTF-16.

#
HttpResponse

source

pub(all) struct HttpResponse {
  status : Int
  headers : Map[String, String]
  body : Bytes
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

#
HttpResponse::body_text

source

fn HttpResponse::body_text(self : HttpResponse) -> String

The body as text. Lossy, because a malformed body must still be reportable rather than turning into a second, less useful error.

#
HttpResponse::content_type

source

fn HttpResponse::content_type(self : HttpResponse) -> String?

The media type, without parameters -- application/json from application/json; charset=utf-8.

#
HttpResponse::header

source

fn HttpResponse::header(self : HttpResponse, name : String) -> String?

#
Method

source

pub(all) enum Method {
  Query
  Procedure
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A query reads and a procedure writes, and that is the only thing that decides the HTTP method.

#
Method::http_method

source

fn Method::http_method(self : Method) -> String

#
ParamValue

source

pub(all) enum ParamValue {
  Str(String)
  Int(Int64)
  Bool(Bool)
  Strs(Array[String])
  Ints(Array[Int64])
  Bools(Array[Bool])
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

#
Params

source

pub(all) struct Params {
  entries : Array[(String, ParamValue)]
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

An ordered list rather than a map, because two entries may share a key -- that is how arrays are spelled -- and because a stable order makes a request comparable in a test.

#
Params::encode

source

fn Params::encode(self : Params) -> String

The query string, without a leading ?, or "" when there is nothing to send. An empty array contributes nothing at all, which matches the reference implementation -- ?tags= would mean a tag that is the empty string.

#
Params::is_empty

source

fn Params::is_empty(self : Params) -> Bool

#
Params::length

source

fn Params::length(self : Params) -> Int

#
Params::new

source

fn Params::new() -> Params

#
Params::of

source

fn Params::of(entries : Array[(String, ParamValue)]) -> Params

#
Params::put

source

fn Params::put(self : Params, key : String, value : ParamValue) -> Unit

#
Params::put_bool

source

fn Params::put_bool(self : Params, key : String, value : Bool?) -> Unit

#
Params::put_int

source

fn Params::put_int(self : Params, key : String, value : Int64?) -> Unit

#
Params::put_opt

source

fn Params::put_opt(self : Params, key : String, value : ParamValue?) -> Unit

The whole reason this type exists rather than a Map: an absent optional argument must vanish, not become an empty string. Every generated call is a column of these.

#
Params::put_string

source

fn Params::put_string(self : Params, key : String, value : String?) -> Unit

#
Params::put_strings

source

fn Params::put_strings(self : Params, key : String, value : Array[String]?) -> Unit

#
USER_AGENT

source

let USER_AGENT : String

#
build_request

source

fn build_request(service : String, nsid : @marianoguerra/atproto/syntax.Nsid
Nsid, kind : Method, params? : Params, body? : Body, credential? : Credential, accept? : String, extra_headers? : Map[String, String]) -> HttpRequest

Assembles a request. Pure, and the reason almost all of this package can be tested without a transport.

service is the origin to send to -- https://bsky.social, or the PDS from the account's DID document. A trailing slash on it is tolerated, because callers paste these from configuration and one showing up should not produce //xrpc/....

#
interpret

source

fn interpret(response : HttpResponse) -> @marianoguerra/atproto/data.LexValue
LexValue raise XrpcError

Turns a response into the decoded body, or into the right error.

The order matters. A 429 is a rate limit whatever its body says; a non-2xx is an error even if the body happens to parse; and only then is a 2xx body worth decoding.

#
interpret_bytes

source

fn interpret_bytes(response : HttpResponse) -> Bytes raise XrpcError

A 2xx whose body is not JSON: getBlob, getRepo, the video endpoints. Returns the bytes and lets the caller decide what they are.

#
percent_encode

source

fn percent_encode(text : String) -> String

RFC 3986 percent-encoding of everything outside the unreserved set.

Encoding goes through the UTF-8 bytes, not the string's UTF-16 code units. Getting that wrong is invisible until someone searches for a word with an accent in it, and then the query silently matches nothing.

#
status_error_name

source

fn status_error_name(status : Int) -> String

The name to use when the server sent a status but no error field.

The table is the reference implementation's ResponseType. Anything unlisted collapses to InvalidRequest below 500 and InternalServerError at or above, which is what upstream's fallback does.

#
to_xrpc_error

source

fn to_xrpc_error(e : Error) -> XrpcError

Narrows a caught Error back to this taxonomy.

Needed because variant patterns are the only way to match an error value -- the suberror TYPE name is not a pattern -- and they are only in scope inside this package. Anything from elsewhere becomes a transport failure, which is the honest reading: it came from the code that does the sending.

Source Files

Site source Report issue Packages Build queue Skills Statistics

#Transport

#XrpcError

#XrpcError::describe_error

#XrpcError::error_name

#XrpcError::is_expired_token

#XrpcError::message

#XrpcError::retry_after_millis

#XrpcError::should_retry

#XrpcError::status

#Body

#Credential

#HttpRequest

#HttpRequest::body_text

#HttpRequest::content_length

#HttpResponse

#HttpResponse::body_text

#HttpResponse::content_type

#HttpResponse::header

#Method

#Method::http_method

#ParamValue

#Params

#Params::encode

#Params::is_empty

#Params::length

#Params::new

#Params::of

#Params::put

#Params::put_bool

#Params::put_int

#Params::put_opt

#Params::put_string

#Params::put_strings

#USER_AGENT

#build_request

#interpret

#interpret_bytes

#percent_encode

#status_error_name

#to_xrpc_error

Source Files

#
Transport

#
XrpcError

#
XrpcError::describe_error

#
XrpcError::error_name

#
XrpcError::is_expired_token

#
XrpcError::message

#
XrpcError::retry_after_millis

#
XrpcError::should_retry

#
XrpcError::status

#
Body

#
Credential

#
HttpRequest

#
HttpRequest::body_text

#
HttpRequest::content_length

#
HttpResponse

#
HttpResponse::body_text

#
HttpResponse::content_type

#
HttpResponse::header

#
Method

#
Method::http_method

#
ParamValue

#
Params

#
Params::encode

#
Params::is_empty

#
Params::length

#
Params::new

#
Params::of

#
Params::put

#
Params::put_bool

#
Params::put_int

#
Params::put_opt

#
Params::put_string

#
Params::put_strings

#
USER_AGENT

#
build_request

#
interpret

#
interpret_bytes

#
percent_encode

#
status_error_name

#
to_xrpc_error