jacquard_common/
xrpc.rs

1//! # Stateless XRPC utilities and request/response mapping
2//!
3//! Mapping overview:
4//! - Success (2xx): parse body into the endpoint's typed output.
5//! - 400: try typed error; on failure, fall back to a generic XRPC error (with
6//!   `nsid`, `method`, and `http_status`) and map common auth errors.
7//! - 401: if `WWW-Authenticate` is present, return
8//!   `ClientError::Auth(AuthError::Other(header))` so higher layers (OAuth/DPoP)
9//!   can inspect `error="invalid_token"` or `error="use_dpop_nonce"` and refresh/retry.
10//!   If the header is absent, parse the body and map auth errors to
11//!   `AuthError::TokenExpired`/`InvalidToken`.
12use bytes::Bytes;
13use http::{
14    HeaderName, HeaderValue, Request, StatusCode,
15    header::{AUTHORIZATION, CONTENT_TYPE},
16};
17use serde::{Deserialize, Serialize};
18use smol_str::SmolStr;
19use std::fmt::{self, Debug};
20use std::{error::Error, marker::PhantomData};
21use url::Url;
22
23use crate::http_client::HttpClient;
24use crate::types::value::Data;
25use crate::{AuthorizationToken, error::AuthError};
26use crate::{CowStr, error::XrpcResult};
27use crate::{IntoStatic, error::DecodeError};
28use crate::{error::TransportError, types::value::RawData};
29
30/// Error type for encoding XRPC requests
31#[derive(Debug, thiserror::Error, miette::Diagnostic)]
32pub enum EncodeError {
33    /// Failed to serialize query parameters
34    #[error("Failed to serialize query: {0}")]
35    Query(
36        #[from]
37        #[source]
38        serde_html_form::ser::Error,
39    ),
40    /// Failed to serialize JSON body
41    #[error("Failed to serialize JSON: {0}")]
42    Json(
43        #[from]
44        #[source]
45        serde_json::Error,
46    ),
47    /// Other encoding error
48    #[error("Encoding error: {0}")]
49    Other(String),
50}
51
52/// XRPC method type
53#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
54pub enum XrpcMethod {
55    /// Query (HTTP GET)
56    Query,
57    /// Procedure (HTTP POST)
58    Procedure(&'static str),
59}
60
61impl XrpcMethod {
62    /// Get the HTTP method string
63    pub const fn as_str(&self) -> &'static str {
64        match self {
65            Self::Query => "GET",
66            Self::Procedure(_) => "POST",
67        }
68    }
69
70    /// Get the body encoding type for this method (procedures only)
71    pub const fn body_encoding(&self) -> Option<&'static str> {
72        match self {
73            Self::Query => None,
74            Self::Procedure(enc) => Some(enc),
75        }
76    }
77}
78
79/// Trait for XRPC request types (queries and procedures)
80///
81/// This trait provides metadata about XRPC endpoints including the NSID,
82/// HTTP method, encoding, and associated output type.
83///
84/// The trait is implemented on the request parameters/input type itself.
85pub trait XrpcRequest: Serialize {
86    /// The NSID for this XRPC method
87    const NSID: &'static str;
88
89    /// XRPC method (query/GET or procedure/POST)
90    const METHOD: XrpcMethod;
91
92    /// Response type returned from the XRPC call (marker struct)
93    type Response: XrpcResp;
94
95    /// Encode the request body for procedures.
96    ///
97    /// Default implementation serializes to JSON. Override for non-JSON encodings.
98    fn encode_body(&self) -> Result<Vec<u8>, EncodeError> {
99        Ok(serde_json::to_vec(self)?)
100    }
101
102    /// Decode the request body for procedures.
103    ///
104    /// Default implementation deserializes from JSON. Override for non-JSON encodings.
105    fn decode_body<'de>(body: &'de [u8]) -> Result<Box<Self>, DecodeError>
106    where
107        Self: Deserialize<'de>,
108    {
109        let body: Self = serde_json::from_slice(body).map_err(|e| DecodeError::Json(e))?;
110
111        Ok(Box::new(body))
112    }
113}
114
115/// Trait for XRPC Response types
116///
117/// It mirrors the NSID and carries the encoding types as well as Output (success) and Err types
118pub trait XrpcResp {
119    /// The NSID for this XRPC method
120    const NSID: &'static str;
121
122    /// Output encoding (MIME type)
123    const ENCODING: &'static str;
124
125    /// Response output type
126    type Output<'de>: Deserialize<'de> + IntoStatic;
127
128    /// Error type for this request
129    type Err<'de>: Error + Deserialize<'de> + IntoStatic;
130}
131
132/// XRPC server endpoint trait
133///
134/// Defines the fully-qualified path and method, as well as request and response types
135/// This exists primarily to work around lifetime issues for crates like Axum
136/// by moving the lifetime from the trait itself into an associated type.
137///
138/// It is implemented by the code generation on a marker struct, like the client-side [XrpcResp] trait.
139pub trait XrpcEndpoint {
140    /// Fully-qualified path ('/xrpc/\[nsid\]') where this endpoint should live on the server
141    const PATH: &'static str;
142    /// XRPC method (query/GET or procedure/POST)
143    const METHOD: XrpcMethod;
144    /// XRPC Request data type
145    type Request<'de>: XrpcRequest + Deserialize<'de> + IntoStatic;
146    /// XRPC Response data type
147    type Response: XrpcResp;
148}
149
150/// Error type for XRPC endpoints that don't define any errors
151#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
152pub struct GenericError<'a>(#[serde(borrow)] Data<'a>);
153
154impl<'de> fmt::Display for GenericError<'de> {
155    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
156        self.0.fmt(f)
157    }
158}
159
160impl Error for GenericError<'_> {}
161
162impl IntoStatic for GenericError<'_> {
163    type Output = GenericError<'static>;
164    fn into_static(self) -> Self::Output {
165        GenericError(self.0.into_static())
166    }
167}
168
169/// Per-request options for XRPC calls.
170#[derive(Debug, Default, Clone)]
171pub struct CallOptions<'a> {
172    /// Optional Authorization to apply (`Bearer` or `DPoP`).
173    pub auth: Option<AuthorizationToken<'a>>,
174    /// `atproto-proxy` header value.
175    pub atproto_proxy: Option<CowStr<'a>>,
176    /// `atproto-accept-labelers` header values.
177    pub atproto_accept_labelers: Option<Vec<CowStr<'a>>>,
178    /// Extra headers to attach to this request.
179    pub extra_headers: Vec<(HeaderName, HeaderValue)>,
180}
181
182impl IntoStatic for CallOptions<'_> {
183    type Output = CallOptions<'static>;
184
185    fn into_static(self) -> Self::Output {
186        CallOptions {
187            auth: self.auth.map(|auth| auth.into_static()),
188            atproto_proxy: self.atproto_proxy.map(|proxy| proxy.into_static()),
189            atproto_accept_labelers: self
190                .atproto_accept_labelers
191                .map(|labelers| labelers.into_static()),
192            extra_headers: self.extra_headers,
193        }
194    }
195}
196
197/// Extension for stateless XRPC calls on any `HttpClient`.
198///
199/// Example
200/// ```no_run
201/// # #[tokio::main]
202/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
203/// use jacquard_common::xrpc::XrpcExt;
204/// use jacquard_common::http_client::HttpClient;
205///
206/// let http = reqwest::Client::new();
207/// let base = url::Url::parse("https://public.api.bsky.app")?;
208/// // let resp = http.xrpc(base).send(&request).await?;
209/// # Ok(())
210/// # }
211/// ```
212pub trait XrpcExt: HttpClient {
213    /// Start building an XRPC call for the given base URL.
214    fn xrpc<'a>(&'a self, base: Url) -> XrpcCall<'a, Self>
215    where
216        Self: Sized,
217    {
218        XrpcCall {
219            client: self,
220            base,
221            opts: CallOptions::default(),
222        }
223    }
224}
225
226impl<T: HttpClient> XrpcExt for T {}
227
228/// Stateful XRPC call trait
229pub trait XrpcClient: HttpClient {
230    /// Get the base URI for the client.
231    fn base_uri(&self) -> Url;
232
233    /// Get the call options for the client.
234    fn opts(&self) -> impl Future<Output = CallOptions<'_>> {
235        async { CallOptions::default() }
236    }
237    /// Send an XRPC request and parse the response
238    fn send<R>(
239        &self,
240        request: R,
241    ) -> impl Future<Output = XrpcResult<Response<<R as XrpcRequest>::Response>>>
242    where
243        R: XrpcRequest + Send + Sync,
244        <R as XrpcRequest>::Response: Send + Sync;
245}
246
247/// Stateless XRPC call builder.
248///
249/// Example (per-request overrides)
250/// ```no_run
251/// # #[tokio::main]
252/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
253/// use jacquard_common::xrpc::XrpcExt;
254/// use jacquard_common::{AuthorizationToken, CowStr};
255///
256/// let http = reqwest::Client::new();
257/// let base = url::Url::parse("https://public.api.bsky.app")?;
258/// let call = http
259///     .xrpc(base)
260///     .auth(AuthorizationToken::Bearer(CowStr::from("ACCESS_JWT")))
261///     .accept_labelers(vec![CowStr::from("did:plc:labelerid")])
262///     .header(http::header::USER_AGENT, http::HeaderValue::from_static("jacquard-example"));
263/// // let resp = call.send(&request).await?;
264/// # Ok(())
265/// # }
266/// ```
267pub struct XrpcCall<'a, C: HttpClient> {
268    pub(crate) client: &'a C,
269    pub(crate) base: Url,
270    pub(crate) opts: CallOptions<'a>,
271}
272
273impl<'a, C: HttpClient> XrpcCall<'a, C> {
274    /// Apply Authorization to this call.
275    pub fn auth(mut self, token: AuthorizationToken<'a>) -> Self {
276        self.opts.auth = Some(token);
277        self
278    }
279    /// Set `atproto-proxy` header for this call.
280    pub fn proxy(mut self, proxy: CowStr<'a>) -> Self {
281        self.opts.atproto_proxy = Some(proxy);
282        self
283    }
284    /// Set `atproto-accept-labelers` header(s) for this call.
285    pub fn accept_labelers(mut self, labelers: Vec<CowStr<'a>>) -> Self {
286        self.opts.atproto_accept_labelers = Some(labelers);
287        self
288    }
289    /// Add an extra header.
290    pub fn header(mut self, name: HeaderName, value: HeaderValue) -> Self {
291        self.opts.extra_headers.push((name, value));
292        self
293    }
294    /// Replace the builder's options entirely.
295    pub fn with_options(mut self, opts: CallOptions<'a>) -> Self {
296        self.opts = opts;
297        self
298    }
299
300    /// Send the given typed XRPC request and return a response wrapper.
301    ///
302    /// Note on 401 handling:
303    /// - When the server returns 401 with a `WWW-Authenticate` header, this surfaces as
304    ///   `ClientError::Auth(AuthError::Other(header))` so higher layers (e.g., OAuth/DPoP) can
305    ///   inspect the header for `error="invalid_token"` or `error="use_dpop_nonce"` and react
306    ///   (refresh/retry). If the header is absent, the 401 body flows through to `Response` and
307    ///   can be parsed/mapped to `AuthError` as appropriate.
308    pub async fn send<R>(self, request: &R) -> XrpcResult<Response<<R as XrpcRequest>::Response>>
309    where
310        R: XrpcRequest + Send + Sync,
311        <R as XrpcRequest>::Response: Send + Sync,
312    {
313        let http_request = build_http_request(&self.base, request, &self.opts)
314            .map_err(crate::error::TransportError::from)?;
315
316        let http_response = self
317            .client
318            .send_http(http_request)
319            .await
320            .map_err(|e| crate::error::TransportError::Other(Box::new(e)))?;
321
322        process_response(http_response)
323    }
324}
325
326/// Process the HTTP response from the server into a proper xrpc response statelessly.
327///
328/// Exposed to make things more easily pluggable
329#[inline]
330pub fn process_response<Resp>(http_response: http::Response<Vec<u8>>) -> XrpcResult<Response<Resp>>
331where
332    Resp: XrpcResp,
333{
334    let status = http_response.status();
335    // If the server returned 401 with a WWW-Authenticate header, expose it so higher layers
336    // (e.g., DPoP handling) can detect `error="invalid_token"` and trigger refresh.
337    if status.as_u16() == 401 {
338        if let Some(hv) = http_response.headers().get(http::header::WWW_AUTHENTICATE) {
339            return Err(crate::error::ClientError::Auth(
340                crate::error::AuthError::Other(hv.clone()),
341            ));
342        }
343    }
344    let buffer = Bytes::from(http_response.into_body());
345
346    if !status.is_success() && !matches!(status.as_u16(), 400 | 401) {
347        return Err(crate::error::HttpError {
348            status,
349            body: Some(buffer),
350        }
351        .into());
352    }
353
354    Ok(Response::new(buffer, status))
355}
356
357/// HTTP headers commonly used in XRPC requests
358pub enum Header {
359    /// Content-Type header
360    ContentType,
361    /// Authorization header
362    Authorization,
363    /// `atproto-proxy` header - specifies which service (app server or other atproto service) the user's PDS should forward requests to as appropriate.
364    ///
365    /// See: <https://atproto.com/specs/xrpc#service-proxying>
366    AtprotoProxy,
367    /// `atproto-accept-labelers` header used by clients to request labels from specific labelers to be included and applied in the response. See [label](https://atproto.com/specs/label) specification for details.
368    AtprotoAcceptLabelers,
369}
370
371impl From<Header> for HeaderName {
372    fn from(value: Header) -> Self {
373        match value {
374            Header::ContentType => CONTENT_TYPE,
375            Header::Authorization => AUTHORIZATION,
376            Header::AtprotoProxy => HeaderName::from_static("atproto-proxy"),
377            Header::AtprotoAcceptLabelers => HeaderName::from_static("atproto-accept-labelers"),
378        }
379    }
380}
381
382/// Build an HTTP request for an XRPC call given base URL and options
383pub fn build_http_request<'s, R>(
384    base: &Url,
385    req: &R,
386    opts: &CallOptions<'_>,
387) -> core::result::Result<Request<Vec<u8>>, crate::error::TransportError>
388where
389    R: XrpcRequest,
390{
391    let mut url = base.clone();
392    let mut path = url.path().trim_end_matches('/').to_owned();
393    path.push_str("/xrpc/");
394    path.push_str(<R as XrpcRequest>::NSID);
395    url.set_path(&path);
396
397    if let XrpcMethod::Query = <R as XrpcRequest>::METHOD {
398        let qs = serde_html_form::to_string(&req)
399            .map_err(|e| crate::error::TransportError::InvalidRequest(e.to_string()))?;
400        if !qs.is_empty() {
401            url.set_query(Some(&qs));
402        } else {
403            url.set_query(None);
404        }
405    }
406
407    let method = match <R as XrpcRequest>::METHOD {
408        XrpcMethod::Query => http::Method::GET,
409        XrpcMethod::Procedure(_) => http::Method::POST,
410    };
411
412    let mut builder = Request::builder().method(method).uri(url.as_str());
413
414    if let XrpcMethod::Procedure(encoding) = <R as XrpcRequest>::METHOD {
415        builder = builder.header(Header::ContentType, encoding);
416    }
417    let output_encoding = <R::Response as XrpcResp>::ENCODING;
418    builder = builder.header(http::header::ACCEPT, output_encoding);
419
420    if let Some(token) = &opts.auth {
421        let hv = match token {
422            AuthorizationToken::Bearer(t) => {
423                HeaderValue::from_str(&format!("Bearer {}", t.as_ref()))
424            }
425            AuthorizationToken::Dpop(t) => HeaderValue::from_str(&format!("DPoP {}", t.as_ref())),
426        }
427        .map_err(|e| {
428            TransportError::InvalidRequest(format!("Invalid authorization token: {}", e))
429        })?;
430        builder = builder.header(Header::Authorization, hv);
431    }
432
433    if let Some(proxy) = &opts.atproto_proxy {
434        builder = builder.header(Header::AtprotoProxy, proxy.as_ref());
435    }
436    if let Some(labelers) = &opts.atproto_accept_labelers {
437        if !labelers.is_empty() {
438            let joined = labelers
439                .iter()
440                .map(|s| s.as_ref())
441                .collect::<Vec<_>>()
442                .join(", ");
443            builder = builder.header(Header::AtprotoAcceptLabelers, joined);
444        }
445    }
446    for (name, value) in &opts.extra_headers {
447        builder = builder.header(name, value);
448    }
449
450    let body = if let XrpcMethod::Procedure(_) = R::METHOD {
451        req.encode_body()
452            .map_err(|e| TransportError::InvalidRequest(e.to_string()))?
453    } else {
454        vec![]
455    };
456
457    builder
458        .body(body)
459        .map_err(|e| TransportError::InvalidRequest(e.to_string()))
460}
461
462/// XRPC response wrapper that owns the response buffer
463///
464/// Allows borrowing from the buffer when parsing to avoid unnecessary allocations.
465/// Generic over the response marker type (e.g., `GetAuthorFeedResponse`), not the request.
466pub struct Response<Resp>
467where
468    Resp: XrpcResp, // HRTB: Resp works with any lifetime
469{
470    _marker: PhantomData<fn() -> Resp>,
471    buffer: Bytes,
472    status: StatusCode,
473}
474
475impl<Resp> Response<Resp>
476where
477    Resp: XrpcResp,
478{
479    /// Create a new response from a buffer and status code
480    pub fn new(buffer: Bytes, status: StatusCode) -> Self {
481        Self {
482            buffer,
483            status,
484            _marker: PhantomData,
485        }
486    }
487
488    /// Get the HTTP status code
489    pub fn status(&self) -> StatusCode {
490        self.status
491    }
492
493    /// Get the raw buffer
494    pub fn buffer(&self) -> &Bytes {
495        &self.buffer
496    }
497
498    /// Parse the response, borrowing from the internal buffer
499    pub fn parse<'s>(
500        &'s self,
501    ) -> Result<<Resp as XrpcResp>::Output<'s>, XrpcError<<Resp as XrpcResp>::Err<'s>>> {
502        // 200: parse as output
503        if self.status.is_success() {
504            match serde_json::from_slice::<_>(&self.buffer) {
505                Ok(output) => Ok(output),
506                Err(e) => Err(XrpcError::Decode(e)),
507            }
508        // 400: try typed XRPC error, fallback to generic error
509        } else if self.status.as_u16() == 400 {
510            match serde_json::from_slice::<_>(&self.buffer) {
511                Ok(error) => Err(XrpcError::Xrpc(error)),
512                Err(_) => {
513                    // Fallback to generic error (InvalidRequest, ExpiredToken, etc.)
514                    match serde_json::from_slice::<GenericXrpcError>(&self.buffer) {
515                        Ok(mut generic) => {
516                            generic.nsid = Resp::NSID;
517                            generic.method = ""; // method info only available on request
518                            generic.http_status = self.status;
519                            // Map auth-related errors to AuthError
520                            match generic.error.as_str() {
521                                "ExpiredToken" => Err(XrpcError::Auth(AuthError::TokenExpired)),
522                                "InvalidToken" => Err(XrpcError::Auth(AuthError::InvalidToken)),
523                                _ => Err(XrpcError::Generic(generic)),
524                            }
525                        }
526                        Err(e) => Err(XrpcError::Decode(e)),
527                    }
528                }
529            }
530        // 401: always auth error
531        } else {
532            match serde_json::from_slice::<GenericXrpcError>(&self.buffer) {
533                Ok(mut generic) => {
534                    generic.nsid = Resp::NSID;
535                    generic.method = ""; // method info only available on request
536                    generic.http_status = self.status;
537                    match generic.error.as_str() {
538                        "ExpiredToken" => Err(XrpcError::Auth(AuthError::TokenExpired)),
539                        "InvalidToken" => Err(XrpcError::Auth(AuthError::InvalidToken)),
540                        _ => Err(XrpcError::Auth(AuthError::NotAuthenticated)),
541                    }
542                }
543                Err(e) => Err(XrpcError::Decode(e)),
544            }
545        }
546    }
547
548    /// Parse this as validated, loosely typed atproto data.
549    ///
550    /// NOTE: If the response is an error, it will still parse as the matching error type for the request.
551    pub fn parse_data<'s>(&'s self) -> Result<Data<'s>, XrpcError<<Resp as XrpcResp>::Err<'s>>> {
552        // 200: parse as output
553        if self.status.is_success() {
554            match serde_json::from_slice::<_>(&self.buffer) {
555                Ok(output) => Ok(output),
556                Err(e) => Err(XrpcError::Decode(e)),
557            }
558        // 400: try typed XRPC error, fallback to generic error
559        } else if self.status.as_u16() == 400 {
560            match serde_json::from_slice::<_>(&self.buffer) {
561                Ok(error) => Err(XrpcError::Xrpc(error)),
562                Err(_) => {
563                    // Fallback to generic error (InvalidRequest, ExpiredToken, etc.)
564                    match serde_json::from_slice::<GenericXrpcError>(&self.buffer) {
565                        Ok(mut generic) => {
566                            generic.nsid = Resp::NSID;
567                            generic.method = ""; // method info only available on request
568                            generic.http_status = self.status;
569                            // Map auth-related errors to AuthError
570                            match generic.error.as_str() {
571                                "ExpiredToken" => Err(XrpcError::Auth(AuthError::TokenExpired)),
572                                "InvalidToken" => Err(XrpcError::Auth(AuthError::InvalidToken)),
573                                _ => Err(XrpcError::Generic(generic)),
574                            }
575                        }
576                        Err(e) => Err(XrpcError::Decode(e)),
577                    }
578                }
579            }
580        // 401: always auth error
581        } else {
582            match serde_json::from_slice::<GenericXrpcError>(&self.buffer) {
583                Ok(mut generic) => {
584                    generic.nsid = Resp::NSID;
585                    generic.method = ""; // method info only available on request
586                    generic.http_status = self.status;
587                    match generic.error.as_str() {
588                        "ExpiredToken" => Err(XrpcError::Auth(AuthError::TokenExpired)),
589                        "InvalidToken" => Err(XrpcError::Auth(AuthError::InvalidToken)),
590                        _ => Err(XrpcError::Auth(AuthError::NotAuthenticated)),
591                    }
592                }
593                Err(e) => Err(XrpcError::Decode(e)),
594            }
595        }
596    }
597
598    /// Parse this as raw atproto data with minimal validation.
599    ///
600    /// NOTE: If the response is an error, it will still parse as the matching error type for the request.
601    pub fn parse_raw<'s>(&'s self) -> Result<RawData<'s>, XrpcError<<Resp as XrpcResp>::Err<'s>>> {
602        // 200: parse as output
603        if self.status.is_success() {
604            match serde_json::from_slice::<_>(&self.buffer) {
605                Ok(output) => Ok(output),
606                Err(e) => Err(XrpcError::Decode(e)),
607            }
608        // 400: try typed XRPC error, fallback to generic error
609        } else if self.status.as_u16() == 400 {
610            match serde_json::from_slice::<_>(&self.buffer) {
611                Ok(error) => Err(XrpcError::Xrpc(error)),
612                Err(_) => {
613                    // Fallback to generic error (InvalidRequest, ExpiredToken, etc.)
614                    match serde_json::from_slice::<GenericXrpcError>(&self.buffer) {
615                        Ok(mut generic) => {
616                            generic.nsid = Resp::NSID;
617                            generic.method = ""; // method info only available on request
618                            generic.http_status = self.status;
619                            // Map auth-related errors to AuthError
620                            match generic.error.as_str() {
621                                "ExpiredToken" => Err(XrpcError::Auth(AuthError::TokenExpired)),
622                                "InvalidToken" => Err(XrpcError::Auth(AuthError::InvalidToken)),
623                                _ => Err(XrpcError::Generic(generic)),
624                            }
625                        }
626                        Err(e) => Err(XrpcError::Decode(e)),
627                    }
628                }
629            }
630        // 401: always auth error
631        } else {
632            match serde_json::from_slice::<GenericXrpcError>(&self.buffer) {
633                Ok(mut generic) => {
634                    generic.nsid = Resp::NSID;
635                    generic.method = ""; // method info only available on request
636                    generic.http_status = self.status;
637                    match generic.error.as_str() {
638                        "ExpiredToken" => Err(XrpcError::Auth(AuthError::TokenExpired)),
639                        "InvalidToken" => Err(XrpcError::Auth(AuthError::InvalidToken)),
640                        _ => Err(XrpcError::Auth(AuthError::NotAuthenticated)),
641                    }
642                }
643                Err(e) => Err(XrpcError::Decode(e)),
644            }
645        }
646    }
647
648    /// Reinterpret this response as a different response type.
649    ///
650    /// This transmutes the response by keeping the same buffer and status code,
651    /// but changing the type-level marker. Useful for converting generic XRPC responses
652    /// into collection-specific typed responses.
653    ///
654    /// # Safety
655    ///
656    /// This is safe in the sense that no memory unsafety occurs, but logical correctness
657    /// depends on ensuring the buffer actually contains data that can deserialize to `NEW`.
658    /// Incorrect conversion will cause deserialization errors at runtime.
659    pub fn transmute<NEW: XrpcResp>(self) -> Response<NEW> {
660        Response {
661            buffer: self.buffer,
662            status: self.status,
663            _marker: PhantomData,
664        }
665    }
666}
667
668impl<Resp> Response<Resp>
669where
670    Resp: XrpcResp,
671{
672    /// Parse the response into an owned output
673    pub fn into_output(
674        self,
675    ) -> Result<<Resp as XrpcResp>::Output<'static>, XrpcError<<Resp as XrpcResp>::Err<'static>>>
676    where
677        for<'a> <Resp as XrpcResp>::Output<'a>:
678            IntoStatic<Output = <Resp as XrpcResp>::Output<'static>>,
679        for<'a> <Resp as XrpcResp>::Err<'a>: IntoStatic<Output = <Resp as XrpcResp>::Err<'static>>,
680    {
681        // Use a helper to make lifetime inference work
682        fn parse_output<'b, R: XrpcResp>(
683            buffer: &'b [u8],
684        ) -> Result<R::Output<'b>, serde_json::Error> {
685            serde_json::from_slice(buffer)
686        }
687
688        fn parse_error<'b, R: XrpcResp>(buffer: &'b [u8]) -> Result<R::Err<'b>, serde_json::Error> {
689            serde_json::from_slice(buffer)
690        }
691
692        // 200: parse as output
693        if self.status.is_success() {
694            match parse_output::<Resp>(&self.buffer) {
695                Ok(output) => {
696                    return Ok(output.into_static());
697                }
698                Err(e) => Err(XrpcError::Decode(e)),
699            }
700        // 400: try typed XRPC error, fallback to generic error
701        } else if self.status.as_u16() == 400 {
702            let error = match parse_error::<Resp>(&self.buffer) {
703                Ok(error) => XrpcError::Xrpc(error),
704                Err(_) => {
705                    // Fallback to generic error (InvalidRequest, ExpiredToken, etc.)
706                    match serde_json::from_slice::<GenericXrpcError>(&self.buffer) {
707                        Ok(mut generic) => {
708                            generic.nsid = Resp::NSID;
709                            generic.method = ""; // method info only available on request
710                            generic.http_status = self.status;
711                            // Map auth-related errors to AuthError
712                            match generic.error.as_ref() {
713                                "ExpiredToken" => XrpcError::Auth(AuthError::TokenExpired),
714                                "InvalidToken" => XrpcError::Auth(AuthError::InvalidToken),
715                                _ => XrpcError::Generic(generic),
716                            }
717                        }
718                        Err(e) => XrpcError::Decode(e),
719                    }
720                }
721            };
722            Err(error.into_static())
723        // 401: always auth error
724        } else {
725            let error: XrpcError<<Resp as XrpcResp>::Err<'_>> =
726                match serde_json::from_slice::<GenericXrpcError>(&self.buffer) {
727                    Ok(mut generic) => {
728                        let status = self.status;
729                        generic.nsid = Resp::NSID;
730                        generic.method = ""; // method info only available on request
731                        generic.http_status = status;
732                        match generic.error.as_ref() {
733                            "ExpiredToken" => XrpcError::Auth(AuthError::TokenExpired),
734                            "InvalidToken" => XrpcError::Auth(AuthError::InvalidToken),
735                            _ => XrpcError::Auth(AuthError::NotAuthenticated),
736                        }
737                    }
738                    Err(e) => XrpcError::Decode(e),
739                };
740
741            Err(error.into_static())
742        }
743    }
744}
745
746/// Generic XRPC error format for untyped errors like InvalidRequest
747///
748/// Used when the error doesn't match the endpoint's specific error enum
749#[derive(Debug, Clone, Deserialize, Serialize)]
750pub struct GenericXrpcError {
751    /// Error code (e.g., "InvalidRequest")
752    pub error: SmolStr,
753    /// Optional error message with details
754    pub message: Option<SmolStr>,
755    /// XRPC method NSID that produced this error (context only; not serialized)
756    #[serde(skip)]
757    pub nsid: &'static str,
758    /// HTTP method used (GET/POST) (context only; not serialized)
759    #[serde(skip)]
760    pub method: &'static str,
761    /// HTTP status code (context only; not serialized)
762    #[serde(skip)]
763    pub http_status: StatusCode,
764}
765
766impl std::fmt::Display for GenericXrpcError {
767    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
768        if let Some(msg) = &self.message {
769            write!(
770                f,
771                "{}: {} (nsid={}, method={}, status={})",
772                self.error, msg, self.nsid, self.method, self.http_status
773            )
774        } else {
775            write!(
776                f,
777                "{} (nsid={}, method={}, status={})",
778                self.error, self.nsid, self.method, self.http_status
779            )
780        }
781    }
782}
783
784impl IntoStatic for GenericXrpcError {
785    type Output = Self;
786
787    fn into_static(self) -> Self::Output {
788        self
789    }
790}
791
792impl std::error::Error for GenericXrpcError {}
793
794/// XRPC-specific errors returned from endpoints
795///
796/// Represents errors returned in the response body
797/// Type parameter `E` is the endpoint's specific error enum type.
798#[derive(Debug, thiserror::Error, miette::Diagnostic)]
799pub enum XrpcError<E: std::error::Error + IntoStatic> {
800    /// Typed XRPC error from the endpoint's specific error enum
801    #[error("XRPC error: {0}")]
802    #[diagnostic(code(jacquard_common::xrpc::typed))]
803    Xrpc(E),
804
805    /// Authentication error (ExpiredToken, InvalidToken, etc.)
806    #[error("Authentication error: {0}")]
807    #[diagnostic(code(jacquard_common::xrpc::auth))]
808    Auth(#[from] AuthError),
809
810    /// Generic XRPC error not in the endpoint's error enum (e.g., InvalidRequest)
811    #[error("XRPC error: {0}")]
812    #[diagnostic(code(jacquard_common::xrpc::generic))]
813    Generic(GenericXrpcError),
814
815    /// Failed to decode the response body
816    #[error("Failed to decode response: {0}")]
817    #[diagnostic(code(jacquard_common::xrpc::decode))]
818    Decode(#[from] serde_json::Error),
819}
820
821impl<E> IntoStatic for XrpcError<E>
822where
823    E: std::error::Error + IntoStatic,
824    E::Output: std::error::Error + IntoStatic,
825    <E as IntoStatic>::Output: std::error::Error + IntoStatic,
826{
827    type Output = XrpcError<E::Output>;
828    fn into_static(self) -> Self::Output {
829        match self {
830            XrpcError::Xrpc(e) => XrpcError::Xrpc(e.into_static()),
831            XrpcError::Auth(e) => XrpcError::Auth(e.into_static()),
832            XrpcError::Generic(e) => XrpcError::Generic(e),
833            XrpcError::Decode(e) => XrpcError::Decode(e),
834        }
835    }
836}
837
838#[cfg(test)]
839mod tests {
840    use super::*;
841    use serde::{Deserialize, Serialize};
842
843    #[derive(Serialize, Deserialize)]
844    #[allow(dead_code)]
845    struct DummyReq;
846
847    #[derive(Deserialize, Debug, thiserror::Error)]
848    #[error("{0}")]
849    struct DummyErr<'a>(#[serde(borrow)] CowStr<'a>);
850
851    impl IntoStatic for DummyErr<'_> {
852        type Output = DummyErr<'static>;
853        fn into_static(self) -> Self::Output {
854            DummyErr(self.0.into_static())
855        }
856    }
857
858    struct DummyResp;
859
860    impl XrpcResp for DummyResp {
861        const NSID: &'static str = "test.dummy";
862        const ENCODING: &'static str = "application/json";
863        type Output<'de> = ();
864        type Err<'de> = DummyErr<'de>;
865    }
866
867    impl XrpcRequest for DummyReq {
868        const NSID: &'static str = "test.dummy";
869        const METHOD: XrpcMethod = XrpcMethod::Procedure("application/json");
870        type Response = DummyResp;
871    }
872
873    #[test]
874    fn generic_error_carries_context() {
875        let body = serde_json::json!({"error":"InvalidRequest","message":"missing"});
876        let buf = Bytes::from(serde_json::to_vec(&body).unwrap());
877        let resp: Response<DummyResp> = Response::new(buf, StatusCode::BAD_REQUEST);
878        match resp.parse().unwrap_err() {
879            XrpcError::Generic(g) => {
880                assert_eq!(g.error.as_str(), "InvalidRequest");
881                assert_eq!(g.message.as_deref(), Some("missing"));
882                assert_eq!(g.nsid, DummyResp::NSID);
883                assert_eq!(g.method, ""); // method info only on request
884                assert_eq!(g.http_status, StatusCode::BAD_REQUEST);
885            }
886            other => panic!("unexpected: {other:?}"),
887        }
888    }
889
890    #[test]
891    fn auth_error_mapping() {
892        for (code, expect) in [
893            ("ExpiredToken", AuthError::TokenExpired),
894            ("InvalidToken", AuthError::InvalidToken),
895        ] {
896            let body = serde_json::json!({"error": code});
897            let buf = Bytes::from(serde_json::to_vec(&body).unwrap());
898            let resp: Response<DummyResp> = Response::new(buf, StatusCode::UNAUTHORIZED);
899            match resp.parse().unwrap_err() {
900                XrpcError::Auth(e) => match (e, expect) {
901                    (AuthError::TokenExpired, AuthError::TokenExpired) => {}
902                    (AuthError::InvalidToken, AuthError::InvalidToken) => {}
903                    other => panic!("mismatch: {other:?}"),
904                },
905                other => panic!("unexpected: {other:?}"),
906            }
907        }
908    }
909
910    #[test]
911    fn no_double_slash_in_path() {
912        #[derive(Serialize, Deserialize)]
913        struct Req;
914        #[derive(Deserialize, Debug, thiserror::Error)]
915        #[error("{0}")]
916        struct Err<'a>(#[serde(borrow)] CowStr<'a>);
917        impl IntoStatic for Err<'_> {
918            type Output = Err<'static>;
919            fn into_static(self) -> Self::Output {
920                Err(self.0.into_static())
921            }
922        }
923        struct Resp;
924        impl XrpcResp for Resp {
925            const NSID: &'static str = "com.example.test";
926            const ENCODING: &'static str = "application/json";
927            type Output<'de> = ();
928            type Err<'de> = Err<'de>;
929        }
930        impl XrpcRequest for Req {
931            const NSID: &'static str = "com.example.test";
932            const METHOD: XrpcMethod = XrpcMethod::Query;
933            type Response = Resp;
934        }
935
936        let opts = CallOptions::default();
937        for base in [
938            Url::parse("https://pds").unwrap(),
939            Url::parse("https://pds/").unwrap(),
940            Url::parse("https://pds/base/").unwrap(),
941        ] {
942            let req = build_http_request(&base, &Req, &opts).unwrap();
943            let uri = req.uri().to_string();
944            assert!(uri.contains("/xrpc/com.example.test"));
945            assert!(!uri.contains("//xrpc"));
946        }
947    }
948}
jacquard_common/xrpc.rs

jacquard_common/
xrpc.rs
