atproto libraries implementation in ocaml
gdiazlo.tngl.sh
1{0 AT Protocol OCaml Libraries}
2
3This is the documentation for the AT Protocol OCaml library suite.
4
5{1 Overview}
6
7The AT Protocol (Authenticated Transfer Protocol) is a federated social
8networking protocol. This library suite provides a complete implementation
9in OCaml, designed to be:
10
11- {b Type-safe}: Leverage OCaml's type system for correctness
12- {b Runtime-agnostic}: Uses OCaml 5.4 effects for pluggable I/O
13- {b Modular}: 11 independent packages, use only what you need
14- {b Spec-compliant}: Passes all official interoperability tests
15
16{1 Package Index}
17
18{2 Foundation Layer}
19
20- [atproto-multibase]: Base encoding (base32-sortable, base58btc, base32lower)
21- [atproto-syntax]: Identifier parsing (handles, DIDs, NSIDs, TIDs, AT-URIs)
22- [atproto-crypto]: Cryptography (P-256, K-256, did:key, JWT)
23
24{2 Data Layer}
25
26- [atproto-ipld]: IPLD support (DAG-CBOR, CIDs, CAR files)
27- [atproto-mst]: Merkle Search Tree for repositories
28- [atproto-repo]: Repository operations and commits
29
30{2 Identity Layer}
31
32- [atproto-identity]: DID and Handle resolution
33
34{2 Network Layer}
35
36- [atproto-effects]: Effects-based I/O abstraction
37- [atproto-xrpc]: XRPC HTTP API client and server
38- [atproto-sync]: Firehose event streams and repository sync
39
40{2 Application Layer}
41
42- [atproto-lexicon]: Lexicon schema parsing and validation
43- [atproto-api]: High-level API client
44
45{1 Quick Start}
46
47{2 Parsing Identifiers}
48
49{[
50open Atproto_syntax
51
52(* Parse a handle *)
53let handle = Handle.of_string "alice.bsky.social" |> Result.get_ok
54
55(* Parse a DID *)
56let did = Did.of_string "did:plc:z72i7hdynmk6r22z27h6tvur" |> Result.get_ok
57
58(* Parse an AT-URI *)
59let uri = At_uri.of_string "at://did:plc:xyz/app.bsky.feed.post/abc" |> Result.get_ok
60]}
61
62{2 Using Cryptography}
63
64{[
65open Atproto_crypto
66
67(* Generate and use a P-256 key pair *)
68let keypair = P256.generate ()
69let signature = P256.sign keypair.private_key (Bytes.of_string "data")
70let valid = P256.verify keypair.public_key (Bytes.of_string "data") signature
71
72(* Encode as did:key *)
73let did_key = Did_key.encode_p256 keypair.public_key
74]}
75
76{2 Working with IPLD}
77
78{[
79open Atproto_ipld
80
81(* Encode data as DAG-CBOR and compute CID *)
82let data = Dag_cbor.Map [("hello", Dag_cbor.String "world")]
83let bytes = Dag_cbor.encode data
84let cid = Cid.of_dag_cbor bytes
85]}
86
87{1 Effects System}
88
89All I/O operations use OCaml 5 algebraic effects. This allows the libraries
90to be used with any async runtime. See the [atproto-effects] package for details.
91
92Example handler:
93{[
94open Atproto_effects.Effects
95
96let run f =
97 Effect.Deep.match_with f () {
98 retc = Fun.id;
99 exnc = raise;
100 effc = fun (type a) (eff : a Effect.t) ->
101 match eff with
102 | Http_get uri -> Some (fun k ->
103 let resp = (* your HTTP implementation *) in
104 Effect.Deep.continue k resp)
105 | Now -> Some (fun k ->
106 Effect.Deep.continue k (Ptime_clock.now ()))
107 | _ -> None
108 }
109]}
110
111{1 Resources}
112
113- {{: https://atproto.com/specs } AT Protocol Specification}
114- {{: https://github.com/gdiazlo/atproto } GitHub Repository}
115- {{: https://github.com/bluesky-social/atproto-interop-tests } Interop Tests}