The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
DTA-CAB-1.115
River stage zero No dependents
/ DTA::CAB::Server::HTTP

NAME

DTA::CAB::Server::HTTP - DTA::CAB standalone HTTP server using HTTP::Daemon

SYNOPSIS

##========================================================================
## PRELIMINARIES

use DTA::CAB::Server::HTTP;

##========================================================================
## Constructors etc.

$obj = CLASS_OR_OBJ->new(%args);

##========================================================================
## Methods: subclass API (abstractions for HTTP::UNIX)

$str = $srv->socketLabel();
$str = $srv->daemonLabel();
$bool = $srv->canBindSocket();
$class = $srv->daemonClass();
$class_or_undef = $srv->clientClass();

##========================================================================
## Methods: Generic Server API

$rc = $srv->prepareLocal();
$rc = $srv->run();

##========================================================================
## Methods: Local: Path Handlers

$handler = $srv->registerPathHandler($pathStr, \%handlerSpec);
($handler,$localPath) = $srv->getPathHandler($hreq_uri);

##========================================================================
## Methods: Local: Access Control

$bool = $srv->clientAllowed($clientSock);
undef = $srv->denyClient($clientSock);

##========================================================================
## Methods: Local: error handling

undef = $srv->clientError($clientSock,$status,@message);

DESCRIPTION

Globals

Variable: @ISA

DTA::CAB::Server::HTTP inherits from DTA::CAB::Server, and supports the DTA::CAB::Server API.

Constructors etc.

new
$srv = CLASS_OR_OBJ->new(%args);
Arguments and Object Structure:
(
 ##-- Underlying HTTP::Daemon server
 daemonMode => $daemonMode,    ##-- one of 'serial', or 'fork' [default='serial']
 daemonArgs => \%daemonArgs,   ##-- args to HTTP::Daemon->new()
 paths      => \%path2handler, ##-- maps local URL paths to handlers
 daemon     => $daemon,        ##-- underlying HTTP::Daemon object
 cxsrv      => $cxsrv,         ##-- associated DTA::CAB::Server::XmlRpc object (for XML-RPC handlers)
 xopt       => \%xmlRpcOpts,   ##-- options for RPC::XML::Server sub-object (for XML-RPC handlers; default: {no_http=>1,logRegisterProc=>'off'})
 ##
 ##-- caching
 cacheSize  => $nelts,         ##-- maximum number of responses to cache (default=1024; undef for no cache)
 cacheLimit => $nbytes,        ##-- max number of content bytes for cached responses (default=undef: no limit)
 cache      => $lruCache,      ##-- response cache: (key = $url, value = $response), a DTA::CAB::Cache::LRU object
 ##
 ##-- security
 allowUserOptions => $bool,   ##-- allow client-specified analysis options? (default: true)
 allow => \@allow_ip_regexes, ##-- allow queries from these clients (default=none)
 deny  => \@deny_ip_regexes,  ##-- deny queries from these clients (default=none)
 _allow => $allow_ip_regex,   ##-- single allow regex (compiled by 'prepare()')
 _deny  => $deny_ip_regex,    ##-- single deny regex (compiled by 'prepare()')
 maxRequestSize => $bytes,    ##-- maximum request content-length in bytes (default: undef//-1: no max)
 ##
 ##-- forking
 forkOnGet => $bool,	    ##-- fork() handler for HTTP GET requests? (default=0)
 forkOnPost => $bool,	    ##-- fork() handler for HTTP POST requests? (default=1)
 forkMax => $n,	    ##-- maximum number of subprocess to spwan (default=4; 0~no limit)
 children => \%pids,	    ##-- child PIDs
 pid => $pid,		    ##-- PID of parent server process
 ##
 ##-- logging
 logRegisterPath => $level,   ##-- log registration of path handlers at $level (default='info')
 logAttempt => $level,        ##-- log connection attempts at $level (default=undef: none)
 logConnect => $level,        ##-- log successful connections (client IP and requested path) at $level (default='debug')
 logRquestData => $level,     ##-- log full client request data at $level (default=undef: none)
 logResponse => $level,       ##-- log full client response at $level (default=undef: none)
 logCache => $level,          ##-- log cache hit data at $level (default=undef: none)
 logClientError => $level,    ##-- log errors to client at $level (default='debug')
 logClose => $level,          ##-- log close client connections (default=undef: none)
 logReap => $level,           ##-- log harvesting of child pids (default=undef: none)
 logSpawn => $level,          ##-- log spawning of child pids (default=undef: none)
 ##
 ##-- (inherited from DTA::CAB::Server)
 as  => \%analyzers,    ##-- ($name=>$cab_analyzer_obj, ...)
 aos => \%anlOptions,   ##-- ($name=>\%analyzeOptions, ...) : %opts passed to $anl->analyzeXYZ($xyz,%opts)
)
path handlers:

