The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Dicop-Base-3.03
++
/ Dicop::Request::Pattern

NAME

Dicop::Request::Pattern -- an object containing one request pattern

SYNOPSIS

        use Dicop::Request::Pattern

        push @patterns, Dicop::Request::Pattern->new (
                match => 'cmd_status;type_main',
                req => 'id',
                opt => 'style',
                output => 'html',
                type => 'status',
                tpl => 'main.txt',
                auth => 0,
                class => 'admin',
                throw => 'error message',
        );

        # automatically checks the new Request against all the patterns
        # and selects the one fitting it (or generates an error in the
        # Request)
        $request = new Dicop::Request (
          id => 'req0001',
          data => 'req_0000=cmd_status;type_main',
          patterns => \@patterns,
          );

        if ($request->error() ne '')
          {
          # error, no pattern matched
          die ($request->error());
          }

          print "The request '", $request->as_request_string(), "' is valid.\n";
          print "We should output ", $match->output($request), " with the title '",
                $match->title($request),"'\n";
          print "We should read the template ", $match->template($request), "\n";
          }

REQUIRES

perl5.8, Dicop::Base, Dicop::Item, Dicop::Event

EXPORTS

Exports nothing.

DESCRIPTION

Class to represent a pattern that represents a valid request. All requests can be checked against this pattern to determine whether they are valid or not. In praxis a list of all valid pattersn would be maintained and each request checked against each pattern.

A request in Dicop is simple a message passed between machines like the server, clients or a proxy.

Storage

Pattern descriptions are stored in a flat file in text format and are read by the code at startup.

Sample entry

        {
        match = "cmd_status;type_test"
        nonempty = "start end description jobtype charset"
        req = "id"
        opt = "style"
        output = "html"
        tpl = "test.txt"
        title = "Test Status Page"
        type = "status"
        class = "status"
        auth = 1
        }

Pattern properties

Below follows a detailed description on the possible pattern properties and their meaning:

Sample entry

match
        match = "cmd_status;type_test"

The patterns is valid for all requests that match this pattern. The order is not important, so type_test;cmd_status would work as well. All params must match exactly - otherwise the request pattern doesn't match this request. It is possible to enter regular expressions for the values, e.g.

        match = "cmd_status;type_/^(test|work)$"

Note the closing "/" is missing and the regexp must come last.

nonempty
        nonempty = "start end description jobtype charset"

These params must be non-empty (and also present). Default is "".

req
        req = "id"

These params must be present, but can be empty unless they are listed in nonempty. Default is "". Any params in 'match' and "nonempty" are automatically added to 'required' so you don't need to list them twice.

opt
        opt = "style"

These params are optional (and can be empty if they are not listed in nonempty). Default is "style". If you don't want "style" to be optional, set opt = "".

output
        output = "html-table"

The type of output sent when this pattern matches. Valid are "html", "html-table" or "text". Default is "html".

tpl
        tpl = "test.txt"

Name of the template file to reply if this pattern matches. Optional and only neccessary if type = "html" or "html-table". If left empty, and type is "html", the vaue will be "TYPE.tpl" where TYPE is the value of the type-param of the request, e.g. for cmd_status;type_test it would be "test". This if course works only if "type" is an allowed, nonempty param.

title
        title = "Test Status Page"

The title string, only necc. if output is "html" or "html-table".

type
        type = "status"

The type of the request. Types: "status", "info", "auth", "request", "other". Default is "status". This is used to keep statistics about request types.

class
        class = "status"

The class of the request. This is used to deny/allow requests based on IPs and nets. Other then that, the class is not used. Possible are "admin", "stats", "status" and "work". Default is "admin".

auth
        auth = 1

Set this to 1 to require user authentication (e.g. password and username) for this request.

sort
        sort = "down"

The sort oder for output "html-table". Possible are "up", "upstr", "down" and "downstr". The default is "up". The variants "upstr" and "downstr" sort strings, while "up" and "down" are for numerical fields.

See also sort_by.

sort_by
        sort_by = "id"

Which field to sort the output by. Default is "id", and can be any field of the objects to list. Only works for output of "html-table" or if the output contains a list of objects. See also sort.

carry
        carry = "job_id"

List of fields that need to be carried over for forms. These will be added as hidden params to the form.

throw
        throw = "some error message"

If this request matched without an error, throw this error message and bail out. Used to catch specific forbidden requests.

METHODS

error

Get/set error message. Returns empty string in case of no error.

check

        ($match, $error) = $pattern->check ( $request );

Check the given request of whether it matches this pattern (with or without error) or not. Will return $match = undef for no match, and $match = $pattern for a match. Upon $match beeing equal to $pattern, $error will indicate whether there was an error or not.

output

        $output_type = $pattern->output($request);

Returns the defined output for the request matching this pattern, or the empty string for none.

template_name

        $tpl = $pattern->template_name();

Returns the defined name of the template for this pattern, or the empty string for none. This will only be set if output_type() equals 'html'.

type

        $type = $pattern->type($request);

Returns the type of the request matching this pattern.

title

        $title = $pattern->title($request);

Returns the title of the request matching this pattern.

sort_order

        ($sort_order, $sort_by) = $pattern->sort_order();

Return the sort order ('up', or 'down') and the name of the field to sort on. The default is ('up', 'id').

auth

        $auth = $pattern->auth();

Returns a flag indicating whether we need user authentication (e.g. pwd and username) for matching requests or not.

class

        $class = $pattern->class();

Returns the class of the request matching this pattern.

carry

        my $carry = $pattern->carry();

Return a list of fields that the form must include to carry over.

BUGS

None known yet.

AUTHOR

(c) Bundesamt fuer Sicherheit in der Informationstechnik 1998-2006

DiCoP is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

See http://www.bsi.de/ for more information.