lib/Catalyst/Plugin/Session/Store.pm

   1 #!/usr/bin/perl
   2
   3 package Catalyst::Plugin::Session::Store;
   4
   5 use strict;
   6 use warnings;
   7
   8 __PACKAGE__;
   9
  10 __END__
  11
  12 =pod
  13
  14 =head1 NAME
  15
  16 Catalyst::Plugin::Session::Store - Base class for session storage
  17 drivers.
  18
  19 =head1 SYNOPSIS
  20
  21     package Catalyst::Plugin::Session::Store::MyBackend;
  22     use base qw/Catalyst::Plugin::Session::Store/;
  23
  24 =head1 DESCRIPTION
  25
  26 This class doesn't actually provide any functionality, but when the
  27 C<Catalyst::Plugin::Session> module sets up it will check to see that
  28 C<< YourApp->isa("Catalyst::Plugin::Session::Store") >>. When you write
  29 a session storage plugin you should subclass this module for this
  30 reason. This documentation is intended for authors of session storage
  31 plugins, not for end users.
  32
  33 =head1 WRITING STORE PLUGINS
  34
  35 All session storage plugins need to adhere to the following interface
  36 specification to work correctly:
  37
  38 =head2 Required Methods
  39
  40 =over 4
  41
  42 =item get_session_data $key
  43
  44 =item store_session_data $key, $data
  45
  46 Retrieve or store session data by key.
  47
  48 C<$data> is currently either a hash reference (for most keys) or an
  49 integer value (for expires), but all value types should be supported.
  50
  51 Keys are in the format C<prefix:id>, where C<prefix> is C<session>,
  52 C<expires>, or C<flash>, and C<id> is always the session ID. Plugins
  53 such as L<Catalyst::Plugin::Session::PerUser> store extensions to this
  54 format, such as C<user:username>.
  55
  56 It is suggested that the store should split on the colon and store the
  57 data more efficiently - the API should remain stable, with the possible
  58 addition of new prefixes in the future.
  59
  60 For example, C<Store::DBI> maps C<expires:id> a column of C<session:id>
  61 by special-casing C<get_session_data> and C<store_session_data> for that
  62 key format, in order to ease the implementation of
  63 C<delete_expired_sessions>.
  64
  65 The only assurance stores are required to make is that given
  66
  67     $c->store_session_data( $x, $y );
  68
  69 for any $x,
  70
  71     $y == $c->get_session_data( $x )
  72
  73 will hold.
  74
  75 =item store_session_data ( $key, $data )
  76
  77 Store a session whose KEY is the first parameter and data is the second
  78 parameter in storage.
  79
  80 The second parameter is a hash reference, which should normally be
  81 serialized (and later deserialized by C<get_session_data>).
  82
  83 =item delete_session_data ( $key )
  84
  85 Delete the session whose KEY is the parameter.
  86
  87 =item delete_expired_sessions
  88
  89 This method is not called by any code at present, but may be called in the
  90 future, as part of a Catalyst-specific maintenance script.
  91
  92 If you are wrapping around a backend which manages its own auto expiry
  93 you can just give this method an empty body.
  94
  95 =back
  96
  97 =head2 Error handling
  98
  99 All errors should be thrown using L<Catalyst::Exception>. Return values
 100 are not checked, and are assumed to be OK. Missing values are not errors.
 101
 102 =head2 Auto-Expiry on the Backend
 103
 104 Storage plugins are encouraged to use C<< $c->session_expires >>, C<<
 105 $c->config('Plugin::Session' => { expires => $val }) >>, or the storage of the
 106 C<expires:$sessionid> key to perform more efficient expiration, but only
 107 for the key prefixes C<session>, C<flash> and C<expires>.
 108
 109 If the backend chooses not to do so, L<Catalyst::Plugin::Session> will
 110 detect expired sessions as they are retrieved and delete them if
 111 necessary.
 112
 113 Note that session store that use this approach may leak disk space,
 114 since nothing will actively delete an expired session. The
 115 C<delete_expired_sessions> method is there so that regularly scheduled
 116 maintenance scripts can give your backend the opportunity to clean up.
 117
 118 =head2 Early Finalization
 119
 120 By default the main session plugin will finalize during body finalization
 121 which ensures that all controller code related to the session has completed.
 122 However some storage plugins may wish to finalize earlier, during header
 123 finalization.  For example a storage that saved state in a client cookie
 124 would wish this.  If a storage plugin wants to finalize early it should set
 125 $c->_needs_early_session_finalization to true.  Please note that if you
 126 do this in a storage plugin, you should warn users not to attempt to change
 127 or add session keys if you use a streaming or socket interface such as
 128 $c->res->write, $c->res->write_fh or $c->req->io_fh.
 129
 130 =cut
 131
 132