=encoding utf8
=head1 NAME
XML::Compile::SOAP::Daemon::AnyDaemon - SOAP server based on Any::Daemon
=head1 INHERITANCE
XML::Compile::SOAP::Daemon::AnyDaemon
is a XML::Compile::SOAP::Daemon
XML::Compile::SOAP::Daemon::AnyDaemon
is a Any::Daemon
=head1 SYNOPSIS
#### have a look in the examples directory!
use XML::Compile::SOAP::Daemon::AnyDaemon;
use XML::Compile::SOAP11;
use XML::Compile::SOAP::WSA; # optional
my $daemon = XML::Compile::SOAP::Daemon::AnyDaemon->new;
# daemon definitions from WSDL
my $wsdl = XML::Compile::WSDL11->new(...);
$wsdl->importDefinitions(...); # more schemas
$daemon->operationsFromWSDL($wsdl, callbacks => ...);
# daemon definitions added manually (when no WSDL)
my $soap11 = XML::Compile::SOAP11::Server->new(schemas => $wsdl->schemas);
my $handler = $soap11->compileHandler(...);
$daemon->addHandler('getInfo', $soap11, $handler);
# see what is defined:
$daemon->printIndex;
# finally, run the server. This never returns.
$daemon->run(@daemon_options);
=head1 DESCRIPTION
This module handles the exchange of SOAP messages over HTTP with
Any::Daemon as daemon implementation. It is a simple pre-forked
daemon, much easier than the Net::Server implementations.
We use HTTP::Daemon as HTTP-connection implementation. The
HTTP::Request and HTTP::Response objects (provided
by C<HTTP-Message>) are handled via functions provided by
L<XML::Compile::SOAP::Daemon::LWPutil|XML::Compile::SOAP::Daemon::LWPutil>.
This abstraction level of the object (code in this pm file) is not
concerned with parsing or composing XML, but only worries about the
HTTP transport specifics of SOAP messages. The processing of the SOAP
message is handled by the L<XML::Compile::SOAP::Daemon|XML::Compile::SOAP::Daemon> base-class.
The server is as flexible as possible: accept M-POST (HTTP Extension
Framework) and POST (standard HTTP) for any message. It can be used
for any SOAP1.1 and SOAP1.2 mixture. Although SOAP1.2 itself is
not implemented yet.
Extends L<"DESCRIPTION" in XML::Compile::SOAP::Daemon|XML::Compile::SOAP::Daemon/"DESCRIPTION">.
=head1 METHODS
Extends L<"METHODS" in XML::Compile::SOAP::Daemon|XML::Compile::SOAP::Daemon/"METHODS">.
=head2 Constructors
Extends L<"Constructors" in XML::Compile::SOAP::Daemon|XML::Compile::SOAP::Daemon/"Constructors">.
=over 4
=item XML::Compile::SOAP::Daemon::AnyDaemon-E<gt>B<new>(%options)
Create the server handler, which extends some class which implements
a Net::Server daemon.
As %options, you can pass everything accepted by Any::Daemon subroutine new,
like C<pid_file>, C<user>, C<group>, and C<workdir>,
-Option --Defined in --Default
accept_slow_select XML::Compile::SOAP::Daemon <true>
output_charset XML::Compile::SOAP::Daemon 'UTF-8'
soap_action_input XML::Compile::SOAP::Daemon {}
wsa_action_input XML::Compile::SOAP::Daemon {}
wsa_action_output XML::Compile::SOAP::Daemon {}
=over 2
=item accept_slow_select => BOOLEAN
=item output_charset => STRING
=item soap_action_input => HASH|ARRAY
=item wsa_action_input => HASH|ARRAY
=item wsa_action_output => HASH|ARRAY
=back
=back
=head2 Attributes
Extends L<"Attributes" in XML::Compile::SOAP::Daemon|XML::Compile::SOAP::Daemon/"Attributes">.
=over 4
=item $obj-E<gt>B<addSoapAction>(HASH|PAIRS)
Inherited, see L<XML::Compile::SOAP::Daemon/"Attributes">
=item $obj-E<gt>B<addWsaTable>( <'INPUT'|'OUTPUT'>, [HASH|PAIRS] )
Inherited, see L<XML::Compile::SOAP::Daemon/"Attributes">
=item $obj-E<gt>B<outputCharset>()
Inherited, see L<XML::Compile::SOAP::Daemon/"Attributes">
=back
=head2 Running the server
Extends L<"Running the server" in XML::Compile::SOAP::Daemon|XML::Compile::SOAP::Daemon/"Running the server">.
=over 4
=item $obj-E<gt>B<process>($client, $xmlin, $request, $action)
Inherited, see L<XML::Compile::SOAP::Daemon/"Running the server">
=item $obj-E<gt>B<run>(%options)
-Option --Default
background <true>
child_init undef
client_maxreq 100
client_reqbonus 0
client_timeout 30
host undef
listen SOMAXCONN
max_childs 10
port undef
postprocess undef
server_name undef
socket undef
=over 2
=item background => BOOLEAN
=item child_init => CODE
This CODE reference will get called by each child which gets started,
before the "accept" waiting starts. Ideal moment to start your
database-connection.
=item client_maxreq => NUMBER
Maximum number of requests per connection.
=item client_reqbonus => SECONDS
Time to add to the timeout as bonus per handled client request. Fast
clients get more time over slow clients, more time to reach their
maximum number of requests.
=item client_timeout => SECONDS
The maximum time a connection may exist, before being terminated.
=item host => STRING
Ignored when a socket is provided, otherwise required.
=item listen => INTEGER
Ignored when a socket is provided.
=item max_childs => INTEGER
=item port => INTEGER
Ignored when a socket is provided, otherwise required.
=item postprocess => CODE
See the section about this option in the DETAILS chapter of the
L<XML::Compile::SOAP::Daemon::LWPutil|XML::Compile::SOAP::Daemon::LWPutil> manual-page.
=item server_name => STRING
=item socket => SOCKET
Pass your own socket, in stead of having one created for you. The SOCKET
must be an C<IO::Socket::INET> (or compatible like IO::Socket::SSL and
IO::Socket::IP)
=back
=back
=head2 Preparations
Extends L<"Preparations" in XML::Compile::SOAP::Daemon|XML::Compile::SOAP::Daemon/"Preparations">.
=over 4
=item $obj-E<gt>B<addHandler>($name, $soap, CODE)
Inherited, see L<XML::Compile::SOAP::Daemon/"Preparations">
=item $obj-E<gt>B<operationsFromWSDL>($wsdl, %options)
Inherited, see L<XML::Compile::SOAP::Daemon/"Preparations">
=item $obj-E<gt>B<setWsdlResponse>( $filename, [$filetype] )
Inherited, see L<XML::Compile::SOAP::Daemon/"Preparations">
=back
=head2 Helpers
Extends L<"Helpers" in XML::Compile::SOAP::Daemon|XML::Compile::SOAP::Daemon/"Helpers">.
=over 4
=item $obj-E<gt>B<faultInvalidXML>($error)
Inherited, see L<XML::Compile::SOAP::Daemon/"Helpers">
=item $obj-E<gt>B<faultNotSoapMessage>($nodetype)
Inherited, see L<XML::Compile::SOAP::Daemon/"Helpers">
=item $obj-E<gt>B<faultUnsupportedSoapVersion>($env_ns)
Inherited, see L<XML::Compile::SOAP::Daemon/"Helpers">
=item $obj-E<gt>B<handlers>( <'SOAP11'|'SOAP12'|$soap> )
Inherited, see L<XML::Compile::SOAP::Daemon/"Helpers">
=item $obj-E<gt>B<printIndex>( [$fh] )
Inherited, see L<XML::Compile::SOAP::Daemon/"Helpers">
=item $obj-E<gt>B<soapVersions>()
Inherited, see L<XML::Compile::SOAP::Daemon/"Helpers">
=back
=head1 DETAILS
Extends L<"DETAILS" in XML::Compile::SOAP::Daemon|XML::Compile::SOAP::Daemon/"DETAILS">.
=head2 Operation handlers
Extends L<"Operation handlers" in XML::Compile::SOAP::Daemon|XML::Compile::SOAP::Daemon/"Operation handlers">.
=head2 Returning errors
Extends L<"Returning errors" in XML::Compile::SOAP::Daemon|XML::Compile::SOAP::Daemon/"Returning errors">.
=head2 AnyDaemon with SSL
First, create certificates and let them be signed by a CA (or yourself)
See F<http://devsec.org/info/ssl-cert.html> to understand this.
# generate secret private key
openssl genrsa -out privkey.pem 1024
# create a "certification request" (CSR)
openssl req -new -key privkey.pem -out certreq.csr
# send the CSR to the Certification Authority or self-sign:
openssl x509 -req -days 3650 -in certreq.csr -signkey privkey.pem -out newcert.pem
# publish server certificate
( openssl x509 -in newcert.pem; cat privkey.pem ) > server.pem
ln -s server.pem `openssl x509 -hash -noout -in server.pem`.0 # dot-zero
Assuming that the certificates are in 'certs/', the program looks like this:
use Log::Report;
use XML::Compile::SOAP::Daemon::AnyDaemon;
use XML::Compile::WSDL11;
use IO::Socket::SSL 'SSL_VERIFY_NONE';
use IO::Socket 'SOMAXCONN';
my $daemon = XML::Compile::SOAP::Daemon::AnyDaemon->new;
my $wsdl = XML::Compile::WSDL11->new($wsdl);
my %handlers = ();
$daemon->operationsFromWSDL($wsdl, callbacks => \%handlers);
my $socket = IO::Socket::SSL->new
( LocalHost => 'localhost'
, LocalPort => 4444
, Listen => SOMAXCONN
, Reuse => 1
, SSL_server => 1
, SSL_verify_mode => SSL_VERIFY_NONE
, SSL_key_file => 'certs/privkey.pem'
, SSL_cert_file => 'certs/server.pem'
) or error __x"cannot create socket at {interface}: {err}"
, interface => "$host:$port"
, err => IO::Socket::SSL::errstr();
$daemon->run
( name => basename($0)
, max_childs => 1
, socket => $socket
, child_init => \&for_instance_connect_to_db
)
=head1 SEE ALSO
This module is part of XML-Compile-SOAP-Daemon distribution version 3.13,
built on November 02, 2017. Website: F<http://perl.overmeer.net/xml-compile/>
Please post questions or ideas to the mailinglist at
F<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile> .
For live contact with other developers, visit the C<#xml-compile> channel
on C<irc.perl.org>.
=head1 LICENSE
Copyrights 2007-2017 by [Mark Overmeer]. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://dev.perl.org/licenses/>