[](https://github.com/shinyorg/httpserver/actions/workflows/build.yml)
[](https://www.nuget.org/packages/Shiny.Net.HttpServer)
# Shiny HTTP Server
ASP.NET Core is heavyweight and does not run on .NET MAUI or in several embedded server scenarios.
This is a dependency-light, fully AOT/trim-clean HTTP/1.1, HTTP/2 & HTTP/3 server that runs anywhere
.NET runs โ including .NET MAUI and native tvOS โ plus tunnelling so a server embedded in a phone app
is reachable from the public internet.
Only `Microsoft.Extensions.*` abstractions are taken as dependencies. Everything else โ JSON, crypto,
JWT, OpenAPI, HPACK, QPACK โ is built on what is in the box.
## Packages
| Package | Description |
| --- | --- |
| [Shiny.Net.HttpServer](https://www.nuget.org/packages/Shiny.Net.HttpServer) | The server: HTTP/1.1, HTTP/2 & HTTP/3, routing, middleware, DI scopes, static files, WebSockets, SSE, sessions, OpenAPI, CORS, rate limiting, IP filtering, host filtering, request localization, webhook signature verification, tunnelling. Includes the typed-endpoint source generator |
| [Shiny.Net.HttpServer.Jwt](https://www.nuget.org/packages/Shiny.Net.HttpServer.Jwt) | JWT authentication on in-box crypto โ no `Microsoft.IdentityModel` dependency |
| [Shiny.Net.HttpServer.Acme](https://www.nuget.org/packages/Shiny.Net.HttpServer.Acme) | Automatic HTTPS from Let's Encrypt, ZeroSSL or any ACME CA โ HTTP-01 and TLS-ALPN-01 answered by the server itself, account and certificate stored owner-only, renewed on schedule (or when the CA's ARI says) and hot-swapped into the running server with no restart. `AcmeCertificateRegistry` serves many hosts from one server โ one certificate per entry, chosen by SNI, entries added, imported and removed at runtime, first issuance always explicit. Issuance and expiry metrics. In-box crypto only; for hosts with public DNS, not phones |
| [Shiny.Net.HttpServer.AzureRelay](https://www.nuget.org/packages/Shiny.Net.HttpServer.AzureRelay) | Azure Relay tunnel provider |
| [Shiny.Net.HttpServer.Ssh](https://www.nuget.org/packages/Shiny.Net.HttpServer.Ssh) | SSH remote-forwarding tunnel provider, including zero-account quick tunnels |
| [Shiny.Net.HttpServer.Proxy](https://www.nuget.org/packages/Shiny.Net.HttpServer.Proxy) | A reverse proxy โ destination clusters, load balancing, active and passive health checks, session affinity, a transform pipeline, WebSocket and HTTP upgrade forwarding, response trailers (so gRPC proxies), upstream latency and error metrics, and routes read from `IConfiguration` with hot reload |
| [Shiny.Net.HttpServer.Switchboard](https://www.nuget.org/packages/Shiny.Net.HttpServer.Switchboard) | SignalR-shaped real-time calls over Server-Sent Events and plain POSTs โ switchboards (hubs) with groups and users, an operator for reaching clients from anywhere, client results, server hang-ups, and lines that resume after a drop with what they missed. Typed `Switchboard<TClient>` and contract export for clients in another repo. Source generator included; not wire-compatible with SignalR |
| [Shiny.Net.HttpServer.Switchboard.Client](https://www.nuget.org/packages/Shiny.Net.HttpServer.Switchboard.Client) | The .NET client for a switchboard โ calls, streams, handlers for the server's calls and questions, state events and automatic resume โ plus a generator that turns the contract interfaces into a typed client. No dependency on the server; MAUI, Blazor WebAssembly and console, trimmed or Native AOT |
| [Shiny.Net.HttpServer.Mcp](https://www.nuget.org/packages/Shiny.Net.HttpServer.Mcp) | Model Context Protocol (Streamable HTTP) transport โ host an MCP server without ASP.NET Core, including inside a MAUI app |
| [Shiny.Net.HttpServer.Mediator](https://www.nuget.org/packages/Shiny.Net.HttpServer.Mediator) | Publishes Shiny.Mediator requests, commands and streams as endpoints generated at compile time. Generator included |
| [Shiny.Net.HttpServer.DocumentDb](https://www.nuget.org/packages/Shiny.Net.HttpServer.DocumentDb) | Publishes a Shiny.DocumentDb type as a REST resource โ list, by-id, count, CRUD, merge-patch or JSON Patch and a live SSE tail |
| [Shiny.Net.HttpServer.WebDav](https://www.nuget.org/packages/Shiny.Net.HttpServer.WebDav) | A WebDAV (RFC 4918) class 1 & 2 server over a directory โ mount an app's storage in Finder, Windows Explorer or any WebDAV client, and open the same URL in a browser for a file manager with upload, rename and delete |
| [Shiny.Net.HttpServer.CalDav](https://www.nuget.org/packages/Shiny.Net.HttpServer.CalDav) | CalDAV (RFC 4791) and CardDAV (RFC 6352) on top of the WebDAV package: serve an app's calendars and contacts so iOS and macOS Calendar and Contacts, Thunderbird and DAVxโต can discover, subscribe and sync. Supports well-known discovery, sync-collection, queries with recurrence-aware time ranges, and a directory-backed store or your own `ICalendarStore` / `IAddressBookStore` |
| [Shiny.Net.HttpServer.Grpc](https://www.nuget.org/packages/Shiny.Net.HttpServer.Grpc) | gRPC and gRPC-Web โ unary, streaming and bidirectional methods over the same HTTP/2 stack, with serialization you supply |
| [Shiny.Net.HttpServer.Discovery](https://www.nuget.org/packages/Shiny.Net.HttpServer.Discovery) | mDNS/DNS-SD (Bonjour) โ advertises the server on the local link and finds the ones other devices advertise, so nobody has to type an IP address. The advertisement is held through a restart rather than blinking out and back, and a registration the responder refuses is retried before it is reported. The locator leaves out the app's own advertisement, so a device that hosts and browses never finds itself |
| [Shiny.Net.HttpServer.Mobile](https://www.nuget.org/packages/Shiny.Net.HttpServer.Mobile) | Mobile lifecycle on Shiny.Core โ stop on background and start on resume, an Android foreground service that follows the server's own running state to keep serving, an iOS resume that restarts the server the suspension took, rebind when the device changes network with a bounded retry for the bind a half-up network refuses, and a check for the manifest or bundle entries that silently break local networking. iOS and Android, with or without MAUI |
| [Shiny.Net.HttpServer.Testing](https://www.nuget.org/packages/Shiny.Net.HttpServer.Testing) | An `HttpClient` wired to the server through memory โ endpoint tests with no port, no listener and no socket, but the real parser, router and middleware |
| [Shiny.Net.HttpServer.Tunnels](https://www.nuget.org/packages/Shiny.Net.HttpServer.Tunnels) | Agent-backed tunnels โ supervises `cloudflared`, `ngrok` or `tailscale` and reports the public URL. Desktop, server and CLI. iOS and tvOS forbid process creation, so the agents throw there with a message pointing at the SSH provider or the relay |
| [Shiny.Net.HttpServer.OAuthLoopback](https://www.nuget.org/packages/Shiny.Net.HttpServer.OAuthLoopback) | The OAuth 2.0 / OpenID Connect loopback redirect receiver (RFC 8252). A desktop app or CLI signs in through the system browser, the way VS Code and `gh auth login` do, on an ephemeral `127.0.0.1` port. It validates `state`, accepts form_post, times out and shows a completion page, and it replaces `HttpListener`. PKCE and the token exchange stay with your OAuth client. Desktop only |
| [Shiny.Net.HttpServer.Tus](https://www.nuget.org/packages/Shiny.Net.HttpServer.Tus) | Resumable uploads over the tus 1.0.0 protocol โ a phone upload that drops half way resumes from the last byte instead of restarting; works with tus-js-client, Uppy and TusDotNetClient |
| [Shiny.Net.HttpServer.NuGet](https://www.nuget.org/packages/Shiny.Net.HttpServer.NuGet) | A private NuGet feed โ the V3 protocol with push, unlist, relist, search and autocomplete, so `dotnet nuget push`, `dotnet restore`, Visual Studio and Rider work against it unchanged. Packages are stored in NuGet's own folder-feed layout; versions use the official NuGet.Versioning |
| [Shiny.Net.HttpServer.Npm](https://www.nuget.org/packages/Shiny.Net.HttpServer.Npm) | A private npm registry: install (full and abbreviated metadata), publish, dist-tags, deprecate, unpublish, owners, search, whoami and login for npm, pnpm and Yarn. Token auth with per-package maintainers, and optional fall-through to registry.npmjs.org so one URL serves private and public packages |
| [Shiny.Net.HttpServer.FileSync](https://www.nuget.org/packages/Shiny.Net.HttpServer.FileSync) | Dropbox-style file sync server. Content-defined chunks are stored once by hash, so an edit to a large file moves only the chunks that changed and a copy moves nothing. Includes a change feed with long-poll, optimistic revisions for conflict detection, tombstones, per-user stores and resumable pack uploads over tus |
| [Shiny.Net.HttpServer.FileSync.Client](https://www.nuget.org/packages/Shiny.Net.HttpServer.FileSync.Client) | The sync client: keeps a local folder and the server in sync both ways, reuses chunks already on the device instead of downloading them, creates conflicted copies instead of losing edits, and runs transfers through Shiny.Net.Http so they continue in the background on iOS and Android |
| [Shiny.Net.HttpServer.CommandLine](https://www.nuget.org/packages/Shiny.Net.HttpServer.CommandLine) | A .NET tool โ `shinyhttpserver` โ that serves a directory over WebDAV, so one address is both a browser file manager (browse, upload, rename, delete) and a drive Finder or Explorer can mount, with basic auth, per-operation permissions, and a QR code in the banner so a phone can scan its way in โ `--tunnel` swaps the LAN address for a public pinggy.io tunnel so the phone need not be on the same network. In a terminal it opens a dashboard: live requests (clearable), uploads and downloads in progress, and a settings form that changes the tunnel, HTTPS, port, users and permissions on the running server (`--no-tui` for the plain banner) |
## Getting Started
```csharp
var server = new HttpServer(new HttpServerOptions { Port = 8080 });
server.MapGet("/ping", ctx => ctx.Response.WriteAsync("pong"));
await server.RunAsync();
```
Every registration this library owns hangs off one builder, in both hosting shapes:
```csharp
var builder = HttpServer.CreateBuilder();
builder.Options.Port = 8080;
builder.AddAuthentication().AddJwtBearer(o => { o.Issuer = "app"; o.Audience = "app"; o.SigningKey = key; });
builder.AddRateLimiter(o => o.GlobalPolicy = new FixedWindowRateLimitPolicy(100, TimeSpan.FromMinutes(1)));
builder.AddHealthChecks().AddServerCheck();
var app = builder.Build();
// โฆor, inside an app that already owns a container โ the same calls:
services.AddShinyHttpServer(http =>
{
http.Options.Port = 8080;
http.AddHealthChecks().AddServerCheck();
http.Configure(server => server.MapMyAppEndpoints());
});
```
Typed endpoints, generated at compile time:
```csharp
[Route("/api/users")]
public class UserEndpoints(IUserService users, ILogger<UserEndpoints> logger)
{
[Get("/{id:int}")]
public async Task<IActionResult> GetUser(int id, CancellationToken ct)
=> await users.FindAsync(id, ct) is { } u ? new OkObjectResult(u) : new NotFoundResult();
}
app.MapMyAppEndpoints(); // emitted for every [Route] class in the assembly
app.MapGroup("/v2", api => api.MapMyAppEndpoints()); // or mounted under a prefix
```
An MCP server, on the same host, reachable from a MAUI app:
```csharp
builder.Services
.AddMcpServer(o => o.ServerInfo = new() { Name = "thermostat", Version = "1.0.0" })
.WithTools<ThermostatTools>()
.WithHttpTransport();
var app = builder.Build();
app.MapMcp(); // POST/GET/DELETE/OPTIONS on /mcp
```
The MCP package is trim- and AOT-clean like the rest, with one thing the compiler cannot check for
you: a tool's parameter and return types are published as a JSON schema, and building that schema by
reflection does not survive trimming. Tools that trade only in primitives need nothing extra; give
the rest a source-generated context, and `MapMcp()` will tell you if you missed one.
```csharp
[JsonSerializable(typeof(Query))]
[JsonSerializable(typeof(IReadOnlyList<Reading>))]
public partial class ToolJson : JsonSerializerContext;
.WithTools<ThermostatTools>(ToolJson.Default.Options)
```
On a phone, where the server has to be found and has to survive the device moving:
```csharp
builder.Services.AddShinyHttpServer(
http =>
{
http.Options.Address = IPAddress.Any;
// Keeps serving in the background on Android through a foreground service; on iOS, where
// nothing can, restores the server on resume if it was running. Both rebind on a network change.
http.AddHttpServerLifecycle(o => o.BackgroundMode = BackgroundServerMode.KeepAlive);
// Advertises on the local link, so the other device does not need an IP address.
http.AddHttpServerAdvertisement(o => o.ServiceType = "_myapp._tcp");
},
autoStart: false
);
```
and on the other device:
```csharp
var found = await locator.FindFirstAsync("_myapp._tcp");
using var client = new HttpClient { BaseAddress = found!.BaseAddress };
```
## What is in the box
**The four tiers** โ one delegate, raw routes, middleware, and source-generated typed endpoints. Each
is built on the one below and they compose in the same app.
| | |
| --- | --- |
| **Core** | Routing with constraints, runtime-mutable routes and API versioning (URL segment, query, header or media type, with deprecation and sunset headers), ASP.NET-shaped middleware that can read and rewrite both bodies of an exchange, a real `IServiceScope` per request, results in both `Results.*` and `IActionResult` spellings, RFC 9457 problem details and an exception-handler chain, per-endpoint request timeouts, Idempotency-Key handling (draft-ietf-httpapi-idempotency-key-header) so a retried POST gets its stored response instead of running twice, request localization from the query string, a cookie or `Accept-Language`, RFC 6902 JSON Patch over RFC 6901 JSON Pointer โ applied all-or-nothing, bound as a typed endpoint parameter, and failing as problem details that name the operation |
| **Caching** | Conditional requests for handlers that are not serving a file โ `If-Match`, `If-None-Match`, `If-Modified-Since`, 304 and 412 โ plus output caching with a bounded in-memory store, where the saving is battery rather than bandwidth |
| **Diagnostics** | Health checks with liveness/readiness tags, telemetry on the in-box primitives โ one `Activity` per request continuing the caller's `traceparent`, and the OpenTelemetry HTTP metrics an ASP.NET dashboard already reads โ and W3C access logs, rolled and pruned, written off the request path |
| **Formats** | Content negotiation in both directions โ responses chosen from `Accept`, request bodies from `Content-Type`. JSON out of the box; XML, MessagePack and protobuf are one line each, and a format of your own is an `IOutputFormatter`/`IInputFormatter` pair. XML and MessagePack need no dependency and no attributes on your DTOs: they read the same `JsonTypeInfo` the JSON path reads, which is what keeps them AOT-clean where `XmlSerializer` cannot be |
| **Protocols** | HTTP/1.1, HTTP/2 (own HPACK), HTTP/3 (own QPACK), WebSockets, Server-Sent Events, trailing headers on all three versions, 103 Early Hints and other 1xx interim responses on all three. Never guessed โ ALPN over TLS, connection preface over cleartext. WebSockets carry permessage-deflate, keepalive pings, and a registry for broadcasting to a group |
| **Content** | Static files from disk, embedded resources *or* a zip archive (on disk or embedded), a published Blazor WebAssembly app, streaming multipart uploads with a request body limit per endpoint (a large-upload route stays open while the rest of the server keeps a small default), downloads with byte ranges and conditional GETs, a file browser over a directory, and brotli/gzip/deflate compression in both directions, and RFC 9530 Content-Digest/Repr-Digest verified on uploads as they stream and sent on responses as a header or a trailer |
| **Security** | Authentication and authorization split ASP.NET-style, with Basic, API key, cookie and JWT schemes; policies, roles and claims; CORS, rate limiting and IP filtering, all with per-endpoint policies; host filtering against DNS rebinding; webhook receivers that verify GitHub, Stripe, Slack, Standard Webhooks and generic HMAC signatures over the raw body, with replay protection, duplicate suppression and key rotation, plus a signer for outgoing webhooks; signed double-submit antiforgery, the browser security headers, HSTS and an HTTPS redirect |
| **TLS** | Several endpoints with per-endpoint TLS, self-signed certificates generated in managed code (iOS and Android included), client certificates, and SPKI pinning for the app's own `HttpClient`; the PROXY protocol (v1 and v2) per endpoint, so the real client behind a TCP load balancer reaches the IP filter, rate limiter and logs; and publicly trusted certificates issued and renewed automatically over ACME (Let's Encrypt, ZeroSSL) and hot-swapped with no restart |
| **OpenAPI** | An OpenAPI 3.0.3 document built entirely from compile-time metadata and your `JsonSerializerContext` โ no reflection, no document object model โ one document per API version, and a Scalar API reference page that the browser loads from the CDN, so the app ships no UI |
| **Tunnelling** | A pluggable `ITunnelProvider`, the reference relay (both ends), SSH remote forwarding, zero-account quick tunnels, and Azure Relay |
| **Proxy** | A reverse proxy that goes further than a forwarded route: destination clusters with five load-balancing policies, active probes and passive failure tracking that take a bad instance out of rotation, cookie or header session affinity, a composable transform pipeline for paths, queries and headers in both directions, WebSocket and HTTP upgrade forwarding, response trailers relayed on every protocol version so gRPC works through it, upstream latency and error metrics, and routes read from `IConfiguration` and reloaded onto the running server without dropping the routes that did not change |
| **Switchboard** | Real-time calls both ways, SignalR-style, without WebSockets: one event stream down and plain POSTs up, so it crosses proxies and tunnels and every call goes through the normal auth and middleware. Groups, users, an operator, `Task<T>` client results the server waits on, hang-ups that invalidate the line, calls run in the order they were made, streamed results, and lines held for a resume window so a phone that drops keeps its groups and gets what it missed. Typed on both ends, with the contract exportable as one file; dispatch and proxies generated at compile time |
| **Mediator** | Shiny.Mediator handlers published as endpoints โ requests as JSON, commands as a status code, stream requests as Server-Sent Events, all bound at compile time |
| **DocumentDb** | A document type as a complete HTTP resource, with filtering, cursor paging, sparse fieldsets, ETag/If-Match, RFC 7396 merge patch or RFC 6902 JSON Patch, a live SSE tail, and server-side scopes enforced on both sides of a write |
| **gRPC** | Unary, client-streaming, server-streaming and bidirectional methods, deadlines, per-message compression and status in trailers โ plus gRPC-Web for browsers and anything on HTTP/1.1. Marshalling is yours, so nothing reflects over your messages |
| **WebDAV** | RFC 4918 classes 1 and 2 over a directory โ or over anything an `IWebDavFileSystem` describes โ `PROPFIND`, `PROPPATCH`, `MKCOL`, `COPY`, `MOVE`, `LOCK`/`UNLOCK`, the `If` header and dead properties โ so an app's storage mounts as a drive with no client to write |
| **CalDAV & CardDAV** | Calendars and contacts over RFC 4791 / 6352: `/.well-known` discovery, principals per signed-in user, `MKCALENDAR`, validated `PUT` with `no-uid-conflict` and ETag preconditions, `calendar-query` / `addressbook-query` / multiget / free-busy / `sync-collection` โ so the phone's own Calendar and Contacts apps sync with your app |
| **Resumable uploads** | tus 1.0.0 core plus creation, creation-with-upload, defer-length, termination, expiration, checksum and concatenation โ streamed to a pluggable store, bytes from an interrupted request kept, offsets durable across restarts |
| **NuGet feed** | The NuGet V3 server API โ service index, package content, registrations, search and autocomplete โ plus push, delete-as-unlist and relist behind API keys, so a team's packages need a route, not another service |
| **npm registry** | The npm registry API (publish with integrity checks, install with abbreviated metadata and ETag revalidation, dist-tags, deprecate, unpublish, owners, search, login) with bearer tokens, maintainer rules and an optional upstream, so a team's JavaScript packages need a route, not Verdaccio |
| **File sync** | Two-way folder sync, Dropbox-style: FastCDC content-defined chunking and a content-addressed store, so only changed bytes cross the network in either direction. Includes a change feed with long-poll, conflicted copies, background and resumable transfers through Shiny.Net.Http, and a client that can be interrupted at any point and picks up where it stopped |
| **Lifecycle** | Start, stop and restart at runtime, serialized and idempotent, with an observable state โ an embedded server gets toggled, not just booted. It also follows the device: rebinding when the addresses change, and following the app between foreground and background |
| **Resilience** | Every state change says *why* it happened and carries the exception behind it, and a server that stops serving never does it quietly. A listener that dies underneath a running server is logged, reported and rebound; a transient accept failure is retried with backoff; a restart or a rebind whose bind is refused keeps trying and, if it never succeeds, says so unmistakably rather than leaving a server that claims to be running with nothing behind it. On by default โ an app that has to opt in to not-silently-dying will not have opted in |
| **Sign-in** | The loopback half of an OAuth / OpenID Connect sign-in from a desktop app or CLI. It opens the system browser, receives the redirect on an ephemeral `127.0.0.1` port and checks `state`. The code is handed to whichever OAuth client you already use, and the user is told to return to the app |
| **Discovery** | The other half of hosting on a phone. mDNS advertises the server as the device moves and withdraws it when the server stops โ telling a restart apart from a stop, so peers are not made to re-resolve a service that never went away โ and a publication the responder refuses is retried rather than leaving an app that runs perfectly and is found by nobody; the locator turns what is on the link into a base address a client can call |
| **Testing** | An in-memory transport, so an endpoint test costs no port and leaks no listener while still going through the real parser, router, middleware and framing |
Everything shipping targets `net10.0` with the trim, AOT and single-file analyzers enabled, so
"AOT-clean" is enforced by the build rather than claimed in a readme.
## Documentation
Full docs are at [shinylib.net/httpserver](https://shinylib.net/httpserver).
## Support
Shiny is free and will continue to be, but maintenance and support take a heavy toll on
sustainability. If you or your company have the resources, please consider
[becoming a GitHub Sponsor](https://sponsor.shinylib.net).