ducky/devices
ducky/devices/vendor/code.secondbit.org/trout.hg/doc.go
Add updating devices to apiv1. We needed a way to be able to update devices after they were created. This is supported in the devices package, we just needed to expose it using apiv1 endpoints. In doing so, it became apparent that allowing users to change the Owner of their Devices wasn't properly thought through, and pending a reason to use it, I'm just removing it. The biggest issue came when trying to return usable error messages; we couldn't distinguish between "you don't own the device you're trying to update" and "you're not allowed to change the owner of the device". I also couldn't figure out _who should be able to_ change the owner of the device, which is generally an indication that I'm building a feature before I have a use case for it. To support this change, the apiv1.DeviceChange type needed its Owner property removed. I also needed to add deviceFromAPI and devicesFromAPI helpers to return devices.Device types from apiv1.Device types. There's now a new validateDeviceUpdate helper that checks to ensure that a device update request is valid and the user has the appropriate permissions. The createRequest type now accepts a slice of Devices, not a slice of DeviceChanges, because we want to pass the Owner in. A new updateRequest type is created, which accepts a DeviceChange to apply. A new handleUpdateDevice handler is created, which is assigned to the endpoint for PATCH requests against a device ID. It checks that the user is logged in, the Device they're trying to update exists, and that it's a valid update. If all of that is true, the device is updated and the updated device is returned. Finally, we had to add two new scopes to support new functionality: ScopeUpdateOtherUserDevices allows a user to update other user's devices, and ScopeUpdateLastSeen allows a user to update the LastSeen property of a device. Pending some better error messages, this should be a full implementation of updating a device, which leaves only the deletion endpoint to deal with.
| paddy@15 | 1 /* |
| paddy@15 | 2 Package trout provides an opinionated router that's implemented |
| paddy@15 | 3 using a basic trie. |
| paddy@15 | 4 |
| paddy@15 | 5 The router is opinionated and biased towards basic RESTful |
| paddy@15 | 6 services. Its main constraint is that its URL templating is very |
| paddy@15 | 7 basic and has no support for regular expressions, prefix matching, |
| paddy@15 | 8 or anything other than a direct equality comparison, unlike many |
| paddy@15 | 9 routing libraries. |
| paddy@15 | 10 |
| paddy@15 | 11 The router is specifically designed to support users that want to |
| paddy@15 | 12 return correct information with HEAD requests, so it enables users |
| paddy@15 | 13 to retrieve a list of HTTP methods an Endpoint is configured to |
| paddy@15 | 14 respond to. It will not return the configurations an Endpoint is |
| paddy@15 | 15 implicitly configured to respond to by associated a Handler with the |
| paddy@15 | 16 Endpoint itself. These HTTP methods can be accessed through the |
| paddy@15 | 17 Trout-Methods header that is injected into the http.Request object. |
| paddy@15 | 18 Each method will be its own string in the slice. |
| paddy@15 | 19 |
| paddy@15 | 20 The router is also specifically designed to differentiate between a |
| paddy@15 | 21 404 (Not Found) response and a 405 (Method Not Allowed) response. It |
| paddy@15 | 22 will use the configured Handle404 http.Handler when no Endpoint is found |
| paddy@15 | 23 that matches the http.Request's Path property. It will use the |
| paddy@15 | 24 configured Handle405 http.Handler when an Endpoint is found for the |
| paddy@15 | 25 http.Request's Path, but the http.Request's Method has no Handler |
| paddy@15 | 26 associated with it. Setting a default http.Handler for the Endpoint will |
| paddy@15 | 27 result in the Handle405 http.Handler never being used for that Endpoint. |
| paddy@15 | 28 |
| paddy@15 | 29 To map an Endpoint to a http.Handler: |
| paddy@15 | 30 |
| paddy@15 | 31 var router trout.Router |
| paddy@15 | 32 router.Endpoint("/posts/{slug}/comments/{id}").Handler(postsHandler) |
| paddy@15 | 33 |
| paddy@15 | 34 All requests that match that URL structure will be passed to the postsHandler, |
| paddy@15 | 35 no matter what HTTP method they use. |
| paddy@15 | 36 |
| paddy@15 | 37 To map specific Methods to a http.Handler: |
| paddy@15 | 38 |
| paddy@15 | 39 var router trout.Router |
| paddy@15 | 40 router.Endpoint("/posts/{slug}").Methods("GET", "POST").Handler(postsHandler) |
| paddy@15 | 41 |
| paddy@15 | 42 Only requests that match that URL structure will be passed to the postsHandler, |
| paddy@15 | 43 and only if they use the GET or POST HTTP method. |
| paddy@15 | 44 |
| paddy@15 | 45 To access the URL parameter values inside a request, use the RequestVars helper: |
| paddy@15 | 46 |
| paddy@15 | 47 func handler(w http.ResponseWriter, r *http.Request) { |
| paddy@15 | 48 vars := trout.RequestVars(r) |
| paddy@15 | 49 ... |
| paddy@15 | 50 } |
| paddy@15 | 51 |
| paddy@15 | 52 This will return an http.Header object containing the parameter values. They are |
| paddy@15 | 53 passed into the http.Handler by injecting them into the http.Request's Header property, |
| paddy@15 | 54 with the header key of "Trout-Params-{parameter}". The RequestVars helper is just a |
| paddy@15 | 55 convenience function to strip the prefix. Parameters are always passed without the curly |
| paddy@15 | 56 braces. Finally, if a parameter name is used multiple times in a single URL template, values |
| paddy@15 | 57 will be stored in the slice in the order they appeared in the template: |
| paddy@15 | 58 |
| paddy@15 | 59 // for the template /posts/{id}/comments/{id} |
| paddy@15 | 60 // filled with /posts/hello-world/comments/1 |
| paddy@15 | 61 vars := trout.RequestVars(r) |
| paddy@15 | 62 fmt.Println(vars.Get("id")) // outputs `hello-world` |
| paddy@15 | 63 fmt.Println(vars[http.CanonicalHeaderKey("id")]) // outputs `["hello-world", "1"]` |
| paddy@15 | 64 fmt.Println(vars[http.CanonicalHeaderKey("id"})][1]) // outputs `1` |
| paddy@15 | 65 */ |
| paddy@15 | 66 package trout |