view release on metacpan or  search on metacpan

lib/AnyEvent/XMPP/Writer.pm  view on Meta::CPAN

package AnyEvent::XMPP::Writer;
use strict;
use XML::Writer;
use Authen::SASL qw/Perl/;
use MIME::Base64;
use AnyEvent::XMPP::Namespaces qw/xmpp_ns/;
use AnyEvent::XMPP::Util qw/simxml filter_xml_chars filter_xml_attr_hash_chars/;
use Digest::SHA qw/sha1_hex/;
use Encode;

=head1 NAME

AnyEvent::XMPP::Writer - "XML" writer for XMPP

=head1 SYNOPSIS

   use AnyEvent::XMPP::Writer;
   ...

=head1 DESCRIPTION

This module contains some helper functions for writing XMPP "XML", which is not
real XML at all ;-( I use L<XML::Writer> and tune it until it creates "XML"
that is accepted by most servers propably (all of the XMPP servers I tested
should work (jabberd14, jabberd2, ejabberd, googletalk).

I hope the semantics of L<XML::Writer> don't change much in the future, but if
they do and you run into problems, please report them!

The whole "XML" concept of XMPP is fundamentally broken anyway. It's supposed
to be an subset of XML. But a subset of XML productions is not XML. Strictly
speaking you need a special XMPP "XML" parser and writer to be 100% conformant.

On top of that XMPP B<requires> you to parse these partial "XML" documents.
But a partial XML document is not well-formed, heck, it's not even a XML
document!  And a parser should bail out with an error. But XMPP doesn't care,
it just relies on implementation dependend behaviour of chunked parsing modes
for SAX parsing.  This functionality isn't even specified by the XML
recommendation in any way.  The recommendation even says that it's undefined
what happens if you process not-well-formed XML documents.

But I try to be as XMPP "XML" conformant as possible (it should be around
99-100%).  But it's hard to say what XML is conformant, as the specifications
of XMPP "XML" and XML are contradicting. For example XMPP also says you only
have to generated and accept UTF-8 encodings of XML, but the XML recommendation
says that each parser has to accept UTF-8 B<and> UTF-16. So, what do you do? Do
you use a XML conformant parser or do you write your own?

I'm using XML::Parser::Expat because expat knows how to parse broken (aka
'partial') "XML" documents, as XMPP requires. Another argument is that if you
capture a XMPP conversation to the end, and even if a '</stream:stream>' tag
was captured, you wont have a valid XML document. The problem is that you have
to resent a <stream> tag after TLS and SASL authentication each! Awww... I'm
repeating myself.

But well... AnyEvent::XMPP does it's best with expat to cope with the
fundamental brokeness of "XML" in XMPP.

Back to the issue with "XML" generation: I've discoverd that many XMPP servers
(eg.  jabberd14 and ejabberd) have problems with XML namespaces. Thats the
reason why I'm assigning the namespace prefixes manually: The servers just
don't accept validly namespaced XML. The draft 3921bis does even state that a
client SHOULD generate a 'stream' prefix for the <stream> tag.

I advice you to explicitly set the namespaces too if you generate "XML" for
XMPP yourself, at least until all or most of the XMPP servers have been fixed.
Which might take some years :-) And maybe will happen never.

And another note: As XMPP requires all predefined entity characters to be
escaped in character data you need a "XML" writer that will escape everything:

   RFC 3920 - 11.1.  Restrictions:

     character data or attribute values containing unescaped characters
     that map to the predefined entities (Section 4.6 therein);
     such characters MUST be escaped

This means:
You have to escape '>' in the character data. I don't know whether XML::Writer
does that. And I honestly don't care much about this. XMPP is broken by design and
I have barely time to writer my own XML parsers and writers to suit their sick taste
of "XML". (Do I repeat myself?)

I would be happy if they finally say (in RFC3920): "XMPP is NOT XML. It's just
XML-like, and some XML utilities allow you to process this kind of XML.".

=head1 METHODS

=over 4

=item B<new (%args)>

This methods takes following arguments:

=over 4

=item write_cb

The callback that is called when a XML stanza was completely written and is
ready for transfer. The first argument of the callback will be the character
data to send to the socket.

=back

And calls C<init>.

=cut

sub new {
   my $this = shift;
   my $class = ref($this) || $this;
   my $self = {
      write_cb     => sub {},
      send_iq_cb   => sub {},
      send_msg_cb  => sub {},
      send_pres_cb => sub {},