middleware

Documentation

Overview

Package middleware provides helpful functions that implement some common functionalities in http servers. A middleware is a function that returns a http.HandlerFunc

The middlewares All, Get, Post, Head, Put & Delete wrap other internal middleware. The effect of this is that the aforementioned middleware, in addition to their specialised functionality, will:

1. Adds logID for traceability.
2. Add the "real" client IP address to the request context.
3. Recover from panics in the wrappedHandler.
4. Log http requests and responses.
5. Rate limit requests by IP address.
6. Shed load based on http response latencies.
7. Redirect http requests to https.
8. Add some important HTTP security headers and assign them sensible default values.
9. Implement Cross-Origin Resource Sharing support(CORS).
10. Provide protection against Cross Site Request Forgeries(CSRF).
11. Attempt to provide protection against form re-submission when a user reloads an already submitted web form.
12. Implement http sessions.

Example (All)

package main

import (
	"context"
	"io"
	"net/http"
	"os"

	"github.com/komuw/ong/log"
	"github.com/komuw/ong/middleware"
)

func main() {
	l := log.New(os.Stdout, 100)(context.Background())
	opts := middleware.WithOpts("example.com", 443, "secretKey", middleware.DirectIpStrategy, l)

	myHandler := func(w http.ResponseWriter, _ *http.Request) {
		_, _ = io.WriteString(w, "Hello from a HandleFunc \n")
	}

	handler := middleware.All(myHandler, opts)

	http.HandleFunc("/", handler)
	err := http.ListenAndServe(":8080", nil)
	if err != nil {
		panic(err)
	}
}

Example (Get)

package main

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

	"github.com/komuw/ong/log"
	"github.com/komuw/ong/middleware"
)

func loginHandler() http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		cspNonce := middleware.GetCspNonce(r.Context())
		_ = cspNonce

		_, _ = fmt.Fprint(w, "welcome to your favorite website.")
	}
}

func main() {
	l := log.New(os.Stdout, 100)(context.Background())
	opts := middleware.WithOpts("example.com", 443, "secretKey", middleware.DirectIpStrategy, l)
	handler := middleware.Get(loginHandler(), opts)
	_ = handler // use handler

}

Example (GetCspNonce)

package main

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

	"github.com/komuw/ong/log"
	"github.com/komuw/ong/middleware"
)

func loginHandler() http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		cspNonce := middleware.GetCspNonce(r.Context())
		_ = cspNonce

		_, _ = fmt.Fprint(w, "welcome to your favorite website.")
	}
}

func main() {
	l := log.New(os.Stdout, 100)(context.Background())
	handler := middleware.Get(
		loginHandler(),
		middleware.WithOpts("example.com", 443, "secretKey", middleware.DirectIpStrategy, l),
	)
	_ = handler // use handler

}

Example (GetCsrfToken)

package main

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

	"github.com/komuw/ong/log"
	"github.com/komuw/ong/middleware"
)

func welcomeHandler() http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		csrfToken := middleware.GetCsrfToken(r.Context())
		_ = csrfToken

		_, _ = fmt.Fprint(w, "welcome.")
	}
}

func main() {
	l := log.New(os.Stdout, 100)(context.Background())
	handler := middleware.Get(
		welcomeHandler(),
		middleware.WithOpts("example.com", 443, "secretKey", middleware.DirectIpStrategy, l),
	)
	_ = handler // use handler

}

Index

• Constants
• func All(wrappedHandler http.HandlerFunc, o Opts) http.HandlerFunc
• func BasicAuth(wrappedHandler http.HandlerFunc, user, passwd string) http.HandlerFunc
• func ClientIP(r *http.Request) string
• func Delete(wrappedHandler http.HandlerFunc, o Opts) http.HandlerFunc
• func Get(wrappedHandler http.HandlerFunc, o Opts) http.HandlerFunc
• func GetCspNonce(c context.Context) string
• func GetCsrfToken(c context.Context) string
• func Head(wrappedHandler http.HandlerFunc, o Opts) http.HandlerFunc
• func Post(wrappedHandler http.HandlerFunc, o Opts) http.HandlerFunc
• func Put(wrappedHandler http.HandlerFunc, o Opts) http.HandlerFunc
• type ClientIPstrategy
  • func SingleIpStrategy(headerName string) ClientIPstrategy
• type Opts
  • func New(domain string, httpsPort uint16, allowedOrigins []string, ...) Opts
  • func WithOpts(domain string, httpsPort uint16, secretKey string, strategy ClientIPstrategy, ...) Opts

Examples

• Package (All)
• Package (Get)
• Package (GetCspNonce)
• Package (GetCsrfToken)

Constants

