Catalys...ate::URI(3)

📦
version 0.15 · 2 versions
, in fedora 43

✨ NAME ✨

Catalyst::Plugin::Session::State::URI — the plugin that uses URIs to pass the session id between requests 💅

(yes bestie, it's a section 3 perl module, User Contributed Perl Documentation, and it's giving no cookies required energy 🍪🚫)

🦋 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 🌸

okay so here's the tea ☕ For Catalyst::Plugin::Session to actually work, two things need to be true: the session ID has to be available on every single request, and the session data needs to live on the server. That's just how it is, no cap.

This plugin's whole thing? It puts the session id into URIs instead of doing something like a cookie. Iconic, chaotic, but iconic. ✨

By default it rewrites all outgoing URIs — both redirects and outgoing HTML — but bestie, you can exercise control over exactly which URIs get rewritten. Main character energy only. 👑

💖 METHODS 💖

  • session_should_rewrite — finalize consults this method, and URIs will only be rewritten if it returns a true value. The rewriting is controlled by the $c->config('Plugin::Session' => { rewrite_body => $val }) and $c->config('Plugin::Session' => { rewrite_redirect => $val }) config settings, and both of those default to true. Wanna globally disable rewriting? Just set these parameters to false, easy. Also: 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 that's true, it then calls session_should_rewrite_type. Chain reaction, love that for us. 🔗
  • session_should_rewrite_type — this one decides 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 it to do that, you must provide a list of valid content types in $c->config->{'Plugin::Session'}{rewrite_types}, or subclass this method. Your move, bestie. 🎀
  • session_should_rewrite_redirect — determines whether or not to rewrite the Location header of the response. It checks $c->config->{session}{rewrite_redirect} first. If that's 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'll return true for URIs under $c->req->base, and it'll 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 its logic doesn't suit your setup. Live your truth 💜
  • 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. So:
http://myapp/link -> http://myapp/link/-/$sessionid

When using param style rewriting, it will add a parameter key/value pair after the uri path. Like:

http://myapp/link -> http://myapp/link?$param=$sessionid

If $sid is not provided it will default to $c->sessionid. Slay 🫶

  • session_rewrite_if_needed — rewrite the response if necessary. Simple as that.
  • 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 🚨

okay bestie, deep breath, because this is the serious part. URI sessions are very prone to session hijacking problems. Like, extremely. 😭

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. fr fr, we're not kidding.

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:

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

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

and that's the whole page, bestie!! 💖✨🎀🦋🌸💅🫶 this was perl v5.42.0, dated 2025-07-25, and it ate, no crumbs. go forth and maybe don't put your session ids in URIs unless you absolutely have to, iykyk 😭👑🌈⭐💀

📦 where this page comes from