.NET ATProtocol Library - Built for Source Gen
4.6 kB · 135 lines
Markdown
at main

CarpaNet.AspNetCore #

NuGet Version License

ASP.NET Core XRPC server endpoint support for CarpaNet. Generate abstract ATProtocol XRPC controllers from lexicon definitions and implement your own ATProtocol server endpoints.

Installation #

dotnet add package CarpaNet.AspNetCore

You also need the core CarpaNet package (with source generator) to generate the controllers and data model types.

Quick Start #

1. Enable XRPC endpoint generation #

Set CarpaNet_EmitXrpcEndpoints to true in your ASP.NET Core project:

<PropertyGroup>
  <CarpaNet_EmitXrpcEndpoints>true</CarpaNet_EmitXrpcEndpoints>
  <CarpaNet_LexiconAutoResolve>true</CarpaNet_LexiconAutoResolve>
</PropertyGroup>

<ItemGroup>
  <LexiconResolve Include="com.atproto.server.describeServer" />
  <LexiconResolve Include="com.atproto.identity.resolveHandle" />
</ItemGroup>

This tells the CarpaNet source generator to produce abstract controller classes alongside the usual data model types.

2. Implement the generated controllers #

The generator creates abstract controllers grouped by NSID namespace. Subclass them and implement the abstract methods:

using CarpaNet.AspNetCore;
using Microsoft.AspNetCore.Http.HttpResults;

public class MyServerController : Xrpc.ComAtproto.Server.ServerController
{
    public override Task<Results<Ok<ComAtproto.Server.DescribeServerOutput>, ATErrorResult>> DescribeServerAsync(
        CancellationToken cancellationToken = default)
    {
        var output = new ComAtproto.Server.DescribeServerOutput
        {
            AvailableUserDomains = new List<string> { ".example.com" },
            Did = new CarpaNet.ATDid("did:web:example.com"),
        };

        return Task.FromResult<Results<Ok<ComAtproto.Server.DescribeServerOutput>, ATErrorResult>>(
            TypedResults.Ok(output));
    }
}

3. Wire up ASP.NET #

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();

var app = builder.Build();
app.MapControllers();
app.Run();

Your endpoints are now available at /xrpc/{nsid} (e.g., /xrpc/com.atproto.server.describeServer).

How It Works #

The CarpaNet source generator reads ATProtocol lexicon JSON files and produces:

  • Data model classes — Records, objects, input/output types (generated by the existing pipeline)
  • Abstract controllers — One per NSID namespace group (e.g., ServerController for com.atproto.server.*)

Lexicon queries map to [HttpGet] with [FromQuery] parameters. Lexicon procedures map to [HttpPost] with [FromBody] input.

Generated Controller Pattern #

Lexicon: com.atproto.identity.resolveHandle (query)
  ↓
Xrpc.ComAtproto.Identity.IdentityController (abstract)
  → ResolveHandleAsync([FromQuery] string handle, CancellationToken ct)
  → Returns Task<Results<Ok<ResolveHandleOutput>, ATErrorResult>>
Lexicon: com.atproto.repo.createRecord (procedure)
  ↓
Xrpc.ComAtproto.Repo.RepoController (abstract)
  → CreateRecordAsync([FromBody] CreateRecordInput input, CancellationToken ct)
  → Returns Task<Results<Ok<CreateRecordOutput>, ATErrorResult>>

Error Handling #

Use ATErrorResult factory methods to return ATProtocol-compliant error responses:

// Returns { "error": "NotFound", "message": "Record not found" } with HTTP 404
return ATErrorResult.NotFound("Record not found");

// Returns { "error": "AuthMissing", "message": "Authentication Required" } with HTTP 401
return ATErrorResult.Unauthorized();

// Returns { "error": "BadRequest", "message": "Invalid handle format" } with HTTP 400
return ATErrorResult.BadRequest("Invalid handle format");

Available factory methods:

Method Status Code Error Type
BadRequest() 400 BadRequest
Unauthorized() 401 AuthMissing
Forbidden() 403 Forbidden
NotFound() 404 NotFound
PayloadTooLarge() 413 PayloadTooLarge
TooManyRequests() 429 TooManyRequests
InternalServerError() 500 InternalServerError
NotImplemented() 501 NotImplemented
BadGateway() 502 BadGateway
ServiceUnavailable() 503 ServiceUnavailable
GatewayTimeout() 504 GatewayTimeout

MSBuild Properties #

Property Description Default
CarpaNet_EmitXrpcEndpoints Enable XRPC controller generation false