| 1 |
NAME |
| 2 |
|
| 3 |
Plack::Middleware::Session - Middleware for session management |
| 4 |
|
| 5 |
SYNOPSIS |
| 6 |
|
| 7 |
use Plack::Builder; |
| 8 |
|
| 9 |
my $app = sub { |
| 10 |
my $env = shift; |
| 11 |
my $session = $env->{'psgix.session'}; |
| 12 |
return [ |
| 13 |
200, |
| 14 |
[ 'Content-Type' => 'text/plain' ], |
| 15 |
[ "Hello, you've been here for ", $session->{counter}++, "th time!" ], |
| 16 |
]; |
| 17 |
}; |
| 18 |
|
| 19 |
builder { |
| 20 |
enable 'Session'; |
| 21 |
$app; |
| 22 |
}; |
| 23 |
|
| 24 |
# Or, use the File store backend (great if you use multiprocess server) |
| 25 |
# For more options, see perldoc Plack::Session::Store::File |
| 26 |
builder { |
| 27 |
enable 'Session', store => 'File'; |
| 28 |
$app; |
| 29 |
}; |
| 30 |
|
| 31 |
DESCRIPTION |
| 32 |
|
| 33 |
This is a Plack Middleware component for session management. By default |
| 34 |
it will use cookies to keep session state and store data in memory. |
| 35 |
This distribution also comes with other state and store solutions. See |
| 36 |
perldoc for these backends how to use them. |
| 37 |
|
| 38 |
It should be noted that we store the current session as a hash |
| 39 |
reference in the psgix.session key inside the $env where you can access |
| 40 |
it as needed. |
| 41 |
|
| 42 |
NOTE: As of version 0.04 the session is stored in psgix.session instead |
| 43 |
of plack.session. |
| 44 |
|
| 45 |
State |
| 46 |
|
| 47 |
Plack::Session::State |
| 48 |
|
| 49 |
This will maintain session state by passing the session through the |
| 50 |
request params. It does not do this automatically though, you are |
| 51 |
responsible for passing the session param. |
| 52 |
|
| 53 |
Plack::Session::State::Cookie |
| 54 |
|
| 55 |
This will maintain session state using browser cookies. |
| 56 |
|
| 57 |
Store |
| 58 |
|
| 59 |
Plack::Session::Store |
| 60 |
|
| 61 |
This is your basic in-memory session data store. It is volatile |
| 62 |
storage and not recommended for multiprocessing environments. However |
| 63 |
it is very useful for development and testing. |
| 64 |
|
| 65 |
Plack::Session::Store::File |
| 66 |
|
| 67 |
This will persist session data in a file. By default it uses Storable |
| 68 |
but it can be configured to have a custom serializer and |
| 69 |
deserializer. |
| 70 |
|
| 71 |
Plack::Session::Store::Cache |
| 72 |
|
| 73 |
This will persist session data using the Cache interface. |
| 74 |
|
| 75 |
Plack::Session::Store::Null |
| 76 |
|
| 77 |
Sometimes you don't care about storing session data, in that case you |
| 78 |
can use this noop module. |
| 79 |
|
| 80 |
OPTIONS |
| 81 |
|
| 82 |
The following are options that can be passed to this module. |
| 83 |
|
| 84 |
state |
| 85 |
|
| 86 |
This is expected to be an instance of Plack::Session::State or an |
| 87 |
object that implements the same interface. If no option is provided |
| 88 |
the default Plack::Session::State::Cookie will be used. |
| 89 |
|
| 90 |
store |
| 91 |
|
| 92 |
This is expected to be an instance of Plack::Session::Store or an |
| 93 |
object that implements the same interface. If no option is provided |
| 94 |
the default Plack::Session::Store will be used. |
| 95 |
|
| 96 |
It should be noted that this default is an in-memory volatile store |
| 97 |
is only suitable for development (or single process servers). For a |
| 98 |
more robust solution see Plack::Session::Store::File or |
| 99 |
Plack::Session::Store::Cache. |
| 100 |
|
| 101 |
PLACK REQUEST OPTIONS |
| 102 |
|
| 103 |
In addition to providing a psgix.session key in $env for persistent |
| 104 |
session information, this module also provides a psgix.session.options |
| 105 |
key which can be used to control the behavior of the module |
| 106 |
per-request. The following sub-keys exist: |
| 107 |
|
| 108 |
change_id |
| 109 |
|
| 110 |
If set to a true value, forces the session identifier to change |
| 111 |
(rotate). This should always be done after logging in, to prevent |
| 112 |
session fixation attacks from subdomains; see |
| 113 |
http://en.wikipedia.org/wiki/Session_fixation#Attacks_using_cross-subdomain_cooking |
| 114 |
|
| 115 |
expire |
| 116 |
|
| 117 |
If set to a true value, expunges the session from the store, and |
| 118 |
clears the state in the client. |
| 119 |
|
| 120 |
no_store |
| 121 |
|
| 122 |
If set to a true value, no changes made to the session in this |
| 123 |
request will be saved to the store. Either "expire" and "change_id" |
| 124 |
take precedence over this, as both need to update the session store. |
| 125 |
|
| 126 |
late_store |
| 127 |
|
| 128 |
If set to a true value, the session will be saved at the end of the |
| 129 |
request, after all data has been sent to the client -- this may be |
| 130 |
required if streaming responses attempt to alter the session after |
| 131 |
the header has already been sent to the client. Note, however, that |
| 132 |
it introduces a possible race condition, where the server attempts to |
| 133 |
store the updated session before the client makes the next request. |
| 134 |
For redirects, or other responses on which the client needs do |
| 135 |
minimal processing before making a second request, this race is quite |
| 136 |
possible to win -- causing the second request to obtain stale session |
| 137 |
data. |
| 138 |
|
| 139 |
id |
| 140 |
|
| 141 |
This key contains the session identifier of the session. It should be |
| 142 |
considered read-only; to generate a new identifier, use "change_id". |
| 143 |
|
| 144 |
BUGS |
| 145 |
|
| 146 |
All complex software has bugs lurking in it, and this module is no |
| 147 |
exception. If you find a bug please either email me, or add the bug to |
| 148 |
cpan-RT. |
| 149 |
|
| 150 |
AUTHOR |
| 151 |
|
| 152 |
Tatsuhiko Miyagawa |
| 153 |
|
| 154 |
Stevan Little <[email protected]> |
| 155 |
|
| 156 |
COPYRIGHT AND LICENSE |
| 157 |
|
| 158 |
Copyright 2009, 2010 Infinity Interactive, Inc. |
| 159 |
|
| 160 |
http://www.iinteractive.com |
| 161 |
|
| 162 |
This library is free software; you can redistribute it and/or modify it |
| 163 |
under the same terms as Perl itself. |
| 164 |
|