trout
2015-12-13
Parent:6c6ea726570a
trout/doc.go
Publish under MIT license. Add a license so this package can officially be used by any project, basically.
| paddy@0 | 1 /* |
| paddy@0 | 2 Package trout provides an opinionated router that's implemented |
| paddy@0 | 3 using a basic trie. |
| paddy@0 | 4 |
| paddy@0 | 5 The router is opinionated and biased towards basic RESTful |
| paddy@0 | 6 services. Its main constraint is that its URL templating is very |
| paddy@0 | 7 basic and has no support for regular expressions, prefix matching, |
| paddy@0 | 8 or anything other than a direct equality comparison, unlike many |
| paddy@0 | 9 routing libraries. |
| paddy@0 | 10 |
| paddy@0 | 11 The router is specifically designed to support users that want to |
| paddy@0 | 12 return correct information with HEAD requests, so it enables users |
| paddy@0 | 13 to retrieve a list of HTTP methods an Endpoint is configured to |
| paddy@0 | 14 respond to. It will not return the configurations an Endpoint is |
| paddy@0 | 15 implicitly configured to respond to by associated a Handler with the |
| paddy@0 | 16 Endpoint itself. These HTTP methods can be accessed through the |
| paddy@0 | 17 Trout-Methods header that is injected into the http.Request object. |
| paddy@0 | 18 Each method will be its own string in the slice. |
| paddy@0 | 19 |
| paddy@0 | 20 The router is also specifically designed to differentiate between a |
| paddy@0 | 21 404 (Not Found) response and a 405 (Method Not Allowed) response. It |
| paddy@0 | 22 will use the configured Handle404 http.Handler when no Endpoint is found |
| paddy@0 | 23 that matches the http.Request's Path property. It will use the |
| paddy@0 | 24 configured Handle405 http.Handler when an Endpoint is found for the |
| paddy@0 | 25 http.Request's Path, but the http.Request's Method has no Handler |
| paddy@0 | 26 associated with it. Setting a default http.Handler for the Endpoint will |
| paddy@0 | 27 result in the Handle405 http.Handler never being used for that Endpoint. |
| paddy@0 | 28 |
| paddy@0 | 29 To map an Endpoint to a http.Handler: |
| paddy@0 | 30 |
| paddy@0 | 31 var router trout.Router |
| paddy@0 | 32 router.Endpoint("/posts/{slug}/comments/{id}").Handler(postsHandler) |
| paddy@0 | 33 |
| paddy@0 | 34 All requests that match that URL structure will be passed to the postsHandler, |
| paddy@0 | 35 no matter what HTTP method they use. |
| paddy@0 | 36 |
| paddy@0 | 37 To map specific Methods to a http.Handler: |
| paddy@0 | 38 |
| paddy@0 | 39 var router trout.Router |
| paddy@0 | 40 router.Endpoint("/posts/{slug}").Methods("GET", "POST").Handler(postsHandler) |
| paddy@0 | 41 |
| paddy@0 | 42 Only requests that match that URL structure will be passed to the postsHandler, |
| paddy@0 | 43 and only if they use the GET or POST HTTP method. |
| paddy@0 | 44 |
| paddy@0 | 45 To access the URL parameter values inside a request, use the RequestVars helper: |
| paddy@0 | 46 |
| paddy@0 | 47 func handler(w http.ResponseWriter, r *http.Request) { |
| paddy@0 | 48 vars := trout.RequestVars(r) |
| paddy@0 | 49 ... |
| paddy@0 | 50 } |
| paddy@0 | 51 |
| paddy@0 | 52 This will return an http.Header object containing the parameter values. They are |
| paddy@0 | 53 passed into the http.Handler by injecting them into the http.Request's Header property, |
| paddy@0 | 54 with the header key of "Trout-Params-{parameter}". The RequestVars helper is just a |
| paddy@0 | 55 convenience function to strip the prefix. Parameters are always passed without the curly |
| paddy@0 | 56 braces. Finally, if a parameter name is used multiple times in a single URL template, values |
| paddy@0 | 57 will be stored in the slice in the order they appeared in the template: |
| paddy@0 | 58 |
| paddy@0 | 59 // for the template /posts/{id}/comments/{id} |
| paddy@0 | 60 // filled with /posts/hello-world/comments/1 |
| paddy@0 | 61 vars := trout.RequestVars(r) |
| paddy@0 | 62 fmt.Println(vars.Get("id")) // outputs `hello-world` |
| paddy@0 | 63 fmt.Println(vars[http.CanonicalHeaderKey("id")]) // outputs `["hello-world", "1"]` |
| paddy@0 | 64 fmt.Println(vars[http.CanonicalHeaderKey("id"})][1]) // outputs `1` |
| paddy@0 | 65 */ |
| paddy@0 | 66 package trout |