heligo

README

Heligo

Heligo is a fast and minimal HTTP request router for Go.

Main characteristics

• Zero allocations
• Support for URL parameters (:param and *param) with precedence
• Support for middlewares and groups of handlers
• Explicit standard context in handlers
• Explicit HTTP status code and error propagation
• No internal sync.Pool usage
• No dependencies outside the standard library

Example

package main

import (
    "context"
    "fmt"
    "net/http"

    "github.com/sted/heligo"
)

func hello(ctx context.Context, w http.ResponseWriter, r heligo.Request) (int, error) {
    fmt.Fprint(w, "Welcome!\n")
    return http.StatusOK, nil
}

func page(ctx context.Context, w http.ResponseWriter, r heligo.Request) (int, error) {
    fmt.Fprintf(w, "Page %s!\n", r.Param("name"))
    return http.StatusOK, nil
}

func main() {
    router := heligo.New()
    router.Handle("GET", "/", hello)
    router.Handle("GET", "/page/:name", page)

    http.ListenAndServe(":8080", router)
}

Rationale

The handler has some important differences from the standard handler:

• The context is explicit to simplify its usage (no need to extract it from the request and then reinsert it, avoiding extra allocations)
• heligo.Request wraps http.Request and gives access to the request parameters
• The HTTP status and the eventual error are returned to optimize for the fact that they are usually needed

Groups and middlewares

You can create create groups of handlers, each with their own middlewares:

projects := router.Group("/projects", DatabaseMiddleware())
projects.Handle("POST", "/", CreateProject)

Documentation

Index

• Constants
• Variables
• func WriteHeader(w http.ResponseWriter, status int) (int, error)
• func WriteJSON(w http.ResponseWriter, status int, obj any) (int, error)
• type AdapterResponseWriter
  • func (w *AdapterResponseWriter) Status() int
  • func (w *AdapterResponseWriter) WriteHeader(code int)
• type Group
  • func (g *Group) Group(path string, middlewares ...Middleware) *Group
  • func (g *Group) Handle(method string, path string, handler Handler)
• type Handler
  • func Adapt(h http.Handler) Handler
  • func AdaptFunc(hf http.HandlerFunc) Handler
• type Middleware
  • func AdaptAsMiddleware(h http.Handler) Middleware
  • func AdaptFuncAsMiddleware(hf http.HandlerFunc) Middleware
  • func AdaptMiddleware(m func(http.Handler) http.Handler) Middleware
• type Param
  • func ParamsFromContext(ctx context.Context) []Param
• type Request
  • func (r *Request) Param(name string) string
  • func (r *Request) ParamByPos(i int) Param
  • func (r *Request) Params() []Param
  • func (r *Request) ReadJSON(obj any) error
• type Router
  • func New() *Router
  • func (router *Router) Group(path string, middlewares ...Middleware) *Group
  • func (router *Router) Handle(method string, path string, handler Handler)
  • func (router *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (router *Router) Use(middlewares ...Middleware)

Constants

const (
	SLASH = '/'
	COLON = ':'
	STAR  = '*'
)

const MAXPARAMS = 16

Variables

var ParamsTag = paramsKey{}

Functions

func WriteHeader

func WriteHeader(w http.ResponseWriter, status int) (int, error)

WriteHeader is just for convenience

func WriteJSON

func WriteJSON(w http.ResponseWriter, status int, obj any) (int, error)

WriteJSON writes a JSON body with the appropriate header.

Types

type AdapterResponseWriter

type AdapterResponseWriter struct {
	http.ResponseWriter
	// contains filtered or unexported fields
}

func (*AdapterResponseWriter) Status

func (w *AdapterResponseWriter) Status() int

func (*AdapterResponseWriter) WriteHeader

func (w *AdapterResponseWriter) WriteHeader(code int)

type Group

type Group struct {
	// contains filtered or unexported fields
}

func (*Group) Group

func (g *Group) Group(path string, middlewares ...Middleware) *Group

Group creates a new sub-group of handlers, with common middlewares

func (*Group) Handle

func (g *Group) Handle(method string, path string, handler Handler)

Handle registers a new handler under a group for method and path.

type Handler

type Handler func(ctx context.Context, w http.ResponseWriter, r Request) (int, error)

Handler is the signature of a Heligo handler. It gets a standard context taken from http.Request, a http.RequestWriter and a heligo.Request. You should return the HTTP status code and a potential error (or nil).

func Adapt

func Adapt(h http.Handler) Handler

Adapt adapts a standard http.Handler to be used as a Heligo handler. In the standard handler one can retrieve parameters from the context, using ParamsFromContext.

func AdaptFunc

func AdaptFunc(hf http.HandlerFunc) Handler

Adapt adapts a standard http.Handler to be used as a Heligo handler.

type Middleware

type Middleware func(Handler) Handler

Middleware is the signature of a Heligo middleware.

func AdaptAsMiddleware

func AdaptAsMiddleware(h http.Handler) Middleware

AdaptAsMiddleware adapts a standard http.Handler to be used as a Heligo middleware. Note the this is less flexible than the previous AdaptMiddleware, as it doesn't not allow to break the middleware chain except in the case of errors and calls the next handler only at the end.

func AdaptFuncAsMiddleware

func AdaptFuncAsMiddleware(hf http.HandlerFunc) Middleware

AdaptFuncAsMiddleware adapts a standard http.HandlerFunc to be used as a Heligo middleware.

func AdaptMiddleware

func AdaptMiddleware(m func(http.Handler) http.Handler) Middleware

AdaptMiddleware adapts a standard middleware (func(http.Handler) http.Handler) to be used as a Heligo middleware

type Param

type Param struct {
	Name  string
	Value string
}

func ParamsFromContext

func ParamsFromContext(ctx context.Context) []Param

ParamsFromContext gets the route parameters from the context

type Request

type Request struct {
	*http.Request
	// contains filtered or unexported fields
}

Request embeds the standard http.Request and the URL parameters in a compressed format

func (*Request) Param

func (r *Request) Param(name string) string

Param returns a URL parameter by name. It returns an empty string if the requested parameter is not found.

func (*Request) ParamByPos

func (r *Request) ParamByPos(i int) Param

ParamByPos gets a URL parameter by position in the URL (0-based)

func (*Request) Params

func (r *Request) Params() []Param

Params gets all the URL parameters for the request

func (*Request) ReadJSON

func (r *Request) ReadJSON(obj any) error

ReadJSON decodes the JSON in the body into the value pointed by obj

type Router

type Router struct {
	ErrorHandler func(int, error)
	// contains filtered or unexported fields
}

func New

func New() *Router

New creates a new router

func (*Router) Group

func (router *Router) Group(path string, middlewares ...Middleware) *Group

Group creates a new group of handlers, with common middlewares

func (*Router) Handle

func (router *Router) Handle(method string, path string, handler Handler)

Handle registers a new handler for method and path.

func (*Router) ServeHTTP

func (router *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP complies with the standard http.Handler interface

func (*Router) Use

func (router *Router) Use(middlewares ...Middleware)

Use registers a global middleware. The middlewares are called in the order they are registered.