Samples on GenHTTP Webserver

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

A notes API where every user sees their own notes, and administrators see the notes of everyone. Clients send an API key in the X-API-Key header, and AuthenticateAsync turns the key into a user - or rejects it. This is where you would look the key up in your database.

The user injector passes the user to the service methods as a parameter, and [RequireRole("ADMIN")] restricts a method to administrators. Basic, bearer (JWT) and client certificate authentication work the same way. Try it with the keys alice-key (a user) and bob-key (an administrator).

Dependency Injection

Mon, 01 Jan 0001 00:00:00 +0000

Lets the framework construct the book service and pass it what it depends on - a repository and the clock - so the service does not need to know how they are made, and tests can pass fakes instead. The services are registered with Microsoft’s dependency injection, and AddDependencyInjection makes them available to the server.

AddDependentService creates BookService with the repository passed to its constructor, and Add receives the TimeProvider as a parameter of the method.

File Share

Mon, 01 Jan 0001 00:00:00 +0000

Shares a folder with friends: they log in with their browser, browse through the files and download them. Listing renders a page for every folder, and basic authentication asks for a user name and a password - here friend and secret.

Range support lets browsers and download managers pause and resume the download of a large file. Put the files to share into a files folder next to the program.

Layouting

Mon, 01 Jan 0001 00:00:00 +0000

Most applications are made of several parts, such as an API, static files and a website. A layout routes every request to the part it belongs to by its path: here, /assets/ serves files and /api/ a small API.

Layouts can be nested to build deeper structures, and what you add to a layout - such as authentication or CORS - applies to everything below it. Put some files into a files folder next to the program to have something to serve.

Webservices

Mon, 01 Jan 0001 00:00:00 +0000

A small API for a book shelf: clients list the books, add one and delete one. The API is a plain C# class whose methods are marked with [ResourceMethod] - the attribute sets the HTTP method and path, and GenHTTP reads the parameters from the request and writes the return value as the response.

AddService<BookService>("books") serves the class below /books/. Books are read and written as JSON, or in another format such as XML if the client asks for it. Throwing a ProviderException ends a request with the given status, here 409 when the shelf is full.

CORS

Mon, 01 Jan 0001 00:00:00 +0000

Lets a frontend on another origin - here a React app on the Vite dev server, at http://localhost:5173 - call the API from the browser. Browsers block such requests unless the server allows them with CORS headers, and ask with a preflight request (OPTIONS) before they send anything but simple requests.

CorsPolicy.Restrictive() allows the origins you add, with the methods you name, and answers the preflight requests for you. Requests from any other origin get no CORS headers, so the browser blocks them.

Functional

Mon, 01 Jan 0001 00:00:00 +0000

The book shelf API of the webservice sample, written as delegates instead of a class - similar to the Minimal APIs of ASP.NET Core. Inline.Create() takes one delegate per HTTP method (and path, such as :id for the id of a book); GenHTTP reads their parameters from the request and writes their result as the response.

This keeps small APIs short. The books live in a local list here, which the delegates share.

Legacy Migration

Mon, 01 Jan 0001 00:00:00 +0000

Replaces an old web application step by step instead of all at once. GenHTTP runs in front of the legacy application: new endpoints and pages are served by GenHTTP, moved pages are redirected, and everything else is passed on to the legacy application by a reverse proxy.

The layout tries its own routes first, so /api/v2/ and /contact are new, /contact.php redirects permanently (search engines learn the new address), and any other path - such as /login.php - still reaches the legacy application on port 5000. Move one route at a time until the proxy can go.

Static Files

Mon, 01 Jan 0001 00:00:00 +0000

Serves the files of a folder, for example downloads or the assets of an application. GenHTTP sends each file with the content type of its extension, and Defaults() adds compression and lets browsers cache the files.

Put your files into a files folder next to the program, so /README.md serves files/README.md. Assets.From("./files") is a shorter way to serve a folder from disk.

API Documentation

Mon, 01 Jan 0001 00:00:00 +0000

Documents the book shelf API with an Open API definition and three viewers to explore and try it: Swagger UI, Redoc and Scalar. AddOpenApi() generates the definition from the service itself - its paths, parameters and the shape of a book - so it is always up to date.

The viewers are served by GenHTTP and need no internet connection. Functional handlers and controllers are documented the same way.

Controllers

Mon, 01 Jan 0001 00:00:00 +0000

The book shelf API once more, in the style of MVC controllers: every public method of BookController is an action, and its name is its path - Index() answers /books/, Create() answers /books/create/ and Delete() answers /books/delete/1/.

[ControllerAction] sets the HTTP method of an action, and [FromPath] takes a parameter from the path instead of the query. Controllers suit APIs with many actions, where a naming convention saves declaring every route.

Error Handling

Mon, 01 Jan 0001 00:00:00 +0000

