Commit | Line | Data |
9e447f9d |
1 | #!/usr/bin/perl |
2 | |
3 | package Catalyst::Plugin::Session::Store; |
4 | |
5 | use strict; |
6 | use warnings; |
7 | |
9e447f9d |
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 | |
45c0711b |
21 | package Catalyst::Plugin::Session::Store::MyBackend; |
22 | use base qw/Catalyst::Plugin::Session::Store/; |
9e447f9d |
23 | |
24 | =head1 DESCRIPTION |
25 | |
c80e9f04 |
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 |
f8827995 |
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. |
c80e9f04 |
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 | |
ea1410bc |
42 | =item get_session_data $key |
c80e9f04 |
43 | |
ea1410bc |
44 | =item store_session_data $key, $data |
c80e9f04 |
45 | |
ea1410bc |
46 | Retrieve or store session data by key. |
c80e9f04 |
47 | |
f8827995 |
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. |
ea1410bc |
50 | |
f8827995 |
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>. |
ea1410bc |
55 | |
f8827995 |
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. |
ea1410bc |
59 | |
f8827995 |
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>. |
ea1410bc |
64 | |
2f038cb0 |
65 | The only assurance stores are required to make is that given |
ea1410bc |
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. |
c80e9f04 |
74 | |
f8827995 |
75 | =item store_session_data ( $key, $data ) |
76 | |
77 | Store a session whose KEY is the first parameter and data is the second |
c80e9f04 |
78 | parameter in storage. |
79 | |
f8827995 |
80 | The second parameter is a hash reference, which should normally be |
81 | serialized (and later deserialized by C<get_session_data>). |
c80e9f04 |
82 | |
f8827995 |
83 | =item delete_session_data ( $key ) |
c80e9f04 |
84 | |
f8827995 |
85 | Delete the session whose KEY is the parameter. |
c80e9f04 |
86 | |
87 | =item delete_expired_sessions |
88 | |
89 | This method is not called by any code at present, but may be called in the |
f8827995 |
90 | future, as part of a Catalyst-specific maintenance script. |
c80e9f04 |
91 | |
f8827995 |
92 | If you are wrapping around a backend which manages its own auto expiry |
93 | you can just give this method an empty body. |
c80e9f04 |
94 | |
95 | =back |
96 | |
97 | =head2 Error handling |
98 | |
f8827995 |
99 | All errors should be thrown using L<Catalyst::Exception>. Return values |
4ccdbb07 |
100 | are not checked, and are assumed to be OK. Missing values are not errors. |
f420593c |
101 | |
f8827995 |
102 | =head2 Auto-Expiry on the Backend |
c80e9f04 |
103 | |
ea1410bc |
104 | Storage plugins are encouraged to use C<< $c->session_expires >>, C<< |
9a50355f |
105 | $c->config('Plugin::Session' => { expires => $val }) >>, or the storage of the |
f8827995 |
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. |
c80e9f04 |
117 | |
fda03636 |
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 | |
9e447f9d |
130 | =cut |
131 | |
132 | |