view release on metacpan or  search on metacpan

lib/Apache2/ClickPath/Store.pm  view on Meta::CPAN

  | | Server N    ||  |
  | |             ||  |
  | |        *--------+
  | |             ||
  | +-------------+|
  +----------------+

=head2 Protocol

The store offers a simple HTTP-form interface to get and set information
items. It doesn't matter whether GET or POST requests are used. The data
is accepted in C<multipart/form-data> or C<application/x-www-form-urlencoded>.
The following CGI-parameter control how the data is accessed:

=over 4

=item B<a>

can be either C<get> or C<set> and defines whether the data is read or written.

=item B<s>

the session identifier. All data is stored in a session-oriented way. Normally
this is a session that was generated by C<Apache2::ClickPath> but in
principle it could be any string not containing a slash (C</>). It must not
start with a hash sign (#).

=item B<k>

within a session data is accessed via a key. The key is a string of characters
all matching Perl's C<\w> regular expression. A particular data item is
identified by combination of session and key.

=item B<v>

this parameter is valid only if C<a> is C<set>. It contains the actual data
to be written.

=back

Normally the store answers a request with HTTP status code 200 (OK). In case
of a read operation the response body contains just the data item. The HTTP
content-type is set to C<application/octet-stream>. In case of a write
operation the string C<ok> is returned with the content-type set to
C<text/plain>.

If something went wrong it is indicated by the HTTP status code. The store
returns the following codes:

=over 4

=item B<500> Server Error

this indicates a configuration error. Maybe the data directory doesn't exist
or is not writeable.

=item B<400> Bad Request

an invalid key or session identifier was used.

=item B<404> Not Found

the data item identified by the combination of session and key was not found.
If the item had once existed then it was possibly hit by a timeout.

=back

=head1 CONFIGURATION

C<Apache2::ClickPath::Store> is loaded with a C<PerlLoadModule> directive and
then configured with the following directives. At least
C<ClickPathStoreDirectory> must be given to use the store.

=over 4

=item B<ClickPathStoreDirectory>

sets the directory where the session data is stored. Under this directory
subdirectories will be created one for each session. These subdirectories
then will contain data files one for each data item.

If a relative path is given it is treated relative to C<ServerRoot>.

=item B<ClickPathStorePath>

set an URI where the store is located. That directive effectively created
a C<< <Location> >> section where the store runs. The following lines have
the same effect as C<ClickPathStorePath /store>:

 <Location /store>
     SetHandler modperl
     PerlResponseHandler Apache2::ClickPath::Store::handler
 </Location>

If omitted the whole server is configured as store.

=item B<ClickPathStoreTimeout>

=item B<ClickPathStoreCleanupInterval>

These 2 directives control data expiring and removal. If a timeout is set
(in seconds) each time a connection is hung up a cleanup handler is run. The
first thing it checks if at least a cleanup interval is passed by since its
last run. If no nothing is done. If yes it finds all subdirectories of
C<ClickPathStoreDirectory> that are not modified for more than a timeout
period. Each time a data item is accessed (read or written) its directories
modification time is adjusted. Thus, checking the modification time of the
directory checks if the session data was in use for the last timeout
period or not.

Then each expired directory is marked by prepending a hash sign (#) to its
name. This way the data is not accessible anymore but pending operations
in parallel processes can finish normally.

C<ClickPathStoreTimeout> specifies the timeout period in seconds.
C<ClickPathStoreCleanupInterval> specifies after how many seconds the cleanup
handler should run again. It defaults to 60.

=back

=head1 SEE ALSO