github.com/volatiletech/authboss@v2.4.1+incompatible/tov2.md (about) 1 # Migrating to v2 from v1 2 3 As always, the best way to understand most of this is to look at the 4 [authboss-sample](https://github.com/volatiletech/authboss-sample). You could even look at 5 the commits that lead from v1 to v2 (though it is not divided nicely into small commits). 6 7 ## Configuration 8 9 The configuration has been changed drastically from an API perspective as it's now sub-divided 10 with substructs into pieces. But in general the same options should be available with few exceptions. 11 12 In most cases the replacements will be very straightforward, and if you were using the default values 13 nothing much should have to change. 14 15 ## HTTP Stack (and defaults package) 16 17 The HTTP stack has been ripped apart into several small interfaces defined in the config struct. 18 Before you panic when you see Responder, Redirector, BodyReader etc, it's important to see the 19 `defaults` package in Authboss. This package contains sane default implementations for all of 20 these components (with the exception of an html renderer, though a JSON one is present). 21 22 You probably will not want to override any of these and so I'd suggest a peek at the method 23 `default.SetCore` (used in the sample as well) that sets up these default implementations 24 easily. 25 26 There is also an HTML renderer available at 27 [authboss-renderer](https://github.com/volatiletech/authboss-renderer). 28 29 ## Server storage 30 31 ### Understanding User vs Storer 32 33 In the past Authboss used extremely confusing terminology and sort of a conflated 34 design of User and Storer (database). In v2 these concepts have been separated and 35 there is now a User interface and a ServerStorer interface. These two interfaces represent 36 the concepts of the User data, and the Server storage mechanism that loads and saves 37 users. 38 39 The user interface is now implemented without reflection. Previously in Authboss we would 40 scrape the values from your struct, and update them via reflection as well. This is extremely 41 error prone and relies on hardcoded types everywhere and it just generally was a bad idea. 42 Despite the verbosity of using methods for every single field value we want, it's type safe 43 and provides a great spot for doing type conversions between whatever you're using in your 44 struct/database and whatever authboss wants for talking to web clients. 45 46 ### ServerStorer 47 48 This interface simply needs to Load and Save Users at the outset. Just like before there 49 are upgraded interfaces that are required by other modules, for example the `recover` module 50 wants a `RecoveringServerStorer` which has the method `LoadByRecoverToken` which you'll have 51 to add to your storer. 52 53 ### User 54 55 Your user struct should be able to remain the same, and all you need to do is add the methods 56 required for getting and setting the fields. Remember the methods are dictated by the interfaces 57 required by the modules you're loading (see authboss README.md for more details). For example 58 the `auth` module requires an `AuthableUser` which requires `Get|PutPassword` methods. 59 60 ## Client state 61 62 The client state interfaces have been rewritten to do a just-in-time write to the response 63 before the headers are completely flushed. This makes sure we only Read and only Write the 64 client state (cookies/sessions) one time. It requires a new middleware `LoadClientStateMiddleware` 65 which wraps the responsewriter with a new one that has the ability to manage client state. 66 67 In the ClientStateReadWriter interface (the one you now implement to handle sessions and cookies) 68 you now return a ClientState interface (basically a map of values) that represents a snapshot of the 69 state of the client when the request was initially read, this ensures that code will use the context 70 for value passing through the middleware stack and not the session as an added bonus. 71 Essentially this ClientState caches the values for the remainder of the request. 72 73 Events are written to the ResponseWriter and eventually the `WriteState` method is called and is 74 given the old state and the events that occurred during request processing, asks for a new state 75 to be written out to the responsewriter's headers.