gohm

func AllowedMethodsHandler ¶

func AllowedMethodsHandler(allowedMethods []string, next http.Handler) http.Handler

AllowedMethodsHandler returns a handler that only permits specified request methods, and responds with an error message when request method is not a member of the sorted list of allowed methods.

func CORSHandler ¶

func CORSHandler(config CORSConfig, next http.Handler) http.Handler

CORSHandler returns a handler that responds to OPTIONS request so that CORS requests from an origin that matches the specified allowed origins regular expression are permitted, while other origins are denied. If a request origin matches the specified regular expression, the handler responds with the specified allowOriginResponse value in the "Access-Control-Allow-Origin" HTTP response header.

func DefaultHandler ¶

func DefaultHandler(pathOfIndexFile string) http.Handler

DefaultHandler serves the specified file when request is for an empty path, "/", but serves a 404 Not Found for all other requests.

When most users first visit a website, they visit it with an empty URL path. This handler responds to such a request with the contents of the specified file. However, the standard library's HTTP multiplexer type, http.ServeMux, will cause all requests that have an URL path that do not match any other registered handler to match against "/", causing invalid URL path requests to be given the index page rather than a 404 Not Found. This handler corrects that behavior by differentiating whether the request URL path is "/". If so it serves the contents of the specified file; otherwise a 404 Not Found is returned to the user.

http.Handle("/", gohm.DefaultHandler(filepath.Join(staticPath, "index.html")))

func Error ¶

func Error(w http.ResponseWriter, text string, code int)

Error formats and emits the specified error message text and status code information to the http.ResponseWriter, to be consumed by the client of the service. This particular helper function has nothing to do with emitting log messages on the server side, and only creates a response for the client. However, if a handler that invokes gohm.Error is wrapped with logging functionality by gohm.New, then gohm will also emit a sensible log message based on the specified status code and message text. Typically handlers will call this method prior to invoking return to return to whichever handler invoked it.

// example function which guards downstream handlers to ensure only HTTP GET method used
// to access resource.
func onlyGet(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			if r.Method != "GET" {
				gohm.Error(w, r.Method, http.StatusMethodNotAllowed)
				// 405 Method Not Allowed: POST
				return
			}
			next.ServeHTTP(w, r)
		})
}

func ForbidDirectories ¶

func ForbidDirectories(next http.Handler) http.Handler

ForbidDirectories prevents clients from probing file servers.

ForbidDirectories will respond to all requests that have a "/" suffix with 403 Forbidden, but will forward all requests without the "/" suffix to the specified next handler.

The standard library's http.FileServer will enumerate a directory's contents when a client requests a directory. This function's purpose is to prevent clients from probing a static file server to see its resources by attempting to query directories.

http.Handle("/static/", gohm.ForbidDirectories(gohm.StaticHandler("/static/", staticPath)))

func New ¶

func New(next http.Handler, config Config) http.Handler

New returns a new http.Handler that calls the specified next http.Handler, and performs the requested operations before and after the downstream handler as specified by the gohm.Config structure passed to it.

It receives a gohm.Config struct rather than a pointer to one, so users less likely to consider modification after creating the http.Handler.

 // Used to control how long it takes to serve a static file.
	const staticTimeout = time.Second

	var (
		// Will store statistics counters for status codes 1xx, 2xx, 3xx, 4xx,
		// 5xx, as well as a counter for all responses
		counters gohm.Counters

		// Used to dynamically control log level of HTTP logging. After handler
     // created, this must be accessed using the sync/atomic package.
		logBitmask = gohm.LogStatusErrors

		// Determines HTTP log format
		logFormat = "{http-CLIENT-IP} {client-ip} [{end}] \"{method} {uri} {proto}\" {status} {bytes} {duration} {message}"
	)

	func main() {

		h := http.StripPrefix("/static/", http.FileServer(http.Dir("static")))

		h = gohm.WithGzip(h) // gzip response if client accepts gzip encoding

		// gohm was designed to wrap other http.Handler functions.
		h = gohm.New(h, gohm.Config{
			Counters:   &counters,   // pointer given so counters can be collected and optionally reset
			LogBitmask: &logBitmask, // pointer given so bitmask can be updated using sync/atomic
			LogFormat:  logFormat,
			LogWriter:  os.Stderr,
			Timeout:    staticTimeout,
		})

		http.Handle("/static/", h)
		log.Fatal(http.ListenAndServe(":8080", nil))
	}

