Falco

open Falco
open Falco.Routing
open Falco.HostBuilder

webHost [||] {
    endpoints [                    
        get "/" (Response.ofPlainText "Hello World")
    ]
}

Falco is a toolkit for building fast, functional-first and fault-tolerant web applications using F#.

Built upon the high-performance primitives of ASP.NET Core.
Optimized for building HTTP applications quickly.
Seamlessly integrates with existing .NET Core middleware and frameworks.

Key Features

Asynchronous request handling.
Simple and powerful routing API.
Fast, secure and configurable web server.
Native F# view engine.
Succinct API for model binding.
Authentication and security utilities.
Built-in support for large uploads.

Design Goals

Aim to be very small and easily learnable.
Should be extensible.
Should provide a toolset to build a working end-to-end web application.

Getting Started
Sample Applications
Request Handling
Routing
Host Builder
Model Binding
JSON
Markup
Authentication
Security
Handling Large Uploads
Why "Falco"?
Find a bug?
License

Getting Started

Using `dotnet new`

The easiest way to get started with Falco is by installing the Falco.Template package, which adds a new template to your dotnet new command line tool:

dotnet new -i "Falco.Template::*"

Afterwards you can create a new Falco application by running:

dotnet new falco -o HelloWorldApp

Manually installing

Create a new F# web project:

dotnet new web -lang F# -o HelloWorldApp

Install the nuget package:

dotnet add package Falco

Remove the Startup.fs file and save the following in Program.fs (if following the manual install path):

module HelloWorld.Program

open Falco
open Falco.Routing
open Falco.HostBuilder

let helloHandler : HttpHandler =
    "Hello world"
    |> Response.ofPlainText

[<EntryPoint>]
let main args =
    webHost args {
        endpoints [ get "/" helloHandler ]
    }
    0

Run the application:

dotnet run

There you have it, an industrial-strength Hello World web app, achieved using only base ASP.NET Core libraries. Pretty sweet!

Sample Applications

Code is always worth a thousand words, so for the most up-to-date usage, the /samples directory contains a few sample applications.

Sample	Description
Hello World	A basic hello world app
Configure Host	Demonstrating how to configure the `IHost` instance using then `webHost` computation expression
Blog	A basic markdown (with YAML frontmatter) blog
Todo MVC	A basic Todo app, following MVC style (work in progress)

Request Handling

The HttpHandler type is used to represent the processing of a request. It can be thought of as the eventual (i.e. asynchronous) completion of and HTTP request processing, defined in F# as: HttpContext -> Task. Handlers will typically involve some combination of: route inspection, form/query binding, business logic and finally response writing. With access to the HttpContext you are able to inspect all components of the request, and manipulate the response in any way you choose.

Basic request/resposne handling is divided between the aptly named Request and Response modules, which offer a suite of continuation-passing style (CPS) HttpHandler functions for common scenarios.

Plain Text responses

let textHandler : HttpHandler =
    Response.ofPlainText "hello world"

HTML responses

let htmlHandler : HttpHandler =
    let doc =
        Elem.html [ Attr.lang "en" ] [
            Elem.head [] [
                Elem.title [] [ Text.raw "Sample App" ]
            ]
            Elem.body [] [
                Elem.main [] [
                    Elem.h1 [] [ Text.raw "Sample App" ]
                ]
            ]
        ]

    doc
    |> Response.ofHtml

Alternatively, if you're using an external view engine and want to return an HTML response from a string literal you can use Response.ofHtmlString.

let htmlHandler : HttpHandler = 
    let html = "<html>...</html>"

    html
    |> Response.ofHtmlString

JSON responses

IMPORTANT: This handler uses the default System.Text.Json.JsonSerializer. See JSON section below for further information.

type Person =
    {
        First : string
        Last  : string
    }

let jsonHandler : HttpHandler =
    { First = "John"; Last = "Doe" }
    |> Response.ofJson

Set the status code of the response

let notFoundHandler : HttpHandler =
    Response.withStatusCode 404
    >> Response.ofPlainText "Not found"

Redirect (301/302) Response (boolean param to indicate permanency)

let oldUrlHandler : HttpHandler =
    Response.redirect "/new-url" true

Accessing route parameters

let helloHandler : HttpHandler =
    let getMessage (route : RouteCollectionReader) =
        route.GetString "name" "World" 
        |> sprintf "Hello %s"
        
    Request.mapRoute getMessage Response.ofPlainText

