ducky/devices
ducky/devices/vendor/code.secondbit.org/trout.hg/doc.go
Begin implementation on apiv1. Begin implementing the apiv1 package, which will define the first iteration of our API endpoints and logic. Each API package should be self-contained and able to run without depending on each other. Think of them as interfaces into manipulating the business logic defined in the devices package. The point is to have total control over backwards compatibility, as long as our business logic doesn't change. If that happens, we're in a bad place, but not as bad as it could be. This required us to pull in all our API tools; the api package, its dependencies, the scopeTypes package (so we can define scopes for our API), the trout router, etc. We also updated uuid to the latest, which now includes a license. Hooray? The new apiv1 package consists of a few things: * The devices.go file defines the types the API will use to communicate, along with some helpers to convert from API types to devices types. There's also a stub for validating the device creation requests, which I haven't implemented yet because I'm a pretty bad person. * endpoints.go just contains a helper function that builds our routes and assigns handlers to them, giving us an http.Handler in the returns that we can listen with. * handlers.go defines our HTTP handlers, which will read requests and write responses, after doing the appropriate validation and executing the appropriating business logic. Right now, we only have a handler for creating devices, and it doesn't actually do any validation. Also, we have some user-correctable errors being returned as 500s right now, which is Bad. Fortunately, they're all marked with BUG, so I can at least come back to them. * response.go defines the Response type that will be used for returning information after a request is executed. It may eventually get some helpers, but for now it's pretty basic. * scopes.go defines the Scopes that we're going to be using in the package to control access. It should probably (eventually) include a helper to register the Scopes, or we should have a collector service that pulls in all the packages, finds all their Scopes, and registers them. I haven't decided how I want to manage Scope registration just yet. We exported the getStorer function (now GetStorer) so other packages can use it. I'm not sure how I feel about this just yet. We also had to create a WithStorer helper method that embeds the Storer into a context.Context, so we can bootstrap in devicesd. We erroneously had Created in the DeviceChange struct, but there's no reason the Created property of a Device should ever change, so it was removed from the logic, from the struct, and from the tests. Our CreateMany helper was erroneously creating the un-modified Devices that were passed in, instead of the Devices that had sensible defaults filled. We created a _very minimal_ (e.g., needs some work before it's ready for production) devicesd package that will spin up a simple server, just so we could take a peek at our apiv1 endpoints as they'd actually be used. (It worked. Yay?) We should continue to expand on this with configuration, more information being logged, etc.
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/vendor/code.secondbit.org/trout.hg/doc.go Mon Dec 14 00:12:33 2015 -0800 1.3 @@ -0,0 +1,66 @@ 1.4 +/* 1.5 +Package trout provides an opinionated router that's implemented 1.6 +using a basic trie. 1.7 + 1.8 +The router is opinionated and biased towards basic RESTful 1.9 +services. Its main constraint is that its URL templating is very 1.10 +basic and has no support for regular expressions, prefix matching, 1.11 +or anything other than a direct equality comparison, unlike many 1.12 +routing libraries. 1.13 + 1.14 +The router is specifically designed to support users that want to 1.15 +return correct information with HEAD requests, so it enables users 1.16 +to retrieve a list of HTTP methods an Endpoint is configured to 1.17 +respond to. It will not return the configurations an Endpoint is 1.18 +implicitly configured to respond to by associated a Handler with the 1.19 +Endpoint itself. These HTTP methods can be accessed through the 1.20 +Trout-Methods header that is injected into the http.Request object. 1.21 +Each method will be its own string in the slice. 1.22 + 1.23 +The router is also specifically designed to differentiate between a 1.24 +404 (Not Found) response and a 405 (Method Not Allowed) response. It 1.25 +will use the configured Handle404 http.Handler when no Endpoint is found 1.26 +that matches the http.Request's Path property. It will use the 1.27 +configured Handle405 http.Handler when an Endpoint is found for the 1.28 +http.Request's Path, but the http.Request's Method has no Handler 1.29 +associated with it. Setting a default http.Handler for the Endpoint will 1.30 +result in the Handle405 http.Handler never being used for that Endpoint. 1.31 + 1.32 +To map an Endpoint to a http.Handler: 1.33 + 1.34 + var router trout.Router 1.35 + router.Endpoint("/posts/{slug}/comments/{id}").Handler(postsHandler) 1.36 + 1.37 +All requests that match that URL structure will be passed to the postsHandler, 1.38 +no matter what HTTP method they use. 1.39 + 1.40 +To map specific Methods to a http.Handler: 1.41 + 1.42 + var router trout.Router 1.43 + router.Endpoint("/posts/{slug}").Methods("GET", "POST").Handler(postsHandler) 1.44 + 1.45 +Only requests that match that URL structure will be passed to the postsHandler, 1.46 +and only if they use the GET or POST HTTP method. 1.47 + 1.48 +To access the URL parameter values inside a request, use the RequestVars helper: 1.49 + 1.50 + func handler(w http.ResponseWriter, r *http.Request) { 1.51 + vars := trout.RequestVars(r) 1.52 + ... 1.53 + } 1.54 + 1.55 +This will return an http.Header object containing the parameter values. They are 1.56 +passed into the http.Handler by injecting them into the http.Request's Header property, 1.57 +with the header key of "Trout-Params-{parameter}". The RequestVars helper is just a 1.58 +convenience function to strip the prefix. Parameters are always passed without the curly 1.59 +braces. Finally, if a parameter name is used multiple times in a single URL template, values 1.60 +will be stored in the slice in the order they appeared in the template: 1.61 + 1.62 + // for the template /posts/{id}/comments/{id} 1.63 + // filled with /posts/hello-world/comments/1 1.64 + vars := trout.RequestVars(r) 1.65 + fmt.Println(vars.Get("id")) // outputs `hello-world` 1.66 + fmt.Println(vars[http.CanonicalHeaderKey("id")]) // outputs `["hello-world", "1"]` 1.67 + fmt.Println(vars[http.CanonicalHeaderKey("id"})][1]) // outputs `1` 1.68 +*/ 1.69 +package trout