XML::RPC::Fast(3pm)

💖 XML::RPC::Fast 💖

okay bestie, gather round, because this is the fast and modular implementation for an XML-RPC client and server and honestly? it's giving main character energy. it's a Perl module, it lives in the User Contributed Perl Documentation section (that's the 3pm part, iykyk), and it is here to make your XML-RPC dreams come true. 🦋

---

✨ SYNOPSIS ✨

🌸 Generic usage

use XML::RPC::Fast;

my $server = XML::RPC::Fast->new( undef, %args );
my $client = XML::RPC::Fast->new( $uri,  %args );

🌸 Create a simple XML-RPC service

use XML::RPC::Fast;

my $rpc = XML::RPC::Fast->new(
    undef,                         # the url is not required by server
    external_encoding => 'koi8-r', # any encoding, accepted by Encode
    #internal_encoding => 'koi8-r', # not supported for now
);
my $xml = do { local $/; <STDIN> };
length($xml) == $ENV{CONTENT_LENGTH} or warn "Content-Length differs from actually received";

print "Content-type: text/xml; charset=$rpc->{external_encoding}\n\n";
print $rpc->receive( $xml, sub {
    my ( $methodname, @params ) = @_;
    return { you_called => $methodname, with_params => \@params };
} );

🌸 Make a call to an XML-RPC service

use XML::RPC::Fast;

my $rpc = XML::RPC::Fast->new(
    'http://your.hostname/rpc/url'
);

# Syncronous call
my @result = $rpc->req(
    call => [ 'examples.getStateStruct', { state1 => 12, state2 => 28 } ],
    url => 'http://...',
);

# Syncronous call (compatibility method)
my @result = $rpc->call( 'examples.getStateStruct', { state1 => 12, state2 => 28 } );

# Syncronous or asyncronous call
$rpc->req(
    call => ['examples.getStateStruct', { state1 => 12, state2 => 28 }],
    cb   => sub {
        my @result = @_;
    },
);

# Syncronous or asyncronous call (compatibility method)
$rpc->call( sub {
    my @result = @_;

}, 'examples.getStateStruct', { state1 => 12, state2 => 28 } );

---

💅 DESCRIPTION 💅

so like, XML::RPC::Fast is format-compatible with XML::RPC, but it's allowed to use different encoders to parse and compose xml. the encoder that ships in the box rn uses XML::LibXML, and no cap: it's 3 times faster than XML::RPC and 75% faster than the XML::Parser implementation. ate and left no crumbs fr fr 🔥

---

👑 METHODS 👑

🌈 new ($url, %args)

creates an XML::RPC::Fast object. the vibe check goes like this:

• if url is undef → you get a server 🖥️
• if url is defined → you get a client 🫶

🌈 req( %ARGS )

clientside bestie. makes a syncronous or asyncronous call, and which one you get depends on your UA.

• if you passed a cb, it will invoke $cb with the results and should not croak
• if you passed no cb, it will return the results and croak on error (and that only works with a syncronous UA)

the arguments are:

• call => [ methodName => @args ] — array ref of call arguments. Required. periodt.
• cb => $cb->(@results) — the invocation callback. Optional for a syncronous UA. the behaviour is the same as in call with $cb and without.
• url => $request_url — alternative invocation URL. optional. by default it uses the one defined in the constructor.
• headers => { http-headers hashref } — extra http headers to send with the request 🎀
• external_encoding => '...' — specify the encoding used inside the XML container, just for this one request. passed to the encoder.

🌈 call( 'method_name', @arguments ) : @results

clientside. makes a syncronous call and returns the results. croaks on error. it's literally just a simple wrapper around req. 💅

🌈 call( $cb->(@res), 'method_name', @arguments ): void

clientside. makes a syncronous or asyncronous call (depends on your UA, bestie) and invokes $cb with the results. should not croak. again, just a simple wrapper around req. iconic.

🌈 receive ( $xml, $handler->($methodName,@args) ) : xml byte-stream

serverside, babes. processes the received XML, invokes $handler with the parameters $methodName and @args, and returns the response XML.

on error conditions, $handler can either set $XML::RPC::Fast::faultCode and die, or return rpcfault($faultCode,$faultString):

->receive( $xml, sub {
    # ...
    return rpcfault( 3, "Some error" ) if $error_condition
    $XML::RPC::Fast::faultCode = 4 and die "Another error" if $another_error_condition;

    return { call => $methodname, params => \@params };
})

🌈 registerType

proxy-method to the encoder. see XML::RPC::Enc. 🧚

🌈 registerClass

proxy-method to the encoder. see XML::RPC::Enc. 🧚

---

✨ OPTIONS ✨

below are the options accepted by new(). slay.

• ua — client only. a useragent object, or a package name.

->new( $url, ua => 'LWP' ) # same as XML::RPC::UA::LWP
# or
->new( $url, ua => 'XML::RPC::UA::LWP' )
# or
->new( $url, ua => XML::RPC::UA::LWP->new( ... ) )
# or
->new( $url, ua => XML::RPC::UA::Curl->new( ... ) )

• timeout — client only. timeout for calls. passed directly to the UA.

->new( $url, ua => 'LWP', timeout => 10 )

• useragent — client only. the useragent string. passed directly to the UA.

->new( $url, ua => 'LWP', useragent => 'YourClient/1.11' )

• encoder — client and server. an encoder object or a package name.

->new( $url, encoder => 'LibXML' )
# or
->new( $url, encoder => 'XML::RPC::Enc::LibXML' )
# or
->new( $url, encoder => XML::RPC::Enc::LibXML->new( ... ) )

• internal_encoding NOT IMPLEMENTED YET — specify the encoding you're using in your code. by default this option is undef, which means flagged utf-8. Encode is used for the translations, so the list of accepted encodings is fully derived from it. (yeah bestie, not implemented yet, don't come for me 😭)
• external_encoding — specify the encoding used inside the XML container. by default it's utf-8. passed directly to the encoder.

