ANNOUNCE: Apache::Quota 0.02 (first release)

[Dave Rolsky <au...@urth.org>]

I just uploaded the first public release of Apache::Quota, a module idea I
mentioned on this list a month or so ago.

It implements very flexible quota tracking with mod_perl.  It's quite a
bit more flexible than mod_bandwidth or mod_throttle, and can be used both
throttling and quota implementation.

For this first release, I'll include the docs below my sig.


-dave

/*=======================
House Absolute Consulting
www.houseabsolute.com
=======================*/


NAME
    Apache::Quota - Flexible transfer limiting/throttling under mod_perl

SYNOPSIS
      PerlSetVar  QuotaFile  /tmp/Apache-Quota.db
      PerlSetVar  QuotaLocker       BerkeleyDB

      <Location /foo>
        PerlSetVar  QuotaLocationKey  foo
        PerlSetVar  QuotaType         client-ip
        PerlSetVar  QuotaPeriod       1d
        PerlSetVar  QuotaLimit        3M
        PerlSetVar  QuotaOnExceed     notes

        PerlFixupHandler  Apache::Quota
      </Location>

      <Location /bar>
        PerlSetVar  QuotaLocationKey  bar
        PerlSetVar  QuotaType         sub
        PerlSetVar  QuotaSub          "MyApp::get_user_id"
        PerlSetVar  QuotaPeriod       60s
        PerlSetVar  QuotaLimit        500k
        PerlSetVar  QuotaOnExceed     deny

        PerlFixupHandler  Apache::Quota
      </Location>

DESCRIPTION
    This module provides flexible transfer quotas for all or part of a site.
    Additionally, limiting may be for the site as a whole, on a per-client
    IP basis, or based on some other criterion you choose.

USAGE
    Most of this module's functionality is used by setting variables via the
    mod_perl "PerlSetVar" directive. The module should be installed as a
    "PerlFixupHandler" for a location.

  PerlSetVar Parameters
    The following directives are available:

    * QuotaFile (required)
        The DB file where quota usage will be recorded. A single file can be
        shared across multiple locations, or you can use multiple files.

    * QuotaLimit (required)
        This sets the quota limit. This can be a plain number, which will be
        interpreted as bytes, or a number followed by a letter. The valid
        letters are "k/K" (kilobytes), "m/M" (megabytes), or "g/G"
        (gigabytes). This module defines a kilobyte as 1024 bytes, a
        megabyte as 1024 ** 2 bytes, and a gigabyte as 1024 ** 3 bytes.

    * QuotaPeriod (required)
        This sets the time period for which a quota is enforced. This can be
        a number, which will be interpreted as seconds, or a number followed
        by a letter. The valid letters are "s/S" (seconds), "m/M" (minutes),
        "h/H" (hours), or "d/D" (days).

    * QuotaType
        This can be one of "global", "client-ip", or "sub". If it is set to
        "global", then the bandwidth limit is shared across all clients
        accessing the particular location.

        If it is set to "client-ip", then quota usage is tracked on a per
        client IP address basis. Of course, given the presence of proxies,
        this may not actually correspond to a single client.

        If it is set to "sub", then the module will call a user-specified
        subroutine to generate the unique identifier for the client. One way
        to use this would be to have it call a subroutine that gets a unique
        id from a cookie.

        This parameter defaults to "global".

    * QuotaSub
        This is the subroutine that should be called if QuotaType is set to
        "sub". This should simply be a string like "MyApp::quota_key". This
        parameter is required if you set QuotaType to "sub".

    * QuotaLocationKey
        If this is specified, then this key is used to uniquely indentify
        the current location. This allows you to use one quota file for
        multiple locations, and track quota usage for each location
        separately. This key can be anything, but it must not contain a
        colon (:).

        If not given, this default to "Apache-Quota global key" for _all_
        locations.

    * QuotaOnExceed
        This parameter defines what the module does when it detects that a
        client has exceed the quota. The two valid options are "deny" or
        "notes". If this is set to "deny", then the module simply returns
        the "FORBIDDEN" constant for the request. If it is set to "notes",
        then it sets "$r->notes('Apache::Quota::exceeded')" to a true value.
        This can be checked from your application code.

        This defaults to "deny".

    * QuotaLocker
        The locking class to use. This should be one of "BerkeleyDB" or
        "DB_File::Lock". Using BerkeleyDB is preferred, as it better
        supported and uses a much more robust locking implementation. If no
        locker is specified, the module will try to load BerkeleyDB and
        DB_File::Lock, in that order. If it cannot load either, it will die.

    * QuotaDebug
        Setting this to a true value turns on debugging messages which are
        sent to the Apache log via "warn()".

  Functions
    This module also offers some functions for directly looking at and
    manipulating quotas. None of these functions are exportable.

    All of these functions accept the following parameters:

    * file (required)
        This is the db file you want to access.

    * locker (required)
        The locker class to use, "BerkeleyDB" or "DB_File::Lock".

    * usage
        This function returns the current usage values in the form of a
        hash.

        It takes an additional optional parameter, "period". If given, this
        will be used to determine which entries to ignore. This can be any
        value which is valid for the "QuotaPeriod" parameter.

        The has returned is keyed on the "full key" used by Apache::Quota
        internally. This should be treated as an opaque value, and is
        returned only so that you can pass it back to the "set_key()" or
        "reset_key()" functions later.

        The hash values are hash references. Each reference always contains
        the key "bytes", which is the total number of bytes used by the
        user/client identified by the "full key".

        The other keys in the hash reference varies depending on whether the
        "QuotaType" parameter was set to "global", "client", or "sub". If it
        was set to "global", then there are no other keys. If the type was
        set to "client-ip", then the other key is "ip", and contains the
        client's IP address. If the type was set to "sub", then the other
        key is "sub", and contains the value returned by the subroutine you
        provided.

    * set_key
        This function requires two additional parameters, "key" and "value".
        The key should be a "full key", as returned by the "usage()"
        function. The value should be a number, which will be the new number
        of bytes for the key. All historical values will be wiped out, and
        the number value will be set, along with the current time.

        If the key is not in the db file, then this method returns a false
        value.

    * reset_key
        This function requires a "key" parameter. This completely resets
        usage information for the given key.

        If the key is not in the db file, then this method returns a false
        value.

SUPPORT
        Please submit bugs to the CPAN RT system at
        http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Apache%3A%3AQuota or
        via email at bug-apache-quota@rt.cpan.org.

AUTHOR
        Dave Rolsky <au...@urth.org>

COPYRIGHT
        Copyright (c) 2003 David Rolsky. All rights reserved. This program
        is free software; you can redistribute it and/or modify it under the
        same terms as Perl itself.

        The full text of the license can be found in the LICENSE file
        included with this module.

SEE ALSO
        The Apache modules mod_bandwidth and mod_throttle.


-- 
Report problems: http://perl.apache.org/bugs/
Mail list info: http://perl.apache.org/maillist/modperl.html
List etiquette: http://perl.apache.org/maillist/email-etiquette.html