Skip to content

Latest commit

 

History

History
256 lines (208 loc) · 16.7 KB

README.md

File metadata and controls

256 lines (208 loc) · 16.7 KB

CodeFusion.Http

An HTTP/1.1 server for .NET 10 that allocates nothing per request, and endpoints written like ASP.NET minimal APIs that a source generator compiles into the same zero-allocation code. Route values, the query string and JSON bodies are read over the request's own bytes; replies are written straight into the connection's buffer.

dotnet add package CodeFusion.Http

Endpoints

using CodeFusion;
using CodeFusion.Http;

var builder = HttpApp.CreateBuilder(args);          // HOST and PORT from the environment
builder.AddJwtAuth(HttpAppBuilder.Setting("JWT_SECRET")!); // at least 32 bytes; tokens live 30 days unless set
builder.AddSingleton(new Catalog());
var app = builder.Build();

var api = app.MapGroup("/api");
api.MapGet("/articles/{slug}", static (Utf8 slug, Page page, Viewer viewer, Catalog catalog) =>
        catalog.Find(slug) is { } a ? Reply.Ok(a.View(viewer.Id)) : Reply.NotFound(Errors.ArticleNotFound))
   .AuthOptional();
api.MapPost("/users/login", static async (LoginBody body, Users users, Jwt jwt) =>
{
    long id = await users.Check(body.Email, body.Password);
    return id > 0 ? Reply.Ok(new UserView(body.Email, jwt.Issue(id))) : Reply.Unauthorized(Errors.WrongLogin);
});
app.Run();                                          // until SIGTERM, then the requests in flight finish

[FromQuery] partial struct Page
{
    [DefaultValue(20), Range(1, 100)] public long Limit;
    public long Offset;
    static ErrorReply Invalid => Errors.BadPage;    // a number that isn't valid gets this 422
}

[JsonEnvelope("user")] partial struct LoginBody     // {"user": {"email": ..., "password": ...}}
{
    public Utf8 Email;                              // required: present and not empty
    public Utf8 Password;
}

[JsonEnvelope("user")] readonly record struct UserView(Utf8 Email, Utf8 Token);

A handler is a static lambda or a static method. Its parameters are bound by kind: Utf8, long and int are route values; a [FromQuery] struct is the query string; any other struct is the JSON body; Viewer is the user id in the Authorization: Token <jwt> header (0 when there is none; an invalid one is a 401); classes are the services registered on the builder, singletons or one per connection (IRequestScoped); IResponse, HttpExchange and CancellationToken (the client has gone) are the connection's. It returns a Reply<T> (Reply.Ok, Reply.Created, or any Reply such as Reply.NotFound(error)), a Reply, an ErrorReply, or any struct implementing IReply; an async lambda returns them through a pooled Pending<T> with no attribute needed.

A body is JSON unless the reply says otherwise: a ContentReply (new ContentReply(MediaType.PlainText, "Hello"u8), made once) sends constant bytes of any media type, and a reply of your own sets response.ContentType. Set builder.Options.ServerName to send a Server header with every response, the server's own refusals included.

A Utf8 is a view of bytes: of the request, or of the request's arena when it had to be decoded. It is valid until the response has been sent, so the analyzer refuses to let a class keep one.

