Skip to content

CLAUDE.md

Latest commit

 

History

History
67 lines (47 loc) · 3.48 KB

CLAUDE.md

File metadata and controls

67 lines (47 loc) · 3.48 KB

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:

  1. MSBuild targets (CarpaNet.targets) resolve lexicon files via DNS/authority/handle lookup and mark them as AdditionalFiles with IsATProtoLexicon metadata
  2. LexiconParser converts JSON to LexiconDocument AST
  3. TypeRegistry maps lexicon definitions to C# types
  4. 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 releases
  • develop - active development, NuGet auto-publishes from this branch when src/ or tests/ change