Each path handler specified in $opts{paths} should be one of the following:

  • An object descended from DTA::CAB::Server::HTTP::Handler.

  • A HASH ref of the form

    { class=>$subclass, %newArgs }

    The handler will be instantiated by $subclass->new(%newArgs). $subclass may be specified as a suffix of DTA::CAB::Server::HTTP::Handler, e.g. $subclass="Query" will instantiate a handler of class DTA::CAB::Server::HTTP::Handler::Query.

  • An ARRAY ref of the form

    [$subclass, @newArgs ]

    The handler will be instantiated by $subclass->new(@newArgs). $subclass may be specified as a suffix of DTA::CAB::Server::HTTP::Handler, e.g. $subclass="Query" will instantiate a handler of class DTA::CAB::Server::HTTP::Handler::Query.

Methods: subclass API

socketLabel
$str = $srv->socketLabel();

returns symbolic label for bound socket address; default returns string of the form "ADDR:PORT" using $srv->{daemonArgs}.

daemonLabel
$str = $srv->daemonLabel();

returns symbolic label for running daemon; default returns string of the form "ADDR:PORT" using $srv->{daemon}.

canBindSocket
$bool = $srv->canBindSocket();

returns true iff socket can be bound; should set $! on error; default tries to bind INET socket as specified in $srv->{daemonArgs}.

daemonClass
$class = $srv->daemonClass();

get underlying HTTP::Daemon class, default returns 'HTTP::Daemon'.

clientClass
$class_or_undef = $srv->clientClass();

get class for client connections, or undef (default) if client sockets are not to be re-blessed into a different class.

Methods: Generic Server API

prepareLocal
$rc = $srv->prepareLocal();

Subclass-local initialization. This override initializes the underlying HTTP::Daemon object, sets up the path handlers, and compiles the server's _allow and _deny regexes.

run
$rc = $srv->run();

Run the server on the specified port until further notice.

Methods: Local: Path Handlers

registerPathHandler
$handler = $srv->registerPathHandler($pathStr, \%handlerSpec);
$handler = $srv->registerPathHandler($pathStr, \@handlerSpec)
$handler = $srv->registerPathHandler($pathStr, $handlerObject)

Registers a path handler for path $pathStr (and all sub-paths). See "new"() for a description of the allowed forms for handler specifications.

Sets $srv->{paths}{$pathStr} = $handler

getPathHandler
($handler,$localPath) = $srv->getPathHandler($hreq_uri);

Gets the most specific path handler (and its local path) for the URI object $hreq_uri.

Methods: Local: Access Control

clientAllowed
$bool = $srv->clientAllowed($clientSock);

Returns true iff $clientSock may access the server.

denyClient
undef = $srv->denyClient($clientSock);
undef = $srv->denyClient($clientSock, $denyMessage)

Denies access to $clientSock and shuts down client socket.

Methods: Local: error handling

clientError
undef = $srv->clientError($clientSock,$status,@message);

Sends an error message to the client and shuts down the client socket. $status defaults to RC_INTERNAL_SERVER_ERROR (see HTTP::Status).

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2010-2019 by Bryan Jurish

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.24.1 or, at your option, any later version of Perl 5 you may have available.

SEE ALSO

DTA::CAB::Server(3pm), DTA::CAB::Server::HTTP::Handler(3pm), DTA::CAB::Server::HTTP::UNIX(3pm), DTA::CAB::Client::HTTP(3pm), DTA::CAB(3pm), perl(1), ...