Debian Codegraph @

README

raw
1 NAME
2 Catalyst::Plugin::Session - Generic Session plugin - ties together
3 server side storage and client side state required to maintain session
4 data.
5
6 SYNOPSIS
7 # To get sessions to "just work", all you need to do is use these plugins:
8
9 use Catalyst qw/
10 Session
11 Session::Store::FastMmap
12 Session::State::Cookie
13 /;
14
15 # you can replace Store::FastMmap with Store::File - both have sensible
16 # default configurations (see their docs for details)
17
18 # more complicated backends are available for other scenarios (DBI storage,
19 # etc)
20
21
22 # after you've loaded the plugins you can save session data
23 # For example, if you are writing a shopping cart, it could be implemented
24 # like this:
25
26 sub add_item : Local {
27 my ( $self, $c ) = @_;
28
29 my $item_id = $c->req->param("item");
30
31 # $c->session is a hash ref, a bit like $c->stash
32 # the difference is that it' preserved across requests
33
34 push @{ $c->session->{items} }, $item_id;
35
36 $c->forward("MyView");
37 }
38
39 sub display_items : Local {
40 my ( $self, $c ) = @_;
41
42 # values in $c->session are restored
43 $c->stash->{items_to_display} =
44 [ map { MyModel->retrieve($_) } @{ $c->session->{items} } ];
45
46 $c->forward("MyView");
47 }
48
49 DESCRIPTION
50 The Session plugin is the base of two related parts of functionality
51 required for session management in web applications.
52
53 The first part, the State, is getting the browser to repeat back a
54 session key, so that the web application can identify the client and
55 logically string several requests together into a session.
56
57 The second part, the Store, deals with the actual storage of information
58 about the client. This data is stored so that the it may be revived for
59 every request made by the same client.
60
61 This plugin links the two pieces together.
62
63 RECOMENDED BACKENDS
64 Session::State::Cookie
65 The only really sane way to do state is using cookies.
66
67 Session::Store::File
68 A portable backend, based on Cache::File.
69
70 Session::Store::FastMmap
71 A fast and flexible backend, based on Cache::FastMmap.
72
73 METHODS
74 sessionid
75 An accessor for the session ID value.
76
77 session
78 Returns a hash reference that might contain unserialized values from
79 previous requests in the same session, and whose modified value will
80 be saved for future requests.
81
82 This method will automatically create a new session and session ID
83 if none exists.
84
85 You can also set session keys by passing a list of key/value pairs
86 or a hashref.
87
88 $c->session->{foo} = "bar"; # This works.
89 $c->session(one => 1, two => 2); # And this.
90 $c->session({ answer => 42 }); # And this.
91
92 session_expires
93 This method returns the time when the current session will expire,
94 or 0 if there is no current session. If there is a session and it
95 already expired, it will delete the session and return 0 as well.
96
97 flash
98 This is like Ruby on Rails' flash data structure. Think of it as a
99 stash that lasts for longer than one request, letting you redirect
100 instead of forward.
101
102 The flash data will be cleaned up only on requests on which actually
103 use $c->flash (thus allowing multiple redirections), and the policy
104 is to delete all the keys which haven't changed since the flash data
105 was loaded at the end of every request.
106
107 Note that use of the flash is an easy way to get data across
108 requests, but it's also strongly disrecommended, due it it being
109 inherently plagued with race conditions. This means that it's
110 unlikely to work well if your users have multiple tabs open at once,
111 or if your site does a lot of AJAX requests.
112
113 Catalyst::Plugin::StatusMessage is the recommended alternative
114 solution, as this doesn't suffer from these issues.
115
116 sub moose : Local {
117 my ( $self, $c ) = @_;
118
119 $c->flash->{beans} = 10;
120 $c->response->redirect( $c->uri_for("foo") );
121 }
122
123 sub foo : Local {
124 my ( $self, $c ) = @_;
125
126 my $value = $c->flash->{beans};
127
128 # ...
129
130 $c->response->redirect( $c->uri_for("bar") );
131 }
132
133 sub bar : Local {
134 my ( $self, $c ) = @_;
135
136 if ( exists $c->flash->{beans} ) { # false
137
138 }
139 }
140
141 clear_flash
142 Zap all the keys in the flash regardless of their current state.
143
144 keep_flash @keys
145 If you want to keep a flash key for the next request too, even if it
146 hasn't changed, call "keep_flash" and pass in the keys as arguments.
147
148 delete_session REASON
149 This method is used to invalidate a session. It takes an optional
150 parameter which will be saved in "session_delete_reason" if
151 provided.
152
153 NOTE: This method will also delete your flash data.
154
155 session_delete_reason
156 This accessor contains a string with the reason a session was
157 deleted. Possible values include:
158
159 * "address mismatch"
160
161 * "session expired"
162
163 session_expire_key $key, $ttl
164 Mark a key to expire at a certain time (only useful when shorter
165 than the expiry time for the whole session).
166
167 For example:
168
169 __PACKAGE__->config('Plugin::Session' => { expires => 10000000000 }); # "forever"
170 (NB If this number is too large, Y2K38 breakage could result.)
171
172 # later
173
174 $c->session_expire_key( __user => 3600 );
175
176 Will make the session data survive, but the user will still be
177 logged out after an hour.
178
179 Note that these values are not auto extended.
180
181 change_session_id
182 By calling this method you can force a session id change while
183 keeping all session data. This method might come handy when you are
184 paranoid about some advanced variations of session fixation attack.
185
186 If you want to prevent this session fixation scenario:
187
188 0) let us have WebApp with anonymous and authenticated parts
189 1) a hacker goes to vulnerable WebApp and gets a real sessionid,
190 just by browsing anonymous part of WebApp
191 2) the hacker inserts (somehow) this values into a cookie in victim's browser
192 3) after the victim logs into WebApp the hacker can enter his/her session
193
194 you should call change_session_id in your login controller like
195 this:
196
197 if ($c->authenticate( { username => $user, password => $pass } )) {
198 # login OK
199 $c->change_session_id;
200 ...
201 } else {
202 # login FAILED
203 ...
204 }
205
206 change_session_expires $expires
207 You can change the session expiration time for this session;
208
209 $c->change_session_expires( 4000 );
210
211 Note that this only works to set the session longer than the config
212 setting.
213
214 INTERNAL METHODS
215 setup
216 This method is extended to also make calls to
217 "check_session_plugin_requirements" and "setup_session".
218
219 check_session_plugin_requirements
220 This method ensures that a State and a Store plugin are also in use
221 by the application.
222
223 setup_session
224 This method populates "$c->config('Plugin::Session')" with the
225 default values listed in "CONFIGURATION".
226
227 prepare_action
228 This method is extended.
229
230 Its only effect is if the (off by default) "flash_to_stash"
231 configuration parameter is on - then it will copy the contents of
232 the flash to the stash at prepare time.
233
234 finalize_headers
235 This method is extended and will extend the expiry time before
236 sending the response.
237
238 finalize_body
239 This method is extended and will call finalize_session before the
240 other finalize_body methods run. Here we persist the session data if
241 a session exists.
242
243 initialize_session_data
244 This method will initialize the internal structure of the session,
245 and is called by the "session" method if appropriate.
246
247 create_session_id
248 Creates a new session ID using "generate_session_id" if there is no
249 session ID yet.
250
251 validate_session_id SID
252 Make sure a session ID is of the right format.
253
254 This currently ensures that the session ID string is any amount of
255 case insensitive hexadecimal characters.
256
257 generate_session_id
258 This method will return a string that can be used as a session ID.
259 It is simply a hexidecimal string of raw bytes from the system
260 entropy source, e.g. /dev/urandom.
261
262 session_hash_seed
263 This method returns raw bytes from the system random source. It is
264 no longer used but exists for legacy code that might override
265 "generate_session_id" but still uses this method.
266
267 finalize_session
268 Clean up the session during "finalize".
269
270 This clears the various accessors after saving to the store.
271
272 dump_these
273 See "dump_these" in Catalyst - ammends the session data structure to
274 the list of dumped objects if session ID is defined.
275
276 calculate_extended_session_expires
277 calculate_initial_session_expires
278 create_session_id_if_needed
279 delete_session_id
280 extend_session_expires
281 Note: this is *not* used to give an individual user a longer
282 session. See 'change_session_expires'.
283
284 extend_session_id
285 get_session_id
286 reset_session_expires
287 session_is_valid
288 set_session_id
289 initial_session_expires
290
291 USING SESSIONS DURING PREPARE
292 The earliest point in time at which you may use the session data is
293 after Catalyst::Plugin::Session's "prepare_action" has finished.
294
295 State plugins must set $c->session ID before "prepare_action", and
296 during "prepare_action" Catalyst::Plugin::Session will actually load the
297 data from the store.
298
299 sub prepare_action {
300 my $c = shift;
301
302 # don't touch $c->session yet!
303
304 $c->NEXT::prepare_action( @_ );
305
306 $c->session; # this is OK
307 $c->sessionid; # this is also OK
308 }
309
310 CONFIGURATION
311 $c->config('Plugin::Session' => {
312 expires => 1234,
313 });
314
315 All configuation parameters are provided in a hash reference under the
316 "Plugin::Session" key in the configuration hash.
317
318 expires
319 The time-to-live of each session, expressed in seconds. Defaults to
320 7200 (two hours).
321
322 expiry_threshold
323 Only update the session expiry time if it would otherwise expire
324 within this many seconds from now.
325
326 The purpose of this is to keep the session store from being updated
327 when nothing else in the session is updated.
328
329 Defaults to 0 (in which case, the expiration will always be
330 updated).
331
332 verify_address
333 When true, "$c->request->address" will be checked at prepare time.
334 If it is not the same as the address that initiated the session, the
335 session is deleted.
336
337 Defaults to false.
338
339 verify_user_agent
340 When true, "$c->request->user_agent" will be checked at prepare
341 time. If it is not the same as the user agent that initiated the
342 session, the session is deleted.
343
344 Defaults to false.
345
346 flash_to_stash
347 This option makes it easier to have actions behave the same whether
348 they were forwarded to or redirected to. On prepare time it copies
349 the contents of "flash" (if any) to the stash.
350
351 SPECIAL KEYS
352 The hash reference returned by "$c->session" contains several keys which
353 are automatically set:
354
355 __expires
356 This key no longer exists. Use "session_expires" instead.
357
358 __updated
359 The last time a session was saved to the store.
360
361 __created
362 The time when the session was first created.
363
364 __address
365 The value of "$c->request->address" at the time the session was
366 created. This value is only populated if "verify_address" is true in
367 the configuration.
368
369 __user_agent
370 The value of "$c->request->user_agent" at the time the session was
371 created. This value is only populated if "verify_user_agent" is true
372 in the configuration.
373
374 CAVEATS
375 Round the Robin Proxies
376 "verify_address" could make your site inaccessible to users who are
377 behind load balanced proxies. Some ISPs may give a different IP to each
378 request by the same client due to this type of proxying. If addresses
379 are verified these users' sessions cannot persist.
380
381 To let these users access your site you can either disable address
382 verification as a whole, or provide a checkbox in the login dialog that
383 tells the server that it's OK for the address of the client to change.
384 When the server sees that this box is checked it should delete the
385 "__address" special key from the session hash when the hash is first
386 created.
387
388 Race Conditions
389 In this day and age where cleaning detergents and Dutch football (not
390 the American kind) teams roam the plains in great numbers, requests may
391 happen simultaneously. This means that there is some risk of session
392 data being overwritten, like this:
393
394 1. request a starts, request b starts, with the same session ID
395
396 2. session data is loaded in request a
397
398 3. session data is loaded in request b
399
400 4. session data is changed in request a
401
402 5. request a finishes, session data is updated and written to store
403
404 6. request b finishes, session data is updated and written to store,
405 overwriting changes by request a
406
407 For applications where any given user's session is only making one
408 request at a time this plugin should be safe enough.
409
410 AUTHORS
411 Andy Grundman
412
413 Christian Hansen
414
415 Yuval Kogman, "[email protected]"
416
417 Sebastian Riedel
418
419 Tomas Doran (t0m) "[email protected]" (current maintainer)
420
421 Sergio Salvi
422
423 kmx "[email protected]"
424
425 Florian Ragwitz (rafl) "[email protected]"
426
427 Kent Fredric (kentnl)
428
429 And countless other contributers from #catalyst. Thanks guys!
430
431 Contributors
432 Devin Austin (dhoss) <[email protected]>
433
434 Robert Rothenberg <[email protected]>
435
436 COPYRIGHT & LICENSE
437 Copyright (c) 2005 the aforementioned authors. All rights
438 reserved. This program is free software; you can redistribute
439 it and/or modify it under the same terms as Perl itself.
440