Protocol::XMPP(3)

📦 version 0.007, in alpine 3.24

💖 NAME 💖

ok so bestie, welcome to Protocol::XMPP — it's protocol-level support for XMPP interaction, fr fr. like, the whole Protocol::XMPP(3) situation. this is the User Contributed Perl Documentation era and we're living in it. 🦋

✨ SYNOPSIS ✨

my $xmpp = Protocol::XMPP::Stream->new;
$xmpp->();

that's it. that's the whole vibe check. two lines and you're in. 😭

🌸 DESCRIPTION 🌸

okay so this module hands you an API for the Extensible Message Passing Protocol (yes, that XMPP). people usually use it to hook up with Jabber servers and Google Talk, but honestly XMPP itself is out here supporting a whole bunch of extended features for a distributed multi-server, multi-client message exchange system. it's giving main character energy for messaging protocols. 👑

the primary implementation is based on RFC3920bis, which — no cap — is still in flux. the instant message support is defined by RFC3921bis. so yeah, we're building on a moving target, love that for us. 💀

the two main classes you'll be hanging with:

  • Protocol::XMPP::Stream — provides hooks for the underlying XML message stream ✨
  • Protocol::XMPP::Handler — passes the SAX events from this stream on to the appropriate handlers 🎀

if you're writing a client or server implementation, you should create an instance of the Protocol::XMPP::Stream class for each connection, passing callbacks so the protocol implementation can send data over the connection and process received data. one stream per connection, that's the rule, periodt. 💅

🔥 IMPLEMENTATION 🔥

here's the whole connection lifetime for a typical client session, like a little glow-up journey:

  • Connect to server
  • Establish session, including authentication and stream requirements such as TLS or compression
  • Retrieve roster
  • Send presence update to server
  • Send and receive messages as required
  • Terminate session

and like — the details of connecting to sockets and upgrading to TLS? those are left to the implementation, bestie. not our problem, respectfully. this module deals with the underlying protocol stream only, providing hooks that the implementation can call rather than attempting to implement the functionality directly. we provide the hooks, you do the socket-y bits. 🫶

🎀 Roster 🎀

a roster is a list of contacts, each of which may also have presence information. this list is stored on the server, although each client may also maintain a cached copy of the list. iykyk. 📋

roster information is exchanged using Protocol::XMPP::IQ::Roster queries and responses.

roster includes the "ver" information, which is an opaque server token used to identify the version of the roster information. it's literally just a version tag the server made up, don't overthink it. 🦋

a roster query has a single item, and the response can have multiple. noted.

each item may also belong to zero or more groups. flexible icon.

subscription states, aka the relationship statuses:

  • none — neither source nor destination contact have an existing subscription. it's giving strangers. 💀
  • to — we have a subscription to the contact, but they don't have us. unrequited, honestly.
  • from — they have us, we don't have them.
  • both — mutual subscription. 💖 the dream. slay.

⭐ MOTIVATION ⭐

this distribution is written with the intention to provide a base for XMPP implementations which can work on an event-based ("asynchronous") or standard blocking model. it uses XML::LibXML::SAX::ChunkedParser to deal with the XML fragments required by the protocol, and attempts to minimise any blocking operations. avoiding blocking? we love to see it. 🔥

🌈 SEE ALSO 🌈

  • AnyEvent::XMPP — this is an event-based implementation of XMPP, seems to support the core protocol and some key XEPs such as multi-user chat. The documentation is somewhat terse (rants about XML notwithstanding) but more detailed than Protocol::XMPP. 🙈
  • Net::XMPP — another implementation, sadly the XML parser is blocking so although it provides the Net::XMPP::Protocol abstraction layer for the XMPP protocol, which probably has better feature support than this module, it's not too suitable for dealing with asynchronous / event-based implementations. Also, I wasn't too keen on some of the implementation details, such as the direct checking for ref and callback handling. 😭
  • Net::XMPP3::Protocol — seems to be the same module as above, under a slightly different namespace. 💀

👑 AUTHOR 👑

Tom Molesworth <protocol-xmpp@entitymodel.com>

🧚 CONTRIBUTORS 🧚

with thanks to the following for contribution, absolute icons the lot of them:

  • Arthur Axel "fREW" Schmidt for testing, documentation, pointing out some of my mistakes, that sort of thing 🫶
  • Paul "LeoNerd" Evans for adding Futures to IO::Async (and writing both in the first place) ✨
  • Matt Trout for testing early versions 🌸

💜 LICENSE 💜

Copyright Tom Molesworth 2010-2026. Licensed under the same terms as Perl itself.

so anyway, that's the whole page. perl v5.42.2, dated 2026-02-15 — mwah, sending you off with a kiss and a Protocol::XMPP(3) footer. bye bestie, go build something iconic 🎀💅💖
📦 where this page comes from