1Dancer2::Core::Role::SeUssseironCFoancttroirbyu(t3e)d PeDralncDeorc2u:m:eCnotraet:i:oRnole::SessionFactory(3)
2
3
4

NAME

6       Dancer2::Core::Role::SessionFactory - Role for session factories
7

VERSION

9       version 0.400000
10

DESCRIPTION

12       Any class that consumes this role will be able to store, create,
13       retrieve and destroy session objects.
14
15       The default values for attributes can be overridden in your Dancer2
16       configuration. See "Session-engine" in Dancer2::Config.
17

ATTRIBUTES

19   cookie_name
20       The name of the cookie to create for storing the session key
21
22       Defaults to "dancer.session"
23
24   cookie_domain
25       The domain of the cookie to create for storing the session key.
26       Defaults to the empty string and is unused as a result.
27
28   cookie_path
29       The path of the cookie to create for storing the session key.  Defaults
30       to "/".
31
32   cookie_duration
33       Default duration before session cookie expiration.  If set, the
34       Dancer2::Core::Session "expires" attribute will be set to the current
35       time plus this duration (expression parsed by Dancer2::Core::Time).
36
37   cookie_same_site
38       Restricts the session cookie to a first-party or same-site context.
39       Defaults to the empty string and is unused as a result.  See
40       "same_site" in Dancer2::Core::Cookie.
41
42   session_duration
43       Duration in seconds before sessions should expire, regardless of cookie
44       expiration.  If set, then SessionFactories should use this to enforce a
45       limit on session validity.
46
47   is_secure
48       Boolean flag to tell if the session cookie is secure or not.
49
50       Default is false.
51
52   is_http_only
53       Boolean flag to tell if the session cookie is http only.
54
55       Default is true.
56

INTERFACE

58       Following is the interface provided by this role. When specified the
59       required methods to implement are described.
60
61   create
62       Create a brand new session object and store it. Returns the newly
63       created session object.
64
65       Triggers an exception if the session is unable to be created.
66
67           my $session = MySessionFactory->create();
68
69       This method does not need to be implemented in the class.
70
71   generate_id
72       Returns a randomly-generated, guaranteed-unique string.  By default, it
73       is a 32-character, URL-safe, Base64 encoded combination of a 32 bit
74       timestamp and a 160 bit SHA1 digest of random seed data.  The timestamp
75       ensures that session IDs are generally monotonic.
76
77       The default algorithm is not guaranteed cryptographically secure, but
78       it's still reasonably strong for general use.
79
80       If you have installed Math::Random::ISAAC::XS and Crypt::URandom, the
81       seed data will be generated from a cryptographically-strong random
82       number generator.
83
84       This method is used internally by create() to set the session ID.
85
86       This method does not need to be implemented in the class unless an
87       alternative method for session ID generation is desired.
88
89   validate_id
90       Returns true if a session id is of the correct format, or false
91       otherwise.
92
93       By default, this ensures that the session ID is a string of characters
94       from the Base64 schema for "URL Applications" plus the "~" character.
95
96       This method does not need to be implemented in the class unless an
97       alternative set of characters for session IDs is desired.
98
99   retrieve
100       Return the session object corresponding to the session ID given. If
101       none is found, triggers an exception.
102
103           my $session = MySessionFactory->retrieve(id => $id);
104
105       The method "_retrieve" must be implemented.  It must take $id as a
106       single argument and must return a hash reference of session data.
107
108   change_id
109       Changes the session ID of the corresponding session.
110
111           MySessionFactory->change_id(session => $session_object);
112
113       The method "_change_id" must be implemented. It must take $old_id and
114       $new_id as arguments and change the ID from the old one to the new one
115       in the underlying session storage.
116
117   destroy
118       Purges the session object that matches the ID given. Returns the ID of
119       the destroyed session if succeeded, triggers an exception otherwise.
120
121           MySessionFactory->destroy(id => $id);
122
123       The "_destroy" method must be implemented. It must take $id as a single
124       argument and destroy the underlying data.
125
126   flush
127       Make sure the session object is stored in the factory's backend. This
128       method is called to notify the backend about the change in the session
129       object.
130
131       The Dancer application will not call flush unless the session
132       "is_dirty" attribute is true to avoid unnecessary writes to the
133       database when no data has been modified.
134
135       An exception is triggered if the session is unable to be updated in the
136       backend.
137
138           MySessionFactory->flush(session => $session);
139
140       The "_flush" method must be implemented.  It must take two arguments:
141       the $id and a hash reference of session data.
142
143   set_cookie_header
144       Sets the session cookie into the response object
145
146           MySessionFactory->set_cookie_header(
147               response  => $response,
148               session   => $session,
149               destroyed => undef,
150           );
151
152       The "response" parameter contains a Dancer2::Core::Response object.
153       The "session" parameter contains a Dancer2::Core::Session object.
154
155       The "destroyed" parameter is optional.  If true, it indicates the
156       session was marked destroyed by the request context.  The default
157       "set_cookie_header" method doesn't need that information, but it is
158       included in case a SessionFactory must handle destroyed sessions
159       differently (such as signalling to middleware).
160
161   cookie
162       Coerce a session object into a Dancer2::Core::Cookie object.
163
164           MySessionFactory->cookie(session => $session);
165
166   sessions
167       Return a list of all session IDs stored in the backend.  Useful to
168       create cleaning scripts, in conjunction with session's creation time.
169
170       The "_sessions" method must be implemented.  It must return an array
171       reference of session IDs (or an empty array reference).
172

CONFIGURATION

174       If there are configuration values specific to your session factory in
175       your config.yml or environment, those will be passed to the constructor
176       of the session factory automatically.  In order to accept and store
177       them, you need to define accessors for them.
178
179           engines:
180             session:
181               Example:
182                 database_connection: "some_data"
183
184       In your session factory:
185
186           package Dancer2::Session::Example;
187           use Moo;
188           with "Dancer2::Core::Role::SessionFactory";
189
190           has database_connection => ( is => "ro" );
191
192       You need to do this for every configuration key. The ones that do not
193       have accessors defined will just go to the void.
194

AUTHOR

196       Dancer Core Developers
197

199       This software is copyright (c) 2022 by Alexis Sukrieh.
200
201       This is free software; you can redistribute it and/or modify it under
202       the same terms as the Perl 5 programming language system itself.
203
204
205
206perl v5.36.0                      2023-01D-a2n0cer2::Core::Role::SessionFactory(3)
Impressum