Accessing query parameters

let helloHandler : HttpHandler =
    let getMessage (query : QueryCollectionReader) =
        query.GetString "name" "World" 
        |> sprintf "Hello %s"
        
    Request.mapQuery getMessage Response.ofPlainText

Routing

The breakdown of Endpoint Routing is simple. Associate a a specific route pattern (and optionally an HTTP verb) to an HttpHandler which represents the ongoing processing (and eventual return) of a request.

Bearing this in mind, routing can practically be represented by a list of these "mappings" known in Falco as an HttpEndpoint which bind together: a route, verb and handler.

let helloHandler : HttpHandler =
    let getMessage (route : RouteCollectionReader) =
        route.GetString "name" "World" 
        |> sprintf "Hello %s"
        
    Request.mapRoute getMessage Response.ofPlainText

let loginHandler : HttpHandler = // ...

let loginSubmitHandler : HttpHandler = // ...  

let endpoints : HttpEndpoint list =
  [
    // a basic GET handler
    get "/hello/{name:alpha}" helloHandler

    // multi-method endpoint
    all "/login"
        [
            POST, loginSubmitHandler
            GET,  loginHandler
        ]
  ]

Host Builder

Kestrel is the web server at the heart of ASP.NET. It's a performant, secure and maintained by incredibly smart people. Getting it up and running is usually done using Host.CreateDefaultBuilder(args), but it can grow verbose quickly. To make things a little cleaner, Falco exposes an optional computation expression. Below is an example using the builder, taken from the Configure Host sample.

module ConfigureHost.Program

open Falco
open Falco.Markup
open Falco.Routing
open Falco.HostBuilder
open Microsoft.AspNetCore.Builder
open Microsoft.AspNetCore.Hosting
open Microsoft.Extensions.DependencyInjection
open Microsoft.Extensions.Logging

// ... rest of startup code

let configureHost (endpoints : HttpEndpoint list) (webhost : IWebHostBuilder) =
    // definitions omitted for brevity
    webhost.ConfigureLogging(configureLogging)
           .ConfigureServices(configureServices)
           .Configure(configureApp endpoints)

[<EntryPoint>]
let main args =
    webHost args {
        configure configureHost
        endpoints [
                      get "/" ("hello world" |> Response.ofPlainText)
                  ]
    }
    0

Model Binding

Binding at IO boundaries is messy, error-prone and often verbose. Reflection-based abstractions tend to work well for simple use cases, but quickly become very complicated as the expected complexity of the input rises. This is especially true for an algebraic type system like F#'s. As such, it is often advisable to take back control of this process from the runtime. An added bonus of doing this is that it all but eliminates the need for [<CLIMutable>] attributes.

We can make this simpler by creating a succinct API to obtain typed values from IFormCollection, IQueryCollection, RouteValueDictionary and IHeaderCollection. Readers for all four exist as derivatives of StringCollectionReader which is an abstraction intended to make it easier to work with the string-based key/value collections.

Route Binding

Route binding will normally achieved through Request.mapRoute or Request.bindRoute if you are concerned with handling bind failures explicitly. Both are continuation-style handlers, which expose an opportunity to project the values from RouteCollectionReader, which also has full access to the query string via QueryCollectionReader.

let mapRouteHandler : HttpHandler =
    let routeMap (route : RouteCollectionReader) = route.GetString "Name" "John Doe"
    
    Request.mapRoute
        routeMap
        Response.ofJson

let bindRouteHandler : HttpHandler = 
    let routeBind (route : RouteCollectionReader) =
        match route.TryGetString "Name" with
        | Some name -> Ok name
        | _         -> Error {| Message = "Invalid route" |}
    
    Request.bindRoute
        routeBind
        Response.ofJson // handle Ok
        Response.ofJson // handle Error

let manualRouteHandler : HttpHandler =
    fun ctx ->
        let route = Request.getRoute ctx
        let name = route.GetString "Name" "John Doe"
        
        // You also have access to the query string
        let q = route.Query.GetString "q" "{default value}"
        Response.ofJson name ctx

Query Binding

Query binding will normally achieved through Request.mapQuery or Request.bindQuery if you are concerned with handling bind failures explicitly. Both are continuation-style handlers, which expose an opportunity to project the values from QueryCollectionReader.

type Person = { FirstName : string; LastName : string }

