bad-example.com
forked from
nonbinary.computer/jacquard
A better Rust ATProto crate
1# Jacquard
2
3A suite of Rust crates for the AT Protocol.
4
5## Goals
6
7- Validated, spec-compliant, easy to work with, and performant baseline types (including typed at:// uris)
8- Batteries-included, but easily replaceable batteries.
9 - Easy to extend with custom lexicons
10- lexicon Value type for working with unknown atproto data (dag-cbor or json)
11- order of magnitude less boilerplate than some existing crates
12 - either the codegen produces code that's easy to work with, or there are good handwritten wrappers
13- didDoc type with helper methods for getting handles, multikey, and PDS endpoint
14- use as much or as little from the crates as you need
15
16## Development
17
18This repo uses [Flakes](https://nixos.asia/en/flakes) from the get-go.
19
20```bash
21# Dev shell
22nix develop
23
24# or run via cargo
25nix develop -c cargo run
26
27# build
28nix build
29```
30
31There's also a [`justfile`](https://just.systems/) for Makefile-esque commands to be run inside of the devShell, and you can generally `cargo ...` or `just ...` whatever just fine if you don't want to use Nix and have the prerequisites installed.
32
33
34
35### String types
36Something of a note to self. Developing a pattern with the string types (may macro-ify at some point). Each needs:
37- new(): constructing from a string slice with the right lifetime that borrows
38- new_owned(): constructing from an impl AsRef<str>, taking ownership
39- new_static(): construction from a &'static str, using SmolStr's/CowStr's new_static() constructor to not allocate
40- raw(): same as new() but panics instead of erroring
41- unchecked(): same as new() but doesn't validate. marked unsafe.
42- as_str(): does what it says on the tin
43#### Traits:
44- Serialize + Deserialize (custom impl for latter, sometimes for former)
45- FromStr
46- Display
47- Debug, PartialEq, Eq, Hash, Clone
48- From<T> for String, CowStr, SmolStr,
49- From<String>, From<CowStr>, From<SmolStr>, or TryFrom if likely enough to fail in practice to make panics common
50- AsRef<str>
51- Deref with Target = str (usually)
52
53Use `#[repr(transparent)]` as much as possible. Main exception is at-uri type and components.
54Use SmolStr directly as the inner type if most or all of the instances will be under 24 bytes, save lifetime headaches.
55Use CowStr for longer to allow for borrowing from input.
56
57TODO: impl IntoStatic trait to take ownership of string types