Catalyst::Plugin::Session::State::URI - Saves session IDs by rewriting URIs delivered to the client, and extracting the session ID from requested URIs.
use Catalyst qw/Session Session::State::URI Session::Store::Foo/; # If you want the param style rewriting, set the parameter MyApp->config->{session} = { param => 'sessionid', # or whatever you like };
In order for Catalyst::Plugin::Session to work the session ID needs to be stored on the client, and the session data needs to be stored on the server.
This plugin cheats and instead of storing the session id on the client, it simply embeds the session id into every URI sent to the user.
This method is consulted by finalize. The body will be rewritten only if it returns a true value.
finalize
This method will not return true unless $c->config->{session}{rewrite} is true (the default). To globally disable rewriting simply set this parameter to false.
$c->config->{session}{rewrite}
If $c->config->{session}{no_rewrite_if_cookie} is true (the default), Catalyst::Plugin::Session::State::Cookie is also in use, and the user agent sent a cookie for the sesion then this method will return false.
$c->config->{session}{no_rewrite_if_cookie}
This method just calls session_should_rewrite_type.
session_should_rewrite_type
Whether or not the content type of the body should be rewritten.
For compatibility this method will not test the response's content type without configuration. If you want to do that you must provide a list of valid content types in $c->config->{session}{rewrite_types}, or subclass this method.
$c->config->{session}{rewrite_types}
Whether or not to rewrite the Location header of the response.
Location
If the status code is a number in the 3xx range then this returns true.
This method is to determine whether a URI should be rewritten.
It will return true for URIs under $c->req->base, and it will also use MIME::Types to filter the links which point to png, pdf and etc with the file extension.
$c->req->base
You are encouraged to override this method if it's logic doesn't suit your setup.
A sub test of session_should_rewrite_uri, that checks if the file name's guessed mime type is of a kind we should rewrite URIs to.
Files which are typically static (images, etc) will thus not be rewritten in order to not get 404s or pass bogus parameters to the server.
If $uri_obj's path causes MIME::Types to return true for the isBinary test then then the URI will not be rewritten.
$uri_obj
isBinary
By path style rewriting, it will appends /-/$sessionid to the uri path.
/-/$sessionid
http://myapp/link -> http://myapp/link/-/$sessionid
By param style rewriting, it will add a parameter key/value pair after the uri path.
http://myapp/link -> http://myapp/link?$param=$sessionid
If $sid is not provided it will default to $c->sessionid.
$c->sessionid
Rewrite the response if necessary.
Calls either rewrite_html_with_session_id or rewrite_text_with_session_id depending on the content type.
rewrite_html_with_session_id
rewrite_text_with_session_id
Rewrites the body using HTML::TokePaser::Simple.
This method of rewriting also matches relative URIs, and is thus more robust.
Rewrites the body using URI::Find.
This method is used when the content does not appear to be HTML.
Rewrites the Location header.
Will restore the session if the request URI is formatted accordingly, and rewrite the URI to remove the additional part.
If session_should_rewrite returns a true value, HTML::TokePaser::Simple is used to traverse the body to replace all URLs which get true returned by session_should_rewrite_uri so that they contain the session ID.
session_should_rewrite
session_should_rewrite_uri
URI sessions are very prone to session hijacking problems.
Make sure your users know not to copy and paste URIs to prevent these problems, and always provide a way to safely link to public resources.
Also make sure to never link to external sites without going through a gateway page that does not have session data in it's URI, so that the external site doesn't get any session IDs in the http referrer header.
Due to these issues this plugin should be used as a last resort, as Catalyst::Plugin::Session::State::Cookie is more appropriate 99% of the time.
Take a look at the IP address limiting features in Catalyst::Plugin::Session to see make some of these problems less dangerous.
To exclude some sections of your application, like a goodbye page (see "CAVEATS") you should make extend the session_should_rewrite_uri method to return true if the URI does not point to the goodbye page, extend prepare_action to not rewrite URIs that match /-/ (so that external URIs with that in their path as a parameter to the goodbye page will not be destroyed) and finally extend uri_with_sessionid to rewrite URIs with the following logic:
prepare_action
/-/
uri_with_sessionid
URIs that match /^$base/ are appended with session data ( $c->NEXT::uri_with_sessionid).
/^$base/
$c->NEXT::uri_with_sessionid
External URIs (everything else) should be prepended by the goodbye page. (e.g. http://myapp/link/http://the_url_of_whatever/foo.html).
http://myapp/link/http://the_url_of_whatever/foo.html
But note that this behavior will be problematic when you are e.g. submitting POSTs to forms on external sites.
Catalyst, Catalyst::Plugin::Session,Catalyst::Plugin::Session::FastMmap HTML::TokeParser::Simple, MIME::Types.
HTML::TokeParser::Simple
MIME::Types
This module is derived from Catalyst::Plugin::Session::FastMmap code, and has been heavily modified since.
nothingmuch@woobling.org
This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.
2 POD Errors
The following errors were encountered while parsing the POD:
'=item' outside of any '=over'
You forgot a '=back' before '=head1'
To install Catalyst::Plugin::Session::State::URI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Catalyst::Plugin::Session::State::URI
CPAN shell
perl -MCPAN -e shell install Catalyst::Plugin::Session::State::URI
For more information on module installation, please visit the detailed CPAN module installation guide.