let mapQueryHandler : HttpHandler =    
    Request.mapQuery
        (fun rd -> { 
            FirstName = rd.GetString "FirstName" "John" // Get value or return default value
            LastName = rd.GetString "LastName" "Doe" 
        })
        Response.ofJson 

let bindQueryHandler : HttpHandler = 
    Request.bindQuery 
        (fun rd -> 
            match rd.TryGetString "FirstName", rd.TryGetString "LastName" with
            | Some f, Some l -> Ok { FirstName = f; LastName = l }
            | _  -> Error {| Message = "Invalid query string" |})
        Response.ofJson // handle Ok
        Response.ofJson // handle Error

let manualQueryHandler : HttpHandler =
    fun ctx ->
        let query = Request.getQuery ctx
        
        let person = 
            { 
                FirstName = query.GetString "FirstName" "John" // Get value or return default value
                LastName = query.GetString "LastName" "Doe" 
            }

        Response.ofJson person ctx

Form Binding

Form binding will normally achieved through Request.mapForm or Request.bindForm if you are concerned with handling bind failures explicitly. Both are continuation-style handlers, which expose an opportunity to project the values from FormCollectionReader, which also has full access to the IFormFilesCollection via the _.Files member.

Note the addition of Request.mapFormSecure and Request.bindFormSecure which will automatically validate CSRF tokens for you.

type Person = { FirstName : string; LastName : string }

let mapFormHandler : HttpHandler =    
    Request.mapForm
        (fun rd -> { 
            FirstName = rd.GetString "FirstName" "John" // Get value or return default value
            LastName = rd.GetString "LastName" "Doe" 
        })
        Response.ofJson 

let mapFormSecureHandler : HttpHandler =    
    Request.mapFormSecure
        (fun rd -> { 
            FirstName = rd.GetString "FirstName" "John" // Get value or return default value
            LastName = rd.GetString "LastName" "Doe" 
        })
        Response.ofJson 
        (Response.withStatusCode 400 >> Response.ofEmpty)

let bindFormHandler : HttpHandler = 
    Request.bindForm 
        (fun rd -> 
            match rd.TryGetString "FirstName", rd.TryGetString "LastName" with
            | Some f, Some l -> Ok { FirstName = f; LastName = l }
            | _  -> Error {| Message = "Invalid form data" |})
        Response.ofJson // handle Ok
        Response.ofJson // handle Error

let bindFormSecureHandler : HttpHandler = 
    Request.bindFormSecure
        (fun rd -> 
            match rd.TryGetString "FirstName", rd.TryGetString "LastName" with
            | Some f, Some l -> Ok { FirstName = f; LastName = l }
            | _  -> Error {| Message = "Invalid form data" |})
        Response.ofJson // handle Ok
        Response.ofJson // handle Error
        (Response.withStatusCode 400 >> Response.ofEmpty)

let manualFormHandler : HttpHandler =
    fun ctx -> task {
        let! query = Request.getForm ctx
        
        let person = 
            { 
                FirstName = query.GetString "FirstName" "John" // Get value or return default value
                LastName = query.GetString "LastName" "Doe" 
            }

        return! Response.ofJson person ctx
    }

JSON

Included in Falco are basic JSON in/out handlers, Request.bindJson and Response.ofJson respectively. Both rely on System.Text.Json, thus without support for F#'s algebraic types.

type Person =
    {
        First : string
        Last  : string
    }

let jsonHandler : HttpHandler =
    { First = "John"; Last = "Doe" }
    |> Response.ofJson

let jsonBindHandler : HttpHandler =    
    Request.bindJson
        (fun person -> Response.ofPlainText (sprintf "hello %s %s" person.First person.Last))
        (fun error -> Response.withStatusCode 400 >> Response.ofPlainText (sprintf "Invalid JSON: %s" error))

Markup

A core feature of Falco is the XML markup module. It can be used to produce any form of angle-bracket markup (i.e. HTML, SVG, XML etc.).

For example, the module is easily extended since creating new tags is simple. An example to render <svg>'s:

let svg (width : float) (height : float) =
    Elem.tag "svg" [
        Attr.create "version" "1.0"
        Attr.create "xmlns" "http://www.w3.org/2000/svg"
        Attr.create "viewBox" (sprintf "0 0 %f %f" width height)
    ]

let path d = Elem.tag "path" [ Attr.create "d" d ] []

