1
0
mirror of https://github.com/volatiletech/authboss.git synced 2024-11-24 08:42:17 +02:00
authboss/tov2.md
2018-09-03 13:03:41 -07:00

4.0 KiB

Migrating to v2 from v1

As always, the best way to understand most of this is to look at the authboss-sample. You could even look at the commits that lead from v1 to v2 (though it is not divided nicely into small commits).

Configuration

The configuration has been changed drastically from an API perspective as it's now sub-divided with substructs into pieces. But in general the same options should be available with few exceptions.

In most cases the replacements will be very straightforward, and if you were using the default values nothing much should have to change.

HTTP Stack (and defaults package)

The HTTP stack has been ripped apart into several small interfaces defined in the config struct. Before you panic when you see Responder, Redirector, BodyReader etc, it's important to see the defaults package in Authboss. This package contains sane default implementations for all of these components (with the exception of an html renderer, though a JSON one is present).

You probably will not want to override any of these and so I'd suggest a peek at the method default.SetCore (used in the sample as well) that sets up these default implementations easily.

There is also an HTML renderer available at authboss-renderer.

Server storage

Understanding User vs Storer

In the past Authboss used extremely confusing terminology and sort of a conflated design of User and Storer (database). In v2 these concepts have been separated and there is now a User interface and a ServerStorer interface. These two interfaces represent the concepts of the User data, and the Server storage mechanism that loads and saves users.

The user interface is now implemented without reflection. Previously in Authboss we would scrape the values from your struct, and update them via reflection as well. This is extremely error prone and relies on hardcoded types everywhere and it just generally was a bad idea. Despite the verbosity of using methods for every single field value we want, it's type safe and provides a great spot for doing type conversions between whatever you're using in your struct/database and whatever authboss wants for talking to web clients.

ServerStorer

This interface simply needs to Load and Save Users at the outset. Just like before there are upgraded interfaces that are required by other modules, for example the recover module wants a RecoveringServerStorer which has the method LoadByRecoverToken which you'll have to add to your storer.

User

Your user struct should be able to remain the same, and all you need to do is add the methods required for getting and setting the fields. Remember the methods are dictated by the interfaces required by the modules you're loading (see authboss README.md for more details). For example the auth module requires an AuthableUser which requires Get|PutPassword methods.

Client state

The client state interfaces have been rewritten to do a just-in-time write to the response before the headers are completely flushed. This makes sure we only Read and only Write the client state (cookies/sessions) one time. It requires a new middleware LoadClientStateMiddleware which wraps the responsewriter with a new one that has the ability to manage client state.

In the ClientStateReadWriter interface (the one you now implement to handle sessions and cookies) you now return a ClientState interface (basically a map of values) that represents a snapshot of the state of the client when the request was initially read, this ensures that code will use the context for value passing through the middleware stack and not the session as an added bonus. Essentially this ClientState caches the values for the remainder of the request.

Events are written to the ResponseWriter and eventually the WriteState method is called and is given the old state and the events that occurred during request processing, asks for a new state to be written out to the responsewriter's headers.