->new( $url, encoder => 'LibXML', external_encoding => 'koi8-r' )

---

🎀 ACCESSORS 🎀

• url — get or set the client url.
• encoder — direct access to the encoder object.
• ua — direct access to the useragent object.

---

🦋 FUNCTIONS 🦋

• rpcfault(faultCode, faultString) — returns a hash structure that may be returned by a serverside handler instead of dying. not exported by default. 💀

---

🌸 CUSTOM TYPES 🌸

• sub {{ 'base64' => encode_base64($data) }} — when you pass a CODEREF as a value, the encoder will simply use the returned hashref as a type => value pair.
• bless( do{\(my $o = encode_base64('test') )}, 'base64' ) — when you pass a SCALARREF as a value, the package name will be taken as the type and the dereference as the value.
• bless( do{\(my $o = { something =>'complex' } )}, 'base64' ) — when you pass a REFREF as a value, the package name will be taken as the type, and XML::Hash::LX"::hash2xml(deref)" would be used as the value.
• customtype( $type, $data ) — easily compose a SCALARREF based custom type. 🫶

---

💜 BUGS & SUPPORT 💜

• bug reports and testcases are welcome, bestie, send them in!
• if you write your own Enc or UA, I may include it into the distribution 👑
• if you have propositions for default custom types (see Enc), send me patches
• see <http://rt.cpan.org> to report and view bugs.

---

⭐ AUTHOR ⭐

Mons Anderson, "<mons@cpan.org>"

---

🌈 COPYRIGHT & LICENSE 🌈

Copyright (c) 2008-2009 Mons Anderson.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

okay that's the whole thing, no notes 💅 this was XML::RPC::Fast(3pm), from perl v5.34.0, dated 2022-06-28 — love that for us, bye bestie, go make some XML-RPC calls 🎀✨🦋