let bars =
    svg 384.0 384.0 [
            path "M368 154.668H16c-8.832 0-16-7.168-16-16s7.168-16 16-16h352c8.832 0 16 7.168 16 16s-7.168 16-16 16zm0 0M368 32H16C7.168 32 0 24.832 0 16S7.168 0 16 0h352c8.832 0 16 7.168 16 16s-7.168 16-16 16zm0 0M368 277.332H16c-8.832 0-16-7.168-16-16s7.168-16 16-16h352c8.832 0 16 7.168 16 16s-7.168 16-16 16zm0 0"
        ]

HTML View Engine

Most of the standard HTML tags & attributes have been built into the markup module, which produce objects to represent the HTML node. Nodes are either:

Text which represents string values. (Ex: Text.raw "hello", Text.rawf "hello %s" "world")
SelfClosingNode which represent self-closing tags (Ex: <br />).
ParentNode which represent typical tags with, optionally, other tags within it (Ex: <div>...</div>).

The benefits of using the Falco markup module as an HTML engine include:

Writing your views in plain F#, directly in your assembly.
Markup is compiled alongside the rest of your code, leading to improved performance and ultimately simpler deployments.

// Create an HTML5 document using built-in template
let doc = 
    Templates.html5 "en"
        [ Elem.title [] [ Text.raw "Sample App" ] ] // <head></head>
        [ Elem.h1 [] [ Text.raw "Sample App" ] ]    // <body></body>

Since views are plain F# they can easily be made strongly-typed:

type Person =
    {
        First : string
        Last  : string
    }

let doc (person : Person) = 
    Elem.html [ Attr.lang "en" ] [
            Elem.head [] [                    
                    Elem.title [] [ Text.raw "Sample App" ]                                                            
                ]
            Elem.body [] [                     
                    Elem.main [] [
                            Elem.h1 [] [ Text.raw "Sample App" ]
                            Elem.p  [] [ Text.rawf "%s %s" person.First person.Last ]
                        ]
                ]
        ]

Views can also be combined to create more complex views and share output:

let master (title : string) (content : XmlNode list) =
    Elem.html [ Attr.lang "en" ] [
            Elem.head [] [                    
                    Elem.title [] [ Text.raw "Sample App" ]                                                            
                ]
            Elem.body [] content
        ]

