Something went wrong. Try again.
.NET ATProtocol Library - Built for Source Gen
Something went wrong. Try again.
CLAUDE.md #
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Build Commands #
# Build (requires .NET SDK 10.0+)
dotnet build CarpaNet.slnx
# Run tests
dotnet test tests/CarpaNet.UnitTests/CarpaNet.UnitTests.csproj
# Run a single test
dotnet test tests/CarpaNet.UnitTests/CarpaNet.UnitTests.csproj --filter "FullyQualifiedName~TestClassName.TestMethodName"
# Pack NuGet packages
dotnet pack src/CarpaNet/CarpaNet.csproj --configuration Release --output nupkg
dotnet pack src/CarpaNet.OAuth/CarpaNet.OAuth.csproj --configuration Release --output nupkg
dotnet pack src/CarpaNet.Jetstream/CarpaNet.Jetstream.csproj --configuration Release --output nupkg
# Build samples (separate solution)
dotnet build CarpaNet.Samples.slnx
Architecture #
CarpaNet is a .NET ATProtocol library that uses Roslyn source generators to produce API bindings from Lexicon JSON schema files. It is designed for full NativeAOT compatibility with minimal dependencies.
Project Layout #
- src/CarpaNet - Core runtime:
IATProtoClient/ATProtoClient, XRPC protocol, identity resolution, DAG-CBOR serialization, CAR file reading, event streams - src/CarpaNet.SourceGen - Roslyn incremental source generator (
LexiconGenerator). Parses Lexicon JSON files and generates C# records, API extension methods, union types, and JSON/CBOR serialization contexts - src/CarpaNet.BuildTasks - MSBuild tasks for DNS-based lexicon resolution at build time (resolving NSIDs, authorities, handles to lexicon files)
- src/CarpaNet.OAuth - OAuth 2.0 with PAR, PKCE, and DPoP support via
OAuthSession - src/CarpaNet.Jetstream - Real-time event subscription via Bluesky Jetstream (Zstandard-compressed WebSocket)
Source Generator Pipeline #
The source generator (LexiconGenerator) is the core architectural piece:
- MSBuild targets (
CarpaNet.targets) resolve lexicon files via DNS/authority/handle lookup and mark them asAdditionalFileswithIsATProtoLexiconmetadata LexiconParserconverts JSON toLexiconDocumentASTTypeRegistrymaps lexicon definitions to C# types- Generators emit: data model records (
ObjectGenerator), client extension methods (ApiGenerator), discriminated unions (UnionGenerator), JSON context (JsonContextGenerator), CBOR context (CborContextGenerator)
Consumer projects include lexicons via MSBuild items (LexiconFiles, LexiconResolve, LexiconResolveAuthority, LexiconResolveHandle) and the generator produces all bindings at compile time.
Key Patterns #
- Multi-targeting: Core libraries target net8.0/net9.0/net10.0/netstandard2.0. Source generator targets netstandard2.0 only. Tests target net10.0.
- Central Package Management: All package versions in
Directory.Packages.props - Strong naming: Assemblies signed with
Key.snk - GitVersion: Semantic versioning via
Version.props - Token providers: Authentication abstracted via
ITokenProvider(session-based or DPoP) - No reflection: All serialization uses source-generated contexts (System.Text.Json and System.Formats.Cbor)
Design Principles #
- Minimal runtime dependencies (only ZstdSharp.Port beyond framework libs)
- NativeAOT compatible - no JIT-time reflection
- ATProtocol-focused, not Bluesky-specific
- Simple APIs - complexity lives in the source generator, not the consumer API surface
Branching #
main- stable releasesdevelop- active development, NuGet auto-publishes from this branch when src/ or tests/ change