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

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.