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::Handler

NAME

Dicop::Handler - generic request handler, base class for main server objects

SYNOPSIS

        package Dicop::MyServer;

        use base Dicop::Handler;

        # override methods:
        ...

        package main;

        use Dicop::MyServer;
        $data = Dicop::MyServer->new();

        # further usage as:
        $data->handle_request();

See dicopd and dicopp on how to use this.

REQUIRES

perl5.008, Dicop::Item, Dicop::Request, Dicop::Config, Dicop::Security, Mail::Sendmail, Dicop::Event, Time::HiRes, File::Spec

EXPORTS

Exports nothing.

DESCRIPTION

Dicop::Handler is a base object for server singletons.

Upon creating such an object, the server locks a file and reads its data into memory. Upon destroying the object, the lock is released and possible changes are written back to the disk. From time to time the modified data is written back to the disk, and pending emails are flushed out of the email queue.

For each client-connect an extra file is locked to prevent from multiply client-connects to interfere with each other. This lock is released after the response was sent to the client.

All the data is read immidiately, but only written back if changed or a certain time period has passed.

METHODS

authenticate_user()

        my $rc = $self->authenticate_user($username,$password);

Finds a user by his name, and then check that the hash from the given password matches the stored hash value. Return 0 for okay, -1 for no such user and -2 for wrong pwd.

build(), version()

These methods return the version and build number of the current event handler.

request_auth()

A client (or proxy) connected, so check the authentication request and all the info requests (in case of proxy). This routine also builds an initial response, either saying helo or denying access.

This returns a list, consisting of the client, the response text and a ref to an hash containing as keys the request IDs in case the requests came over a proxy.

        ($client,$res,$req_map) = $self->request_auth($request);

If the returned $client is undefined, than the authentication failed entirely and $res contains the error text. If the returned $client is defined and a proxy (check $client-type()>), $req_map contains a hash ref where the keys are the request IDs, and the values are (currently) refs to a client object or undef. So you can check each single request and whether it authenticated ok, or not.

request_file()

The client requested a file, so send to him where to find that file and what the file hash is.

name_from_type()

        $name = $self->name_from_type('foo');

Given a type as 'proxy', wil return 'proxies'. This is used to turn the type name ('case', 'job' etc) into the field name used to store these objects ('cases', 'jobs' etc).

class_from_type()

        $self->class_from_type('foo');

Return a class name of the form BASE::Foo from the type param from a request. The BASE part is the class of $self, e.g. for a Dicop::Handler object that would be 'Dicop::Handler::Foo', for a Dicop::Data object it would be 'Dicop::Data::Foo' and so on.

cfg_default()

Given a set of keys and their values (a list or hash reference), sets these values as default in the internal cfg object, unless the key is already defined there.

check()

Applies self-check and crumbles if errors in data structure are present.

check_peer()

        $rc = $self->check_peer($peer,$ip,$mask,$client) = @_;

Cchecks the client IP/MASK against the peeraddress. Returns undef for ok, otherwise an error message.

default_request()

Return a request that can be used if the connect does not contain any requests at all. This happens typically if the user accessed the GUI with a browser by typing in just the IP and port number.

parse_requests()

This parses the form parameters as send by the client (via GET/PUT) and breaks them into requests. It then sorts the requests into groups and returns references to these groups (as arrays):

        ($auth,$info,$reports,$requests,$forms) = $self->parse_requests();

other_request()

Returns a class and type for requests with unknown patterns. Used by parse_requests().

handle_requests()

Takes the returned request groups from parse_requests and handles them after some basic checks, like for maximum number of requests, existing authentication etc.

This also prints the result back to the client on STDOUT.

convert_browser_request()

