Developer Guide

Library overview

The internals of the library are laid out as such:

A. Http Backend

The Http Backend

1. Consumes network input from the remote client
2. Converts it to the normalized HttpRequest (source) form
3. Hands the request to the Router (source) to get a future Task<HttpResponse> outcome (source)
4. Awaits on the future and writes the response back to the client

B. Router

The Router

1. Takes in a HttpRequest from the backend
2. Enumerates the RouteTable, performs URL matching (and path-variables extraction) on the request to resolve its associated Endpoint
3. Hands the (converted) Request (source) off to the resolved Endpoint handler for execution
4. Returns a future Task<HttpResponse> of the handler outcome to the backend

C. RouteTable

The RouteTable (source) bridges the library into the client application code space. It composes a collection of Endpoints which define what client code methods to invoke for handling requests.

Endpoints

An Endpoint associates a URI path pattern (represented by the Route class (source)) to its Handler. Examples of path patterns include

• /accounts
• /accounts/{id}/history
• /files/*

A handler takes a Request and returns a Task<HttpResponse>, ie. a handler is a function conforming to the Func<Request, Task<HttpResponse>> type signature. The Endpoint class (source) is implemented as such

    public class Endpoint
    {
        public readonly Method Method;
        public readonly Route Route;
        public readonly Func<Request, Task<HttpResponse>> Handler;

        public Endpoint(Method method, Route route, Func<Request, Task<HttpResponse>> handler)
        {
            Method = method;
            Route = route;
            Handler = handler;
        }
    }

D. Handlers & Application code

The library restricts handlers to the normalized form of Func<Request, Task<HttpResponse>>; the application code will thus be required to implement its (endpoint) methods signature to match before they may be accepted by the Endpoint class for construction and insertion into the RouteTable.

This restriction can be somewhat ameliorated with function lifting. The Handlers namespace provides helper methods to lift possibly commonly desired application method shapes to the required form.