| Taxi::Mysql::Server - extendable full-text index using mysql: server daemon |
Taxi::Mysql::Server - extendable full-text index using mysql: server daemon
##======================================================================== ## PRELIMINARIES
use Taxi::Mysql::Server;
##======================================================================== ## Constructors etc.
$srv = $CLASS_OR_OBJ->new(%args);
##======================================================================== ## API: signal handlers
$reaper_sub = $srv->_reaper(); $catcherSub = $srv->_catcher();
##======================================================================== ## API: prepare underlying objects
$undef = $srv->propagateLogger($obj); $srv = $srv->prepare();
##======================================================================== ## API: access control
$csock = $srv->clientSocket($clientRequestOrSocket); $bool = $srv->clientAllowed($clientSock); $undef = $srv->denyClient($clientSock);
##======================================================================== ## API: error handling
$undef = $srv->clientError($clientSock,$statusCode,@message);
##======================================================================== ## API: run server
$rc = $srv->run(); $rc = $srv->runSerial(); $rc = $srv->runForked();
##======================================================================== ## API: client request
($uri,$localPath) = $srv->getURI($uri_string); \%clientRequestParams_or_undef = $srv->parseClientRequest($csock); $rc = $srv->serveClientRequest(\%clientRequestParams_or_undef);
##======================================================================== ## I/O: Hooks
$tmpData = $obj->preSaveHook(); $undef = $obj->postSaveHook($tmpData);
##======================================================================== ## URI configs: general
$uri = $class_or_obj->new(%options); $shortname = $uri->shortname(); $bool = $uri->prepare($server); \%clientRequest = $uri->parseClientRequest($server, $localPath, $clientSocket, $clientHttpRequest); $rc = $uri->processClientRequest($server, \%clientRequest);
##======================================================================== ## URI configs: General
$uri = $class_or_obj->new(%options);
##======================================================================== ## URI configs: static responses
$uri = $class_or_obj->new(%options); $bool = $obj->prepare($srv);
##======================================================================== ## URI configs: static files
$uri = $class_or_obj->new(%options); $bool = $uri->prepare($server); $rc = $uri->processClientRequest($server, $clientRequest);
##======================================================================== ## URI configs: static directories
$uri = $class_or_obj->new(%options); $bool = $uri->prepare($server); \%clientRequest = $uri->parseClientRequest($server, $localPath, $clientSocket, $clientHttpRequest); $rc = $uri->processClientRequest($server, $clientRequest);
##======================================================================== ## URI configs: index queries
$uri = $class_or_obj->new(%options); $bool = $uri->prepare($server); \%clientRequest = $uri->parseClientRequest($server, $localPath, $clientSocket, $clientHttpRequest); $rc = $uri->processClientRequest($server, $clientRequest);
Taxi::Mysql::Server implements a standalone HTTP server for parsing user queries passed in as CGI parameters via HTTP requests, formatting them according to user specifications, and passing the formatted results back to the remote client.
The Taxi::Mysql::Server::URI classes implement processing routines for various kinds of data which may be requested by a client. By far the most interesting (and the most complex) of these is the Taxi::Mysql::Server::URI::query class.
Taxi::Mysql::Server inherits from Taxi::Mysql::Base.
$srv = $CLASS_OR_OBJ->new(%args);
Object structure / known %args:
##-- Basic options #index => $index, ##-- underlying index fmtClass => $class, ##-- query hit formatter class (default: see $ix->newFormat()) fmtArgs => \%fmtArgs, ##-- underlying hit formatter args (default: see $ix->newFormat()) parserClass => $class, ##-- query parser class parserArgs => \%prsrArgs, ##-- underlying query parser args (default: index only)
##-- Daemon options daemonArgs => \%daemonArgs, ##-- args to HTTP::Daemon->new() daemonMode => $daemonMode, ##-- one of 'fork', 'serial' [default='serial'] uris => \%uri2config, ##-- maps local URI paths to configs (see below)
##-- Access control options: ($allowed || !$denied) 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()')
##-- Logging options logger => $logger, ##-- a Taxi::Mysql::Logger object verbose => $verbose, ##-- verbosity level
##-- Low-level data daemon => $http_daemon, ##-- underlying HTTP daemon
URI config values as specified in 'uris' may be specified as:
An object descending from Taxi::Mysql::Server::URI, or
a HASH ref { class=>$uri_subclass, %classNewArgs }
an ARRAY ref [ $uri_subclass, @classNewArgs ]
Common URI subclasses and their arguments:
response (response=>$http_response) : cached static response
file (file=>$path) : static file
dir (dir=>$path) : static directory (recursive)
query (index=>$ix, format=>$fmt) : index query
$reaper_sub = $srv->_reaper();
Zombie killer for forking server.
$catcherSub = $srv->_catcher();
POSIX signal handler. Default implementation shuts down after catching any signal.
undef = $srv->propagateLogger($obj); undef = $srv->propagateLogger($obj, $logClass)
Annoying hack to propagate the server object's logging facility to another object $obj. Called e.g. for $srv->{index}.
This is very ugly and should be replaced with something more sensible.
$srv = $srv->prepare();
Prepares server to run, compiling URI objects as needed from user specifications.
$csock = $srv->clientSocket($clientRequestOrSocket);
Return the actual socket (IO::Socket::INET or subclass) associated with $clientRequestOrSocket, which itself may be either a socket or a client request HASH-ref.
$bool = $srv->clientAllowed($clientSock);
Returns true iff $cli is allowed to access the server.
undef = $srv->denyClient($clientSock); undef = $srv->denyClient($clientSock, $denyMessage)
Kicks $clientSock off the server, with denial message $denyMessage. Shuts down the client socket.
undef = $srv->clientError($clientSock,$statusCode,@message);
Sends an error message to the client and shuts down the client socket. $statusCode is an HTTP status code, e.g. HTTP::Status::RC_FORBIDDEN().
$rc = $srv->run()
Runs the server daemon in the selected operation mode (serial or fork) until a fatal error occurs.
See also: nohup(1), kill(1).
$rc = $srv->runSerial();
Guts for the serial server; called by run() in serial mode.
$rc = $srv->runForked();
Guts for the forking server; called by run() in forking mode.
($uri,$localPath) = $srv->getURI($uri_string);
Gets the URI object associated with the client request $uri_string, or undef if no URI matched.
\%clientRequestParams_or_undef = $srv->parseClientRequest($csock); \%clientRequestParams_or_undef = $srv->parseClientRequest($csock,$httpRequest)
Common code for client request parsing, returns a client request HASH-ref on success, undef if parsing the client request failed. Note that this code always runs in top-level server process (even for the forking mode server), due chiefly to threading problems with Parse::Lex.
$rc = $srv->serveClientRequest(\%clientRequestParams_or_undef);
Service the client request \%clientRequestParams_or_undef via the URI associated with it. This code is run in a separate process for the forking server.
$tmpData = $obj->preSaveHook();
undef = $obj->postSaveHook($tmpData);
$uri = $class_or_obj->new(%options);
New URI.
$shortname = $uri->shortname();
Short URI name, for log messages.
$bool = $uri->prepare($server);
Prepare the URI for running under $server.
\%clientRequest = $uri->parseClientRequest($server, $localPath, $clientSocket, $clientHttpRequest);
Perform any parsing necessary on the client request.
$rc = $uri->processClientRequest($server, $clientRequest);
Process the client request, sending data back to the client as required.
For URIs using static cached HTTP::Response objects.
Inherits from Taxi::Mysql::Server::URI.
$uri = $class_or_obj->new(%options);
%options:
response => $response ##-- HTTP::Response to serve to clients
(undocumented)
URI subclass for serving static files.
Inherits from Taxi::Mysql::Server::URI.
$uri = $class_or_obj->new(%options);
%options:
file => $filename ##-- filename to serve to clients
$bool = $obj->prepare($srv);
URI subclass for serving any file recursively under some directory.
Inherits from Taxi::Mysql::Server::URI.
$uri = $class_or_obj->new(%options);
%options:
dir => $directory ##-- directory to serve (default='.')
$bool = $uri->prepare($server);
$rc = $uri->processClientRequest($server, $clientRequest);
URI subclass for processing client index queries.
Inherits from Taxi::Mysql::Server::URI.
$uri = $class_or_obj->new(%options);
%options:
encoding=>'UTF-8', ##-- default query encoding index=>undef, ##-- underlying index [REQUIRED] format=>undef, ##-- deault hit format [REQUIRED(?)]
$bool = $uri->prepare($server);
\%clientRequest = $uri->parseClientRequest($server, $localPath, $clientSocket, $clientHttpRequest);
$rc = $uri->processClientRequest($server, $clientRequest);
Perl by Larry Wall.
Bryan Jurish <moocow@ling.uni-potsdam.de>
Copyright (C) 2006 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.8.7 or, at your option, any later version of Perl 5 you may have available.
perl(1), taxi-query.perl(1), taxi-server.perl(1), Taxi::Mysql(3perl), Taxi::Mysql::Query::Parser(3perl), Taxi::Mysql::Query::Format(3perl).
| Taxi::Mysql::Server - extendable full-text index using mysql: server daemon |