.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Plack::Session::State 3pm" .TH Plack::Session::State 3pm "2022-10-16" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Plack::Session::State \- Basic parameter\-based session state .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& use Plack::Builder; \& use Plack::Middleware::Session; \& use Plack::Session::State; \& \& my $app = sub { \& return [ 200, [ \*(AqContent\-Type\*(Aq => \*(Aqtext/plain\*(Aq ], [ \*(AqHello Foo\*(Aq ] ]; \& }; \& \& builder { \& enable \*(AqSession\*(Aq, \& state => Plack::Session::State\->new; \& $app; \& }; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This will maintain session state by passing the session through the request params. It does not do this automatically though, you are responsible for passing the session param. .PP This should be considered the state \*(L"base\*(R" class (although subclassing is not a requirement) and defines the spec for all \fBPlack::Session::State::*\fR modules. You will only need to override a couple methods if you do subclass. See Plack::Session::State::Cookie for an example of this. .PP \&\fB\s-1WARNING\s0\fR: parameter based session \s-1ID\s0 management makes session fixation really easy, and that makes your website vulnerable. You should really avoid using this state in the production environment except when you have to deal with legacy \s-1HTTP\s0 clients that do not support cookies. .PP In the future this parameter based state handling will be removed from this base class and will be moved to its own State class. .SH "METHODS" .IX Header "METHODS" .IP "\fBnew ( \f(CB%params\fB )\fR" 4 .IX Item "new ( %params )" The \f(CW%params\fR can include \fIsession_key\fR, \fIsid_generator\fR and \fIsid_checker\fR however in both cases a default will be provided for you. .IP "\fBsession_key\fR" 4 .IX Item "session_key" This is the name of the session key, it defaults to 'plack_session'. .IP "\fBsid_generator\fR" 4 .IX Item "sid_generator" This is a \s-1CODE\s0 ref used to generate unique session ids, by default it will generate a \s-1SHA1\s0 using fairly sufficient entropy. If you are concerned or interested, just read the source. .IP "\fBsid_validator\fR" 4 .IX Item "sid_validator" This is a regex used to validate requested session id. .SS "Session \s-1ID\s0 Managment" .IX Subsection "Session ID Managment" .IP "\fBget_session_id ( \f(CB$env\fB )\fR" 4 .IX Item "get_session_id ( $env )" This is the method used to extract the session id from a \f(CW$env\fR. Subclasses will often only need to override this method and the \&\f(CW\*(C`finalize\*(C'\fR method. .IP "\fBvalidate_session_id ( \f(CB$session_id\fB )\fR" 4 .IX Item "validate_session_id ( $session_id )" This will use the \f(CW\*(C`sid_validator\*(C'\fR regex and confirm that the \&\f(CW$session_id\fR is valid. .IP "\fBextract ( \f(CB$env\fB )\fR" 4 .IX Item "extract ( $env )" This will attempt to extract the session from a \f(CW$env\fR by looking for the \f(CW\*(C`session_key\*(C'\fR in the request params. It will then check to see if the session is valid and that it has not expired. It will return the session id if everything is good or undef otherwise. .IP "\fBgenerate ( \f(CB$request\fB )\fR" 4 .IX Item "generate ( $request )" This will generate a new session id using the \f(CW\*(C`sid_generator\*(C'\fR callback. The \f(CW$request\fR argument is not used by this method but is there for use by subclasses. The \f(CW$request\fR is expected to be a Plack::Request instance or an object with an equivalent interface. .IP "\fBfinalize ( \f(CB$session_id\fB, \f(CB$response\fB )\fR" 4 .IX Item "finalize ( $session_id, $response )" Given a \f(CW$session_id\fR and a \f(CW$response\fR this will perform any finalization necessary to preserve state. This method is called by the Plack::Session \f(CW\*(C`finalize\*(C'\fR method. The \f(CW$response\fR is expected to be a Plack::Response instance or an object with an equivalent interface. .SS "Session Expiration Handling" .IX Subsection "Session Expiration Handling" .IP "\fBexpire_session_id ( \f(CB$id\fB, \f(CB$response\fB )\fR" 4 .IX Item "expire_session_id ( $id, $response )" This will mark the session for \f(CW$id\fR as expired. This method is called by the Plack::Session \f(CW\*(C`expire\*(C'\fR method. .SH "BUGS" .IX Header "BUGS" All complex software has bugs lurking in it, and this module is no exception. If you find a bug please either email me, or add the bug to cpan-RT. .SH "AUTHOR" .IX Header "AUTHOR" Stevan Little .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2009, 2010 Infinity Interactive, Inc. .PP .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.