let divider = 
    Elem.hr [ Attr.class' "divider" ]

let homeView =
    [
        Elem.h1 [] [ Text.raw "Homepage" ]
        divider
        Elem.p  [] [ Text.raw "Lorem ipsum dolor sit amet, consectetur adipiscing."]
    ]
    |> master "Homepage" 

let aboutView =
    [
        Elem.h1 [] [ Text.raw "About" ]
        divider
        Elem.p  [] [ Text.raw "Lorem ipsum dolor sit amet, consectetur adipiscing."]
    ]
    |> master "About Us"

Authentication

ASP.NET Core has amazing built-in support for authentication. Review the docs for specific implementation details. Falco optionally (open Falco.Auth) includes some authentication utilites.

To use the authentication helpers, ensure the service has been registered (AddAuthentication()) with the IServiceCollection and activated (UseAuthentication()) using the IApplicationBuilder.

Prevent user from accessing secure endpoint:

open Falco.Security

let secureResourceHandler : HttpHandler =
    let handleAuth : HttpHandler = 
        "hello authenticated user"
        |> Response.ofPlainText 

    let handleInvalid : HttpHandler =
        Response.withStatusCode 403 
        >> Response.ofPlainText "Forbidden"

    Request.ifAuthenticated handleAuth handleInvalid

Prevent authenticated user from accessing anonymous-only end-point:

open Falco.Security
 
let anonResourceOnlyHandler : HttpHandler =
    let handleAnon : HttpHandler = 
        Response.ofPlainText "hello anonymous"

    let handleInvalid : HttpHandler = 
        Response.withStatusCode 403 
        >> Response.ofPlainText "Forbidden"

    Request.ifNotAuthenticated handleAnon handleInvalid

Allow only user's from a certain group to access endpoint"

open Falco.Security

let secureResourceHandler : HttpHandler =
    let handleAuthInRole : HttpHandler = 
        Response.ofPlainText "hello admin"

    let handleInvalid : HttpHandler = 
        Response.withStatusCode 403 
        >> Response.ofPlainText "Forbidden"

    let rolesAllowed = [ "Admin" ]

    Request.ifAuthenticatedInRole rolesAllowed handleAuthInRole handleInvalid

End user session (sign out):

open Falco.Security

let logOut : HttpHandler =         
    let authScheme = "..."
    let redirectTo = "/login"

    Response.signOutAndRedirect authScheme redirectTo

Security

Cross-site scripting attacks are extremely common, since they are quite simple to carry out. Fortunately, protecting against them is as easy as performing them.

The Microsoft.AspNetCore.Antiforgery package provides the required utilities to easily protect yourself against such attacks.

Falco provides a few handlers via Falco.Security.Xss:

To use the Xss helpers, ensure the service has been registered (AddAntiforgery()) with the IServiceCollection and activated (UseAntiforgery()) using the IApplicationBuilder.

open Falco.Security 

let formView (token : AntiforgeryTokenSet) =     
    Elem.html [] [
        Elem.body [] [
            Elem.form [ Attr.method "post" ] [
                Elem.input [ Attr.name "first_name" ]

                Elem.input [ Attr.name "last_name" ]

                // using the CSRF HTML helper
                Xss.antiforgeryInput token

                Elem.input [ Attr.type' "submit"; Attr.value "Submit" ]
            ]                                
        ]
    ]
    
// A handler that demonstrates obtaining a
// CSRF token and applying it to a view
let csrfViewHandler : HttpHandler = 
    formView
    |> Response.ofHtmlCsrf
    
// A handler that demonstrates validating
// the requests CSRF token
let mapFormSecureHandler : HttpHandler =    
    let mapPerson (form : FormCollectionReader) =
        { FirstName = form.GetString "first_name" "John" // Get value or return default value
          LastName = form.GetString "first_name" "Doe" }

    let handleInvalid : HttpHandler = 
        Response.withStatusCode 400 
        >> Response.ofEmpty

    Request.mapFormSecure mapPerson Response.ofJson handleInvalid

Crytography

Many sites have the requirement of a secure log in and sign up (i.e. registering and maintaining a user's database). Thus, generating strong hashes and random salts is of critical importance.

Falco helpers are accessed by importing Falco.Auth.Crypto.

open Falco.Security

// Generating salt,
// using System.Security.Cryptography.RandomNumberGenerator,
// create a random 16 byte salt and base 64 encode
let salt = Crypto.createSalt 16 

// Generate random int for iterations
let iterations = Crypto.randomInt 10000 50000

// Pbkdf2 Key derivation using HMAC algorithm with SHA256 hashing function
let password = "5upe45ecure"
let hashedPassword = password |> Crypto.sha256 iterations 32 salt

Handling Large Uploads

Microsoft defines large uploads as anything > 64KB, which well... is most uploads. Anything beyond this size, and they recommend streaming the multipart data to avoid excess memory consumption.

To make this process a lot easier Falco exposes an HttpContext extension method TryStreamFormAsync() that will attempt to stream multipart form data, or return an error message indicating the likely problem.

let imageUploadHandler : HttpHandler =
    fun ctx -> task {
        let! form = Request.tryStreamFormAsync()
            
        // Rest of code using `FormCollectionReader`
        // ...
    }

Why "Falco"?

Kestrel has been a game changer for the .NET web stack. In the animal kingdom, "Kestrel" is a name given to several members of the falcon genus. Also known as "Falco".

Find a bug?

There's an issue for that.

License

Built with ♥ by Pim Brouwers in Toronto, ON. Licensed under Apache License 2.0.

ericsampson / Falco

Falco

Key Features

Design Goals

Table of Contents

Getting Started

Using `dotnet new`

Manually installing

Sample Applications

Request Handling

Plain Text responses

HTML responses

JSON responses

Set the status code of the response

Redirect (301/302) Response (boolean param to indicate permanency)

Accessing route parameters

Accessing query parameters

Routing

Host Builder

Model Binding

Route Binding

Query Binding

Form Binding

JSON

Markup

HTML View Engine

Authentication

Security

Crytography

Handling Large Uploads

Why "Falco"?

Find a bug?

License

About

Languages

Falco

Key Features

Design Goals

Table of Contents

Getting Started

Using dotnet new

Manually installing

Sample Applications

Request Handling

Plain Text responses

HTML responses

JSON responses

Set the status code of the response

Redirect (301/302) Response (boolean param to indicate permanency)

Accessing route parameters

Accessing query parameters

Routing

Host Builder

Model Binding

Route Binding

Query Binding

Form Binding

JSON

Markup

HTML View Engine

Authentication

Security

Crytography

Handling Large Uploads

Why "Falco"?

Find a bug?

License

About

Languages

Using `dotnet new`