diff --git a/CHANGELOG.md b/CHANGELOG.md index 12e388bc..38d9eb79 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,15 +5,88 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [Unreleased] -## [2.0.0] - 2018-01-?? +## [2.0.0-rc2] - 2018-05-14 + +Mostly rewrote Authboss by changing many of the core interfaces. This release +is instrumental in providing better support for integrating with many web frameworks +and setups. + ### Added + +- v2 Upgrade guide (tov2.md) + +- API/JSON Support + + Because of the new abstractions it's possible to implement body readers, + responders, redirectors and renderers that all speak JSON (or anything else for that + matter). There are a number of these that exist already in the defaults package. + ### Changed -### Deprecated + +- The core functionality of authboss is now delivered over a set of interfaces + + This change was fairly massive. We've abstracted the HTTP stack completely + so that authboss isn't really doing things like issuing template renderings, + it's just asking a small interface to do it instead. The reason for doing this + was because the previous design was too inflexible and wouldn't integrate nicely + with various frameworks etc. The defaults package helps fill in the gaps for typical + use cases. + +- Storage is now done by many small interfaces + + It became apparent than the old reflect-based mapping was a horrible solution + to passing data back and forth between these structs. So instead we've created a + much more verbose (but type safe) set of interfaces to govern which fields we need. + + Now we can check that our structs have the correct methods using variable declarations + and there's no more confusion about how various types map back and forth inside the + mystical `Bind` and `Unbind` methods. + + The downside to this of course is it's incredibly verbose to create a fully featured + model, but I think that the benefits outweigh the downsides (see bugs in the past about + different types being broken/not supported/not working correctly). + +- Support for context.Context is now much better + + We had a few pull requests that kind of shoved context.Context support in the sides + so that authboss would work in Google App Engine. With this release context is + almost everywhere that an external system would be interacted with. + +- Client State management rewritten + + The old method of client state management performed writes too frequently. By using a + collection of state change events that are later applied in a single write operation at + the end, we make it so we don't get duplicate cookies etc. The bad thing about this is + that we have to wrap the ResponseWriter. But there's an UnderlyingResponseWriter + interface to deal with this problem. + +- Validation has been broken into smaller and hopefully nicer interfaces + + Validation needs to be handled by the BodyReader's set of returned structs. This punts + validation outside of the realm of Authboss for the most part, but there's still + helpful tools in the defaults package to help with validation if you're against writing + rolling your own. + +- Logout has been broken out into it's own module to avoid duplication inside login/oauth2 + since they perform the same function. + +- Config is now a nested struct, this helps organize the properties a little better (but + I hope you never mouse over the type definition in a code editor). + ### Removed + +- Notable removal of AllowInsecureLoginAfterConfirm + ### Fixed -### Security -## 2015-08-02 +- Fix bug where e-mail with only a textbody would send blank e-mails + +### Deprecated + +- Use of gopkg.in, it's no longer a supported method of consuming authboss. Use + manual vendoring, dep or vgo. + +## [1.0.0] - 2015-08-02 ### Changed This change is potentially breaking, it did break the sample since the supporting struct was wrong for the data we were using. diff --git a/tov2.md b/tov2.md new file mode 100644 index 00000000..5215353f --- /dev/null +++ b/tov2.md @@ -0,0 +1,75 @@ +# Migrating to v2 from v1 + +As always, the best way to understand most of this is to look at the +[authboss-sample](https://github.com/volatiletech/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](https://github.com/volatiletech/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 and not the session as an added bonus. But basically caches the client state +values for the remainder of the request. + +Events are written to the ResponseWriter and eventually the `WriteState` method is called and give +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.