Catalyst::Plugin::SessUser:ContributedCatalyst::Plugin::Session::State::URI(3)NAMECatalyst::Plugin::Session::State::URI - Use URIs to pass the session id
between requests
SYNOPSIS
use Catalyst qw/Session Session::State::URI Session::Store::Foo/;
# If you want the param style rewriting, set the parameter
MyApp->config('Plugin::Session' => {
param => 'sessionid', # or whatever you like
});
DESCRIPTION
In order for Catalyst::Plugin::Session to work the session ID needs to
be available on each request, and the session data needs to be stored
on the server.
This plugin puts the session id into URIs instead of something like a
cookie.
By default, it rewrites all outgoing URIs, both redirects and in
outgoing HTML, but you can exercise control over exactly which URIs are
rewritten.
METHODS
session_should_rewrite
This method is consulted by "finalize", and URIs will be rewritten
only if it returns a true value.
Rewriting is controlled by the "$c->config('Plugin::Session' => {
rewrite_body => $val })" and "$c->config('Plugin::Session' => {
rewrite_redirect => $val })" config settings, both of which default
to true.
To globally disable rewriting simply set these parameters to false.
If "$c->config('Plugin::Session' => { no_rewrite_if_cookie => 1
})", 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. This parameter also defaults to true.
session_should_rewrite_body
This method checks "$c->config('Plugin::Session' => {rewrite_body
=> $val})" first. If this is true, it then calls
"session_should_rewrite_type".
session_should_rewrite_type
This method determines whether or not the body should be rewritten,
based on its content type.
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->{'Plugin::Session'}{rewrite_types}", or subclass this
method.
session_should_rewrite_redirect
This method determines whether or not to rewrite the "Location"
header of the response.
This method checks "$c->config->{session}{rewrite_redirect}" first.
If this is true, it then checks if the status code is a number in
the 3xx range.
session_should_rewrite_uri $uri_text
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.
You are encouraged to override this method if it's logic doesn't
suit your setup.
session_should_rewrite_uri_mime_type $uri_obj
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_with_sessionid $uri_text, [ $sid ]
When using path style rewriting (the default), it will append
"/-/$sessionid" to the uri path.
http://myapp/link -> http://myapp/link/-/$sessionid
When using 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".
session_rewrite_if_needed
Rewrite the response if necessary.
rewrite_body_with_session_id $sid
Calls either "rewrite_html_with_session_id" or
"rewrite_text_with_session_id" depending on the content type.
rewrite_html_with_session_id $sid
Rewrites the body using HTML::TokePaser::Simple.
This method of rewriting also matches relative URIs, and is thus
more robust.
rewrite_text_with_session_id $sid
Rewrites the body using URI::Find.
This method is used when the content does not appear to be HTML.
rewrite_redirect_with_session_id $sid
Rewrites the "Location" header.
uri_with_param_sessionid
uri_with_path_sessionid
EXTENDED METHODS
prepare_path
Will restore the session if the request URI is formatted
accordingly, and rewrite the URI to remove the additional part.
finalize
Rewrite a redirect or the body HTML as appropriate.
delete_session_id
get_session_id
set_session_id
setup_session
uri_for
CAVEATS
Session Hijacking
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.
Goodbye page recipe
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_path" 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:
· URIs that match "/^$base/" are appended with session data (
"$c->maybe::next::method").
· External URIs (everything else) should be prepended by the goodbye
page. (e.g.
"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.
SEE ALSO
Catalyst, Catalyst::Plugin::Session,Catalyst::Plugin::Session::FastMmap
"HTML::TokeParser::Simple", "MIME::Types".
AUTHORS
This module is derived from Catalyst::Plugin::Session::FastMmap code,
and has been heavily modified since.
Andrew Ford
Andy Grundman
Christian Hansen
Dave Rolsky
Yuval Kogman, "nothingmuch@woobling.org"
Marcus Ramberg
Sebastian Riedel
Hu Hailin
Tomas Doran, "bobtfish@bobtfish.net" (Current maintainer)
Florian Ragwitz "rafl@debian.org"
COPYRIGHT
This program is free software, you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.12010Catalyst::Plugin::Session::State::URI(3)