···

       
4
       
 
       
//!

     

       
5
       
 
       
//! Jacquard has a couple of `.send()` methods. One is stateless. it's the output of a method that creates a request builder, implemented as an extension trait, `XrpcExt`, on any http client which implements a very simple HttpClient trait. You can use a bare `reqwest::Client` to make XRPC requests. You call `.xrpc(base_url)` and get an `XrpcCall` struct. `XrpcCall` is a builder, which allows you to pass authentication, atproto proxy settings, labeler headings, and set other options for the final request. There's also a similar trait `DpopExt` in the `jacquard-oauth` crate, which handles that form of authenticated request in a similar way. For basic stuff, this works great, and it's a useful building block for more complex logic, or when one size does **not** in fact fit all.

     

       
6
       
 
       
//!

     

       
7
       
-
       
//! ```rust

     

       
8
       
 
       
//! use jacquard_common::xrpc::XrpcExt;

     

       
9
       
 
       
//! use jacquard_common::http_client::HttpClient;

     

       
10
       
 
       
//! // ...

     
···

       
18
       
 
       
//!

     

       
19
       
 
       
//! Here is the entire text of `XrpcCall::send()`. [`build_http_request()`](https://tangled.org/@nonbinary.computer/jacquard/blob/main/crates/jacquard-common/src/xrpc.rs#L400) and [`process_response()`](https://tangled.org/@nonbinary.computer/jacquard/blob/main/crates/jacquard-common/src/xrpc.rs#L344) are public functions and can be used in other crates. The first does more or less what it says on the tin. The second does less than you might think. It mostly surfaces authentication errors at an earlier level so you don't have to fully parse the response to know if there was an error or not.

     

       
20
       
 
       
//!

     

       
21
       
-
       
//! ```rust

     

       
22
       
 
       
//! pub async fn send<'s, R>(

     

       
23
       
 
       
//!         self,

     

       
24
       
 
       
//!         request: &R,

     
···

       
44
       
 
       
//!

     

       
45
       
 
       
//! So how does this work? How does `send()` and its helper functions know what to do? The answer shouldn't be surprising to anyone familiar with Rust. It's traits! Specifically, the following traits, which have generated implementations for every lexicon type ingested by Jacquard's API code generation, but which honestly aren't hard to just implement yourself (more tedious than anything). XrpcResp is always implemented on a unit/marker struct with no fields. They provide all the request-specific instructions to the functions.

     

       
46
       
 
       
//!

     

       
47
       
-
       
//! ```rust

     

       
48
       
 
       
//! pub trait XrpcRequest<'de>: Serialize + Deserialize<'de> {

     

       
49
       
 
       
//!     const NSID: &'static str;

     

       
50
       
 
       
//!     /// XRPC method (query/GET or procedure/POST)

     
···

       
70
       
 
       
//! ```

     

       
71
       
 
       
//! Here are the implementations for [`GetTimeline`](https://tangled.org/@nonbinary.computer/jacquard/blob/main/crates/jacquard-api/src/app_bsky/feed/get_timeline.rs). You'll also note that `send()` doesn't return the fully decoded response on success. It returns a Response struct which has a generic parameter that must implement the XrpcResp trait above. Here's its definition. It's essentially just a cheaply cloneable byte buffer and a type marker.

     

       
72
       
 
       
//!

     

       
73
       
-
       
//! ```rust

     

       
74
       
 
       
//! pub struct Response<R: XrpcResp> {

     

       
75
       
 
       
//!     buffer: Bytes,

     

       
76
       
 
       
//!     status: StatusCode,

     

···

       
4
       
 
       
//!

     

       
5
       
 
       
//! Jacquard has a couple of `.send()` methods. One is stateless. it's the output of a method that creates a request builder, implemented as an extension trait, `XrpcExt`, on any http client which implements a very simple HttpClient trait. You can use a bare `reqwest::Client` to make XRPC requests. You call `.xrpc(base_url)` and get an `XrpcCall` struct. `XrpcCall` is a builder, which allows you to pass authentication, atproto proxy settings, labeler headings, and set other options for the final request. There's also a similar trait `DpopExt` in the `jacquard-oauth` crate, which handles that form of authenticated request in a similar way. For basic stuff, this works great, and it's a useful building block for more complex logic, or when one size does **not** in fact fit all.

     

       
6
       
 
       
//!

     

       
7
       
+
       
//! ```ignore

     

       
8
       
 
       
//! use jacquard_common::xrpc::XrpcExt;

     

       
9
       
 
       
//! use jacquard_common::http_client::HttpClient;

     

       
10
       
 
       
//! // ...

     
···

       
18
       
 
       
//!

     

       
19
       
 
       
//! Here is the entire text of `XrpcCall::send()`. [`build_http_request()`](https://tangled.org/@nonbinary.computer/jacquard/blob/main/crates/jacquard-common/src/xrpc.rs#L400) and [`process_response()`](https://tangled.org/@nonbinary.computer/jacquard/blob/main/crates/jacquard-common/src/xrpc.rs#L344) are public functions and can be used in other crates. The first does more or less what it says on the tin. The second does less than you might think. It mostly surfaces authentication errors at an earlier level so you don't have to fully parse the response to know if there was an error or not.

     

       
20
       
 
       
//!

     

       
21
       
+
       
//! ```ignore

     

       
22
       
 
       
//! pub async fn send<'s, R>(

     

       
23
       
 
       
//!         self,

     

       
24
       
 
       
//!         request: &R,

     
···

       
44
       
 
       
//!

     

       
45
       
 
       
//! So how does this work? How does `send()` and its helper functions know what to do? The answer shouldn't be surprising to anyone familiar with Rust. It's traits! Specifically, the following traits, which have generated implementations for every lexicon type ingested by Jacquard's API code generation, but which honestly aren't hard to just implement yourself (more tedious than anything). XrpcResp is always implemented on a unit/marker struct with no fields. They provide all the request-specific instructions to the functions.

     

       
46
       
 
       
//!

     

       
47
       
+
       
//! ```ignore

     

       
48
       
 
       
//! pub trait XrpcRequest<'de>: Serialize + Deserialize<'de> {

     

       
49
       
 
       
//!     const NSID: &'static str;

     

       
50
       
 
       
//!     /// XRPC method (query/GET or procedure/POST)

     
···

       
70
       
 
       
//! ```

     

       
71
       
 
       
//! Here are the implementations for [`GetTimeline`](https://tangled.org/@nonbinary.computer/jacquard/blob/main/crates/jacquard-api/src/app_bsky/feed/get_timeline.rs). You'll also note that `send()` doesn't return the fully decoded response on success. It returns a Response struct which has a generic parameter that must implement the XrpcResp trait above. Here's its definition. It's essentially just a cheaply cloneable byte buffer and a type marker.

     

       
72
       
 
       
//!

     

       
73
       
+
       
//! ```ignore

     

       
74
       
 
       
//! pub struct Response<R: XrpcResp> {

     

       
75
       
 
       
//!     buffer: Bytes,

     

       
76
       
 
       
//!     status: StatusCode,