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.