1 /* 2 Package goji is a minimalistic and flexible HTTP request multiplexer. 3 4 Goji itself has very few features: it is first and foremost a standard set of 5 interfaces for writing web applications. Several subpackages are distributed 6 with Goji to provide standard production-ready implementations of several of the 7 interfaces, however users are also encouraged to implement the interfaces on 8 their own, especially if their needs are unusual. 9 */ 10 package goji 11 12 import "net/http" 13 14 /* 15 Pattern determines whether a given request matches some criteria. Goji users 16 looking for a concrete type that implements this interface should consider 17 Goji's "pat" sub-package, which implements a small domain specific language for 18 HTTP routing. 19 20 Patterns typically only examine a small portion of incoming requests, most 21 commonly the HTTP method and the URL's RawPath. As an optimization, Goji can 22 elide calls to your Pattern for requests it knows cannot match. Pattern authors 23 who wish to take advantage of this functionality (and in some cases an 24 asymptotic performance improvement) can augment their Pattern implementations 25 with any of the following methods: 26 27 // HTTPMethods returns a set of HTTP methods that this Pattern matches, 28 // or nil if it's not possible to determine which HTTP methods might be 29 // matched. Put another way, requests with HTTP methods not in the 30 // returned set are guaranteed to never match this Pattern. 31 HTTPMethods() map[string]struct{} 32 33 // PathPrefix returns a string which all RawPaths that match this 34 // Pattern must have as a prefix. Put another way, requests with 35 // RawPaths that do not contain the returned string as a prefix are 36 // guaranteed to never match this Pattern. 37 PathPrefix() string 38 39 The presence or lack of these performance improvements should be viewed as an 40 implementation detail and are not part of Goji's API compatibility guarantee. It 41 is the responsibility of Pattern authors to ensure that their Match function 42 always returns correct results, even if these optimizations are not performed. 43 44 All operations on Patterns must be safe for concurrent use by multiple 45 goroutines. 46 */ 47 type Pattern interface { 48 // Match examines the input Request to determine if it matches some 49 // criteria, and if so returns a non-nil output Request. This returned 50 // Request will be passed to the middleware stack and the final Handler. 51 // 52 // Patterns often extract variables from the Request, for instance from 53 // the URL or from HTTP headers. In this case, it is common for the 54 // Request returned from the Match function to be derived from the input 55 // Request using the WithContext function, with a Context that contains 56 // those variable bindings. If no variable bindings are necessary, 57 // another common choice is to return the input Request unchanged. 58 // 59 // Match must not mutate the passed request if it returns nil. 60 // Implementers are also strongly discouraged from mutating the input 61 // Request even in the event of a match; instead, prefer making a copy. 62 Match(*http.Request) *http.Request 63 } 64