func Prefix ¶ added in v2.15.0

func Prefix(r *http.Request) (prefix string)

Prefix strips the prefix from the start of the request's path and returns it, modifying the request's path by removing the stripped prefix. When the request path is for the empty URL, it returns an empty string and does not modify the request.

func ShiftPath ¶ added in v2.15.0

func ShiftPath(p string) (string, string)

ShiftPath splits off the first component of p. The first return value will never contain a slash, while the second return value will always start with a slash, followed by all remaining path components, with the final slash removed when remaining path components are returned.

Example:

"/foo/bar/baz"  -> "foo", "/bar/baz"
"/foo/bar/baz/" -> "foo", "/bar/baz"

Inspired by:

https://blog.merovius.de/2017/06/18/how-not-to-use-an-http-router.html

Expects paths to be initially cleaned:

p = path.Clean("/" + p)[1:]
head, tail := shiftPath(p)

func StaticHandler ¶

func StaticHandler(virtualRoot, fileSystemRoot string) http.Handler

StaticHandler serves static files, preventing clients from probing file servers.

The specified virtual root will be stripped from the prefix, such that when "$virtualRoot/foo/bar" is requested, "$fileSystemRoot/foo/bar" will be served.

This handler will respond to all requests that have a "/" suffix with 403 Forbidden, but will attempt to serve all requests without the "/" suffix by serving the corresponding file.

The standard library's http.FileServer will enumerate a directory's contents when a client requests a directory. This function's purpose is to prevent clients from probing a static file server to see its resources by attempting to query directories.

http.Handle("/static/", gohm.StaticHandler("/static/", staticPath))

func StaticHandlerWithoutProbingProtection ¶

func StaticHandlerWithoutProbingProtection(virtualRoot, fileSystemRoot string) http.Handler

StaticHandlerWithoutProbingProtection serves static files, and when a directory is requested, will serve a representation of the directory's contents.

The specified virtual root will be stripped from the prefix, such that when "$virtualRoot/foo/bar" is requested, "$fileSystemRoot/foo/bar" will be served.

Please use the StaticHandler function rather than this function, unless your application specifically benefits from clients probing your file server's contents.

func WithCompression ¶

func WithCompression(next http.Handler) http.Handler

WithCompression returns a new http.Handler that optionally compresses the response text using either the gzip or deflate compression algorithm when the HTTP request's `Accept-Encoding` header includes the string `gzip` or `deflate`. To prevent the downstream http.Handler from also seeing the `Accept-Encoding` request header, and possibly also compressing the data a second time, this function removes that header from the request.

NOTE: The specified next http.Handler ought not set `Content-Length` header, or the reported length value will be wrong. As a matter of fact, all HTTP response handlers ought to allow net/http library to set `Content-Length` response header or not based on a handful of RFCs.

mux := http.NewServeMux()
mux.Handle("/example/path", gohm.WithCompression(someHandler))

func WithGzip ¶

func WithGzip(next http.Handler) http.Handler

WithGzip returns a new http.Handler that optionally compresses the response text using the gzip compression algorithm when the HTTP request's `Accept-Encoding` header includes the string `gzip`.

NOTE: The specified next http.Handler ought not set `Content-Length` header, or the reported length value will be wrong. As a matter of fact, all HTTP response handlers ought to allow net/http library to set `Content-Length` response header or not based on a handful of RFCs.

mux := http.NewServeMux()
mux.Handle("/example/path", gohm.WithGzip(someHandler))

func WithRequestDumper ¶

func WithRequestDumper(flag *uint32, next http.Handler) http.Handler

WithRequestDumper wraps http.Handler and optionally dumps the request when the specified flag is non-zero. It uses atomic.LoadUnit32 to read the flag. When 0, requests will not be dumped. When 1, all but the body will be dumped. When 2, the entire request including the body will be dumped.

func XFrameOptions ¶

func XFrameOptions(value string, next http.Handler) http.Handler

XFrameOptions sets the X-Frame-Options response header to the specified value, then serves the request by the specified next handler.

The X-Frame-Options HTTP response header is frequently used to block against clickjacking attacks. See https://tools.ietf.org/html/rfc7034 for more information.

someHandler = gohm.XFrameOptions("SAMEORIGIN", someHandler)