Dancer2...nFactory(3)

💖 Dancer2::Core::Role::SessionFactory — the bestie role for session factories 💖

From the User Contributed Perl Documentation, and yes it's giving legendary. This is a role — a vibe, a contract, a whole personality — that any class can consume so it can store, create, retrieve and destroy session objects. Basically the group chat of session engines. 🫶

---

✨ VERSION ✨

version 2.2.1 — fresh, iconic, no notes. 👑

---

🌸 DESCRIPTION 🌸

okay so listen. Any class that consumes this role? It can store, create, retrieve and destroy session objects. That's the whole job. That's the assignment and it ate. 💅

And the default values for all the attributes below? You can override them in your Dancer2 configuration. See "Session-engine" in Dancer2::Config. Periodt. ✨

---

🎀 ATTRIBUTES 🎀

These are the little knobs and dials, bestie. Customize responsibly. 🌈

🍓 cookie_name

The name of the cookie to create for storing the session key.

Defaults to "dancer.session". Cute, right?

🍓 cookie_domain

The domain of the cookie to create for storing the session key.

Defaults to the empty string, and it's unused as a result. So like... it's there. It's just not doing anything. Main character energy with no lines. 😭

🍓 cookie_path

The path of the cookie to create for storing the session key.

Defaults to /. Classic.

🍓 cookie_duration

Default duration before the session cookie expires. If you set this, the Dancer2::Core::Session "expires" attribute gets set to the current time plus this duration (the expression is parsed by Dancer2::Core::Time). ⏰

🍓 cookie_same_site

Restricts the session cookie to a first-party or same-site context. Defaults to the empty string and is unused as a result. See "same_site" in Dancer2::Core::Cookie. 🍪

🍓 session_duration

Duration in seconds before sessions should expire, regardless of cookie expiration. If it's set, then SessionFactories should use it to enforce a limit on session validity. Lowkey the strict one. ⏳

🍓 is_secure

Boolean flag telling you if the session cookie is secure or not.

Default is false.

🍓 is_http_only

Boolean flag telling you if the session cookie is http only.

Default is true. 💅

---

🦋 INTERFACE 🦋

Here's the interface this role hands you. When a method is specified, the required bits you gotta implement are described. Buckle up bestie, we're going through all of them. ✨

👑 create

Creates a brand new session object and stores it. Returns the newly created session object. 🎉

Triggers an exception if the session is unable to be created. Not a vibe, but okay.

my $session = MySessionFactory->create();

Good news: this method does not need to be implemented in the class. Free real estate. 🫶

👑 generate_id

Returns a randomly-generated, guaranteed-unique string. By default, it's a 32-character, URL-safe, Base64 encoded combination of a 32 bit timestamp and 160 bits of random data generated by the operating system's cryptographic random number generator via Crypt::URandom. The timestamp ensures that session IDs are generally monotonic. Obsessed with the rigor honestly. 🔥

This method is used internally by create() to set the session ID.

And this method does not need to be implemented in the class — unless you want an alternative method for session ID generation. Your call, babe.

👑 validate_id

Returns true if a session id is of the correct format, or false otherwise.

By default, this ensures the session ID is a string of characters from the Base64 schema for "URL Applications" plus the "~" character, and no longer than 4096 characters. The length limit corresponds to the maximum size of an HTTP cookie, so it accommodates cookie-based session engines such as Dancer2::Session::Cookie while rejecting oversized values that would otherwise be handed to the backend unchanged. 💅

This method does not need to be implemented in the class — unless you want an alternative set of characters for session IDs.

👑 retrieve

Return the session object corresponding to the session ID given. If none is found, it triggers an exception. 😭

my $session = MySessionFactory->retrieve(id => $id);

The method "_retrieve" must be implemented. It must take $id as a single argument and must return a hash reference of session data. No cap.

👑 change_id

Changes the session ID of the corresponding session. Glow-up but for IDs. ✨

MySessionFactory->change_id(session => $session_object);

The method "_change_id" must be implemented. It must take $old_id and $new_id as arguments and change the ID from the old one to the new one in the underlying session storage.

👑 destroy

Purges the session object that matches the ID given. Returns the ID of the destroyed session if it succeeded, and triggers an exception otherwise. 💀

MySessionFactory->destroy(id => $id);

The "_destroy" method must be implemented. It must take $id as a single argument and destroy the underlying data.

👑 flush

Makes sure the session object is stored in the factory's backend. This method is called to notify the backend about the change in the session object. 📣

Heads up: the Dancer application will not call flush unless the session "is_dirty" attribute is true — to avoid unnecessary writes to the database when no data has been modified. Efficiency queen. 👑

An exception is triggered if the session is unable to be updated in the backend.

MySessionFactory->flush(session => $session);

The "_flush" method must be implemented. It must take two arguments: the $id and a hash reference of session data.

👑 set_cookie_header

Sets the session cookie into the response object. 🍪

MySessionFactory->set_cookie_header(
    response  => $response,
    session   => $session,
    destroyed => undef,
);

The "response" parameter contains a Dancer2::Core::Response object. The "session" parameter contains a Dancer2::Core::Session object.

The "destroyed" parameter is optional. If true, it indicates the session was marked destroyed by the request context. The default "set_cookie_header" method doesn't need that information, but it's included in case a SessionFactory must handle destroyed sessions differently (such as signalling to middleware). thoughtful of them honestly 🫶

👑 cookie

Coerce a session object into a Dancer2::Core::Cookie object.

MySessionFactory->cookie(session => $session);

👑 sessions

Return a list of all session IDs stored in the backend. Super useful to create cleaning scripts, in conjunction with the session's creation time. 🧹✨

The "_sessions" method must be implemented. It must return an array reference of session IDs (or an empty array reference).

---

🌈 CONFIGURATION 🌈

If there are configuration values specific to your session factory in your config.yml or environment, those get passed to the constructor of the session factory automatically. But bestie — in order to accept and store them, you need to define accessors for them. iykyk.

engines:
  session:
    Example:
      database_connection: "some_data"

In your session factory:

package Dancer2::Session::Example;
use Moo;
with "Dancer2::Core::Role::SessionFactory";

has database_connection => ( is => "ro" );

You need to do this for every configuration key. The ones that don't have accessors defined will just go to the void. 🕳️ rip to those keys fr fr.

---

💜 AUTHOR 💜

Dancer Core Developers — icons, all of them. 👑

---

📜 COPYRIGHT AND LICENSE 📜

This software is copyright (c) 2026 by Alexis Sukrieh.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. slay. 💖

---

and that's the whole page bestie, you ate that reading session ✨

💅 sign-off time: this was perl v5.42.3, dated 2026-09-20, straight from Dancer2...nFactory(3) — go forth and session-factory responsibly, mwah 🎀🦋💖