const (
	// DirectIpStrategy should be used if the server accepts direct connections, rather than through a proxy.
	//
	// See the warning in [ClientIP]
	DirectIpStrategy = ClientIPstrategy("DirectIpStrategy")

	// LeftIpStrategy derives the client IP from the leftmost valid and non-private IP address in the `X-Fowarded-For` or `Forwarded` header.
	// Note: This MUST NOT be used for security purposes. This IP can be trivially SPOOFED.
	//
	// See the warning in [ClientIP]
	LeftIpStrategy = ClientIPstrategy("LeftIpStrategy")

	// RightIpStrategy derives the client IP from the rightmost valid and non-private IP address in the `X-Fowarded-For` or `Forwarded` header.
	//
	// See the warning in [ClientIP]
	RightIpStrategy = ClientIPstrategy("RightIpStrategy")
)

const (
	// CsrfTokenFormName is the name of the html form name attribute for csrf token.
	CsrfTokenFormName = "csrftoken" // named after what django uses.
	// CsrfHeader is the name of the http header that Ong uses to store csrf token.
	CsrfHeader = "X-Csrf-Token" // named after what fiber uses.

)

Functions

func All

func All(wrappedHandler http.HandlerFunc, o Opts) http.HandlerFunc

All is a middleware that allows all http methods.

See the package documentation for the additional functionality provided by this middleware.

func BasicAuth

func BasicAuth(wrappedHandler http.HandlerFunc, user, passwd string) http.HandlerFunc

BasicAuth is a middleware that protects wrappedHandler using basic authentication.

func ClientIP

func ClientIP(r *http.Request) string

ClientIP returns the "real" client IP address.

Warning: This should be used with caution. Clients CAN easily spoof IP addresses. Fetching the "real" client is done in a best-effort basis and can be grossly inaccurate & precarious. You should especially heed this warning if you intend to use the IP addresses for security related activities. Proceed at your own risk.

func Delete

func Delete(wrappedHandler http.HandlerFunc, o Opts) http.HandlerFunc

Delete is a middleware that only allows http DELETE requests and http OPTIONS requests.

See the package documentation for the additional functionality provided by this middleware.

func Get

func Get(wrappedHandler http.HandlerFunc, o Opts) http.HandlerFunc

Get is a middleware that only allows http GET requests and http OPTIONS requests.

See the package documentation for the additional functionality provided by this middleware.

func GetCspNonce

func GetCspNonce(c context.Context) string

GetCspNonce returns the Content-Security-Policy nonce that was set for the http request in question.

func GetCsrfToken

func GetCsrfToken(c context.Context) string

GetCsrfToken returns the csrf token that was set for the http request in question.

func Head

func Head(wrappedHandler http.HandlerFunc, o Opts) http.HandlerFunc

Head is a middleware that only allows http HEAD requests and http OPTIONS requests.

See the package documentation for the additional functionality provided by this middleware.

func Post

func Post(wrappedHandler http.HandlerFunc, o Opts) http.HandlerFunc

Post is a middleware that only allows http POST requests and http OPTIONS requests.

See the package documentation for the additional functionality provided by this middleware.

func Put

func Put(wrappedHandler http.HandlerFunc, o Opts) http.HandlerFunc

Put is a middleware that only allows http PUT requests and http OPTIONS requests.

See the package documentation for the additional functionality provided by this middleware.

Types

type ClientIPstrategy

type ClientIPstrategy string

ClientIPstrategy is a middleware option that describes the strategy to use when fetching the client's IP address. The strategies supported are DirectIpStrategy, LeftIpStrategy, RightIpStrategy & SingleIpStrategy

func SingleIpStrategy

func SingleIpStrategy(headerName string) ClientIPstrategy

SingleIpStrategy derives the client IP from http header headerName.

headerName MUST not be either `X-Forwarded-For` or `Forwarded`. It can be something like `CF-Connecting-IP`, `Fastly-Client-IP`, `Fly-Client-IP`, etc; depending on your usecase.

See the warning in ClientIP

type Opts

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

Opts are the various parameters(optionals) that can be used to configure middlewares.

Use either New or WithOpts to get a valid Opts.

func New

func New(
	domain string,
	httpsPort uint16,
	allowedOrigins []string,
	allowedMethods []string,
	allowedHeaders []string,
	secretKey string,
	strategy ClientIPstrategy,
	l *slog.Logger,
) Opts

New returns a new Opts.

domain is the domain name of your website.

httpsPort is the tls port where http requests will be redirected to.

allowedOrigins, allowedMethods, & allowedHeaders are used by the CORS middleware. If allowedOrigins is nil, all origins are allowed. You can also use * to allow all. If allowedMethods is nil, "GET", "POST", "HEAD" are allowed. Use * to allow all. If allowedHeaders is nil, "Origin", "Accept", "Content-Type", "X-Requested-With" are allowed. Use * to allow all.

secretKey is used for securing signed data. It should be unique & kept secret. If it becomes compromised, generate a new one and restart your application using the new one.

strategy is the algorithm to use when fetching the client's IP address. It is important to choose your strategy carefully, see the warning in ClientIP. The strategies supported are DirectIpStrategy, LeftIpStrategy, RightIpStrategy & SingleIpStrategy

func WithOpts

func WithOpts(
	domain string,
	httpsPort uint16,
	secretKey string,
	strategy ClientIPstrategy,
	l *slog.Logger,
) Opts

WithOpts returns a new Opts that has sensible defaults. See New for extra documentation.