Converts a hash with the submitted fields from a browser to a hash containing (faked normal requests. Removes the unneccessary 'submit' field, and creates an authentication request from the two fields 'auth-user' and 'auth-pass'.

log_msg()

Return a message string by number, along with embedded parameters. Works just like Event::msg, but it also logs the message to a logfile, depending on log_level and the message code.

Typical usage:

        $self->log_msg(430,$type,$id);

_clear_email_queue()

        $self->_clear_email_queue();

Delete everything in the email send queue. Mainly used by the testsuite.

flush_email_queue()

Tries to send all mails in the queue, and return the number of mails successfully sent. This is called outside the code that handles a client request, so that the client does not need to wait until all the emails are sent.

This routine will also put all to-be-sent emails into a logfile.

type()

        $data->type();

Return the type of the server as string, e.g. either 'server' or 'proxy'.

html_header()

Read in the HTML header template and return it.

html_footer()

Read in the HTML footer template and return it.

read_template()

Read a 'normal' template file from the template dir, honouring styles (e.g. the latter override the general templates). Inside the template text, includes file via ##include_filename.inc##.

Returns the 'finished' template, ready to be filled with data as a scalar ref. On errors, returns undef.

_read_template()

Used by read_template() to just read one template file.

read_table_template()

Works just like read_template(), except that it looks for an embedded table template via <!-- start --> and <!-- end --> and generates both the normal template text and a template for one row of the embedded table.

This also honours styles and includes files vi ##include_filename.inc##.

_include_template()

Find ##include_filename.inc## inside a template and include the file there.

find_template()

        my $tpl = $handler->find_template();

Try to find a template file, first looking at the currently set style directory, then in the generic template directory.

email()

Prepare email based on a template and further info, then place it in the send queue.

check_auth_request()

Check the auth or info request a client/proxy sent us for basic validity.

status()

A generic routine to generate as HTML output a table listing certain objects. When no status_xxx() routine is found by handle_requests(), this one is used as a fallback.

status_style()

Create a HTML page with a table of all available styles and layouts.

status_dir()

Creates an HTML table with files and directories, that can be used to traverse directory trees by the user. The directories are selectable by default. See also status_file().

status_file()

Creates an HTML table with files and directories, that can be used to traverse directory trees by the user. The files are selectable. See also status_dir().

status_config()

Create a HTML table containing the current configuration.

get_id_list

        my @list = $data->get_id_list('job');

Return a list of all existing IDs from a given object type.

_gen_table()

An even more generic routine to generate as HTML output a table listing certain objects. Used internally by search() and status().

Examples:

    $self->_gen_table( $self->{tpl}, $self->{tplrow}, $highlight_this_id,
      [ 'cases' ], $self->_status_sort($req));

    $result_ids = { 1; }
    $job_ids = { 2 => $self->{jobs}->{2}, 3 => $self->{jobs}->{3}; }
    $self->_gen_table( $tpl, $tplrow, 0,        # 0 for none 
      [ { ids => $result_ids, type => 'results' }, { ids => $job_ids, type ='jobs') ],
      sub { $Dicop::Handler::b <=> $Dicop::Handler::a } );

get_object()

        $self->get_object($request);

Generalized form to return object from { id => X, type => FOO }. You need to overwrite this routine in your code to actually return the object (depending on how you store them). For instance, this is used in edit/add forms.

_check_templates()

        $self->_check_templates ( 'mail', 'no_warn', qw/new_job failed .../);

Checks that the given list of template files does exist. $type can be 'mail', 'event' etc. If true, the second parameter inhibits warning messages (used by the testsuite).

_construct_file_names

        $self->_construct_file_names( $args, $cfg, @OBJECTS);

Construct $self->{filenames} for flush() from the given object list. Does also set $self->{dir}.

finish_html_request()

        $handler->finish_html_request(\$request);

Called for each request after handling it.

finish_connect()

        $handler->finish_connect();

Hook, called once after each client connect.

pre_connect()

        $handler->pre_connect($peer, $params);

Hook, called once before each client connect is handled.

BUGS

See the BUGS file for details.

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.