# CarpaNet.AspNetCore [![NuGet Version](https://img.shields.io/nuget/v/CarpaNet.AspNetCore.svg)](https://www.nuget.org/packages/CarpaNet.AspNetCore/) ![License](https://img.shields.io/badge/License-MIT-blue.svg) ASP.NET Core XRPC server endpoint support for [CarpaNet](https://github.com/drasticactions/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: ```xml true true ``` 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: ```csharp using CarpaNet.AspNetCore; using Microsoft.AspNetCore.Http.HttpResults; public class MyServerController : Xrpc.ComAtproto.Server.ServerController { public override Task, ATErrorResult>> DescribeServerAsync( CancellationToken cancellationToken = default) { var output = new ComAtproto.Server.DescribeServerOutput { AvailableUserDomains = new List { ".example.com" }, Did = new CarpaNet.ATDid("did:web:example.com"), }; return Task.FromResult, ATErrorResult>>( TypedResults.Ok(output)); } } ``` ### 3. Wire up ASP.NET ```csharp 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, ATErrorResult>> ``` ``` Lexicon: com.atproto.repo.createRecord (procedure) ↓ Xrpc.ComAtproto.Repo.RepoController (abstract) → CreateRecordAsync([FromBody] CreateRecordInput input, CancellationToken ct) → Returns Task, ATErrorResult>> ``` ## Error Handling Use `ATErrorResult` factory methods to return ATProtocol-compliant error responses: ```csharp // 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` |