This is a module to make an Apache::Session store available to methods in your controllers. It is not just a session id - if you just need a tracking mechanism or a way to store data in cookies, you should roll your own handler with Apache2::Cookie.

Your session module uses an Apache2::Controller::Session tracker module as a base and you specify your Apache::Session options either as config variables or by implementing a method <getoptions()>.

Instead of having a bunch of different options for all the different Apache::Session types, it's easier for me to make you provide a method session_options() in your subclass that will return a has of the appropriate options for your chosen session store.

When this handler runs, it ties the session into a special hash that it keeps internally, and loads a copy into $r->pnotes->{a2c}{session}. So, modifying the session hash is fine, as long as you do not dereference it, or as long as you save your changes back to $r->pnotes->{a2c}{session}.

No changes are auto-committed. The one in pnotes is copied back into the tied session hash in a PerlLogHandler, after the server finishes output but before it closes the connection to the client. If the connection is detected to be aborted in the PerlLogHandler phase, changes are NOT saved into the session object.

If you implemented get_options() as per above and decided to save your $dbh for later use in your controllers, feel free to start transactions and use them normally. Just make sure you use "eval" in perlfunc correctly and roll back or commit your transactions.

If you decide to push a PerlLogHandler to roll back transactions for broken connections or something, or PerlCleanupHandler to do something else (don't use post-connection phases for database transactions or you'll get out of sync), be aware that this handler 'unshifts' a log handler closure that saves the copy in pnotes back into the tied hash. It does this by re-ordering the PerlLogHandler stack with "get_handlers" in Apache2::RequestUtil and set_handlers(). So if you push another post-response handler that wants to choose whether to save the session or not, be aware that it may not work as you expect unless you re-order that phase's handler stack again.

Generally in your code, it's complicated to decide whether everything has worked before you save anything to the session. It's easier just to save stuff, and then if something goes wrong, it is as if this rolls back.

A PerlLogHandler subroutine is 'unshifted' to the request stack which decides whether to save changes to the session. By default, it saves changes only if A) the connection is not aborted, and B) your controller set HTTP status < 300, i.e. it returned OK (0), one of the HTTP_CONTINUE family (100+) or one of the HTTP_OK family (200+).

So for an HTTP_SERVER_ERROR, or throwing an exception, redirecting, forbidding access, etc (>= 300), it normally would not save changes. If your Apache2::Controller controller module returns one of these non-OK statuses, but you want to force the saving of the session contents, set $self->pnotes->{a2c}{session_force_save} = 1 before your response phase controller returns a status to Apache2::Controller.

If the connection is aborted mid-way (i.e. the pipe was broken due to a network failure or the user clicked 'stop' in the browser), then the session will not be saved, whether you set the force save flag or not. (If this is not useful and correct behavior contact me and I will add another switch, but it seems right to me.)

It actually re-orders the PerlLogHandler stack so that its handlers run first, before the handler pushed by Apache2::Controller::DBI::Connector commits the database transaction, for example.

This used to push a PerlCleanupHandler to save the session, which made sense at the time, but the OpenID auth tests revealed that the Cleanup handler is apparently assigned a thread to process it independently, even under prefork with Apache::Test. So, the test script was firing off a new request before the old request Cleanup handler ran to save the session, which resulted in sporadic and inconsistent failures... yeah, THOSE kind, you know the type, the most maddening ones.

Apache::Session does not always save automatically, for example if you change something in the bottom tier of a multi-level hash. If you want to, set the directive flag A2C_Session_Always_Save and this will set a top-level timestamp $r->pnotes->{a2c}{session}{a2c_timestamp} on the way out to trigger Apache::Session to save everything. But if you are potentially accessing the session contents without setting it every time, you should just set a top-level timestamp manually to indicate to Apache::Session that you want things saved at the end of every request, but this may slow you down on a busy site, so it is not the default. See "A2C_Session_Always_Save" in Apache2::Controller::Directives and "BEHAVIOR" in Apache::Session.

See Apache2::Controller::Session::Cookie for how to implement a custom tracker subclass. This implements $sid = get_session_id() which gets a session id from a cookie, and set_session_id($sid) which sets the session id in the cookie.

Perhaps some custom tracker subclass would implement get_session_id() to get the session_id out of the request query params, and set_session_id() would push a PerlOutputFilterHandler to post-process all other handler output and append the session id param onto any url links that refer to our site. That would be cool... release your own plug-in. If you wanted to do it with combined cookies and url params in this way you could overload get_session_id() and set_session_id(), etc. etc.

The process() method attaches or creates a session, and pushes a PerlLogHandler closure to save the session after the end of the request.

It sets the session id cookie with an expiration that you set in your subclass as our $expiration = ... in a format that is passed to Apache2::Cookie. (i.e. '3M', '2D', etc.) Don't set that if you want them to expire at the end of the browser session.