+1 -1

crates/jacquard-axum/src/service_auth.rs

reviewed

··· 249 249 #[error("missing Authorization header")] 250 250 MissingAuthHeader, 251 251 252 252 - /// Authorization header is malformed (not "Bearer <token>") 252 252 + /// Authorization header is malformed (not "Bearer `token`") 253 253 #[error("invalid Authorization header format")] 254 254 InvalidAuthHeader, 255 255

+3 -12

crates/jacquard-common/src/cowstr.rs

reviewed

··· 1 1 - use serde::{Deserialize, Deserializer, Serialize}; 1 1 + use serde::{Deserialize, Serialize}; 2 2 use smol_str::SmolStr; 3 3 use std::{ 4 4 borrow::Cow, ··· 9 9 10 10 use crate::IntoStatic; 11 11 12 12 - /// Shamelessly copied from [](https://github.com/bearcove/merde) 13 12 /// A copy-on-write immutable string type that uses [`SmolStr`] for 14 13 /// the "owned" variant. 15 14 /// 16 15 /// The standard [`Cow`] type cannot be used, since 17 16 /// `<str as ToOwned>::Owned` is `String`, and not `SmolStr`. 17 17 + /// 18 18 + /// Shamelessly ported from [merde](https://github.com/bearcove/merde) 18 19 #[derive(Clone)] 19 20 pub enum CowStr<'s> { 20 21 /// &str varaiant ··· 330 331 { 331 332 deserializer.deserialize_str(CowStrVisitor) 332 333 } 333 333 - } 334 334 - 335 335 - /// Serde helper for deserializing stuff when you want an owned version 336 336 - pub fn deserialize_owned<'de, T, D>(deserializer: D) -> Result<<T as IntoStatic>::Output, D::Error> 337 337 - where 338 338 - T: Deserialize<'de> + IntoStatic, 339 339 - D: Deserializer<'de>, 340 340 - { 341 341 - let value = T::deserialize(deserializer)?; 342 342 - Ok(value.into_static()) 343 334 } 344 335 345 336 /// Convert to a CowStr.

+2 -1

crates/jacquard-common/src/into_static.rs

reviewed

··· 7 7 use std::hash::Hash; 8 8 use std::sync::Arc; 9 9 10 10 - /// Shamelessly copied from [](https://github.com/bearcove/merde) 11 10 /// Allow turning a value into an "owned" variant, which can then be 12 11 /// returned, moved, etc. 13 12 /// 14 13 /// This usually involves allocating buffers for `Cow<'a, str>`, etc. 14 14 + /// 15 15 + /// Shamelessly copied from [merde](https://github.com/bearcove/merde) 15 16 pub trait IntoStatic: Sized { 16 17 /// The "owned" variant of the type. For `Cow<'a, str>`, this is `Cow<'static, str>`, for example. 17 18 type Output: 'static;

+12 -2

crates/jacquard-common/src/lib.rs

reviewed

··· 211 211 /// HTTP client abstraction used by jacquard crates. 212 212 pub mod http_client; 213 213 pub mod macros; 214 214 - /// Generic session storage traits and utilities. 215 215 - pub mod session; 216 214 /// Service authentication JWT parsing and verification. 217 215 #[cfg(feature = "service-auth")] 218 216 pub mod service_auth; 217 217 + /// Generic session storage traits and utilities. 218 218 + pub mod session; 219 219 /// Baseline fundamental AT Protocol data types. 220 220 pub mod types; 221 221 // XRPC protocol types and traits ··· 239 239 } 240 240 } 241 241 } 242 242 + 243 243 + /// Serde helper for deserializing stuff when you want an owned version 244 244 + pub fn deserialize_owned<'de, T, D>(deserializer: D) -> Result<<T as IntoStatic>::Output, D::Error> 245 245 + where 246 246 + T: serde::Deserialize<'de> + IntoStatic, 247 247 + D: serde::Deserializer<'de>, 248 248 + { 249 249 + let value = T::deserialize(deserializer)?; 250 250 + Ok(value.into_static()) 251 251 + }

+1 -1

crates/jacquard-common/src/types/collection.rs

reviewed

··· 21 21 const NSID: &'static str; 22 22 23 23 /// A marker type implementing [`XrpcResp`] that allows typed deserialization of records 24 24 - /// from this collection. Used by [`Agent::get_record`] to return properly typed responses. 24 24 + /// from this collection. Used by [`AgentSessionExt::get_record`](https://docs.rs/jacquard/latest/jacquard/client/trait.AgentSessionExt.html) to return properly typed responses. 25 25 type Record: XrpcResp; 26 26 27 27 /// Returns the [`Nsid`] for the Lexicon that defines the schema of records in this

+79 -25

crates/jacquard/src/lib.rs

reviewed

··· 1 1 //! # Jacquard 2 2 //! 3 3 - //! A suite of Rust crates for the AT Protocol. 3 3 + //! A suite of Rust crates intended to make it much easier to get started with atproto development, 4 4 + //! without sacrificing flexibility or performance. 5 5 + //! 6 6 + //! [Jacquard is simpler](https://whtwnd.com/nonbinary.computer/3m33efvsylz2s) because it is 7 7 + //! designed in a way which makes things simple that almost every other atproto library seems to make difficult. 8 8 + //! 9 9 + //! It is also designed around zero-copy/borrowed deserialization: types like [`Post<'_>`](https://docs.rs/jacquard-api/latest/jacquard_api/app_bsky/feed/post/struct.Post.html) can borrow data (via the [`CowStr<'_>`](https://docs.rs/jacquard/latest/jacquard/cowstr/enum.CowStr.html) type and a host of other types built on top of it) directly from the response buffer instead of allocating owned copies. Owned versions are themselves mostly inlined or reference-counted pointers and are therefore still quite efficient. The `IntoStatic` trait (which is derivable) makes it easy to get an owned version and avoid worrying about lifetimes. 4 10 //! 5 11 //! 6 12 //! ## Goals and Features 7 13 //! 8 14 //! - Validated, spec-compliant, easy to work with, and performant baseline types 9 15 //! - Batteries-included, but easily replaceable batteries. 10 10 - //! - Easy to extend with custom lexicons 11 11 - //! - Straightforward OAuth 12 12 - //! - stateless options (or options where you handle the state) for rolling your own 13 13 - //! - all the building blocks of the convenient abstractions are available 14 14 - //! - lexicon Value type for working with unknown atproto data (dag-cbor or json) 15 15 - //! - order of magnitude less boilerplate than some existing crates 16 16 - //! - use as much or as little from the crates as you need 16 16 + //! - Easy to extend with custom lexicons using code generation or handwritten api types 17 17 + //! - Straightforward OAuth 18 18 + //! - Stateless options (or options where you handle the state) for rolling your own 19 19 + //! - All the building blocks of the convenient abstractions are available 20 20 + //! - Server-side convenience features 21 21 + //! - Lexicon Data value type for working with unknown atproto data (dag-cbor or json) 22 22 + //! - An order of magnitude less boilerplate than some existing crates 23 23 + //! - Use as much or as little from the crates as you need 24 24 + //! 17 25 //! 18 26 //! 19 27 //! ··· 77 85 //!} 78 86 //! ``` 79 87 //! 80 80 - //! ## Client options: 88 88 + //! 89 89 + //! ## Component crates 90 90 + //! 91 91 + //! Jacquard is split into several crates for modularity. The main `jacquard` crate 92 92 + //! re-exports most of the others, so you typically only need to depend on it directly. 93 93 + //! 94 94 + //! - [`jacquard-common`](https://docs.rs/jacquard-common/latest/jacquard_common/index.html) - AT Protocol types (DIDs, handles, at-URIs, NSIDs, TIDs, CIDs, etc.) 95 95 + //! - [`jacquard-api`](https://docs.rs/jacquard-api/latest/jacquard_api/index.html) - Generated API bindings from 646+ lexicon schemas 96 96 + //! - [`jacquard-axum`](https://docs.rs/jacquard-axum/latest/jacquard_axum/index.html) - Server-side XRPC handler extractors for Axum framework (not re-exported, depends on jacquard) 97 97 + //! - [`jacquard-oauth`](https://docs.rs/jacquard-oauth/latest/jacquard_oauth/index.html) - OAuth/DPoP flow implementation with session management 98 98 + //! - [`jacquard-identity`](https://docs.rs/jacquard-identity/latest/jacquard_identity/index.html) - Identity resolution (handle → DID, DID → Doc, OAuth metadata) 99 99 + //! - [`jacquard-lexicon`](https://docs.rs/jacquard-lexicon/latest/jacquard_lexicon/index.html) - Lexicon resolution, fetching, parsing and Rust code generation from schemas 100 100 + //! - [`jacquard-derive`](https://docs.rs/jacquard-derive/latest/jacquard_derive/index.html) - Macros (`#[lexicon]`, `#[open_union]`, `#[derive(IntoStatic)]`) 101 101 + //! 102 102 + //! 103 103 + //! ### A note on lifetimes 104 104 + //! 105 105 + //! You'll notice a bunch of lifetimes all over Jacquard types, examples, and so on. If you're newer 106 106 + //! to Rust or have simply avoided them, they're part of how Rust knows how long to keep something 107 107 + //! around before cleaning it up. They're not unique to Rust (C and C++ have the same concept 108 108 + //! internally) but Rust is perhaps the one language that makes them explicit, because they're part 109 109 + //! of how it validates that things are memory-safe, and being able to give information to the compiler 110 110 + //! about how long it can expect something to stick around lets the compiler reason out much more 111 111 + //! sophisticated things. [The Rust book](https://doc.rust-lang.org/book/ch10-03-lifetime-syntax.html) has a section on them if you want a refresher. 112 112 + //! 113 113 + //! > On Jacquard types like [`CowStr`], a `'static` lifetime parameter is used to refer to the owned 114 114 + //! version of a type, in the same way `String` is the owned version of `&str`. 115 115 + //! 116 116 + //! This is somewhat in tension with the 'make things simpler' goal of the crate, but it is honestly 117 117 + //! pretty straightforward once you know the deal, and Jacquard provides a number of escape hatches 118 118 + //! and easy ways to work. 119 119 + //! 120 120 + //! Because explicit lifetimes are somewhat unique to Rust and are not something you may be used to 121 121 + //! thinking about, they can seem a bit scary to work with. Normally the compiler is pretty good at 122 122 + //! them, but Jacquard is [built around borrowed deserialization](https://docs.rs/jacquard-common/latest/jacquard_common/#working-with-lifetimes-and-zero-copy-deserialization) and types. This is for reasons of 123 123 + //! speed and efficiency, because borrowing from your source buffer saves copying the data around. 124 124 + //! 125 125 + //! However, it does mean that any Jacquard type that can borrow (not all of them do) is annotated 126 126 + //! with a lifetime, to confirm that all the borrowed bits are ["covariant"](https://doc.rust-lang.org/nomicon/subtyping.html), i.e. that they all live 127 127 + //! at least the same amount of time, and that lifetime matches or exceeds the lifetime of the data 128 128 + //! structure. This also imposes certain restrictions on deserialization. Namely the [`DeserializeOwned`](https://serde.rs/lifetimes.html) 129 129 + //! bound does not apply to almost any types in Jacquard. There is a [`deserialize_owned`] function 130 130 + //! which you can use in a serde `deserialize_with` attribute to help, but the general pattern is 131 131 + //! to do borrowed deserialization and then call [`.into_static()`] if you need ownership. 132 132 + //! 133 133 + //! ### Easy mode 134 134 + //! 135 135 + //! Easy mode for jacquard is to mostly just use `'static` for your lifetime params and derive/use 136 136 + //! [`.into_static()`] as needed. When writing, first see if you can get away with `Thing<'_>` 137 137 + //! and let the compiler infer. second-easiest after that is `Thing<'static>`, third-easiest is giving 138 138 + //! everything one lifetime, e.g. `fn foo<'a>(&'a self, thing: Thing<'a>) -> /* thing with lifetime 'a */`. 139 139 + //! 140 140 + //! When parsing the output of atproto API calls, you can call `.into_output()` on the `Response<R>` 141 141 + //! struct to get an owned version with a `'static` lifetime. When deserializing, do not use 142 142 + //! `from_writer()` type deserialization functions, or features like Axum's `Json` extractor, as they 143 143 + //! have DeserializeOwned bounds and cannot borrow from their buffer. Either use Jacquard's features 144 144 + //! to get an owned version or follow the same [patterns](https://whtwnd.com/nonbinary.computer/3m33efvsylz2s) it uses in your own code. 145 145 + //! 146 146 + //! ## Client options 81 147 //! 82 148 //! - Stateless XRPC: any `HttpClient` (e.g., `reqwest::Client`) implements `XrpcExt`, 83 149 //! which provides `xrpc(base: Url) -> XrpcCall` for per-request calls with ··· 112 178 //! base endpoint to the user's PDS on login/restore. 113 179 //! - Stateful client (OAuth): `OAuthClient<S, T>` and `OAuthSession<S, T>` where `S: ClientAuthStore` and 114 180 //! `T: OAuthResolver + HttpClient`. The client is used to authenticate, returning a session which handles authentication and token refresh internally. 115 115 - //! - `Agent<A: AgentSession>` Session abstracts over the above two options. Currently it is a thin wrapper, but this will be the thing that gets all the convenience helpers. 181 181 + //! - `Agent<A: AgentSession>` Session abstracts over the above two options and provides some useful convenience features via the [`AgentSessionExt`] trait. 116 182 //! 117 183 //! Per-request overrides (stateless) 118 184 //! ```no_run ··· 145 211 //! } 146 212 //! ``` 147 213 //! 148 148 - //! ## Component Crates 149 149 - //! 150 150 - //! Jacquard is split into several crates for modularity. The main `jacquard` crate 151 151 - //! re-exports most of the others, so you typically only need to depend on it directly. 152 152 - //! 153 153 - //! - [`jacquard-common`] - AT Protocol types (DIDs, handles, at-URIs, NSIDs, TIDs, CIDs, etc.) 154 154 - //! - [`jacquard-api`] - Generated API bindings from 646+ lexicon schemas 155 155 - //! - [`jacquard-axum`] - Server-side XRPC handler extractors for Axum framework (not re-exported, depends on jacquard) 156 156 - //! - [`jacquard-oauth`] - OAuth/DPoP flow implementation with session management 157 157 - //! - [`jacquard-identity`] - Identity resolution (handle→DID, DID→Doc, OAuth metadata) 158 158 - //! - [`jacquard-lexicon`] - Lexicon resolution, fetching, parsing and Rust code generation from schemas 159 159 - //! - [`jacquard-derive`] - Macros (`#[lexicon]`, `#[open_union]`, `#[derive(IntoStatic)]`) 214 214 + //! [`deserialize_owned`]: crate::deserialize_owned 215 215 + //! [`AgentSessionExt`]: crate::client::AgentSessionExt 216 216 + //! [`.into_static()`]: IntoStatic 160 217 161 218 #![warn(missing_docs)] 162 219 ··· 164 221 165 222 pub use common::*; 166 223 #[cfg(feature = "api")] 167 167 - /// If enabled, re-export the generated api crate 168 224 pub use jacquard_api as api; 169 225 pub use jacquard_common as common; 170 226 171 227 #[cfg(feature = "derive")] 172 172 - /// if enabled, reexport the attribute macros 173 228 pub use jacquard_derive::*; 174 229 175 230 pub use jacquard_identity as identity; 176 231 177 177 - /// OAuth usage helpers (discovery, PAR, token exchange) 178 232 pub use jacquard_oauth as oauth;