middleware

Documentation

Overview

Package middleware provides some types and functions common among middleware.

Index

• Constants
• func NewReplacer(r *http.Request, rr *responseRecorder) replacer
• func NewResponseRecorder(w http.ResponseWriter) *responseRecorder
• func SplitCommandAndArgs(command string) (cmd string, args []string, err error)
• type Controller
• type Dispenser
• type Generator
• type Handler
• type HandlerFunc
  • func (f HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request) (int, error)
• type Middleware
• type Path
  • func (p Path) Matches(other string) bool

Constants

const (
	EmptyStringReplacer = "-"
)

Functions

func NewReplacer

func NewReplacer(r *http.Request, rr *responseRecorder) replacer

NewReplacer makes a new replacer based on r and rr. Do not create a new replacer until r and rr have all the needed values, because this function copies those values into the replacer.

func NewResponseRecorder

func NewResponseRecorder(w http.ResponseWriter) *responseRecorder

NewResponseRecorder makes and returns a new responseRecorder, which captures the HTTP Status code from the ResponseWriter and also the length of the response body written through it. Because a status is not set unless WriteHeader is called explicitly, this constructor initializes with a status code of 200 to cover the default case.

func SplitCommandAndArgs

func SplitCommandAndArgs(command string) (cmd string, args []string, err error)

SplitCommandAndArgs takes a command string and parses it shell-style into the command and its separate arguments.

Types

type Controller

type Controller interface {
	Dispenser

	// Startup registers a function to execute when the server starts.
	Startup(func() error)

	// Shutdown registers a function to execute when the server exits.
	Shutdown(func() error)

	// Root returns the file path from which the server is serving.
	Root() string

	// Context returns the path scope that the Controller is in.
	// Note: This is not currently used, but may be in the future.
	Context() Path
}

A Controller provides access to properties of the server. Middleware generators use a Controller to construct their instances.

type Dispenser

type Dispenser interface {
	// Next loads the next token. Returns true if a token
	// was loaded; false otherwise. If false, all tokens
	// have already been consumed.
	Next() bool

	// NextArg loads the next token if it is on the same
	// line. Returns true if a token was loaded; false
	// otherwise. If false, all tokens on the line have
	// been consumed.
	NextArg() bool

	// NextLine loads the next token only if it is NOT on the same
	// line as the current token, and returns true if a token was
	// loaded; false otherwise. If false, there is not another token
	// or it is on the same line.
	NextLine() bool

	// NextBlock can be used as the condition of a for loop
	// to load the next token as long as it opens a block or
	// is already in a block. It returns true if a token was
	// loaded, or false when the block's closing curly brace
	// was loaded and thus the block ended. Nested blocks are
	// not (currently) supported.
	NextBlock() bool

	// Val gets the text of the current token.
	Val() string

	// Args is a convenience function that loads the next arguments
	// (tokens on the same line) into an arbitrary number of strings
	// pointed to in arguments. If there are fewer tokens available
	// than string pointers, the remaining strings will not be changed
	// and false will be returned. If there were enough tokens available
	// to fill the arguments, then true will be returned.
	Args(...*string) bool

	// RemainingArgs loads any more arguments (tokens on the same line)
	// into a slice and returns them. Open curly brace tokens also indicate
	// the end of arguments, and the curly brace is not included in
	// the return value nor is it loaded.
	RemainingArgs() []string

	// ArgErr returns an argument error, meaning that another
	// argument was expected but not found. In other words,
	// a line break, EOF, or open curly brace was encountered instead of
	// an argument.
	ArgErr() error

	// Err generates a custom parse error with a message of msg.
	Err(string) error
}

A Dispenser provides structured access to tokens from a configuration file. It dispenses tokens to middleware for parsing so that middleware can configure themselves.

type Generator

type Generator func(Controller) (Middleware, error)

Generator represents the outer layer of a middleware that parses tokens to configure the middleware instance.

Note: This type will be moved into a different package in the future.

type Handler

type Handler interface {
	ServeHTTP(http.ResponseWriter, *http.Request) (int, error)
}

Handler is like http.Handler except ServeHTTP returns a status code and an error. The status code is for the client's benefit; the error value is for the server's benefit. The status code will be sent to the client while the error value will be logged privately. Sometimes, an error status code (4xx or 5xx) may be returned with a nil error when there is no reason to log the error on the server.

If a HandlerFunc returns an error (status >= 400), it should NOT write to the response. This philosophy makes middleware.Handler different from http.Handler: error handling should happen at the application layer or in dedicated error-handling middleware only rather than with an "every middleware for itself" paradigm.

The application or error-handling middleware should incorporate logic to ensure that the client always gets a proper response according to the status code. For security reasons, it should probably not reveal the actual error message. (Instead it should be logged, for example.)

Handlers which do write to the response should return a status value < 400 as a signal that a response has been written. In other words, only error-handling middleware or the application will write to the response for a status code >= 400. When ANY handler writes to the response, it should return a status code < 400 to signal others to NOT write to the response again, which would be erroneous.

type HandlerFunc

type HandlerFunc func(http.ResponseWriter, *http.Request) (int, error)

HandlerFunc is a convenience type like http.HandlerFunc, except ServeHTTP returns a status code and an error. See Handler documentation for more information.

func (HandlerFunc) ServeHTTP

func (f HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request) (int, error)

ServeHTTP implements the Handler interface.

type Middleware

type Middleware func(Handler) Handler

Middleware is the middle layer which represents the traditional idea of middleware: it chains one Handler to the next by being passed the next Handler in the chain.

Note: This type will be moved into a different package in the future.

type Path

type Path string

Path represents a URI path, maybe with pattern characters.

func (Path) Matches

func (p Path) Matches(other string) bool

Path matching will probably not always be a direct comparison; this method assures that paths can be easily and consistently matched.