Per-request state management middleware.
npm install flowstateThis middleware manages and propagates per-request state across HTTP requests to
a web application. This allows for implementing flows which are sequences of
requests and responses that, taken together, culminate in a desired outcome.
By default, this state is kept in the session. The session itself stores state
by setting a cookie which applies to _all_ requests to an application. This
middleware isolates that state so it can be applied to an individual sequence of
requests. To do this, state is propagated in return_to and state parameters
across requests. This middleware does this automatically whenever possible,
such as when redirecting. When not possible, such as when rendering a view,
locals and helpers are made available to the view so that return_to andstate parameters can be added to links and forms.
This middleware emerged from the state management functionality implemented by
authentication-related packages, in particular passport-oauth2 and
oauth2orize which implement OAuth 2.0. With
this package, the functionality is made generic so that it can be applied to
any HTTP endpoint.
``bash`
$ npm install flowstate
#### Add Middleware
Add state middleware to your application or route:
`js
var flowstate = require('flowstate');
app.get('/login', flowstate(), function(req, res, next) {
// ...
});
`
The middleware will attempt to load any state intended for the endpoint, based
the state parameter in the query or body of the request. If state is loaded,req.state
it will be set at so that the handler can process it. The value setreq.state
at is referred to as the "current state".
If state is not loaded, an "uninitialized" state will be set at req.state. Areturn_to
state is uninitialized when it is new but not modified. If the request contains
a and optional state parameter, those will be captured by the
uninitialized state as the location to return the user to when the current state
has been completely processed.
When a response is sent, any modifications to the current state will be saved
if the state is not complete. If the state is complete, any persisted state
will be removed. Note that an uninitialized state will never be saved since it
is not modified. However, the location to return the user to will be preserved
by propagating the return_to and optional state parameters on subsequent
requests.
#### Render a View
`js
app.get('/login', flowstate(), function(req, res, next) {
var msgs = req.state.messages || [];
res.locals.messages = msgs;
res.locals.hasMessages = !! msgs.length;
res.render('login');
});
`
When a response is sent by rendering a view, if there is state associated with
the request, res.locals.state will be set to the current state's handle.return_to
Otherwise the and state parameters, if any, will be propagated byres.locals.returnTo
setting and res.locals.state. The view is expected to
decorate links with these properties and add them as hidden input to forms, in
order to propagate state to subsequent requests.
For example, if the above /login endpoint is requested with a return_to
parameter:
`http`
GET /login?return_to=%2Fdashboard HTTP/1.1
Then res.locals.returnTo will be set to /dashboard, making it available to
the view.
If the /login endpoint is requested with both a return_to and state
parameter:
`http`
GET /login?return_to=%2Fauthorize%2Fcontinue&state=xyz HTTP/1.1
Then res.locals.returnTo will be set to /authorize/continue and res.locals.statexyz
will be set to , making them available to the view.
If the /login endpoint is requested with:
`http`
GET /login?state=Zwu8y84x HTTP/1.1
Assuming the state was valid and intended for /login, res.locals.state willZwu8y84x
be set to and made available to the view. res.locals.returnTo will
_not_ be set.
#### Redirect to a Location
`js
app.post('/login', flowstate(), authenticate(), function(req, res, next) {
if (mfaRequired(req.user)) {
return res.redirect('/stepup');
}
// ...
}, function(err, req, res, next) {
if (err.status !== 401) { return next(err); }
req.state.messages = req.state.messages || [];
req.state.messages.push('Invalid username or password.');
req.state.failureCount = req.state.failureCount ? req.state.failureCount + 1 : 1;
req.state.complete(false);
res.redirect('/login');
});
`
When a response redirects the browser, if the current state is complete, any
return_to and state parameters will be propagated by decorating the target
URL. If the current state is not complete, modifications will be saved and the
redirect will be decorated with the current state's handle.
For example, if the above /login endpoint is requested with a return_to andstate parameter:
`http
POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded
username=alice&password=letmein&return_to=%2Fauthorize%2Fcontinue&state=xyz
`
Then the user will be redirected to /stepup?return_to=%2Fauthorize%2Fcontinue&state=xyz,
assuming the password is valid and MFA is required.
If the password is not valid, an uninitialized state is set at req.state thatreturn_to
captures the and state parameters. It is then saved and the user/login?state=Zwu8y84x
is redirected to (where 'Zwu8y84x' is the handle of
the newly saved state). The state data stored in the session is as follows:
`json`
{
"state": {
"Zwu8y84x": {
"location": "https://www.example.com/login",
"messages": [ "Invalid username or password." ],
"failureCount": 1,
"returnTo": "/authorize/continue",
"state": "xyz"
}
}
}
This redirect will cause the browser to request the GET /login route above.state=Zwu8y84x
Since the request is made with a query parameter, the route willstate
load the state and make the handle (as well as messages) available to the view.
The view must add the handle to the login form as a hidden input field named. When submitted, the browser will then make a request with that state
parameter:
`http
POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded
username=alice&password=letmeinnow&state=Zwu8y84x
`
This time, the POST /login route will load the state. If the password is/stepup?return_to=%2Fauthorize%2Fcontinue&state=xyz
valid and MFA is required, the user will be will be redirected to, as before. This isreturn_to
because the original and state parameters were captured by the
loaded state object, and are propagated by decorating the redirect location.
If another invalid password is submitted, the cycle of redirecting, rendering
the login view, and prompting the user for a password will repeat, with the
failureCount incremented and saved each time.
#### Resume State
`js
app.post('/login', flowstate(), authenticate(), function(req, res, next) {
if (mfaRequired(req.user)) {
return res.redirect('/stepup');
}
res.resumeState(next);
}, function(req, res, next) {
res.redirect('/');
}, function(err, req, res, next) {
// ...
});
`
When a user has completed a given flow, they should be returned to the location
they were navigating prior to entering the flow. This is accomplished by
calling resumeState(), a function added to the response by this middleware.
If a current state was loaded, resumeState() will return the user to thereturn_to
captured and state parameters, if any. Otherwise, it will returnreturn_to
the user to the and state parameters carried by the request. IfresumeState()
neither of these exist, will call a callback, which willnext
typically be to invoke the next middleware. This middleware can then
redirect the user to a default location.
For example, when POST /login is requested with a state parameter:
`http
POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded
username=alice&password=letmeinnow&state=Zwu8y84x
`
Then the user will be redirected to /authorize/continue&state=xyz,
assuming the password is valid and MFA is not required.
If the /login endpoint is requested with a return_to parameter:
`http
POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded
username=alice&password=letmein&return_to=%2Fdashboard
`
Then the user will be redirected to /dashboard, after logging in.
If the /login endpoint is requested without any state-related parameters:
`http
POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded
username=alice&password=letmein
`
Then the user will be redirected to /` by the next middleware in the stack.
#### Push State
- Jared Hanson {      }
Copyright (c) 2016-2023 Jared Hanson