view release on metacpan or  search on metacpan

lib/Net/Async/Matrix.pm  view on Meta::CPAN

The following events are invoked, either using subclass methods or C<CODE>
references in parameters:

=head2 on_log $message

A request to write a debugging log message. This is provided temporarily for
development and debugging purposes, but will at some point be removed when the
code has reached a certain level of stability.

=head2 on_presence $user, %changes

Invoked on receipt of a user presence change event from the homeserver.
C<%changes> will map user state field names to 2-element ARRAY references,
each containing the old and new values of that field.

=head2 on_room_new $room

Invoked when a new room first becomes known about.

Passed an instance of L<Net::Async::Matrix::Room>.

=head2 on_room_del $room

Invoked when the user has now left a room.

=head2 on_invite $event

Invoked on receipt of a room invite. The C<$event> will contain the plain
Matrix event as received; with at least the keys C<inviter> and C<room_id>.

=head2 on_unknown_event $event

Invoked on receipt of any sort of event from the event stream, that is not
recognised by any of the other code. This can be used to handle new kinds of
incoming events.

=cut

=head1 PARAMETERS

The following named parameters may be passed to C<new> or C<configure>. In
addition, C<CODE> references for event handlers using the event names listed
above can also be given.

=head2 server => STRING

Hostname and port number to contact the homeserver at. Given in the form

 $hostname:$port

This string will be interpolated directly into HTTP request URLs.

=head2 SSL => BOOL

Whether to use SSL/TLS to communicate with the homeserver. Defaults false.

=head2 SSL_* => ...

Any other parameters whose names begin C<SSL_> will be stored for passing to
the HTTP user agent. See L<IO::Socket::SSL> for more detail.

=head2 path_prefix => STRING

Optional. Gives the path prefix to find the Matrix client API at. Normally
this should not need modification.

=head2 on_room_member, on_room_message => CODE

Optional. Sets default event handlers on new room objects.

=head2 enable_events => BOOL

Optional. Normally enabled, but if set to a defined-but-false value (i.e. 0 or
empty string) the event stream will be disabled. This will cause none of the
incoming event handlers to be invoked, because the server will not be polled
for events.

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.

=head2 longpoll_timeout => NUM

Optional. Timeout in seconds for the C</events> longpoll operation. Defaults
to 30 seconds if not supplied.

=head2 first_sync_limit => NUM

Optional. Number of events per room to fetch on the first C</sync> request on
startup. Defaults to the server's builtin value if not defined, which is
likely to be 10.

=cut

sub _init
{
   my $self = shift;
   my ( $params ) = @_;

   $self->SUPER::_init( $params );

   $params->{ua} ||= do {
      require Net::Async::HTTP;
      Net::Async::HTTP->VERSION( '0.36' ); # SSL params
      my $ua = Net::Async::HTTP->new(
         fail_on_error => 1,
         max_connections_per_host => 3, # allow 2 longpolls + 1 actual command
         user_agent => __PACKAGE__,
         pipeline => 0,
      );
      $self->add_child( $ua );
      $ua
   };

   # Injectable for unit tests, other event systems, etc..
   # For now undocumented while I try to work out the wider design issues
   $self->{make_delay} = delete $params->{make_delay} || $self->_capture_weakself( sub {
      my ( $self, $secs ) = @_;
      $self->loop->delay_future( after => $secs );
   } );