NAME
    Catalyst::Plugin::Session::State::URI - Saves session IDs by rewriting
    URIs delivered to the client, and extracting the session ID from
    requested URIs.

SYNOPSIS
        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
        };

DESCRIPTION
    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.

METHODS
    session_should_rewrite
        This method is consulted by "finalize". The body will be rewritten
        only if it returns a true value.

        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.

        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.

        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.

    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.

    uri_with_sessionid $uri_text
        By path style rewriting, it will appends "/-/$sessionid" to the uri
        path.

        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

EXTENDED METHODS
    prepare_action
        Will restore the session if the request URI is formatted
        accordingly, and rewrite the URI to remove the additional part.

    finalize
        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.

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_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:

    *   URIs that match "/^$base/" are appended with session data (
        "$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").

    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
    Yuval Kogman, "nothingmuch@woobling.org"
    Marcus Ramberg
    Sebastian Riedel
    Hu Hailin

COPYRIGHT
    This program is free software, you can redistribute it and/or modify it
    under the same terms as Perl itself.

POD ERRORS
    Hey! The above document had some coding errors, which are explained
    below:

    Around line 343:
        '=item' outside of any '=over'

    Around line 357:
        You forgot a '=back' before '=head1'