Skip to content

Commit 27190e3

Browse files
aarondlaarondl
committed
Update changelog.
- Add tov2.md upgrade guide
1 parent c38f794 commit 27190e3

2 files changed

Lines changed: 152 additions & 4 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 77 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,88 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
55

66
## [Unreleased]
77

8-
## [2.0.0] - 2018-01-??
8+
## [2.0.0-rc2] - 2018-05-14
9+
10+
Mostly rewrote Authboss by changing many of the core interfaces. This release
11+
is instrumental in providing better support for integrating with many web frameworks
12+
and setups.
13+
914
### Added
15+
16+
- v2 Upgrade guide (tov2.md)
17+
18+
- API/JSON Support
19+
20+
Because of the new abstractions it's possible to implement body readers,
21+
responders, redirectors and renderers that all speak JSON (or anything else for that
22+
matter). There are a number of these that exist already in the defaults package.
23+
1024
### Changed
11-
### Deprecated
25+
26+
- The core functionality of authboss is now delivered over a set of interfaces
27+
28+
This change was fairly massive. We've abstracted the HTTP stack completely
29+
so that authboss isn't really doing things like issuing template renderings,
30+
it's just asking a small interface to do it instead. The reason for doing this
31+
was because the previous design was too inflexible and wouldn't integrate nicely
32+
with various frameworks etc. The defaults package helps fill in the gaps for typical
33+
use cases.
34+
35+
- Storage is now done by many small interfaces
36+
37+
It became apparent than the old reflect-based mapping was a horrible solution
38+
to passing data back and forth between these structs. So instead we've created a
39+
much more verbose (but type safe) set of interfaces to govern which fields we need.
40+
41+
Now we can check that our structs have the correct methods using variable declarations
42+
and there's no more confusion about how various types map back and forth inside the
43+
mystical `Bind` and `Unbind` methods.
44+
45+
The downside to this of course is it's incredibly verbose to create a fully featured
46+
model, but I think that the benefits outweigh the downsides (see bugs in the past about
47+
different types being broken/not supported/not working correctly).
48+
49+
- Support for context.Context is now much better
50+
51+
We had a few pull requests that kind of shoved context.Context support in the sides
52+
so that authboss would work in Google App Engine. With this release context is
53+
almost everywhere that an external system would be interacted with.
54+
55+
- Client State management rewritten
56+
57+
The old method of client state management performed writes too frequently. By using a
58+
collection of state change events that are later applied in a single write operation at
59+
the end, we make it so we don't get duplicate cookies etc. The bad thing about this is
60+
that we have to wrap the ResponseWriter. But there's an UnderlyingResponseWriter
61+
interface to deal with this problem.
62+
63+
- Validation has been broken into smaller and hopefully nicer interfaces
64+
65+
Validation needs to be handled by the BodyReader's set of returned structs. This punts
66+
validation outside of the realm of Authboss for the most part, but there's still
67+
helpful tools in the defaults package to help with validation if you're against writing
68+
rolling your own.
69+
70+
- Logout has been broken out into it's own module to avoid duplication inside login/oauth2
71+
since they perform the same function.
72+
73+
- Config is now a nested struct, this helps organize the properties a little better (but
74+
I hope you never mouse over the type definition in a code editor).
75+
1276
### Removed
77+
78+
- Notable removal of AllowInsecureLoginAfterConfirm
79+
1380
### Fixed
14-
### Security
1581

16-
## 2015-08-02
82+
- Fix bug where e-mail with only a textbody would send blank e-mails
83+
84+
### Deprecated
85+
86+
- Use of gopkg.in, it's no longer a supported method of consuming authboss. Use
87+
manual vendoring, dep or vgo.
88+
89+
## [1.0.0] - 2015-08-02
1790
### Changed
1891
This change is potentially breaking, it did break the sample since the supporting struct was wrong for the data we were using.
1992

‎tov2.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
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 and not the session as an added bonus. But basically caches the client state
71+
values for the remainder of the request.
72+
73+
Events are written to the ResponseWriter and eventually the `WriteState` method is called and give
74+
the old state and the events that occurred during request processing, asks for a new state to be
75+
written out to the responsewriter's headers.

0 commit comments

Comments
 (0)