README
1NAME
2
3 Plack::Middleware::Session - Middleware for session management
4
5SYNOPSIS
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
31DESCRIPTION
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
80OPTIONS
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
101PLACK 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. This
111 should always be done after logging in, to prevent session fixation
112 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
144BUGS
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
150AUTHOR
151
152 Tatsuhiko Miyagawa
153
154 Stevan Little <stevan.little@iinteractive.com>
155
156COPYRIGHT 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
165