Net::A...Matrix(3pm)

✨ NAME ✨

ok so bestie, "Net::Async::Matrix" — it's literally "use Matrix with IO::Async". that's the whole vibe 💅

(also hi yes this is the User Contributed Perl Documentation version, we're in the Net::A...Matrix(3pm) house tonight 🏠)

---

🦋 SYNOPSIS 🦋

use Net::Async::Matrix;
use IO::Async::Loop;

my $loop = IO::Async::Loop->new;

my $matrix = Net::Async::Matrix->new(
   server => "my.home.server",
);

$loop->add( $matrix );

$matrix->login(
   user_id  => '@my-user:home.server',
   password => 'SeKr1t',
)->get;

look at that. that's the whole starter pack, no cap 🔥

---

🌸 DESCRIPTION 🌸

ok so Matrix is a new open standard for interoperable Instant Messaging and VoIP, and it's giving pragmatic HTTP APIs plus open source reference implementations so you can create and run your own real-time communication infrastructure. iconic behaviour honestly.

This module lets a program interact with a Matrix homeserver as a connected user client. yes. that's the job. 👑

<http://matrix.org/>

---

💜 EVENTS 💜

these events get invoked, either as subclass methods or as CODE references passed in as parameters:

🎀 on_log $message

a request to write a debugging log message. heads up bestie, this one is provided temporarily for development and debugging purposes — at some point it'll be removed once the code has reached a certain level of stability. so don't get too attached 💀

🎀 on_presence $user, %changes

invoked when a user presence change event arrives from the homeserver. %changes maps user state field names to 2-element ARRAY references, each one holding the old and new values of that field. glow-ups tracked in real time fr fr ✨

🎀 on_room_new $room

invoked when a new room first becomes known about. you get passed an instance of Net::Async::Matrix::Room. new room just dropped 🫶

🎀 on_room_del $room

invoked when the user has now left a room. it's giving exit, stage left 😭

🎀 on_invite $event

invoked when a room invite arrives. $event contains the plain Matrix event as received, with at least the keys inviter and room_id. you've been summoned 💌

🎀 on_unknown_event $event

invoked on receipt of any sort of event from the event stream that isn't recognised by any of the other code. use this to handle new kinds of incoming events — future-proofing queen 🌈

---

💖 PARAMETERS 💖

these named parameters can be passed to new or configure. and bonus: CODE references for event handlers using the event names listed above can also be given. two birds, one slay 🦋

⭐ server => STRING

hostname and port number to contact the homeserver at. given in the form

$hostname:$port

this string gets interpolated directly into HTTP request URLs. directly. so be normal about it okay 😭

⭐ SSL => BOOL

whether to use SSL/TLS to communicate with the homeserver. defaults false. 🔒

⭐ SSL_* => ...

any other parameters whose names begin SSL_ get stored for passing to the HTTP user agent. see IO::Socket::SSL for more detail. the SSL_ prefix is doing the heavy lifting here iykyk

⭐ path_prefix => STRING

optional. gives the path prefix to find the Matrix client API at. normally this should not need modification. don't touch it. it's fine. it's fine 🧚

⭐ on_room_member, on_room_message => CODE

optional. sets default event handlers on new room objects. 💅

⭐ enable_events => BOOL

optional. normally enabled, but if you set it to a defined-but-false value (i.e. 0 or empty string) the event stream will be disabled. this means none of the incoming event handlers will be invoked, because the server will not be polled for events. zero events. nada.

this may be useful in simple send-only cases where the client has no interest in receiveing any events, and wishes to reduce the load on the homeserver. (yes that's the original spelling of "receiveing", we keep the lore 💀)

⭐ longpoll_timeout => NUM

optional. timeout in seconds for the /events longpoll operation. defaults to 30 seconds if not supplied. ⏳

⭐ first_sync_limit => NUM

optional. number of events per room to fetch on the first /sync request on startup. defaults to the server's builtin value if not defined, which is likely to be 10. 🙈

---

👑 METHODS 👑

the following methods are documented with a trailing call to ->get — those ones return Future instances. everything else is just... a normal return. okay let's go 🎀

💫 login

$matrix->login( %params )->get

performs the necessary steps required to authenticate with the configured Home Server, actually obtain an access token and start the event stream (unless it's disabled by the enable_events option being false). the returned Future will eventually yield the $matrix object itself, so it can be easily chained. chaining is the moment, periodt 🔗

there are various methods of logging in supported by Matrix; the following sets of arguments determine which is used:

• user_id, password — log in via the m.login.password method.
• user_id, access_token — directly sets the user_id and access_token fields, bypassing the usual login semantics. this presumes you already have an existing access token to re-use, obtained by some other mechanism. this exists largely for testing purposes. 🧪

💫 register

$matrix->register( %params )->get

performs the necessary steps required to create a new account on the configured Home Server. new account, new you, main character energy ✨

💫 sync

$matrix->sync( %params )->get

performs a single /sync request on the server, returning the raw results directly. no filtering, no vibes, just data 💅

takes the following named parameters:

• since => STRING — optional. sync token from the previous request.

💫 start

$f = $matrix->start

performs the initial sync on the server, and starts the event stream to begin receiving events.

while this method does return a Future it is not required that the caller keep track of this; the object itself will store it. it will complete when the initial sync has fininshed, and the event stream has started.

if the initial sync has already been requested, this method simply returns the future it returned the last time, ensuring that you can await the client starting up simply by calling it; it will not start a second time. one and done, no reruns 🫶

💫 stop

$matrix->stop

stops the event stream. after calling this you will need to use start again to continue receiving events. it's giving... we'll be back 😭

💫 myself

$user = $matrix->myself

returns the user object representing the connected user. it's you. you're the user 🪞

💫 user

$user = $matrix->user( $user_id )

returns the user object representing a user of the given ID, if defined, or undef. if they're not there, they're not there 🙈

💫 get_displayname

💫 set_displayname

$name = $matrix->get_displayname->get

$matrix->set_displayname( $name )->get

accessor and mutator for the user account's display name profile field. name reveal incoming 💖

💫 get_presence

💫 set_presence

( $presence, $msg ) = $matrix->get_presence->get

$matrix->set_presence( $presence, $msg )->get

accessor and mutator for the user's current presence state and optional status message string. status message = subtweet, but make it official 💅

💫 create_room

( $room, $room_alias ) = $matrix->create_room( $alias_localpart )->get

requests the creation of a new room and associates a new alias with the given localpart on the server. the returned Future will return an instance of Net::Async::Matrix::Room and a string containing the full alias that was created. two for one deal, we ate 🍓

💫 join_room

$room = $matrix->join_room( $room_alias_or_id )->get

requests to join an existing room with the given alias name or plain room ID. if this room is already known by the $matrix object, this method simply returns it. no double-joining, we're not messy 🌸

💫 add_alias

💫 delete_alias

$matrix->add_alias( $alias, $room_id )->get

$matrix->delete_alias( $alias )->get

performs a directory server request to create the given room alias name, to point at the room ID, or to remove it again.

note that this is likely only to be supported for alias names scoped within the homeserver the client is connected to, and that additionally some form of permissions system may be in effect on the server to limit access to the directory server. so like... it might just say no. don't take it personally 💀

💫 upload

$content_uri = $matrix->upload( %params )->get

performs a post to the server's media content repository, to upload a new piece of content, returning the content URI that points to it.

the content can be specified in any of three ways, with the following three mutually-exclusive arguments (pick ONE, bestie, not all three 😭):

• content => STRING — gives the content directly as an immediate scalar value.
• file => STRING — gives the path to a readable file on the filesystem containing the content.
• fh => IO — gives an opened IO handle the content can be read from.

the following additional arguments are also recognised:

• content_type => STRING — gives the MIME type of the content data.
• content_length => INT — optional. if the content is being delivered from an opened filehandle (via the fh argument), this gives the total length in bytes. this is required in cases such as reading from pipes, when the length of the content isn't immediately available such as by stat()ing the filehandle. 🧚

💫 convert_mxc_url

$url = $matrix->convert_mxc_url( $mxc )

given a plain string or URI instance containing a Matrix media URL (in the mxc: scheme), returns an http: or https: URL in the form of an URI instance pointing at the media repository on the user's local homeserver where it can be downloaded from. translating mxc: into something clickable, doing the Lord's work honestly ✨

---

🌈 USER STRUCTURES 🌈

parameters documented as $user receive a user struct, which supports the following methods:

• $user_id = $user->user_id — user ID of the user.
• $displayname = $user->displayname — profile displayname of the user.
• $presence = $user->presence — presence state. one of offline, unavailable or online.
• $last_active = $user->last_active — epoch time that the user was last active.

that's the whole user card, four fields, no notes 💜

---

🧚 SUBCLASSING METHODS 🧚

the following methods are not normally required by users of this class, but are provided for the convenience of subclasses to override. this is the "for devs only" section, but like, we're all devs here 👑

🎀 $room = $matrix->make_room( %params )

returns a new instance of Net::Async::Matrix::Room. build your own room, customise the whole situation 🔥

---

🔗 SEE ALSO 🔗

• <http://matrix.org/> — matrix.org home page
• <https://github.com/matrix-org> — matrix.org on github

---

🫶 AUTHOR 🫶

Paul Evans <leonerd@leonerd.org.uk>

---

💖 and that's the page!! shoutout to the source: this was perl v5.36.0, dated 2022-12-10, from Net::A...Matrix(3pm) — User Contributed Perl Documentation. stan a legend, drink some water, go read the docs, mwah 💅✨