develooper Front page | perl.module-authors | Postings from November 2005

Would this Module be useful? (Subclass of Apache::Request with input validation / session data)

From:
John Doe
Date:
November 22, 2005 12:18
Subject:
Would this Module be useful? (Subclass of Apache::Request with input validation / session data)
Message ID:
200511222118.20339.security.department@tele2.ch
Hello all,

This is my first post of this kind. I apologize if my question or myself is 
stupid, unclear, the pod below too long etc. 

I'd very appreciate any comments, suggestions, criticism etc. concerning the 
module described in the pod below. My native language is not english.

I also have some specific questions, if the pod is worth to be discussed.

- Could it be useful for other people than me?
- Did I miss a module with similar (small) functionality?
- Is it enough generic? (dbh, DBD::mysql per default...)
- Is anything missing that should not?
- Do you see obvious problems I don't see?
- Could the api be improved?

The module names are _just_temporarily_. The pod misses some clarity.

There is also a helper Module which provides predefined callbacks
and a make_callback() method which can take a regex (string, qr//, 
Regexp::Common), or a set of values, or a dbh and fieldname to search for a 
value in a database.

Thanks a lot for any help, comments...

===
POD (hopefully the formatting is not lost)
===

NAME
    Apache::Request::Restricted - Subclass of Apache::Request adding input
    validation restrictions and optional persistency

DESCRIPTION
    Request values are only accessible if a parameter specification has been
    defined, and if the values pass the validation callback tests.

    Parameters may be marked as persistent, so they are acessible through
    the param() method in further requests. They are automatically updated
    with actual request data.

    The module provides means to centralize input validation and keeping
    session data. No need to care about theses things anymore when request
    parameters are accessed and used.

MODIFIED METHODS
    new(-pconfig=>$param_configuration 
           [, -dbh=>$dbh [, -sid_name=>$sid_name] 
           [, -no_create=>$bool] ])
        Create a new object.

        All acessible request parameters must have a definition in
        $param_configuration, consisting of a hashref with parameter names
        or regexes as keys, and an arrayref of callbacks as values. See
        PARAMETER CONFIGURATION below.

        If session management is wanted, -dbh must be provided, and
        optionally

         - -sid_name: The name of the session id in the request
           (defaults to '_session_id')
         - -no_create=>1 (default 0) if no new session should be
           created if the request contains a session id without
           data in the session. Otherwise, a new session with a
           new session id is created, as if no session id had
           been provided by the request.

        An existent session is opened if a session id is specified in the
        actual request, and data exists for it.

        A session is created if either a session id the actual request is
        only defined but not set, or - in case -no_create is true - if a
        session id is provided but no session data present for it.

        To switch to session management, include a '$sid_name=' into the
        request.

        [Of course this is only applied if -dbh is provided and there are
        persistent request parameters]

        Returns undef on errors.

   instance([@args])
        Analogous to the method in Apache::Request: The same arguments as
        for new() can be provided; they are ignored from the second call on.
        The object is a singleton on a per request level.

    param()
        Returns all defined request parameter names (same as the base
        class).

    param($name)
        Returns the value(s) that passed the validation checks. Data may
        come from the request or the session.

    param($name, @values)
        Set the values of a request parameter (and eventually of the
        session). Note the CGI-Syntax (The base class uses \@values).

ADDITIONAL METHODS
    add_config($pconfig)
        Additionaly to the -pconfig new parameter, parameter specifications
        can be added later on. If the key is a string, an existent old spec
        is overwritten. If the key is a regex, it is appended to the
        existing regexes.

        As soon as a request parameter ist specified as persistent, a
        session is created at the next param() call.

     sid()
        Returns the actual session id or undef if session management is not
        wanted or deactivated because there are no persistent request
        parameters defined.

        NOTE (TODO): A sid is not available before the first call of param()
        with argument(s).

    register_callback ($name, $cb)
        Class method to register callbacks under names, for later retrieval
        with callcack(). Returns false if the name already exists, else
        true.

    callback([$name])
        Class method. With $name provided, get the callback registered with
        register_callback() by its name. Returns undef if the name does not
        exists.

        Without arguments, returns a list of all names of registered
        callbacks.

        Normally this method is not used directly (it is called from new()
        and add_pconfig() when specifying a callback name instead of a
        callback).

    errors()
        Returns the callback validation failures since object creation
        (including ignoring values because no callbacks is available).

        TODO: errors related to the last relevant action only.

    clear_errors()
        Deletes all accumulated errors.

        TODO: Gets obsolete after TODO of errors().

PARAMETER CONFIGURATION
        The -pconfig option of new() and instance(), as well as the argument
        to add_pconfig, is a hashref like follows:

          my @callbacks1=[
               sub {...},
               $registered_callback_name1,
               $callback_obj,
               ...
          ];
          ...

          my $defs={
           _session_id=>{
             -callbacks=>\@callbacks1,
             -persistent=>1, # default false
             -ignore_false=>1, # default false
            },
            name1=>{
              -callbacks=>\@callbacks2,
            },
            qr/a regex/=>{
              -callbacks=>\@callbacks3,
            },
            ...
          };

        Keys of the hashref are names or qr//-precompiled regexes, the
        latter being a "collective key" to all names matchable with the
        regex. If -sid_name is provided to new() or instance(), the hashref
        must contain the definition of the session id parameter.

        @callbacksN above can contain subrefs or names of callbacks
        registered with register_callback().

        The callbacks are executed in the order they are specified. If
        -persistent and -ignore_false are both true, then a false value does
        not update the corresponding session data.

        If no entry has a true -persistent option, session management is
        deactivated, even if a -dbh was provided to new() or instance().

        The callbacks get a reference to a scalar as argument, and should
        return undef if the argument is undef, otherwise the result of the
        callback (boolean). The callback may change the (live) value. For
        details see Apache::Request::Restricted::Callbacks.

        The callback may also return undef if the next callback in the chain
        should be tried (kind of DECLINED in ApacheHandlers).

IMPLEMENTATION NOTES
    There is some caching active:

    Callbacks found via a regex key for a certain request parameter names
    are cached (the param name with it's callback are cached).

    Values once accessed (be it read or write, with or without session
    management) are cached in the object. If session management is on, the
    database is physically updated when the object is destroyed.

SEE ALSO
    Apache::Request(3), Apache::Session(3)

    and

    Apache::Request::Restricted::Callbacks(3) (helper module)
    Apache::Request::Restricted::Session(3) (internal)
    Apache::Request::Restricted::Dispatcher(3) (internal)



nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About