flow

README

A delightfully tiny but powerful HTTP router for Go web applications

---

Flow packs in a bunch of features that you'll probably like:

• Use named parameters, wildcards and (optionally) regexp patterns in your routes.
• Create route groups which use different middleware (a bit like chi).
• Customizable handlers for 404 Not Found and 405 Method Not Allowed responses.
• Automatic handling of OPTIONS and HEAD requests.
• Works with http.Handler, http.HandlerFunc, and standard Go middleware.
• Zero dependencies.
• Tiny, readable, codebase (~160 lines of code).

---

Project status

This package has reached a stable status. It is actively maintained with ongoing bug fixes and essential updates, but significant alterations to the API or behavior are not expected.

---

Installation

$ go get github.com/alexedwards/flow@latest

Basic example

package main

import (
    "fmt"
    "log"
    "net/http"

    "github.com/alexedwards/flow"
)

func main() {
    // Initialize a new router.
    mux := flow.New()

    // Add a `GET /greet/:name` route. The : character is used to denote a 
    // named parameter in the URL path, which acts like a 'wildcard'.
    mux.HandleFunc("/greet/:name", greet, "GET")

    err := http.ListenAndServe(":2323", mux)
    log.Fatal(err)
}

func greet(w http.ResponseWriter, r *http.Request) {
    // Retrieve the value of the named parameter from the request.
    name := r.PathValue("name")

    fmt.Fprintf(w, "Hello %s", name)
}

Kitchen-sink example

mux := flow.New()

// The Use() method can be used to register middleware. Middleware declared at
// the top level will be used on all routes (including error handlers and OPTIONS
// responses).
mux.Use(exampleMiddleware1)

// Routes can use multiple HTTP methods.
mux.HandleFunc("/profile/:name", exampleHandlerFunc1, "GET", "POST")

// Optionally, regular expressions can be used to enforce a specific pattern
// for a named parameter.
mux.HandleFunc("/profile/:name/:age|^[0-9]{1,3}$", exampleHandlerFunc2, "GET")

// The wildcard ... can be used to match the remainder of a request path.
// Notice that HTTP methods are also optional (if not provided, all HTTP
// methods will match the route). The value of the wildcard can be retrieved 
// by calling r.PathValue("...").
mux.Handle("/static/...", exampleHandler)

// You can create route 'groups'.
mux.Group(func(mux *flow.Mux) {
    // Middleware declared within the group will only be used on the routes
    // in the group.
    mux.Use(exampleMiddleware2)

    mux.HandleFunc("/admin", exampleHandlerFunc3, "GET")

    // Groups can be nested.
    mux.Group(func(mux *flow.Mux) {
        mux.Use(exampleMiddleware3)

        mux.HandleFunc("/admin/passwords", exampleHandlerFunc4, "GET")
    })
})

Notes

• Conflicting routes are permitted (e.g. /posts/:id and posts/new). Routes are matched in the order that they are declared.
• Trailing slashes are significant (/profile/:id and /profile/:id/ are not the same).
• An Allow header is automatically set for all OPTIONS and 405 Method Not Allowed responses (including when using custom handlers).
• Once the flow.Mux type is being used by your server, it is not safe to add more middleware or routes concurrently.
• Middleware must be declared before a route in order to be used by that route. Any middleware declared after a route won't act on that route. For example:

mux := flow.New()
mux.Use(middleware1)
mux.HandleFunc("/foo", ...) // This route will use middleware1 only.
mux.Use(middleware2)
mux.HandleFunc("/bar", ...) // This route will use both middleware1 and middleware2.

Thanks

The pattern matching logic for Flow was heavily inspired by matryer/way.

Documentation

Overview

Package flow is a delightfully simple, readable, and tiny HTTP router for Go web applications. Its features include:

* Use named parameters, wildcards and (optionally) regexp patterns in your routes. * Create route groups which use different middleware (a bit like chi). * Customizable handlers for 404 Not Found and 405 Method Not Allowed responses. * Automatic handling of OPTIONS and HEAD requests. * Works with http.Handler, http.HandlerFunc, and standard Go middleware.

Example code:

package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/alexedwards/flow"
)

func main() {
	mux := flow.New()

	// The Use() method can be used to register middleware. Middleware declared at
	// the top level will used on all routes (including error handlers and OPTIONS
	// responses).
	mux.Use(exampleMiddleware1)

	// Routes can use multiple HTTP methods.
	mux.HandleFunc("/profile/:name", exampleHandlerFunc1, "GET", "POST")

	// Optionally, regular expressions can be used to enforce a specific pattern
	// for a named parameter.
	mux.HandleFunc("/profile/:name/:age|^[0-9]{1,3}$", exampleHandlerFunc2, "GET")

	// The wildcard ... can be used to match the remainder of a request path.
	// Notice that HTTP methods are also optional (if not provided, all HTTP
	// methods will match the route).
	mux.Handle("/static/...", exampleHandler)

	// You can create route 'groups'.
	mux.Group(func(mux *flow.Mux) {
		// Middleware declared within in the group will only be used on the routes
		// in the group.
		mux.Use(exampleMiddleware2)

		mux.HandleFunc("/admin", exampleHandlerFunc3, "GET")

		// Groups can be nested.
		mux.Group(func(mux *flow.Mux) {
			mux.Use(exampleMiddleware3)

			mux.HandleFunc("/admin/passwords", exampleHandlerFunc4, "GET")
		})
	})

	err := http.ListenAndServe(":2323", mux)
	log.Fatal(err)
}

Index

• Variables
• func Param(ctx context.Context, param string) string
• type Mux
  • func New() *Mux
  • func (m *Mux) Group(fn func(*Mux))
  • func (m *Mux) Handle(pattern string, handler http.Handler, methods ...string)
  • func (m *Mux) HandleFunc(pattern string, fn http.HandlerFunc, methods ...string)
  • func (m *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (m *Mux) Use(mw ...func(http.Handler) http.Handler)

Variables

var AllMethods = []string{http.MethodGet, http.MethodHead, http.MethodPost, http.MethodPut, http.MethodPatch, http.MethodDelete, http.MethodConnect, http.MethodOptions, http.MethodTrace}

AllMethods is a slice containing all HTTP request methods.

Functions

func Param

func Param(ctx context.Context, param string) string

Deprecated: Use r.PathValue instead (https://pkg.go.dev/net/http#Request.PathValue).

Types

type Mux

type Mux struct {
	NotFound         http.Handler
	MethodNotAllowed http.Handler
	Options          http.Handler
	// contains filtered or unexported fields
}

Mux is a http.Handler which dispatches requests to different handlers.

func New

func New() *Mux

New returns a new initialized Mux instance.

func (*Mux) Group

func (m *Mux) Group(fn func(*Mux))

Group is used to create 'groups' of routes in a Mux. Middleware registered inside the group will only be used on the routes in that group. See the example code at the start of the package documentation for how to use this feature.

func (*Mux) Handle

func (m *Mux) Handle(pattern string, handler http.Handler, methods ...string)

Handle registers a new handler for the given request path pattern and HTTP methods.

func (*Mux) HandleFunc

func (m *Mux) HandleFunc(pattern string, fn http.HandlerFunc, methods ...string)

HandleFunc is an adapter which allows using a http.HandlerFunc as a handler.

func (*Mux) ServeHTTP

func (m *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP makes the router implement the http.Handler interface.

func (*Mux) Use

func (m *Mux) Use(mw ...func(http.Handler) http.Handler)

Use registers middleware with the Mux instance. Middleware must have the signature `func(http.Handler) http.Handler`.