From: Graham Leggett
Date: Sat, 25 Feb 2012 20:32:29 +0000 (+0000)
Subject: Add a section to the mod_session documentation that better describes how to integrate
X-Git-Tag: 2.5.0-alpha~7439
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=5965fdd1f393cacc482108d3f0947d3a791ce512;p=apache
Add a section to the mod_session documentation that better describes how to integrate
applications with mod_session.
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1293678 13f79535-47bb-0310-9956-ffa450edef68
---
diff --git a/docs/manual/mod/mod_session.xml b/docs/manual/mod/mod_session.xml
index eafaff98c7..32c7c4fae6 100644
--- a/docs/manual/mod/mod_session.xml
+++ b/docs/manual/mod/mod_session.xml
@@ -63,10 +63,17 @@
What is a session?
At the core of the session interface is a table of key and value pairs
- that are made accessible across browser requests.
+ that are made accessible across browser requests. These pairs can be set
+ to any valid string, as needed by the application making use of the
+ session.
- These pairs can be set to any valid string, as needed by the
- application making use of the session.
+ The "session" is a application/x-www-form-urlencoded
+ string containing these key value pairs, as defined by the
+ HTML specification.
+
+ The session can optionally be encrypted and base64 encoded before
+ being written to the storage mechanism, as defined by the
+ administrator.
Who can use a session?
@@ -99,9 +106,9 @@
Keeping sessions on the browser
- Where keeping track of a session on a server is too resource
- intensive or inconvenient, the option exists to store the contents
- of the session within a cookie on the client browser instead.
+ In high traffic environments where keeping track of a session on a
+ server is too resource intensive or inconvenient, the option exists to store
+ the contents of the session within a cookie on the client browser instead.
This has the advantage that minimal resources are required on the
server to keep track of sessions, and multiple servers within a server
@@ -251,6 +258,64 @@
examples.
+ Integrating Sessions with External Applications
+
+ In order for sessions to be useful, it must be possible to share the contents
+ of a session with external applications, and it must be possible for an
+ external application to write a session of its own.
+
+ A typical example might be an application that changes a user's password set by
+ mod_auth_form. This application would need to read the current
+ username and password from the session, make the required changes to the user's
+ password, and then write the new password to the session in order to provide a
+ seamless transition to the new password.
+
+ A second example might involve an application that registers a new user for
+ the first time. When registration is complete, the username and password is
+ written to the session, providing a seamless transition to being logged in.
+
+
+ - Apache modules
+ - Modules within the server that need access to the session can use the
+ mod_session.h API in order to read from and write to the
+ session. This mechanism is used by modules like mod_auth_form.
+
+
+ - CGI programs and scripting languages
+ - Applications that run within the webserver can optionally retrieve the
+ value of the session from the HTTP_SESSION environment
+ variable. The session should be encoded as a
+ application/x-www-form-urlencoded string as described by the
+ HTML specification. The environment
+ variable is controlled by the setting of the
+ SessionEnv directive. The session
+ can be written to by the script by returning a
+ application/x-www-form-urlencoded response header with a name
+ set by the SessionHeader
+ directive. In both cases, any encryption or decryption, and the reading the
+ session from or writing the session to the chosen storage mechanism is handled
+ by the mod_session modules and corresponding configuration.
+
+
+ - Applications behind mod_proxy
+ - If the SessionHeader
+ directive is used to define an HTTP request header, the session, encoded as
+ a application/x-www-form-urlencoded string, will be made
+ available to the application. If the same header is provided in the response,
+ the value of this response header will be used to replace the session. As
+ above, any encryption or decryption, and the reading the session from or
+ writing the session to the chosen storage mechanism is handled by the
+ mod_session modules and corresponding configuration.
+
+ - Standalone applications
+ - Applications might choose to manipulate the session outside the control
+ of the Apache HTTP server. In this case, it is the responsibility of the
+ application to read the session from the chosen storage mechanism,
+ decrypt the session, update the session, encrypt the session and write
+ the session to the chosen storage mechanism, as appropriate.
+
+
+
Session