middleware

Documentation

Overview

Package middleware defines the middleware format for Matcha.

See [https://github.com/jnichols-git/matcha/v2/blob/main/docs/routers.md#middleware].

Index

• Constants
• func ExecuteMiddleware(mw []Middleware, w http.ResponseWriter, req *http.Request) *http.Request
• type LogEntry
  • func ParseLog(s string) (*LogEntry, error)
• type Middleware
  • func ExpectHeader(name string, patts ...string) Middleware
  • func ExpectQueryParam(name string, patts ...string) Middleware
  • func Handler(create func(next http.Handler) http.Handler) Middleware
  • func LogRequests(w io.Writer) Middleware
  • func LogRequestsIf(test func(*http.Request) bool, w io.Writer) Middleware
  • func TrimPrefix(prefix string) Middleware
  • func TrimPrefixStrict(prefix string, errMsg string) Middleware

Constants

const OriginAbsent = "-"

The string used to indicate an absent origin in log entries.

Origins take one of the following forms, so must not take any of these forms:

"null"
"<scheme>://<hostname>"
"<scheme>://<hostname>:<port>"

Functions

func ExecuteMiddleware

func ExecuteMiddleware(mw []Middleware, w http.ResponseWriter, req *http.Request) *http.Request

Executes the given middleware functions on the given request. It returns the modified request or nil if any middleware function returns nil.

Types

type LogEntry

type LogEntry struct {
	Timestamp time.Time
	// Will be an empty string "" if no origin header was given on the request.
	Origin string
	Method string
	URL    *url.URL
}

func ParseLog

func ParseLog(s string) (*LogEntry, error)

Parses a log entry generated by LogRequests or LogRequestsIf. See LogRequests for the log entry format.

type Middleware

type Middleware func(http.ResponseWriter, *http.Request) *http.Request

Middleware runs on any incoming request. Attachment behavior is defined by the structure it's attached to (route vs. router).

Returns an *http.Request; the middleware can set router params or reject a request by returning nil.

func ExpectHeader

func ExpectHeader(name string, patts ...string) Middleware

ExpectHeader checks for the presence of a header. Requests are rejected if the header `name` is not present, or if the value doesn't match the provided patterns, if any. `patts` can be left empty to permit any value assigned to `name`, but headers must have a value to be permitted. Invalid patterns are silently discarded.

See package Pattern for more details on pattern construction.

func ExpectQueryParam

func ExpectQueryParam(name string, patts ...string) Middleware

ExpectQueryParam checks for the presence of a query parameter. Requests are rejected if the query parameter `name` is not present, or if the value doesn't match the provided patterns. `patts` can be left empty to permit any or no value assigned to `name`. Invalid patterns are silently discarded.

See package Pattern for more details on pattern construction.

func Handler

func Handler(create func(next http.Handler) http.Handler) Middleware

Handler allows integration of traditional handler-chain-ware.

func LogRequests

func LogRequests(w io.Writer) Middleware

Returns a middleware that logs the details of an incoming request.

Log entries take the form "<timestamp> <origin> <HTTP method> <url>". If no origin is provided with the request, <origin> will be OriginAbsent. <timestamp> is an integer, the number of nanoseconds since the Unix Epoch.

func LogRequestsIf

func LogRequestsIf(test func(*http.Request) bool, w io.Writer) Middleware

Returns a middleware that logs the details of an incoming request only if test(request) == true. Log entries use the same format as LogRequests.

func TrimPrefix

func TrimPrefix(prefix string) Middleware

TrimPrefix trims a static prefix from the path of an inbound request. If the prefix doesn't exist, the request is unmodified. If you want to reject requests without the prefix, use TrimPrefixStrict.

func TrimPrefixStrict

func TrimPrefixStrict(prefix string, errMsg string) Middleware

TrimPrefixStrict trims a static prefix from the path of an inbound request. If the prefix doesn't exist, the request is rejected and the errMsg is sent as a response. An empty errMsg will generate an error message "expected path prefix [prefix]".