3 package Catalyst::Plugin::Session;
4 use base qw/Class::Accessor::Fast/;
10 use Catalyst::Exception ();
14 our $VERSION = "0.02";
17 __PACKAGE__->mk_accessors(qw/_sessionid _session _session_delete_reason _flash _flash_stale_keys/);
25 $c->check_session_plugin_requirements;
31 sub check_session_plugin_requirements {
34 unless ( $c->isa("Catalyst::Plugin::Session::State")
35 && $c->isa("Catalyst::Plugin::Session::Store") )
38 ( "The Session plugin requires both Session::State "
39 . "and Session::Store plugins to be used as well." );
42 Catalyst::Exception->throw($err);
49 my $cfg = ( $c->config->{session} ||= {} );
57 $c->NEXT::setup_session();
63 if ( $c->config->{session}{flash_to_stash} and $c->_sessionid and my $flash_data = $c->flash ) {
64 @{ $c->stash }{ keys %$flash_data } = values %$flash_data;
67 $c->NEXT::prepare_action(@_);
76 $c->NEXT::finalize(@_);
82 if ( my $sid = $c->_sessionid ) {
83 if ( my $session_data = $c->_session ) {
85 # all sessions are extended at the end of the request
87 @{ $session_data }{qw/__updated __expires/} =
88 ( $now, $c->config->{session}{expires} + $now );
90 $c->store_session_data( "session:$sid", $session_data );
98 if ( my $sid = $c->_sessionid ) {
99 if ( my $flash_data = $c->_flash ) {
100 if ( %$flash_data ) { # damn 'my' declarations
101 delete @{ $flash_data }{ @{ $c->_flash_stale_keys || [] } };
102 $c->store_session_data( "flash:$sid", $flash_data );
105 $c->delete_session_data( "flash:$sid" );
113 if ( my $sid = $c->_sessionid ) {
114 no warnings 'uninitialized'; # ne __address
116 my $session_data = $c->_session || $c->_session( $c->get_session_data( "session:$sid" ) );
117 if ( !$session_data or $session_data->{__expires} < time ) {
120 $c->log->debug("Deleting session $sid (expired)") if $c->debug;
121 $c->delete_session("session expired");
123 elsif ($c->config->{session}{verify_address}
124 && $session_data->{__address} ne $c->request->address )
127 "Deleting session $sid due to address mismatch ("
128 . $session_data->{__address} . " != "
129 . $c->request->address . ")",
131 $c->delete_session("address mismatch");
134 $c->log->debug(qq/Restored session "$sid"/) if $c->debug;
137 $c->_expire_ession_keys;
139 return $session_data;
148 if ( my $sid = $c->_sessionid ) {
149 if ( my $flash_data = $c->_flash || $c->_flash( $c->get_session_data( "flash:$sid" ) ) ) {
150 $c->_flash_stale_keys([ keys %$flash_data ]);
158 sub _expire_ession_keys {
159 my ( $c, $data ) = @_;
163 my $expiry = ($data || $c->_session || {})->{__expire_keys} || {};
164 foreach my $key (grep { $expiry->{$_} < $now } keys %$expiry ) {
165 delete $c->_session->{$key};
166 delete $expiry->{$key};
171 my ( $c, $msg ) = @_;
173 # delete the session data
174 my $sid = $c->_sessionid || return;
175 $c->delete_session_data( "session:$sid" );
177 # reset the values in the context object
179 $c->_sessionid(undef);
180 $c->_session_delete_reason($msg);
183 sub session_delete_reason {
186 $c->_load_session if ( $c->_sessionid && !$c->_session ); # must verify session data
188 $c->_session_delete_reason( @_ );
195 if ( $c->validate_session_id( my $sid = shift ) ) {
196 $c->_sessionid( $sid );
197 return unless defined wantarray;
199 my $err = "Tried to set invalid session ID '$sid'";
200 $c->log->error( $err );
201 Catalyst::Exception->throw( $err );
205 $c->_load_session if ( $c->_sessionid && !$c->_session ); # must verify session data
207 return $c->_sessionid;
210 sub validate_session_id {
211 my ( $c, $sid ) = @_;
213 $sid and $sid =~ /^[a-f\d]+$/i;
219 $c->_session || $c->_load_session || do {
220 $c->create_session_id;
222 $c->initialize_session_data;
228 $c->_flash || $c->_load_flash || do {
229 $c->create_session_id;
234 sub session_expire_key {
235 my ( $c, %keys ) = @_;
238 @{ $c->session->{__expire_keys} }{keys %keys} = map { $now + $_ } values %keys;
241 sub initialize_session_data {
246 return $c->_session({
249 __expires => $now + $c->config->{session}{expires},
252 $c->config->{session}{verify_address}
253 ? ( __address => $c->request->address )
259 sub generate_session_id {
262 my $digest = $c->_find_digest();
263 $digest->add( $c->session_hash_seed() );
264 return $digest->hexdigest;
267 sub create_session_id {
270 if ( !$c->_sessionid ) {
271 my $sid = $c->generate_session_id;
273 $c->log->debug(qq/Created session "$sid"/) if $c->debug;
281 sub session_hash_seed {
284 return join( "", ++$counter, time, rand, $$, {}, overload::StrVal($c), );
289 sub _find_digest () {
291 foreach my $alg (qw/SHA-1 MD5 SHA-256/) {
301 or Catalyst::Exception->throw(
302 "Could not find a suitable Digest module. Please install "
303 . "Digest::SHA1, Digest::SHA, or Digest::MD5" );
306 return Digest->new($usable);
313 $c->NEXT::dump_these(),
316 ? ( [ "Session ID" => $c->sessionid ], [ Session => $c->session ], )
329 Catalyst::Plugin::Session - Generic Session plugin - ties together server side
330 storage and client side state required to maintain session data.
334 # To get sessions to "just work", all you need to do is use these plugins:
338 Session::Store::FastMmap
339 Session::State::Cookie
342 # you can replace Store::FastMmap with Store::File - both have sensible
343 # default configurations (see their docs for details)
345 # more complicated backends are available for other scenarios (DBI storage,
349 # after you've loaded the plugins you can save session data
350 # For example, if you are writing a shopping cart, it could be implemented
353 sub add_item : Local {
354 my ( $self, $c ) = @_;
356 my $item_id = $c->req->param("item");
358 # $c->session is a hash ref, a bit like $c->stash
359 # the difference is that it' preserved across requests
361 push @{ $c->session->{items} }, $item_id;
363 $c->forward("MyView");
366 sub display_items : Local {
367 my ( $self, $c ) = @_;
369 # values in $c->session are restored
370 $c->stash->{items_to_display} =
371 [ map { MyModel->retrieve($_) } @{ $c->session->{items} } ];
373 $c->forward("MyView");
378 The Session plugin is the base of two related parts of functionality required
379 for session management in web applications.
381 The first part, the State, is getting the browser to repeat back a session key,
382 so that the web application can identify the client and logically string
383 several requests together into a session.
385 The second part, the Store, deals with the actual storage of information about
386 the client. This data is stored so that the it may be revived for every request
387 made by the same client.
389 This plugin links the two pieces together.
391 =head1 RECCOMENDED BACKENDS
395 =item Session::State::Cookie
397 The only really sane way to do state is using cookies.
399 =item Session::Store::File
401 A portable backend, based on Cache::File.
403 =item Session::Store::FastMmap
405 A fast and flexible backend, based on Cache::FastMmap.
415 An accessor for the session ID value.
419 Returns a hash reference that might contain unserialized values from previous
420 requests in the same session, and whose modified value will be saved for future
423 This method will automatically create a new session and session ID if none
428 This is like Ruby on Rails' flash data structure. Think of it as a stash that
429 lasts a single redirect, not only a forward.
432 my ( $self, $c ) = @_;
434 $c->flash->{beans} = 10;
435 $c->response->redirect( $c->uri_for("foo") );
439 my ( $self, $c ) = @_;
441 my $value = $c->flash->{beans};
445 $c->response->redirect( $c->uri_for("bar") );
449 my ( $self, $c ) = @_;
451 if ( exists $c->flash->{beans} ) { # false
456 =item session_delete_reason
458 This accessor contains a string with the reason a session was deleted. Possible
473 =item session_expire_key $key, $ttl
475 Mark a key to expire at a certain time (only useful when shorter than the
476 expiry time for the whole session).
480 __PACKAGE__->config->{session}{expires} = 1000000000000; # forever
484 $c->session_expire_key( __user => 3600 );
486 Will make the session data survive, but the user will still be logged out after
489 Note that these values are not auto extended.
493 =item INTERNAL METHODS
499 This method is extended to also make calls to
500 C<check_session_plugin_requirements> and C<setup_session>.
502 =item check_session_plugin_requirements
504 This method ensures that a State and a Store plugin are also in use by the
509 This method populates C<< $c->config->{session} >> with the default values
510 listed in L</CONFIGURATION>.
514 This methoid is extended.
516 It's only effect is if the (off by default) C<flash_to_stash> configuration
517 parameter is on - then it will copy the contents of the flash to the stash at
522 This method is extended and will extend the expiry time, as well as persist the
523 session data if a session exists.
525 =item delete_session REASON
527 This method is used to invalidate a session. It takes an optional parameter
528 which will be saved in C<session_delete_reason> if provided.
530 =item initialize_session_data
532 This method will initialize the internal structure of the session, and is
533 called by the C<session> method if appropriate.
535 =item create_session_id
537 Creates a new session id using C<generate_session_id> if there is no session ID
540 =item generate_session_id
542 This method will return a string that can be used as a session ID. It is
543 supposed to be a reasonably random string with enough bits to prevent
544 collision. It basically takes C<session_hash_seed> and hashes it using SHA-1,
545 MD5 or SHA-256, depending on the availibility of these modules.
547 =item session_hash_seed
549 This method is actually rather internal to generate_session_id, but should be
550 overridable in case you want to provide more random data.
552 Currently it returns a concatenated string which contains:
554 =item validate_session_id SID
556 Make sure a session ID is of the right format.
558 This currently ensures that the session ID string is any amount of case
559 insensitive hexadecimal characters.
573 One value from C<rand>.
577 The stringified value of a newly allocated hash reference
581 The stringified value of the Catalyst context object
585 In the hopes that those combined values are entropic enough for most uses. If
586 this is not the case you can replace C<session_hash_seed> with e.g.
588 sub session_hash_seed {
589 open my $fh, "<", "/dev/random";
590 read $fh, my $bytes, 20;
595 Or even more directly, replace C<generate_session_id>:
597 sub generate_session_id {
598 open my $fh, "<", "/dev/random";
599 read $fh, my $bytes, 20;
601 return unpack("H*", $bytes);
604 Also have a look at L<Crypt::Random> and the various openssl bindings - these
605 modules provide APIs for cryptographically secure random data.
609 See L<Catalyst/dump_these> - ammends the session data structure to the list of
610 dumped objects if session ID is defined.
614 =head1 USING SESSIONS DURING PREPARE
616 The earliest point in time at which you may use the session data is after
617 L<Catalyst::Plugin::Session>'s C<prepare_action> has finished.
619 State plugins must set $c->session ID before C<prepare_action>, and during
620 C<prepare_action> L<Catalyst::Plugin::Session> will actually load the data from
626 # don't touch $c->session yet!
628 $c->NEXT::prepare_action( @_ );
630 $c->session; # this is OK
631 $c->sessionid; # this is also OK
636 $c->config->{session} = {
640 All configuation parameters are provided in a hash reference under the
641 C<session> key in the configuration hash.
647 The time-to-live of each session, expressed in seconds. Defaults to 7200 (two
652 When true, C<<$c->request->address>> will be checked at prepare time. If it is
653 not the same as the address that initiated the session, the session is deleted.
657 This option makes it easier to have actions behave the same whether they were
658 forwarded to or redirected to. On prepare time it copies the contents of
659 C<flash> (if any) to the stash.
665 The hash reference returned by C<< $c->session >> contains several keys which
666 are automatically set:
672 A timestamp whose value is the last second when the session is still valid. If
673 a session is restored, and __expires is less than the current time, the session
678 The last time a session was saved. This is the value of
679 C<< $c->session->{__expires} - $c->config->session->{expires} >>.
683 The time when the session was first created.
687 The value of C<< $c->request->address >> at the time the session was created.
688 This value is only populated if C<verify_address> is true in the configuration.
694 =head2 Round the Robin Proxies
696 C<verify_address> could make your site inaccessible to users who are behind
697 load balanced proxies. Some ISPs may give a different IP to each request by the
698 same client due to this type of proxying. If addresses are verified these
699 users' sessions cannot persist.
701 To let these users access your site you can either disable address verification
702 as a whole, or provide a checkbox in the login dialog that tells the server
703 that it's OK for the address of the client to change. When the server sees that
704 this box is checked it should delete the C<__address> sepcial key from the
705 session hash when the hash is first created.
707 =head2 Race Conditions
709 In this day and age where cleaning detergents and dutch football (not the
710 american kind) teams roam the plains in great numbers, requests may happen
711 simultaneously. This means that there is some risk of session data being
712 overwritten, like this:
718 request a starts, request b starts, with the same session id
722 session data is loaded in request a
726 session data is loaded in request b
730 session data is changed in request a
734 request a finishes, session data is updated and written to store
738 request b finishes, session data is updated and written to store, overwriting
743 If this is a concern in your application, a soon to be developed locking
744 solution is the only safe way to go. This will have a bigger overhead.
746 For applications where any given user is only making one request at a time this
747 plugin should be safe enough.
755 =item Christian Hansen
757 =item Yuval Kogman, C<nothingmuch@woobling.org> (current maintainer)
759 =item Sebastian Riedel
763 And countless other contributers from #catalyst. Thanks guys!
765 =head1 COPYRIGHT & LICENSE
767 Copyright (c) 2005 the aforementioned authors. All rights
768 reserved. This program is free software; you can redistribute
769 it and/or modify it under the same terms as Perl itself.