CarpaNet.AspNetCore 1.0.1

CarpaNet.AspNetCore

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:

MSBuild Properties