mirror of
https://github.com/restic/rest-server.git
synced 2025-12-07 09:36:13 -08:00
64 lines
3.0 KiB
Go
64 lines
3.0 KiB
Go
/*
|
|
Package goji is a minimalistic and flexible HTTP request multiplexer.
|
|
|
|
Goji itself has very few features: it is first and foremost a standard set of
|
|
interfaces for writing web applications. Several subpackages are distributed
|
|
with Goji to provide standard production-ready implementations of several of the
|
|
interfaces, however users are also encouraged to implement the interfaces on
|
|
their own, especially if their needs are unusual.
|
|
*/
|
|
package goji
|
|
|
|
import "net/http"
|
|
|
|
/*
|
|
Pattern determines whether a given request matches some criteria. Goji users
|
|
looking for a concrete type that implements this interface should consider
|
|
Goji's "pat" sub-package, which implements a small domain specific language for
|
|
HTTP routing.
|
|
|
|
Patterns typically only examine a small portion of incoming requests, most
|
|
commonly the HTTP method and the URL's RawPath. As an optimization, Goji can
|
|
elide calls to your Pattern for requests it knows cannot match. Pattern authors
|
|
who wish to take advantage of this functionality (and in some cases an
|
|
asymptotic performance improvement) can augment their Pattern implementations
|
|
with any of the following methods:
|
|
|
|
// HTTPMethods returns a set of HTTP methods that this Pattern matches,
|
|
// or nil if it's not possible to determine which HTTP methods might be
|
|
// matched. Put another way, requests with HTTP methods not in the
|
|
// returned set are guaranteed to never match this Pattern.
|
|
HTTPMethods() map[string]struct{}
|
|
|
|
// PathPrefix returns a string which all RawPaths that match this
|
|
// Pattern must have as a prefix. Put another way, requests with
|
|
// RawPaths that do not contain the returned string as a prefix are
|
|
// guaranteed to never match this Pattern.
|
|
PathPrefix() string
|
|
|
|
The presence or lack of these performance improvements should be viewed as an
|
|
implementation detail and are not part of Goji's API compatibility guarantee. It
|
|
is the responsibility of Pattern authors to ensure that their Match function
|
|
always returns correct results, even if these optimizations are not performed.
|
|
|
|
All operations on Patterns must be safe for concurrent use by multiple
|
|
goroutines.
|
|
*/
|
|
type Pattern interface {
|
|
// Match examines the input Request to determine if it matches some
|
|
// criteria, and if so returns a non-nil output Request. This returned
|
|
// Request will be passed to the middleware stack and the final Handler.
|
|
//
|
|
// Patterns often extract variables from the Request, for instance from
|
|
// the URL or from HTTP headers. In this case, it is common for the
|
|
// Request returned from the Match function to be derived from the input
|
|
// Request using the WithContext function, with a Context that contains
|
|
// those variable bindings. If no variable bindings are necessary,
|
|
// another common choice is to return the input Request unchanged.
|
|
//
|
|
// Match must not mutate the passed request if it returns nil.
|
|
// Implementers are also strongly discouraged from mutating the input
|
|
// Request even in the event of a match; instead, prefer making a copy.
|
|
Match(*http.Request) *http.Request
|
|
}
|