###############################################################################
#
# This file copyright (c) 2001-2011 Randy J. Ray, all rights reserved
#
# Copying and distribution are permitted under the terms of the Artistic
# License 2.0 (http://www.opensource.org/licenses/artistic-license-2.0.php) or
# the GNU LGPL (http://www.opensource.org/licenses/lgpl-2.1.php).
#
###############################################################################
#
# Description: This class implements an RPC::XML server, using the core
# XML::RPC transaction code. The server may be created with
# or without an HTTP::Daemon object instance to answer the
# requests.
#
# Functions: new
# version
# url
# product_tokens
# started
# path
# host
# port
# requests
# response
# compress
# compress_thresh
# compress_re
# message_file_thresh
# message_temp_dir
# xpl_path
# add_method
# method_from_file
# get_method
# server_loop
# post_configure_hook
# pre_loop_hook
# process_request
# dispatch
# call
# add_default_methods
# add_methods_in_dir
# delete_method
# list_methods
# share_methods
# copy_methods
# timeout
# server_fault
#
# Libraries: HTTP::Daemon (conditionally)
# HTTP::Response
# HTTP::Status
# URI
# Scalar::Util
# RPC::XML
# RPC::XML::ParserFactory
# RPC::XML::Procedure
#
# Global Consts: $VERSION
# $INSTALL_DIR
# %FAULT_TABLE
#
###############################################################################
package RPC::XML::Server;
use 5.008008;
use strict;
use warnings;
use vars qw($VERSION $INSTALL_DIR %FAULT_TABLE @XPL_PATH %CLASS_MAP
$IO_SOCKET_SSL_HACK_NEEDED $COMPRESSION_AVAILABLE);
use Carp qw(carp croak);
use File::Spec;
use File::Temp;
use IO::Handle;
use HTTP::Status;
use HTTP::Response;
use URI;
use Scalar::Util 'blessed';
use RPC::XML;
use RPC::XML::ParserFactory;
use RPC::XML::Procedure;
BEGIN
{
$INSTALL_DIR =
File::Spec->catpath((File::Spec->splitpath(__FILE__))[0, 1], q{});
@XPL_PATH = ($INSTALL_DIR, File::Spec->curdir);
# For now, I have an ugly hack in place to make the functionality that
# runs under HTTP::Daemon/Net::Server work better with SSL. This flag
# starts out true, then gets set to false the first time the hack is
# applied, so that it doesn't get repeated over and over...
$IO_SOCKET_SSL_HACK_NEEDED = 1;
# Check for compression support
if (! eval { require Compress::Zlib; $COMPRESSION_AVAILABLE = 'deflate'; })
{
$COMPRESSION_AVAILABLE = q{};
}
# Set up the initial table of fault-types and their codes/messages
%FAULT_TABLE = (
badxml => [ 100 => 'XML parse error: %s' ],
badmethod => [ 200 => 'Method lookup error: %s' ],
badsignature => [ 201 => 'Method signature error: %s' ],
execerror => [ 300 => 'Code execution error: %s' ],
);
# This is used by add_method to map "types" to instantiation classes
%CLASS_MAP = (
method => 'RPC::XML::Method',
procedure => 'RPC::XML::Procedure',
function => 'RPC::XML::Function',
);
}
$VERSION = '1.70';
$VERSION = eval $VERSION; ## no critic (ProhibitStringyEval)
###############################################################################
#
# Sub Name: new
#
# Description: Create a new RPC::XML::Server object. This entails getting
# a HTTP::Daemon object, saving several internal values, and
# other operations.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $class in scalar Ref or string for the class
# %args in hash Additional arguments
#
# Returns: Success: object reference
# Failure: error string
#
###############################################################################
sub new ## no critic (ProhibitExcessComplexity)
{
my ($class, %args) = @_;
my (
$self, $http, $resp, $host, $port, $queue, $URI, $srv_version,
$srv_name
);
# Don't accept a blessed value for $class
if (ref $class)
{
return __PACKAGE__ . '::new: Must be called as a static method';
}
$self = bless {}, $class;
$srv_version = delete $args{server_version} || $self->version;
$srv_name = delete $args{server_name} || $class;
$self->{__server_token} = "$srv_name/$srv_version";
if (delete $args{no_http})
{
$self->{__host} = delete $args{host} || q{};
$self->{__port} = delete $args{port} || q{};
}
else
{
require HTTP::Daemon;
$host = delete $args{host} || q{};
$port = delete $args{port} || q{};
$queue = delete $args{queue} || 5;
$http = HTTP::Daemon->new(
Reuse => 1,
($host ? (LocalHost => $host) : ()),
($port ? (LocalPort => $port) : ()),
($queue ? (Listen => $queue) : ())
);
if (! $http)
{
return "${class}::new: Unable to create HTTP::Daemon object: $@";
}
$URI = URI->new($http->url);
$self->{__host} = $URI->host;
$self->{__port} = $URI->port;
$self->{__daemon} = $http;
}
# Create and store the cached response object for later cloning and use
$resp = HTTP::Response->new();
$resp->header(
# This is essentially the same string returned by the
# default "identity" method that may be loaded from a
# XPL file. But it hasn't been loaded yet, and may not
# be, hence we set it here (possibly from option values)
RPC_Server => $self->{__server_token},
RPC_Encoding => 'XML-RPC',
# Set any other headers as well
Accept => 'text/xml'
);
$resp->content_type('text/xml');
$resp->code(RC_OK);
$resp->message('OK');
$self->{__response} = $resp;
# Basic (scalar) properties
$self->{__path} = delete $args{path} || q{};
$self->{__started} = 0;
$self->{__method_table} = {};
$self->{__requests} = 0;
$self->{__auto_methods} = delete $args{auto_methods} || 0;
$self->{__auto_updates} = delete $args{auto_updates} || 0;
$self->{__debug} = delete $args{debug} || 0;
$self->{__xpl_path} = delete $args{xpl_path} || [];
$self->{__timeout} = delete $args{timeout} || 10;
$self->{__parser} = RPC::XML::ParserFactory->new(
$args{parser} ? @{delete $args{parser}} : ()
);
# Add the basic paths (content of @XPL_PATH) to our local XPL path
push @{$self->{__xpl_path}}, @XPL_PATH;
# Set up the default methods unless requested not to
if (! delete $args{no_default})
{
$self->add_default_methods;
}
# Compression support
if (delete $args{no_compress})
{
$self->{__compress} = q{};
}
else
{
$self->{__compress} = $COMPRESSION_AVAILABLE;
# Add some more headers to the default response object for compression.
# It looks wasteful to keep using the hash key, but it makes it easier
# to change the string in just one place (above) if I have to.
if ($self->{__compress})
{
$resp->header(Accept_Encoding => $self->{__compress});
}
$self->{__compress_thresh} = delete $args{compress_thresh} || 4096;
# Yes, I know this is redundant. It's for future expansion/flexibility.
$self->{__compress_re} =
$self->{__compress} ? qr/$self->{__compress}/ : qr/deflate/;
}
# Parameters to control the point at which messages are shunted to temp
# files due to size, and where to home the temp files. Start with a size
# threshhold of 1Meg and no specific dir (which will fall-through to the
# tmpdir() method of File::Spec).
$self->{__message_file_thresh} = delete $args{message_file_thresh} ||
1_048_576;
$self->{__message_temp_dir} = delete $args{message_temp_dir} || q{};
# Set up the table of response codes/messages that will be used when the
# server is sending a controlled error message to a client (as opposed to
# something HTTP-level that is less within our control).
$self->{__fault_table} = {};
for my $fault (keys %FAULT_TABLE)
{
$self->{__fault_table}->{$fault} = [ @{$FAULT_TABLE{$fault}} ];
}
if ($args{fault_code_base})
{
my $base = delete $args{fault_code_base};
# Apply the numerical offset to all (current) error codes
for my $key (keys %{$self->{__fault_table}})
{
$self->{__fault_table}->{$key}->[0] += $base;
}
}
if ($args{fault_table})
{
my $local_table = delete $args{fault_table};
# Merge any data from this table into the object's fault-table
for my $key (keys %{$local_table})
{
$self->{__fault_table}->{$key} = (ref $local_table->{$key}) ?
[ @{$local_table->{$key}} ] : $local_table->{$key};
}
}
# Copy the remaining args over untouched
for (keys %args)
{
$self->{$_} = $args{$_};
}
return $self;
}
# Most of these tiny subs are accessors to the internal hash keys. They not
# only control access to the internals, they ease sub-classing.
sub version { return $VERSION }
sub INSTALL_DIR { return $INSTALL_DIR }
sub url
{
my $self = shift;
my $host;
if ($self->{__daemon})
{
return $self->{__daemon}->url;
}
if (! ($host = $self->host))
{
return;
}
my $path = $self->path;
my $port = $self->port;
if ($port == 443)
{
return "https://$host$path";
}
elsif ($port == 80)
{
return "http://$host$path";
}
else
{
return "http://$host:$port$path";
}
}
sub product_tokens
{
my $self = shift;
my $class = ref $self;
$class ||= $self;
return sprintf '%s/%s', $class, $self->version;
}
# This fetches/sets the internal "started" timestamp. Unlike the other
# plain-but-mutable attributes, this isn't set to the passed-value but
# rather a non-null argument sets it from the current time.
sub started
{
my ($self, $set_started) = @_;
my $old = $self->{__started} || 0;
if ($set_started)
{
$self->{__started} = time;
}
return $old;
}
BEGIN
{
no strict 'refs'; ## no critic (ProhibitNoStrict)
# These are mutable member values for which the logic only differs in
# the name of the field to modify:
for my $method (qw(compress_thresh message_file_thresh message_temp_dir))
{
*{$method} = sub {
my ($self, $value) = @_;
my $old = $self->{"__$method"};
if (defined $value)
{
$self->{"__$method"} = $value;
}
$old;
}
}
# These are immutable member values, so this simple block applies to all
for my $method (qw(path host port requests response compress compress_re
parser))
{
*{$method} = sub { shift->{"__$method"} }
}
}
# Get/set the search path for XPL files
sub xpl_path
{
my ($self, $path) = @_;
my $ret = $self->{__xpl_path};
if ($path && ref $path eq 'ARRAY')
{
$self->{__xpl_path} = $path;
}
return $ret;
}
###############################################################################
#
# Sub Name: add_method
#
# Description: Add a funtion-to-method mapping to the server object.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Object to add to
# $meth in scalar Hash ref of data or file name
#
# Globals: %CLASS_MAP
#
# Returns: Success: $self
# Failure: error string
#
###############################################################################
sub add_method
{
my ($self, $meth) = @_;
my $me = ref($self) . '::add_method';
if (! ref $meth)
{
my $val = $self->method_from_file($meth);
if (! ref $val)
{
return "$me: Error loading from file $meth: $val";
}
else
{
$meth = $val;
}
}
elsif (ref $meth eq 'HASH')
{
# Make a copy of the contents of $meth, so we don't make permanent
# changes:
my %meth_copy = map { $_ => $meth->{$_} } (keys %{$meth});
# If the type of this method is not set, default to "method". The
# add_procedure and add_function calls should set this as needed.
my $type = delete $meth_copy{type} || 'method';
if (! (my $class = $CLASS_MAP{lc $type}))
{
return "$me: Unknown type: $type";
}
else
{
$meth = $class->new(\%meth_copy);
}
}
elsif (! (blessed $meth and $meth->isa('RPC::XML::Procedure')))
{
return "$me: Method argument must be a file name, a hash " .
'reference or an object derived from RPC::XML::Procedure';
}
$self->{__method_table}->{$meth->name} = $meth;
return $self;
}
###############################################################################
#
# Sub Name: add_procedure
#
# Description: This filters through to add_method, but if the passed-in
# value is a hash reference forces the "type" to be
# "procedure".
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Object reference
# $meth in scalar Procedure to add
#
# Returns: threads through to add_method
#
###############################################################################
sub add_procedure
{
my ($self, $meth) = @_;
# Anything else but a hash-reference goes through unaltered
if (ref($meth) eq 'HASH')
{
$meth->{type} = 'procedure';
}
return $self->add_method($meth);
}
###############################################################################
#
# Sub Name: add_function
#
# Description: This filters through to add_method, but if the passed-in
# value is a hash reference forces the "type" to be
# "function".
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Object reference
# $meth in scalar Procedure to add
#
# Returns: threads through to add_method
#
###############################################################################
sub add_function
{
my ($self, $meth) = @_;
# Anything else but a hash-reference goes through unaltered
if (ref($meth) eq 'HASH')
{
$meth->{type} = 'function';
}
return $self->add_method($meth);
}
###############################################################################
#
# Sub Name: method_from_file
#
# Description: Create a RPC::XML::Procedure (or ::Method) object from the
# passed-in file name, using the object's search path if the
# name is not already absolute.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Object of this class
# $file in scalar Name of file to load
#
# Returns: Success: Method-object reference
# Failure: error message
#
###############################################################################
sub method_from_file
{
my ($self, $file) = @_;
if (! File::Spec->file_name_is_absolute($file))
{
my $path;
for my $dir (@{$self->xpl_path})
{
$path = File::Spec->catfile($dir, $file);
if (-f $path)
{
$file = File::Spec->canonpath($path);
last;
}
}
}
# Just in case it still didn't appear in the path, we really want an
# absolute path:
if (! File::Spec->file_name_is_absolute($file))
{
$file = File::Spec->rel2abs($file);
}
# When reading a XPL file, RPC::XML::Procedure->new() acts sort of like a
# factory constructor, returning the type of object the XPL file specifies
# even when that isn't RPC::XML::Procedure.
return RPC::XML::Procedure->new($file);
}
###############################################################################
#
# Sub Name: get_method
#
# Description: Get the current binding for the remote-side method $name.
# Returns undef if the method is not defined for the server
# instance.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Class instance
# $name in scalar Name of the method being looked
# up
#
# Returns: Success: Method-class reference
# Failure: error string
#
###############################################################################
sub get_method
{
my ($self, $name) = @_;
my $meth = $self->{__method_table}->{$name};
if (! defined $meth)
{
if ($self->{__auto_methods})
{
# Try to load this dynamically on the fly, from any of the dirs
# that are in this object's @xpl_path
(my $loadname = $name) =~ s/^system[.]//;
$self->add_method("$loadname.xpl");
}
# If method is still not in the table, we were unable to load it
if (! ($meth = $self->{__method_table}->{$name}))
{
return "Unknown method: $name";
}
}
# Check the mod-time of the file the method came from, if the test is on
if ($self->{__auto_updates} &&
$meth->{file} &&
($meth->{mtime} < (stat $meth->{file})[9]))
{
my $ret = $meth->reload;
if (! ref $ret)
{
return "Reload of method $name failed: $ret";
}
}
return $meth;
}
# For name-symmetry:
*get_procedure = *get_function = \&get_method;
###############################################################################
#
# Sub Name: server_loop
#
# Description: Enter a server-loop situation, using the accept() loop of
# HTTP::Daemon if $self has such an object, or falling back
# Net::Server otherwise.
#
# The critic disabling is because we may manipulate @_
# when using Net::Server.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Object of this class
# %args in hash Additional parameters to set up
# before calling the superclass
# Run method
#
# Returns: string if error, otherwise void
#
###############################################################################
sub server_loop ## no critic (RequireArgUnpacking,ProhibitExcessComplexity)
{
my $self = shift;
if ($self->{__daemon})
{
my ($conn, $req, $resp, $reqxml, $respxml, $exit_now, $timeout,
$eval_return);
my %args = @_;
# Localize and set the signal handler as an exit route
my @exit_signals;
if (exists $args{signal} and $args{signal} ne 'NONE')
{
@exit_signals =
(ref $args{signal}) ? @{$args{signal}} : $args{signal};
}
else
{
push @exit_signals, 'INT';
}
local @SIG{@exit_signals} = (sub { $exit_now++ }) x @exit_signals;
$self->started('set');
$exit_now = 0;
$timeout = $self->{__daemon}->timeout(1);
while (! $exit_now)
{
$conn = $self->{__daemon}->accept;
if ($exit_now)
{
last;
}
if (! $conn)
{
next;
}
$conn->timeout($self->timeout);
$self->process_request($conn);
$eval_return = eval {
local $SIG{PIPE} = sub { die "server_loop: Caught SIGPIPE\n"; };
$conn->close;
1;
};
if ((! $eval_return) && $@)
{
warn "Cannot close conection: $@\n";
}
undef $conn; # Free up any lingering resources
}
if (defined $timeout)
{
$self->{__daemon}->timeout($timeout);
}
}
else
{
# This is the Net::Server block, but for now HTTP::Daemon is needed
# for the code that converts socket data to a HTTP::Request object
require HTTP::Daemon;
my $conf_file_flag = 0;
my $port_flag = 0;
my $host_flag = 0;
# Disable critic on the C-style for-loop because we need to step by
# 2 as we check for Net::Server arguments...
for (my $i = 0; $i < @_; $i += 2) ## no critic (ProhibitCStyleForLoops)
{
if ($_[$i] eq 'conf_file') { $conf_file_flag = 1; }
if ($_[$i] eq 'port') { $port_flag = 1; }
if ($_[$i] eq 'host') { $host_flag = 1; }
}
# An explicitly-given conf-file trumps any specified at creation
if (exists($self->{conf_file}) and (!$conf_file_flag))
{
push @_, 'conf_file', $self->{conf_file};
$conf_file_flag = 1;
}
# Don't do this next part if they've already given a port, or are
# pointing to a config file:
if (! ($conf_file_flag || $port_flag))
{
push @_, 'port', $self->{port} || $self->port || 9000;
push @_, 'host', $self->{host} || $self->host || q{*};
}
# Try to load the Net::Server::MultiType module
if (! eval { require Net::Server::MultiType; 1; })
{
if ($@)
{
return ref($self) .
"::server_loop: Error loading Net::Server::MultiType: $@";
}
}
unshift @RPC::XML::Server::ISA, 'Net::Server::MultiType';
$self->started('set');
# ...and we're off!
$self->run(@_);
}
return;
}
###############################################################################
#
# Sub Name: post_configure_loop
#
# Description: Called by the Net::Server classes after all the config
# steps have been done and merged.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Class object
#
# Returns: $self
#
###############################################################################
sub post_configure_hook
{
my $self = shift;
$self->{__host} = $self->{server}->{host};
$self->{__port} = $self->{server}->{port};
return $self;
}
###############################################################################
#
# Sub Name: pre_loop_hook
#
# Description: Called by Net::Server classes after the post_bind method,
# but before the socket-accept loop starts.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Object instance
#
# Returns: $self
#
###############################################################################
sub pre_loop_hook
{
my $self = shift;
# We have to disable the __DIE__ handler for the sake of XML::Parser::Expat
$SIG{__DIE__} = q{}; ## no critic (RequireLocalizedPunctuationVars)
return $self;
}
###############################################################################
#
# Sub Name: process_request
#
# Description: This is provided for the case when we run as a subclass
# of Net::Server.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref This class object
# $conn in ref If present, it's a connection
# object from HTTP::Daemon
#
# Returns: void
#
###############################################################################
sub process_request ## no critic (ProhibitExcessComplexity)
{
my $self = shift;
my $conn = shift;
my (
$req, $reqxml, $resp, $respxml, $do_compress,
$parser, $com_engine, $length, $read, $buf,
$resp_fh, $tmpdir, $peeraddr, $peerhost, $peerport
);
my $me = ref($self) . '::process_request';
if (! $conn)
{
# Maintain compatibility with Net::Server 0.99, which does not pass
# the connection object at all:
$conn = $self->{server}->{client};
}
if (ref($conn) =~ /^Net::Server::Proto/)
{
bless $conn, 'HTTP::Daemon::ClientConn';
${*{$conn}}{'httpd_daemon'} = $self;
if ($IO::Socket::SSL::VERSION &&
$RPC::XML::Server::IO_SOCKET_SSL_HACK_NEEDED)
{
no strict 'vars'; ## no critic (ProhibitNoStrict)
# RT 43019: Don't do this if Socket6/IO::Socket::INET6 is in
# effect, as it causes calls to unpack_sockaddr_in6 to break.
if (! (defined $Socket6::VERSION ||
defined $IO::Socket::INET6::VERSION))
{
unshift @HTTP::Daemon::ClientConn::ISA, 'IO::Socket::SSL';
}
$RPC::XML::Server::IO_SOCKET_SSL_HACK_NEEDED = 0;
}
}
# These will be attached to any and all request objects that are
# (successfully) read from $conn.
$peeraddr = $conn->peeraddr;
$peerport = $conn->peerport;
$peerhost = $conn->peerhost;
while ($conn and $req = $conn->get_request('headers only'))
{
if ($req->method eq 'HEAD')
{
# The HEAD method will be answered with our return headers,
# both as a means of self-identification and a verification
# of live-status. All the headers were pre-set in the cached
# HTTP::Response object. Also, we don't count this for stats.
$conn->send_response($self->response);
}
elsif ($req->method eq 'POST')
{
# Get a XML::Parser::ExpatNB object
$parser = $self->parser->parse();
if (($req->content_encoding || q{}) =~ $self->compress_re)
{
if (! $self->compress)
{
$conn->send_error(RC_BAD_REQUEST,
"$me: Compression not permitted in " . 'requests');
next;
}
$do_compress = 1;
}
if (($req->content_encoding || q{}) =~ /chunked/i)
{
# Technically speaking, we're not supposed to honor chunked
# transfer-encoding...
croak "$me: 'chunked' content-encoding not (yet) supported";
}
else
{
$length = $req->content_length;
if ($do_compress)
{
# Spin up the compression engine
if (! ($com_engine = Compress::Zlib::inflateInit()))
{
$conn->send_error(RC_INTERNAL_SERVER_ERROR,
"$me: Unable to initialize the " .
'Compress::Zlib engine');
next;
}
}
$buf = q{};
while ($length > 0)
{
if ($buf = $conn->read_buffer)
{
# Anything that get_request read, but didn't use, was
# left in the read buffer. The call to sysread() should
# NOT be made until we've emptied this source, first.
$read = length $buf;
$conn->read_buffer(q{}); # Clear it, now that it's read
}
else
{
$read = sysread $conn, $buf,
($length < 2048) ? $length : 2048;
if (! $read)
{
# Convert this print to a logging-hook call.
# Umm, when I have real logging hooks, I mean.
# The point is, odds are very good that $conn is
# dead to us now, and I don't want this package
# taking over SIGPIPE as well as the ones it
# already monopolizes.
#print STDERR "Error: Connection Dropped\n";
return;
}
}
$length -= $read;
if ($do_compress)
{
if (! ($buf = $com_engine->inflate($buf)))
{
$conn->send_error(RC_INTERNAL_SERVER_ERROR,
"$me: Error inflating " . 'compressed data');
# This error also means that even if Keep-Alive
# is set, we don't know how much of the stream
# is corrupted.
$conn->force_last_request;
next;
}
}
if (! eval { $parser->parse_more($buf); 1; })
{
if ($@)
{
$conn->send_error(
RC_INTERNAL_SERVER_ERROR,
"$me: Parse error in (compressed) " .
"XML request (mid): $@"
);
# Again, the stream is likely corrupted
$conn->force_last_request;
next;
}
}
}
if (! eval { $reqxml = $parser->parse_done(); 1; })
{
if ($@)
{
$conn->send_error(RC_INTERNAL_SERVER_ERROR,
"$me: Parse error in (compressed) " .
"XML request (end): $@");
next;
}
}
}
# Dispatch will always return a RPC::XML::response.
# RT29351: If there was an error from RPC::XML::ParserFactory
# (such as a message that didn't conform to spec), then return it
# directly as a fault, don't have dispatch() try and handle it.
if (ref $reqxml)
{
# Set localized keys on $self, based on the connection info
## no critic (ProhibitLocalVars)
local $self->{peeraddr} = $peeraddr;
local $self->{peerhost} = $peerhost;
local $self->{peerport} = $peerport;
local $self->{request} = $req;
$respxml = $self->dispatch($reqxml);
}
else
{
$respxml = RPC::XML::response->new(
$self->server_fault('badxml', $reqxml));
}
# Clone the pre-fab response and set headers
$resp = $self->response->clone;
# Should we apply compression to the outgoing response?
$do_compress = 0; # In case it was set above for incoming data
if ($self->compress &&
($respxml->length > $self->compress_thresh) &&
(($req->header('Accept-Encoding') || q{}) =~
$self->compress_re))
{
$do_compress = 1;
$resp->header(Content_Encoding => $self->compress);
}
# Next step, determine the response disposition. If it is above the
# threshhold for a requested file cut-off, send it to a temp file
if ($self->message_file_thresh &&
$self->message_file_thresh < $respxml->length)
{
# Start by creating a temp-file
$tmpdir = $self->message_temp_dir || File::Spec->tmpdir;
# File::Temp->new() croaks on error
$resp_fh =
eval { File::Temp->new(UNLINK => 1, DIR => $tmpdir) };
if (! $resp_fh)
{
$conn->send_error(
RC_INTERNAL_SERVER_ERROR,
"$me: Error opening tmpfile: $@"
);
next;
}
# Make it auto-flush
$resp_fh->autoflush();
# Now that we have it, spool the response to it. This is a
# little hairy, since we still have to allow for compression.
# And though the response could theoretically be HUGE, in
# order to compress we have to write it to a second temp-file
# first, so that we can compress it into the primary handle.
if ($do_compress)
{
my $fh_compress =
eval { File::Temp->new(UNLINK => 1, DIR => $tmpdir) };
if (! $fh_compress)
{
$conn->send_error(
RC_INTERNAL_SERVER_ERROR,
"$me: Error opening compression tmpfile: $@"
);
next;
}
# Make it auto-flush
$fh_compress->autoflush();
# Write the request to the second FH
$respxml->serialize($fh_compress);
seek $fh_compress, 0, 0;
# Spin up the compression engine
if (! ($com_engine = Compress::Zlib::deflateInit()))
{
$conn->send_error(RC_INTERNAL_SERVER_ERROR,
"$me: Unable to initialize the " .
'Compress::Zlib engine');
next;
}
# Spool from the second FH through the compression engine,
# into the intended FH.
$buf = q{};
my $out;
while (read $fh_compress, $buf, 4096)
{
if (! defined($out = $com_engine->deflate(\$buf)))
{
$conn->send_error(RC_INTERNAL_SERVER_ERROR,
"$me: Compression failure in " . 'deflate()');
next;
}
print {$resp_fh} $out;
}
# Make sure we have all that's left
if (! defined($out = $com_engine->flush))
{
$conn->send_error(RC_INTERNAL_SERVER_ERROR,
"$me: Compression flush failure in deflate()");
next;
}
print {$resp_fh} $out;
# Close the secondary FH. Rewinding the primary is done
# later.
if (! close $fh_compress)
{
carp "Error closing temp file: $!";
}
}
else
{
$respxml->serialize($resp_fh);
}
seek $resp_fh, 0, 0;
$resp->content_length(-s $resp_fh);
$resp->content(
sub {
my $buffer = q{};
if (! defined(read $resp_fh, $buffer, 4096))
{
return;
}
$buffer;
}
);
}
else
{
# Treat the content strictly in-memory
utf8::downgrade($buf = $respxml->as_string);
if ($do_compress)
{
$buf = Compress::Zlib::compress($buf);
}
$resp->content($buf);
# With $buf force-downgraded to octets, length() should work
$resp->content_length(length $buf);
}
my $eval = eval {
local $SIG{PIPE} = sub { die "Caught SIGPIPE\n"; };
$conn->send_response($resp);
1;
};
if (! $eval && $@ && $@ =~ /Caught SIGPIPE/)
{
# Client disconnected, maybe even before we started sending
# our response. Either way, $conn is useless now.
undef $conn;
}
undef $resp;
}
else
{
$conn->send_error(RC_FORBIDDEN);
}
}
return;
}
###############################################################################
#
# Sub Name: dispatch
#
# Description: Route the request by parsing it, determining what the
# Perl routine should be, etc.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Object of this class
# $xml in ref Reference to the XML text, or
# a RPC::XML::request object.
# If it is a listref, assume
# [ name, @args ].
# $reftable in hashref If present, a reference to the
# current-running table of
# back-references
#
# Returns: RPC::XML::response object
#
###############################################################################
sub dispatch
{
my ($self, $xml) = @_;
my ($reqobj, @args, $response, $name, $meth);
if (ref $xml eq 'SCALAR')
{
$reqobj = $self->parser->parse(${$xml});
if (! ref $reqobj)
{
return RPC::XML::response->
new($self->server_fault(badxml => $reqobj));
}
}
elsif (ref $xml eq 'ARRAY')
{
# This is sort of a cheat, to make the system.multicall API call a
# lot easier. The syntax isn't documented in the manual page, for good
# reason.
$reqobj = RPC::XML::request->new(@{$xml});
}
elsif (blessed $xml && $xml->isa('RPC::XML::request'))
{
$reqobj = $xml;
}
else
{
$reqobj = $self->parser->parse($xml);
if (! ref $reqobj)
{
return RPC::XML::response->
new($self->server_fault(badxml => $reqobj));
}
}
@args = @{$reqobj->args};
$name = $reqobj->name;
# Get the method, call it, and bump the internal requests counter. Create
# a fault object if there is problem with the method object itself.
$meth = $self->get_method($name);
if (ref $meth)
{
$response = $meth->call($self, @args);
if (! (($name eq 'system.status') &&
@args &&
($args[0]->type eq 'boolean') &&
($args[0]->value)))
{
$self->{__requests}++;
}
}
else
{
$response = $self->server_fault(
badmethod => "No method '$meth' on server"
);
}
# All the eval'ing and error-trapping happened within the method class
return RPC::XML::response->new($response);
}
###############################################################################
#
# Sub Name: call
#
# Description: This is an internal, end-run-around-dispatch() method to
# allow the RPC methods that this server has and knows about
# to call each other through their reference to the server
# object.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Object of this class
# $name in scalar Name of the method to call
# @args in list Arguments (if any) to pass
#
# Returns: Success: return value of the call
# Failure: error string
#
###############################################################################
sub call
{
my ($self, $name, @args) = @_;
my $meth;
# Two VERY important notes here: The values in @args are not pre-treated
# in any way, so not only should the receiver understand what they're
# getting, there's no signature checking taking place, either.
#
# Second, if the normal return value is not distinguishable from a string,
# then the caller may not recognize if an error occurs.
$meth = $self->get_method($name);
if (! ref $meth)
{
return $meth;
}
return $meth->call($self, @args);
}
###############################################################################
#
# Sub Name: add_default_methods
#
# Description: This adds all the methods that were shipped with this
# package, by threading through to add_methods_in_dir()
# with the global constant $INSTALL_DIR.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Object reference/static class
# @details in ref Details of names to add or skip
#
# Returns: $self
#
###############################################################################
sub add_default_methods
{
my ($self, @details) = @_;
return $self->add_methods_in_dir($self->INSTALL_DIR, @details);
}
###############################################################################
#
# Sub Name: add_methods_in_dir
#
# Description: This adds all methods specified in the directory passed,
# in accordance with the details specified.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Class instance
# $dir in scalar Directory to scan
# @details in list Possible hanky-panky with the
# list of methods to install
#
# Returns: $self
#
###############################################################################
sub add_methods_in_dir
{
my ($self, $dir, @details) = @_;
my $negate = 0;
my $detail = 0;
my (%details, $ret);
if (@details)
{
$detail = 1;
if ($details[0] =~ /^-?except/i)
{
$negate = 1;
shift @details;
}
for (@details)
{
if (! /[.]xpl$/)
{
$_ .= '.xpl';
}
}
@details{@details} = (1) x @details;
}
my $dh;
if (! opendir $dh, $dir)
{
return "Error opening $dir for reading: $!";
}
my @files = grep { $_ =~ /[.]xpl$/ } readdir $dh;
closedir $dh;
for my $file (@files)
{
# Use $detail as a short-circuit to avoid the other tests when we can
if ($detail &&
($negate ? $details{$file} : ! $details{$file}))
{
next;
}
# n.b.: Giving the full path keeps add_method from having to search
$ret = $self->add_method(File::Spec->catfile($dir, $file));
if (! ref $ret)
{
return $ret;
}
}
return $self;
}
# For name-symmetry:
*add_procedures_in_dir = *add_functions_in_dir = \&add_methods_in_dir;
###############################################################################
#
# Sub Name: delete_method
#
# Description: Remove any current binding for the named method on the
# calling server object. Note that if this method is shared
# across other server objects, it won't be destroyed until
# the last server deletes it.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Object of this class
# $name in scalar Name of method to lost
#
# Returns: Success: $self
# Failure: error message
#
###############################################################################
sub delete_method
{
my ($self, $name) = @_;
if ($name)
{
if ($self->{__method_table}->{$name})
{
delete $self->{__method_table}->{$name};
}
}
else
{
return ref $self . "::delete_method: No such method $name";
}
return $self;
}
# For name-symmetry:
*delete_procedure = *delete_function = \&delete_method;
###############################################################################
#
# Sub Name: list_methods
#
# Description: Return a list of the methods this object has published.
# Returns the names, not the objects.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Object of this class
#
# Returns: List of names, possibly empty
#
###############################################################################
sub list_methods
{
return keys %{shift->{__method_table}};
}
# For name-symmetry:
*list_procedures = *list_functions = \&list_methods;
###############################################################################
#
# Sub Name: share_methods
#
# Description: Share the named methods as found on $src_srv into the
# method table of the calling object.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Object of this class
# $src_srv in ref Another object of this class
# @names in list One or more method names
#
# Returns: Success: $self
# Failure: error message
#
###############################################################################
sub share_methods
{
my ($self, $src_srv, @names) = @_;
my ($me, $pkg, %methods, @methods, $meth, @list, @missing);
$me = ref($self) . '::share_methods';
$pkg = __PACKAGE__; # So it can go inside quoted strings
if (! (blessed $src_srv && $src_srv->isa($pkg)))
{
return "$me: First arg not derived from $pkg, cannot share";
}
if (! @names)
{
return "$me: Must specify at least one method name for sharing";
}
# Scan @names for any regex objects, and if found insert the matches into
# the list.
#
# Only do this once:
@methods = keys %{$src_srv->{__method_table}};
for my $name (@names)
{
if (ref $name eq 'Regexp')
{
for (grep { $_ =~ $name } @methods)
{
$methods{$_}++;
}
}
else
{
$methods{$name}++;
}
}
# This has the benefit of trimming any redundancies caused by regex's
@names = keys %methods;
# Note that the method refs are saved until we've verified all of them.
# If we have to return a failure message, I don't want to leave a half-
# finished job or have to go back and undo (n-1) additions because of one
# failure.
for (@names)
{
$meth = $src_srv->get_method($_);
if (ref $meth)
{
push @list, $meth;
}
else
{
push @missing, $_;
}
}
if (@missing)
{
return "$me: One or more methods not found on source object: " .
join q{ } => @missing;
}
else
{
for (@list)
{
$self->add_method($_);
}
}
return $self;
}
# For name-symmetry:
*share_procedures = *share_functions = \&share_methods;
###############################################################################
#
# Sub Name: copy_methods
#
# Description: Copy the named methods as found on $src_srv into the
# method table of the calling object. This differs from
# share() above in that only the coderef is shared, the
# rest of the method is a completely new object.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Object of this class
# $src_srv in ref Another object of this class
# @names in list One or more method names
#
# Returns: Success: $self
# Failure: error message
#
###############################################################################
sub copy_methods
{
my ($self, $src_srv, @names) = @_;
my ($me, $pkg, %methods, @methods, $meth, @list, @missing);
$me = ref($self) . '::copy_methods';
$pkg = __PACKAGE__; # So it can go inside quoted strings
if (! (blessed $src_srv && $src_srv->isa($pkg)))
{
return "$me: First arg not derived from $pkg, cannot copy";
}
if (! @names)
{
return "$me: Must specify at least one method name/regex for copying";
}
# Scan @names for any regez objects, and if found insert the matches into
# the list.
#
# Only do this once:
@methods = keys %{$src_srv->{__method_table}};
for my $name (@names)
{
if (ref $name eq 'Regexp')
{
for (grep { $_ =~ $name } @methods)
{
$methods{$_}++;
}
}
else
{
$methods{$name}++;
}
}
# This has the benefit of trimming any redundancies caused by regex's
@names = keys %methods;
# Note that the method clones are saved until we've verified all of them.
# If we have to return a failure message, I don't want to leave a half-
# finished job or have to go back and undo (n-1) additions because of one
# failure.
for (@names)
{
$meth = $src_srv->get_method($_);
if (ref $meth)
{
push @list, $meth->clone;
}
else
{
push @missing, $_;
}
}
if (@missing)
{
return "$me: One or more methods not found on source object: @missing";
}
else
{
for (@list)
{
$self->add_method($_);
}
}
return $self;
}
# For name-symmetry:
*copy_procedures = *copy_functions = \©_methods;
###############################################################################
#
# Sub Name: timeout
#
# Description: This sets the timeout for processing connections after
# a new connection has been accepted. It returns the old
# timeout value. If you pass in no value, it returns
# the current timeout.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Object reference/static class
# $timeout in ref New timeout value
#
# Returns: $self->{__timeout}
#
###############################################################################
sub timeout
{
my ($self, $timeout) = @_;
my $old_timeout = $self->{__timeout};
if ($timeout)
{
$self->{__timeout} = $timeout;
}
return $old_timeout;
}
###############################################################################
#
# Sub Name: server_fault
#
# Description: Create a RPC::XML::fault object for the class of error
# and specific message that are passed in.
#
# Arguments: NAME IN/OUT TYPE DESCRIPTION
# $self in ref Object of this class
# $err in scalar Type of error/fault to generate
# $message in scalar Error text for the fault
#
# Returns: RPC::XML::fault instance
#
###############################################################################
sub server_fault
{
my ($self, $err, $message) = @_;
$message ||= q{}; # Avoid any "undef" warnings
my ($code, $text);
if (my $fault = $self->{__fault_table}->{$err})
{
if (ref $fault)
{
# This specifies both code and message
($code, $text) = @{$fault};
# Replace (the first) "%s" with $message
$text =~ s/%s/$message/;
}
else
{
# This is just the code, use $message verbatim
($code, $text) = ($fault, $message);
}
}
else
{
$code = -1;
$text = "Unknown error class '$err' (message is '$message')";
}
return RPC::XML::fault->new($code, $text);
}
1;
__END__
=head1 NAME
RPC::XML::Server - A server base-class for XML-RPC
=head1 SYNOPSIS
use RPC::XML::Server;
...
$srv = RPC::XML::Server->new(port => 9000);
# Several of these, most likely:
$srv->add_method(...);
...
$srv->server_loop; # Never returns
=head1 DESCRIPTION
This is both a base-class for developing XML-RPC servers, and a working server
class in its own right. It is built upon the B<RPC::XML> data classes, and
defaults to using B<HTTP::Daemon> for the communication layer.
=head1 SUBROUTINES/METHODS
Use of the B<RPC::XML::Server> is based on an object model. A server is
instantiated from the class, methods (subroutines) are made public by adding
them through the object interface, and then the server object is responsible
for dispatching requests (and possibly for the HTTP listening, as well).
=head2 Static Methods
These methods are static to the package, and are used to provide external
access to internal settings:
=over 4
=item INSTALL_DIR
Returns the directory that this module is installed into. This is used by
methods such as B<add_default_methods> to locate the XPL files that are
shipped with the distribution.
=item version
Returns the version string associated with this package.
=item product_tokens
This returns the identifying string for the server, in the format
C<NAME/VERSION> consistent with other applications such as Apache and
B<LWP>. It is provided here as part of the compatibility with B<HTTP::Daemon>
that is required for effective integration with B<Net::Server>.
=back
=head2 Methods
The following are object (non-static) methods. Unless otherwise explicitly
noted, all methods return the invoking object reference upon success, and a
non-reference error string upon failure.
See L</Content Compression> below for details of how the server class manages
gzip-based compression and expansion of messages.
=over 4
=item new(OPTIONS)
Creates a new object of the class and returns the blessed reference. Depending
on the options, the object will contain some combination of an HTTP listener, a
pre-populated B<HTTP::Response> object, a B<RPC::XML::ParserFactory>-generated
object, and a dispatch table with the set of default procedures pre-loaded. The
options that B<new> accepts are passed as a hash of key/value pairs (not a hash
reference). The accepted options are:
=over 4
=item B<no_http>
If passed with a C<true> value, prevents the creation and storage of the
B<HTTP::Daemon> object. This allows for deployment of a server object in other
environments. Note that if this is set, the B<server_loop> method described
below will silently attempt to use the B<Net::Server> module.
=item B<no_default>
If passed with a C<true> value, prevents the loading of the default procedures
provided with the B<RPC::XML> distribution. These may be later loaded using
the B<add_default_methods> interface described later. The procedures themselves
are described below (see L<"The Default Procedures Provided">).
=item B<path>
=item B<host>
=item B<port>
=item B<queue>
These four are specific to the HTTP-based nature of the server. The B<path>
argument sets the additional URI path information that clients would use to
contact the server. Internally, it is not used except in outgoing status and
introspection reports. The B<host>, B<port> and B<queue> arguments are passed
to the B<HTTP::Daemon> constructor if they are passed. They set the hostname,
TCP/IP port, and socket listening queue, respectively. They may also be used
if the server object tries to use B<Net::Server> as an alternative server
core.
=item B<xpl_path>
If you plan to add procedures/methods/functions to the server object by passing
filenames to the B<add_method>/B<add_procedure>/B<add_function> calls, this
argument may be used to specify one or more additional directories to be
searched when the passed-in filename is a relative path. The value for this
must be an array reference. See also the B<add_*> and B<xpl_path> methods,
below.
=item B<timeout>
Specify a value (in seconds) for the B<HTTP::Daemon> server to use as a
timeout value when reading request data from an inbound connection. The
default value is 10 seconds. This value is not used except by B<HTTP::Daemon>.
=item B<auto_methods>
If specified and set to a true value, enables the automatic searching for a
requested remote method/procedure/function that is unknown to the server object
handling the request. If set to "no" (or not set at all), then a request for an
unknown function causes the object instance to report an error. If the routine
is still not found, the error is reported. Enabling this is a security risk,
and should only be permitted by a server administrator with fully informed
acknowledgement and consent.
=item B<auto_updates>
If specified and set to a "true" value, enables the checking of the
modification time of the file from which a method/procedure/function was
originally loaded. If the file has changed, the method is re-loaded before
execution is handed off. As with the auto-loading of methods, this represents a
security risk, and should only be permitted by a server administrator with
fully informed acknowledgement and consent.
=item B<parser>
If this parameter is passed, its value is expected to be an array
reference. The contents of that array are passed to the B<new> method of the
B<RPC::XML::ParserFactory> class, which creates the parser object that the
server object caches for its use. See the B<RPC::XML::ParserFactory> manual
page for a list of recognized parameters to the constructor.
=item B<message_file_thresh>
If this key is passed, the value associated with it is assumed to be a
numerical limit to the size of in-memory messages. Any out-bound request that
would be larger than this when stringified is instead written to an anonynous
temporary file, and spooled from there instead. This is useful for cases in
which the request includes B<RPC::XML::base64> objects that are themselves
spooled from file-handles. This test is independent of compression, so even
if compression of a request would drop it below this threshhold, it will be
spooled anyway. The file itself is created via File::Temp with C<UNLINK> set,
so once it is freed the disk space is immediately freed.
=item B<message_temp_dir>
If a message is to be spooled to a temporary file, this key can define a
specific directory in which to open those files. If this is not given, then
the C<tmpdir> method from the B<File::Spec> package is used, instead.
=item B<fault_code_base>
Specify a base integer value that is added to the numerical codes for all
faults the server can return. See L</"Server Faults"> for the list of faults
that are built-in to the server class. This allows an application to "move"
the B<RPC::XML::Server> pre-defined fault codes out of the way of codes that
the application itself may generate.
Note that this value is B<not> applied to any faults specified via the next
option, C<fault_table>. It is assumed that the developer has already applied
any offset to those codes.
=item B<fault_table>
Specify one or more fault types to either add to or override the built-in set
of faults for the server object. The value of this parameter is a hash
reference whose keys are the fault type and whose values are either a scalar
(which is taken to be the numerical code) or a list reference with two elements
(the code followed by the string). See L</"Server Faults"> for the list of
faults that are built-in to the server class, and for more information on
defining your own.
=back
Any other keys in the options hash not explicitly used by the constructor are
copied over verbatim onto the object, for the benefit of sub-classing this
class. All internal keys are prefixed with C<__> to avoid confusion. Feel
free to use this prefix only if you wish to re-introduce confusion.
=item url
This returns the HTTP URL that the server will be responding to, when it is in
the connection-accept loop. If the server object was created without a
built-in HTTP listener, then this method returns C<undef>.
=item requests
Returns the number of requests this server object has marshalled. Note that in
multi-process environments (such as Apache or Net::Server::PreFork) the value
returned will only reflect the messages dispatched by the specific process
itself.
=item response
Each instance of this class (and any subclasses that do not completely
override the C<new> method) creates and stores an instance of
B<HTTP::Response>, which is then used by the B<HTTP::Daemon> or B<Net::Server>
processing loops in constructing the response to clients. The response object
has all common headers pre-set for efficiency. This method returns a reference
to that object.
=item started([BOOL])
Gets and possibly sets the clock-time when the server starts accepting
connections. If a value is passed that evaluates to true, then the current
clock time is marked as the starting time. In either case, the current value
is returned. The clock-time is based on the internal B<time> command of Perl,
and thus is represented as an integer number of seconds since the system
epoch. Generally, it is suitable for passing to either B<localtime> or to the
C<time2iso8601> routine exported by the B<RPC::XML> package.
=item timeout(INT)
You can call this method to set the timeout of new connections after
they are received. This function returns the old timeout value. If
you pass in no value then it will return the old value without
modifying the current value. The default value is 10 seconds.
=item server_fault(STRING, STRING)
Create a B<RPC::XML::fault> object of the specified type, optionally including
the second (string) parameter. See L</"Server Faults"> for the list of faults
defined by B<RPC::XML::Server> (as well as documentation on creating your
own).
=item add_method(FILE | HASHREF | OBJECT)
=item add_procedure(FILE | HASHREF | OBJECT)
=item add_function(FILE | HASHREF | OBJECT)
This adds a new published method/procedure/function to the server object that
invokes it. The new method may be specified in one of three ways: as a
filename, a hash reference or an existing object (generally of either
B<RPC::XML::Procedure>, B<RPC::XML::Method> or B<RPC::XML::Function> classes).
If passed as a hash reference, the following keys are expected:
=over 4
=item B<name>
The published (externally-visible) name for the method.
=item B<version>
An optional version stamp. Not used internally, kept mainly for informative
purposes.
=item B<hidden>
If passed and evaluates to a C<true> value, then the method should be hidden
from any introspection API implementations. This parameter is optional, the
default behavior being to make the method publically-visible.
=item B<code>
A code reference to the actual Perl subroutine that handles this method. A
symbolic reference is not accepted. The value can be passed either as a
reference to an existing routine, or possibly as a closure. See L</"How
Procedures are Called"> for the semantics the referenced subroutine must
follow.
=item B<signature>
A list reference of the signatures by which this routine may be invoked. Every
method has at least one signature. Though less efficient for cases of exactly
one signature, a list reference is always used for sake of consistency.
=item B<help>
Optional documentation text for the method. This is the text that would be
returned, for example, by a B<system.methodHelp> call (providing the server
has such an externally-visible method).
=back
If a file is passed, then it is expected to be in the XML-based format,
described in the B<RPC::XML::Procedure> page (see
L<RPC::XML::Procedure|RPC::XML::Procedure>). If the name passed is not an
absolute pathname, then the file will be searched for in any directories
specified when the object was instantiated, then in the directory into which
this module was installed, and finally in the current working directory. If the
operation fails, the return value will be a non-reference, an error
message. Otherwise, the return value is the object reference.
The B<add_method>, B<add_function> and B<add_procedure> calls are essentialy
identical unless called with hash references. Both files and objects contain
the information that defines the type (method vs. procedure) of the
funtionality to be added to the server. If B<add_method> is called with a file
that describes a procedure, the resulting addition to the server object will be
a B<RPC::XML::Procedure> object, not a method object.
For more on the creation and manipulation of procedures and methods as
objects, see L<RPC::XML::Procedure|RPC::XML::Procedure>.
=item delete_method(NAME)
=item delete_procedure(NAME)
=item delete_function(NAME)
Delete the named method/procedure/function from the calling object. Removes the
entry from the internal table that the object maintains. If the method is
shared across more than one server object (see L</share_methods>), then the
underlying object for it will only be destroyed when the last server object
releases it. On error (such as no method by that name known), an error string
is returned.
The B<delete_procedure> and B<delete_function> calls are identical, supplied
for the sake of symmetry. All calls return the matched object regardless of its
underlying type.
=item list_methods
=item list_procedures
=item list_functions
This returns a list of the names of methods and procedures the server current
has published. Note that the returned values are not the method objects, but
rather the names by which they are externally known. The "hidden" status of a
method is not consulted when this list is created; all methods and procedures
known are listed. The list is not sorted in any specific order.
The B<list_procedures> and B<list_functions> calls are provided for
symmetry. All calls list all published routines on the calling server object,
regardless of underlying type.
=item xpl_path([LISTREF])
Get and/or set the object-specific search path for C<*.xpl> files (files that
specify methods) that are specified in calls to B<add_method>, above. If a
list reference is passed, it is installed as the new path (each element of the
list being one directory name to search). Regardless of argument, the current
path is returned as a list reference. When a file is passed to B<add_method>,
the elements of this path are searched first, in order, before the
installation directory or the current working directory are searched.
=item get_method(NAME)
=item get_procedure(NAME)
=item get_function(NAME)
Returns a reference to an object of the class B<RPC::XML::Method>,
B<RPC::XML::Function> or B<RPC::XML::Procedure>, which is the current binding
for the published method NAME. If there is no such method known to the server,
then C<undef> is returned. Note that this is a referent to the object as stored
on the server object itself, and thus changes to it could affect the behavior
of the server.
The B<get_procedure> and B<get_function> calls are provided for symmetry. All
will return the same object for NAME, regardless of the underlying type.
=item server_loop(HASH)
Enters the connection-accept loop, which generally does not return. This is
the C<accept()>-based loop of B<HTTP::Daemon> if the object was created with
an instance of that class as a part. Otherwise, this enters the run-loop of
the B<Net::Server> class. It listens for requests, and marshalls them out via
the C<dispatch> method described below. It answers HTTP-HEAD requests
immediately (without counting them on the server statistics) and efficiently
by using a cached B<HTTP::Response> object.
Because infinite loops requiring a C<HUP> or C<KILL> signal to terminate are
generally in poor taste, the B<HTTP::Daemon> side of this sets up a localized
signal handler which causes an exit when triggered. By default, this is
attached to the C<INT> signal. If the B<Net::Server> module is being used
instead, it provides its own signal management.
The arguments, if passed, are interpreted as a hash of key/value options (not
a hash reference, please note). For B<HTTP::Daemon>, only one is recognized:
=over 4
=item B<signal>
If passed, should be the traditional name for the signal that should be bound
to the exit function. If desired, a reference to an array of signal names may
be passed, in which case all signals will be given the same handler. The user
is responsible for not passing the name of a non-existent signal, or one that
cannot be caught. If the value of this argument is 0 (a C<false> value) or the
string C<NONE>, then the signal handler will I<not> be installed, and the
loop may only be broken out of by killing the running process (unless other
arrangements are made within the application).
=back
The options that B<Net::Server> responds to are detailed in the manual pages
for that package. All options passed to C<server_loop> in this situation are
passed unaltered to the C<run()> method in B<Net::Server>.
=item dispatch(REQUEST)
This is the server method that actually manages the marshalling of an incoming
request into an invocation of a Perl subroutine. The parameter passed in may
be one of: a scalar containing the full XML text of the request, a scalar
reference to such a string, or a pre-constructed B<RPC::XML::request> object.
Unless an object is passed, the text is parsed with any errors triggering an
early exit. Once the object representation of the request is on hand, the
parameter data is extracted, as is the method name itself. The call is sent
along to the appropriate subroutine, and the results are collated into an
object of the B<RPC::XML::response> class, which is returned. Any non-reference
return value should be presumed to be an error string.
The dispatched method may communicate error in several ways. First, any
non-reference return value is presumed to be an error string, and is encoded
and returned as an B<RPC::XML::fault> response. The method is run under an
C<eval()>, so errors conveyed by C<$@> are similarly encoded and returned. As
a special case, a method may explicitly C<die()> with a fault response, which
is passed on unmodified.
=item add_default_methods([DETAILS])
This method adds all the default methods (those that are shipped with this
extension) to the calling server object. The files are denoted by their
C<*.xpl> extension, and are installed into the same directory as this
B<Server.pm> file. The set of default methods are described below (see
L<"The Default Methods Provided">).
If any names are passed as a list of arguments to this call, then only those
methods specified are actually loaded. If the C<*.xpl> extension is absent on
any of these names, then it is silently added for testing purposes. Note that
the methods shipped with this package have file names without the leading
C<status.> part of the method name. If the very first element of the list of
arguments is C<except> (or C<-except>), then the rest of the list is
treated as a set of names to I<not> load, while all others do get read. The
B<Apache::RPC::Server> module uses this to prevent the loading of the default
C<system.status> method while still loading all the rest of the defaults. (It
then provides a more Apache-centric status method.)
Note that there are no symmetric calls in this case. The provided API is
implemented as methods, and thus only this interface is provided.
=item add_methods_in_dir(DIR [, DETAILS])
=item add_procedures_in_dir(DIR [, DETAILS])
=item add_functions_in_dir(DIR [, DETAILS])
This is exactly like B<add_default_methods> above, save that the caller
specifies which directory to scan for C<*.xpl> files. In fact, the
B<add_default_methods> routine simply calls this routine with the installation
directory as the first argument. The definition of the additional arguments is
the same as above.
B<add_procedures_in_dir> and B<add_functions_in_dir> are provided for symmetry.
=item share_methods(SERVER, NAMES)
=item share_procedures(SERVER, NAMES)
=item share_functions(SERVER, NAMES)
The calling server object shares the methods/procedures/functions listed in
B<NAMES> with the source-server passed as the first object. The source must
derive from this package in order for this operation to be permitted. At least
one method must be specified, and all are specified by name (not by object
refernce). Both objects will reference the same exact B<RPC::XML::Procedure>
(or derivative thereof) object in this case, meaning that call-statistics and
the like will reflect the combined data. If one or more of the passed names are
not present on the source server, an error message is returned and none are
copied to the calling object.
Alternately, one or more of the name parameters passed to this call may be
regular-expression objects (the result of the B<qr> operator). Any of these
detected are applied against the list of all available methods known to the
source server. All matching ones are inserted into the list (the list is pared
for redundancies in any case). This allows for easier addition of whole
classes such as those in the C<system.*> name space (via C<qr/^system[.]/>),
for example. There is no substring matching provided. Names listed in the
parameters to this routine must be either complete strings or regular
expressions.
The B<share_procedures> and B<share_functions> calls are provided for symmetry.
=item copy_methods(SERVER, NAMES)
=item copy_procedures(SERVER, NAMES)
=item copy_functions(SERVER, NAMES)
These behave like the methods B<share_*> above, with the exception that
the calling object is given a clone of each method, rather than referencing
the same exact method as the source server. The code reference part of the
method is shared between the two, but all other data are copied (including a
fresh copy of any list references used) into a completely new
B<RPC::XML::Procedure> (or derivative) object, using the C<clone()> method
from that class. Thus, while the calling object has the same methods
available, and is re-using existing code in the Perl runtime, the method
objects (and hence the statistics and such) are kept separate. As with the
above, an error is flagged if one or more are not found.
This routine also accepts regular-expression objects with the same behavior and
limitations. Again, B<copy_procedures> and B<copy_functions> are provided for
symmetry.
=back
=head2 Specifying Server-Side Remote Procedures
Specifying the methods themselves can be a tricky undertaking. Some packages
(in other languages) delegate a specific class to handling incoming requests.
This works well, but it can lead to routines not intended for public
availability to in fact be available. There are also issues around the access
that the methods would then have to other resources within the same running
system.
The approach taken by B<RPC::XML::Server> (and the B<Apache::RPC::Server>
subclass of it) require that remote procedures be explicitly published in one
of the several ways provided. Procedures may be added directly within code by
using B<add_procedure>/B<add_method>/B<add_function> as described above, with
full data provided for the code reference, signature list, etc. The
B<add_*> technique can also be used with a file that conforms to a
specific XML-based format (detailed in the manual page for the
B<RPC::XML::Procedure> class, see L<RPC::XML::Procedure|RPC::XML::Procedure>).
Entire directories of files may be added using B<add_methods_in_dir>, which
merely reads the given directory for files that appear to be method
definitions.
=head2 The Three Types of Procedures
There are three types of procedures that B<RPC::XML::Server> marshalls calls
to. All are provided by the B<RPC::XML::Procedure> module. You should not
need to load or reference this module directly, as loading B<RPC::XML::Server>
(or a derivative) makes it available. The three types are:
=over
=item Methods (B<RPC::XML::Method>)
Code that is considered a "method" by the server is called as though it were,
in fact, a method in that class. The first argument in the list is the server
object itself, with the arguments to the call making up the rest of the list.
The server checks the signature of the method against the arguments list
before the call is made. See below (L</"How Procedures Are Called">) for more
on the invocation of code as methods.
=item Procedures (B<RPC::XML::Procedure>)
Code that is considered a "procedure" by the server is called like a normal
(non-method) subroutine call. The server object is not injected into the
arguments list. The signature of the procedure is checked again the list of
arguments before the call is made, as with methods.
=item Functions (B<RPC::XML::Function>)
Lastly, code that is considered a "function" is the simplest of the three:
it does not have the server object injected into the arguments list, and no
check of signatures is done before the call is made. It is the responsibility
of the function to properly understand the arguments list, and to return a
value that the caller will understand.
=back
There is (currently) no version that is called like a method but ignores
signatures like a function.
=head2 How Procedures Are Called
When a routine is called via the server dispatcher, it is called with the
arguments that the client request passed. Depending on whether the routine is
considered a "function", a "procedure" or a "method", there may be an extra
argument at the head of the list. The extra argument is present when the
routine being dispatched is part of a B<RPC::XML::Method> object. The extra
argument is a reference to a B<RPC::XML::Server> object (or a subclass
thereof). This is derived from a hash reference, and will include these special
keys:
=over 4
=item method_name
This is the name by which the method was called in the client. Most of the
time, this will probably be consistent for all calls to the server-side
method. But it does not have to be, hence the passing of the value.
=item signature
This is the signature that was used, when dispatching. Perl has a liberal
view of lists and scalars, so it is not always clear what arguments the client
specifically has in mind when calling the method. The signature is an array
reference containing one or more datatypes, each a simple string. The first
of the datatypes specifies the expected return type. The remainder (if any)
refer to the arguments themselves.
=item peeraddr
This is the address part of a packed B<SOCKADDR_IN> structure, as returned by
L<Socket/pack_sockaddr_in>, which contains the address of the client that has
connected and made the current request. This is provided "raw" in case you
need it. While you could re-create it from C<peerhost>, it is readily
available in both this server environment and the B<Apache::RPC::Server>
environment and thus included for convenience.
=item peerhost
This is the address of the remote (client) end of the socket, in C<x.x.x.x>
(dotted-quad) format. If you wish to look up the clients host-name, you
can use this to do so or utilize the encoded structure above directly.
=item peerport
This is the port of the remote (client) end of the socket, taken from the
B<SOCKADDR_IN> structure.
=item request
The L<HTTP::Request|HTTP::Request> object for this request. Can be used to read
HTTP headers sent by the client (C<X-Forwarded-For> for your access checks, for
example).
=back
Those keys should only be referenced within method code itself, as they are
not set on the server object outside of that context.
Note that by passing the server object reference first, method-classed
routines are essentially expected to behave as actual methods of the server
class, as opposed to ordinary functions. Of course, they can also discard the
initial argument completely.
The routines should not make (excessive) use of global variables, for obvious
reasons. When the routines are loaded from XPL files, the code is created as a
closure that forces execution in the B<RPC::XML::Procedure> package (unless the
XPL specifies a namespace, see L<RPC::XML::Procedure|RPC::XML::Procedure>). If
the code element of a procedure/method is passed in as a direct code reference
by one of the other syntaxes allowed by the constructor, the package may well
be different. Thus, routines should strive to be as localized as possible,
independent of specific namespaces. If a group of routines are expected to work
in close concert, each should explicitly set the namespace with a C<package>
declaration as the first statement within the routines themselves.
=head2 The Default Methods Provided
The following methods are provided with this package, and are the ones
installed on newly-created server objects unless told not to. These are
identified by their published names, as they are compiled internally as
anonymous subroutines and thus cannot be called directly:
=over 4
=item B<system.identity>
Returns a B<string> value identifying the server name, version, and possibly a
capability level. Takes no arguments.
=item B<system.introspection>
Returns a series of B<struct> objects that give overview documentation of one
or more of the published methods. It may be called with a B<string>
identifying a single routine, in which case the return value is a
B<struct>. It may be called with an B<array> of B<string> values, in which
case an B<array> of B<struct> values, one per element in, is returned. Lastly,
it may be called with no input parameters, in which case all published
routines are documented. Note that routines may be configured to be hidden
from such introspection queries.
=item B<system.listMethods>
Returns a list of the published methods or a subset of them as an B<array> of
B<string> values. If called with no parameters, returns all (non-hidden)
method names. If called with a single B<string> pattern, returns only those
names that contain the string as a substring of their name (case-sensitive,
and this is I<not> a regular expression evaluation).
=item B<system.methodHelp>
Takes either a single method name as a B<string>, or a series of them as an
B<array> of B<string>. The return value is the help text for the method, as
either a B<string> or B<array> of B<string> value. If the method(s) have no
help text, the string will be null.
=item B<system.methodSignature>
As above, but returns the signatures that the method accepts, as B<array> of
B<string> representations. If only one method is requests via a B<string>
parameter, then the return value is the corresponding array. If the parameter
in is an B<array>, then the returned value will be an B<array> of B<array> of
B<string>.
=item B<system.multicall>
This is a simple implementation of composite function calls in a single
request. It takes an B<array> of B<struct> values. Each B<struct> has at least
a C<methodName> member, which provides the name of the method to call. If
there is also a C<params> member, it refers to an B<array> of the parameters
that should be passed to the call.
=item B<system.status>
Takes no arguments and returns a B<struct> containing a number of system
status values including (but not limited to) the current time on the server,
the time the server was started (both of these are returned in both ISO 8601
and UNIX-style integer formats), number of requests dispatched, and some
identifying information (hostname, port, etc.).
=back
In addition, each of these has an accompanying help file in the C<methods>
sub-directory of the distribution.
These methods are installed as C<*.xpl> files, which are generated from files
in the C<methods> directory of the distribution using the B<make_method> tool
(see L<make_method|make_method>). The files there provide the Perl code that
implements these, their help files and other information.
=head2 Content Compression
The B<RPC::XML::Server> class now supports compressed messages, both incoming
and outgoing. If a client indicates that it can understand compressed content,
the server will use the B<Compress::Zlib> (available from CPAN) module, if
available, to compress any outgoing messages above a certain threshhold in
size (the default threshhold is set to 4096 bytes). The following methods are
all related to the compression support within the server class:
=over 4
=item compress
Returns a false value if compression is not available to the server object.
This is based on the availability of the B<Compress::Zlib> module at start-up
time, and cannot be changed.
=item compress_thresh([MIN_LIMIT])
Return or set the compression threshhold value. Messages smaller than this
size in bytes will not be compressed, even when compression is available, to
save on CPU resources. If a value is passed, it becomes the new limit and the
old value is returned.
=back
=head2 Spooling Large Messages
If the server anticipates handling large out-bound messages (for example, if
the hosted code returns large Base64 values pre-encoded from file handles),
the C<message_file_thresh> and C<message_temp_dir> settings may be used in a
manner similar to B<RPC::XML::Client>. Specifically, the threshhold is used to
determine when a message should be spooled to a filehandle rather than made
into an in-memory string (the B<RPC::XML::base64> type can use a filehandle,
thus eliminating the need for the data to ever be completely in memory). An
anonymous temporary file is used for these operations.
Note that the message size is checked before compression is applied, since the
size of the compressed output cannot be known until the full message is
examined. It is possible that a message will be spooled even if its compressed
size is below the threshhold, if the uncompressed size exceeds the threshhold.
=over 4
=item message_file_thresh
=item message_temp_dir
These methods may be used to retrieve or alter the values of the given keys
as defined earlier for the C<new> method.
=back
=head2 Server Faults
Previous versions of this library had a very loosely-organized set of fault
codes that a server might return in certain (non-fatal) error circumstances.
This has been replaced by a more configurable, adjustable system to allow
users to better integrate the server-defined faults with any that their
application may produce. It also allows for the definition of additional
fault types so that the same mechanism for formatting the pre-defined faults
can be used within sub-classes and user applications.
The server method B<server_fault> is used to generate B<RPC::XML::fault>
objects for these situations. It takes one or two arguments, the first being
the name of the type of fault to create and the second being the specific
message. If a fault is defined with a static message, the second argument may
be skipped (and will be ignored if passed).
In addition to defining their own faults, a user may override the definition
of any of the server's pre-defined faults.
=head3 Defining faults
The user may define their own faults using the C<fault_table> argument to the
constructor of the server class being instantiated. They may also override
any of the pre-defined faults (detailed in the next section) by providing a
new definition for the name.
The value of the C<fault_table> argument is a hash reference whose keys are
the names of the faults and whose values are one of two types:
=over 4
=item An integer
If the value for the key is a scalar, it is assumed to be an integer and will
be used as the fault code. When the fault is created, the message argument
(the second parameter) will be used verbatim as the fault message.
=item A 2-element list reference
If the value is a list reference, it is assumed to have two elements: the first
is the integer fault code to use, and the second is a message "template"
string to use as the fault message. If the string contains the sequence C<%s>,
this will be replaced with the message argument (the second parameter) passed
to B<server_fault>. If that sequence is not in the string, then the fault
message is considered static and the message argument is ignored.
=back
An example of defining faults:
my $server = RPC::XML::Server->new(
...
fault_table => {
limitexceeded => [ 500 => 'Call limit exceeded' ],
accessdenied => [ 600 => 'Access denied: %s' ],
serviceclosed => 700
},
...
);
In this example, the fault-type "limitexceeded" is defined as having a fault
code of 500 and a static message of C<Call limit exceeded>. The next fault
defined is "accessdenied", which has a code of 600 and message that starts
with C<Access denied:> and incorporates whatever message was passed in to the
fault creation. The last example defines a fault called C<serviceclosed> that
has a code of 700 and uses any passed-in message unaltered.
=head3 Server-defined faults
The B<RPC::XML::Server> class defines the following faults and uses them
internally. You can override the codes and messages for these by including them
in the table passed as a C<fault_table> argument. The faults fall into three
groups:
=over 4
=item Request Initialization
Faults in this group stem from the initialization of the request and the
parsing of the XML. The codes for this group fall in the range 100-199.
=item Method Resolution
This group covers problems with mapping the request to a known method or
function on the server. These codes will be in the range 200-299.
=item Execution
Lastly, these faults are for problems in actually executing the requested
code. Their codes are in the range 300-399.
=back
The faults, and the phases they apply to, are:
=over 4
=item badxml (Request Initialization)
This fault is sent back to the client when the XML of the request did not
parse as a valid XML-RPC request.
The code is C<100>, and the message is of the form, C<XML parse error: %s>.
The specific error from the XML parser is included in the message.
=item badmethod (Method Resolution)
This fault is sent when the requested method is unknown to the server. No
method has been configured on the server by that name.
The code is C<200>, and the message is of the form, C<Method lookup error: %s>.
The name of the method and other information is included in the message.
=item badsignature (Method Resolution)
If a method is known on the server, but there is no signature that matches the
sequence of arguments passed, this fault is returned. This fault cannot be
triggered by server-side code configured via B<RPC::XML::Function>, as no
signature-checking is done for those.
The code is C<201>, and the message is of the form, C<Method signature error:
%s>. The name of the method and the signature of the arguments is included in
the message.
=item execerror (Execution)
This fault relates back to the client any exception thrown by the remote code
during execution. If the invoked code returned their error in the form of a
B<RPC::XML::fault> object, that fault is returned instead. Otherwise, the
value of C<$@> is used in the message of the fault that gets generated.
The code is C<300>, and the message is of the form, C<Code execution error:
%s>. The actual text of the exception thrown is included in the message.
=back
There is one special server-fault whose code and message cannot be overridden.
If a call is made to B<server_fault> for an unknown type of fault, the
returned object will have a code of C<-1> and a message stating that the
fault-type is unknown. The message will include both the requested type-name
and any message (if any) that was passed in.
=head3 Adjusting the server-defined codes
If you just want to "move" the range of codes that the server uses out of the
way of your application's own faults, this can be done with the
C<fault_code_base> parameter when constructing the server object. The value
of the parameter must be an integer, and it is added to the value of all
existing fault codes. For example, a value of C<10000> would make the code
for the C<badxml> fault be C<10100>, the code for C<badmethod> be C<10200>,
etc.
This is applied before any user-defined faults are merged in, so their code
values will not be affected by this value.
=head1 DIAGNOSTICS
Unless explicitly stated otherwise, all methods return some type of reference
on success, or an error string on failure. Non-reference return values should
always be interpreted as errors unless otherwise noted.
=head1 BUGS
Please report any bugs or feature requests to
C<bug-rpc-xml at rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will be
notified, and then you'll automatically be notified of progress on
your bug as I make changes.
=head1 SUPPORT
=over 4
=item * RT: CPAN's request tracker
L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
=item * AnnoCPAN: Annotated CPAN documentation
L<http://annocpan.org/dist/RPC-XML>
=item * CPAN Ratings
L<http://cpanratings.perl.org/d/RPC-XML>
=item * Search CPAN
L<http://search.cpan.org/dist/RPC-XML>
=item * MetaCPAN
L<https://metacpan.org/release/RPC-XML>
=item * Source code on GitHub
L<http://github.com/rjray/rpc-xml>
=back
=head1 LICENSE AND COPYRIGHT
This file and the code within are copyright (c) 2011 by Randy J. Ray.
Copying and distribution are permitted under the terms of the Artistic
License 2.0 (L<http://www.opensource.org/licenses/artistic-license-2.0.php>) or
the GNU LGPL 2.1 (L<http://www.opensource.org/licenses/lgpl-2.1.php>).
=head1 CREDITS
The B<XML-RPC> standard is Copyright (c) 1998-2001, UserLand Software, Inc.
See <http://www.xmlrpc.com> for more information about the B<XML-RPC>
specification.
=head1 SEE ALSO
L<RPC::XML|RPC::XML>, L<RPC::XML::Client|RPC::XML::Client>,
L<RPC::XML::ParserFactory|RPC::XML::ParserFactory>
=head1 AUTHOR
Randy J. Ray C<< <rjray@blackperl.com> >>
=cut