The JWT secret must be at least 32 bytes of UTF-8. A deployment handed a shorter fixed one (the Conduit contest's is 26 bytes) passes AddJwtAuth(secret, lifetime, allowShortSecret: true). Its tokens are still standard HS256, but a short secret can be guessed offline from any one token, and whoever finds it can sign as any user (SECURITY.md).

JwtOptions holds the same settings and the header's scheme, Token unless set. The header is the scheme, one space and the token, once surrounding spaces and tabs are trimmed; the scheme is matched exactly, case included:

builder.AddJwtAuth(secret, new JwtOptions { Scheme = "Bearer", AllowShortSecret = true });

Tokens can carry string claims beside sub. The app declares them once, every token is checked for them, and a handler reads each one as a Utf8 view of the token's payload, decoded into the request's arena:

var auth = new JwtOptions { Scheme = "Bearer" };
auth.Claims.Add(new JwtClaim("username") { MaxBytes = 64 });  // required unless Required = false
builder.AddJwtAuth(secret, auth);
// ...
app.MapPost("/posts", static (NewPost body, Viewer viewer, Posts posts) =>
        posts.Create(viewer.Id, viewer.Claim("username"u8), body.Body))
   .AuthRequired();

A token is invalid when its signature, header, JSON, exp or nbf fails. When those pass, its payload is still invalid if sub isn't a positive integer string, or a declared claim is missing (when required), isn't a string, isn't valid text, or is outside MinBytes and MaxBytes once unescaped; so is one whose exp or nbf is too large to be a finite number (1e400). If a claim appears twice, the last one counts, and any bad copy makes the payload invalid. viewer.Claim(name) throws for a name that wasn't declared, and for any name on a Viewer made by hand, which declares none; it gives an empty value for an anonymous viewer, and TryGetClaim tells an absent optional claim from an empty one. A Viewer used after its request throws, from any thread. jwt.Issue(userId, username) issues a token carrying the claims, and refuses values the verifier would refuse.

The generator replaces each MapGet/MapPost/MapPut/MapDelete call with an endpoint that binds the parameters and writes the reply with no reflection and nothing looked up per request. Routes are literal templates; a literal segment wins over a parameter, methods ignore case, HEAD runs the GET endpoint and sends its head without the body, and anything no route matches is a 404 with builder.Errors.NotFound's body. The app's other bodies (401, 422, 500 and the server's own 400, 413, 414, 431) are on builder.Errors too.

A 401 has one body, Errors.Unauthorized, unless the app gives a reason its own. Each reason left null answers as before:

builder.Errors.MissingToken = Errors.MissingToken;          // no header, or not "Bearer <token>"
builder.Errors.InvalidToken = Errors.InvalidToken;          // forged, malformed, not HS256, expired
builder.Errors.InvalidTokenPayload = Errors.InvalidPayload; // genuine, but sub or a declared claim breaks its rule

InvalidTokenPayload falls back to InvalidToken, then to Unauthorized. A header that is present but carries no valid token is a 401 on an AuthOptional endpoint too; only a request with no header at all is anonymous.

A body's failures can be told apart the same way. Errors.InvalidBody (422) answers JSON of another shape (an array, a missing envelope) and a field its struct names no reply for. Two more replies are null unless set:

builder.Errors.MalformedBody = Errors.Malformed; // not JSON: cut short, trailing bytes, a bad escape, past depth 64
builder.Errors.MissingBody = Errors.NoBody;      // no body at all, or Content-Length: 0

A null MissingBody answers as MalformedBody does, and a null MalformedBody as before: the struct's own static ErrorReply InvalidBody, then Errors.InvalidBody. A reason the app sets wins over a struct's own reply, which keeps answering the bodies of another shape.

A long or int route value is ASCII digits that fit its type, within its [Range] if it has one. One that isn't gets Errors.InvalidRouteValue, or the endpoint's own reply, and Errors.NotFound when neither is set. It is checked after auth, so a request with no token gets the 401 whatever its route holds:

builder.Errors.InvalidRouteValue = Errors.InvalidPostId;  // 400 "invalid post id"
app.MapPost("/posts/{id}/like", static ([Range(1, long.MaxValue)] long id, Viewer viewer, Likes likes) =>
        likes.Add(viewer.Id, id))
   .AuthRequired();
app.MapGet("/users/{id}", static ([Range(1, long.MaxValue)] long id, Users users) => users.Find(id))
   .WithInvalidRouteValue(Errors.InvalidUserId);

A body or [FromQuery] struct is bound through its public fields and its public properties with a public setter, and nothing else, so a request can't set a member the struct keeps to itself. A number's [Range] holds in the body as in the query, in each of the attribute's forms, exclusive ends included.

These are build errors (CFH0109 a warning), from the package's analyzers, in every file (one named *.g.cs too):

CFH0001 a handler lambda that isn't static (fix: add static), or an instance method
CFH0002 a string parameter (fix: take a Utf8)
CFH0003 a reply the generator can't send, such as Task<T> or a type with no JSON form
CFH0004 a Utf8 (or RawJson, Utf8List, Viewer, ArenaBytes) kept by a class: in a field, an auto-property, or a primary-constructor parameter one of its members uses; or by a struct's static field or auto-property. A type that only takes one in, such as Func<Utf8, bool> or IEqualityComparer<Utf8>, keeps none. A CodeFusion.Data entity's instance members are exempt, since it is never built: a class a data context has a Table<T> for, and its base classes, or one marked [Table] in an assembly that references CodeFusion.Data and has no data context. A class that derives from one without being an entity is reported for what it inherits
CFH0005 LINQ inside a handler
CFH01xx a Map call the generator can't compile: a route that isn't a literal template, a parameter it can't bind (a [Range] on a Utf8 route value, or one that leaves a long or int route value nothing), a struct that isn't partial, a required member its binder can't set, a handler held as a delegate it can't name (more than 16 parameters, a default value or params), a call it can't intercept
CFH0109 an internal field or settable auto-property of a body or [FromQuery] struct, which the binder leaves at its default: make it public to bind it, or private or [JsonIgnore] to say it isn't. Silence one at the member with #pragma warning disable CFH0109 or [SuppressMessage("CodeFusion", "CFH0109")], or all with NoWarn

The server underneath

The endpoints run on HttpServer, which can also be used directly with a handler of its own:

using System.Net;
using System.Text.Json;
using CodeFusion.Http;

var server = new HttpServer(new HttpServerOptions { EndPoint = new IPEndPoint(IPAddress.Any, 8080) }, static x =>
{
    // One JSON writer per connection, kept in State and pointed at each new response.
    if (x.State is not Utf8JsonWriter w) x.State = w = new Utf8JsonWriter(x);
    else w.Reset(x);

    if (x.Method == RequestMethod.Get && x.Path.SequenceEqual("/hello"u8))
    {
        w.WriteStartObject();
        w.WriteString("hello"u8, "world"u8);
        w.WriteEndObject();
    }
    else x.Status = 404;

    w.Flush();
    return default; // done without waiting: the response goes out now
});

await server.RunAsync(shutdownTimeout: TimeSpan.FromSeconds(10)); // until SIGTERM or Ctrl+C

A handler that awaits (a database query, say) is an async ValueTask method marked [AsyncMethodBuilder(typeof(PooledValueTaskMethodBuilder))]: its state lives in a pooled box instead of a new object per call. x.Aborted fires when the client leaves, as in Kestrel: it closes the connection (a browser tab closed, an HttpClient timeout, a proxy whose own client left), resets it, or the connection fails. After a close the answer is still sent if the handler finishes anyway, since the client may only have closed its sending side; after a reset it is dropped (x.IsAborted). A close behind a pipelined request is seen on Linux and macOS only.

Zero allocations, measured

AllocationTests counts every byte the whole process allocates (GC.GetTotalAllocatedBytes) over thousands of keep-alive requests after warm-up, with sync and async handlers, on 1 and 8 connections: 0 B per request. AppAllocationTests does the same for generated endpoints: route values, the query, bodies with escapes and lists, tokens issued into the arena, async handlers whose waits end on other threads, replies whose writes wait, 401 and 404, and the feed sample (FeedApp): Bearer tokens with a claim read in the handler, each 401 reason, a malformed body and no body, route values out of range before and after auth. A malformed body costs no exception either: one reader binds and checks the body in a single pass. A new connection object (about 1 KB) is made only when the pool of 4,096 is empty.

Against Kestrel answering the same JSON (BenchmarkDotNet short run, load client in the same process, Apple M-series with 8 cores shared with other work; CPU per request is the whole process's, the client's share included):

Connections Kestrel req/s CodeFusion.Http req/s Kestrel CPU/req CodeFusion.Http CPU/req Kestrel alloc/req CodeFusion.Http alloc/req
1 17,230 18,294 87 µs 81 µs 138 B 0
64 120,633 125,730 44 µs 38 µs 138 B 0
1,024 128,117 149,368 43 µs 37 µs 138 B 0

An idle keep-alive connection holds no buffers. With 2,000 of them open, the server kept about 2.3 KB of GC heap per connection and Kestrel about 17.6 KB (HttpIdleBenchmarks, measured on the contest server before extraction).

Event loops on Linux and macOS

On Linux the server runs on its own threads by default (HttpTransport.EventLoop), each waiting on epoll for its share of the connections (EventLoops, one per core); on macOS Transport = HttpTransport.EventLoop does the same with kqueue, and everywhere else .NET's sockets serve. On 8 cores it measured 20% more plaintext requests, 42% more JSON and 9% more database ones than .NET's sockets (TechEmpower's tests). A request then costs one receive call instead of two, and its handler runs on the loop's thread until it first awaits, with no hop through the runtime's socket thread or the thread pool. Every answer finished on a loop's thread waits for the batch's actions (OnEventLoopBatch, and the app's IServiceRegistry.OnEventLoopBatch registrations), where a database commits the batch's writes; an answer finished on another thread goes out at once. A provider that opens a batch from code the loop didn't start as a handler (a continuation resumed while answers are sent) calls EventLoopThread.RequestBatchEnd(), and the actions run once more before the loop waits. So a handler that resumes off its loop (it awaited work another thread completed) and then writes doesn't wait for a batch: it gets its answer once the database commits that write by itself, as with sockets (CodeFusion.Data.Sqlite's writer thread commits such writes in groups), which is correct but later than the loop's batch. On Linux every loop listens on the port itself (SO_REUSEPORT) and accepts its own connections, unless ListenerPerLoop is off. Idle connections still hold no buffer, and each loop keeps a few of its own, so a request answered on its loop rents and returns them without a lock (one whose handler resumes on another thread gives them back to the shared pool).

The loop's thread is shared, so choose Transport = HttpTransport.Sockets when handlers block before their first await (one that blocks holds up every connection on its loop), or when the p99 under a mixed load matters more than throughput (a slow request holds its loop's neighbours, where sockets spread them over the thread pool). The rest is guarded: one connection gets at most 16 reads and 16 handler calls per wake-up before its neighbours' turn, Aborted's callbacks run on the thread pool, and a stop gives a loop a handler holds a second, as it gives the handler.

Limits

HTTP/1.1 only, no TLS: put it behind a proxy that terminates TLS when it faces the internet. Request and response size limits, timeouts, minimum data rates and the connection limit are on HttpServerOptions; the defaults are Kestrel's, apart from a 10-minute keep-alive and a 1 MB body. A body must keep up 240 B/s, and so must a response the client reads slowly, after a 5 s grace period (MinRequestBodyDataRate, MinResponseDataRate; null turns either off). Only a body's own bytes count, not chunk framing, and of a response what the client's TCP acknowledged. Each byte pays for 1/rate seconds, but no more than RequestTimeout (or the grace period, if longer) ahead, so bytes sent early can't buy a crawl later, and a client faster than the rate between any two of its sends or reads is never cut off. A new connection's first request must arrive within RequestTimeout. A request's buffer doubles as its bytes come, so a connection holds about what it sent, not what its Content-Length declares. MaxConnections defaults to the process's descriptor limit less 1024 (less half of a limit under 2048), so past it new connections are closed at once instead of failing to be accepted. The server raises the soft limit to the hard one first, as CoreCLR does and NativeAOT doesn't. On Windows, 32-bit Linux and FreeBSD there is no default limit. SECURITY.md says what these do and don't bound.