A shop with a website for people and an API for programs, each reporting errors in its own way: the API answers with JSON (or the format the client asks for), the website with HTML error pages, such as the 404 for an address that does not exist.

The business logic throws an OutOfStockException without knowing about HTTP, and OutOfStockMapper turns it into a 409 response. A ProviderException brings its status with it, as for an order that does not exist.

Localization

Mon, 01 Jan 0001 00:00:00 +0000

Greets visitors in their language and writes the date the way they are used to. The language is taken from the lang query parameter, or else from the Accept-Language header that browsers send; English is the fallback.

The localization concern sets the culture for every request, so the code simply uses CultureInfo.CurrentCulture. Supports decides which languages the application offers - here the ones it has a greeting for, regional variants such as de-CH included.

Server Sent Events

Mon, 01 Jan 0001 00:00:00 +0000

A stock ticker whose price changes every second, pushed by the server to the browser. Server sent events keep a response open and write an event to it whenever there is news - simpler than websockets when data only flows from the server to the client.

EventSource.Create() runs SendQuotesAsync for every client, as long as it stays connected. In the browser, new EventSource('quotes/') receives the events, and reconnects on its own if the connection drops. The prices are made up.

Websockets

Mon, 01 Jan 0001 00:00:00 +0000

A chat in the browser: every message is pushed to everyone in the same room, instantly and without polling. The page connects to /chat via a websocket, and ChatHandler forwards every message it receives to the connections in the room of the sender.

The reactive websocket API calls OnConnected, OnMessage and OnClose for you, and reads and writes JSON with ReadPayloadAsync and WritePayloadAsync. Open the page in two windows with the same room to chat with yourself.

Inspection

Mon, 01 Jan 0001 00:00:00 +0000

Shows what the server received and what it answered, to find out why a client gets a certain response. Add ?inspect to an address below the layout, and instead of the response you get the request as GenHTTP read it - method, path, query and headers - together with the response it would have sent.

Add the inspector while developing only, as it reveals details of your server.

MCP Tools

Mon, 01 Jan 0001 00:00:00 +0000

A library that AI agents such as Claude can use: it offers tools to find books and to lend them to readers, via the Model Context Protocol (MCP). Every method of LibraryTools marked with [Tool] is a tool. Its name, its parameters and the [Summary] texts tell the agent what the tool does and how to call it, and [Range] limits what it may pass.

Add the server to your agent (see the commands below) and ask it, for example, which books about Rome the library has: the agent finds them with find_books, and may lend one with lend_book.

Pages

Mon, 01 Jan 0001 00:00:00 +0000

Renders HTML pages on the server, for example for an internal tool that does not need a frontend framework. The list of books is rendered from a Cottle template with the books as its model; the about page uses the look of the pages GenHTTP renders itself, such as its error pages.

Templates do not escape HTML for you, so the titles pass Escaped() first. In an application, the template would rather be a file or an embedded resource than a string.

Static Websites

Mon, 01 Jan 0001 00:00:00 +0000

Serves a website made of HTML, CSS and image files, such as the output of a static site generator. A request for a folder is answered with its index.html, so /about/ serves about/index.html.

Put your files into a website folder next to the program. ResourceTree.FromDirectory reads them from there; files embedded into your assembly (ResourceTree.FromAssembly) work the same way.

Virtual Hosting

Mon, 01 Jan 0001 00:00:00 +0000

Hosts a blog and a shop on one server, each on a domain of its own. VirtualHosts picks the website by the domain the request was sent to (its Host header), and sends the visitors of any other domain to the blog.

Browsers resolve every name ending in .localhost to your own machine, so you can try it without setting up any domain: open http://blog.localhost:8080/ and http://shop.localhost:8080/.

Load Balancing

Mon, 01 Jan 0001 00:00:00 +0000

Spreads the requests to an API over three workers and sends downloads to one of two mirror servers. Proxy forwards a request to a worker and passes its response on; Redirect sends the client to a mirror, so downloads do not pass through this server.

A priority decides where a request may go: requests with an X-Canary header prefer the third worker, which can run a new version you want to test with some real traffic first. Everything else goes to the other two workers, which share the load.

Single Page Applications

Mon, 01 Jan 0001 00:00:00 +0000

Hosts a single page application, such as the build output of a React, Angular or Vue app. With ServerSideRouting(), every path that is no file is answered with the index.html of the application, so it can render routes such as /books/42 in the browser - even when they are opened directly or reloaded.

Put the build output of your application into a spa folder next to the program.

Custom Frameworks

Mon, 01 Jan 0001 00:00:00 +0000

Shows the layer that webservices, controllers and functional handlers are built on, to write a framework of your own - for example one that offers scripts or database queries as endpoints. The handler describes an operation - a path, its HTTP methods and the C# method to call - and GenHTTP reads the arguments, calls the method and writes the result.

As the operation is one like any other, the Open API definition and Scalar describe it as well. The reflection layer counts as internal, so it may change in a minor version.