NAME

Kelp::Module::WebSocket::AnyEvent - AnyEvent websocket server integration with Kelp

SYNOPSIS

        # in config

        modules => [qw(Symbiosis WebSocket::AnyEvent)],
        modules_init => {
                "WebSocket::AnyEvent" => {
                        mount => '/ws',
                        serializer => "json",
                },
        },


        # in application's build method

        my $ws = $self->websocket;
        $ws->add(message => sub {
                my ($conn, $msg) = @_;
                $conn->send({received => $msg});
        });

        # can also be mounted like this, if not specified in config
        $self->symbiosis->mount("/ws" => $ws);         # by module object
        $self->symbiosis->mount("/ws" => 'websocket'); # by name


        # in psgi script

        $app = MyApp->new;
        $app->run_all;

DESCRIPTION

This is a module that integrates a websocket instance into Kelp using Kelp::Module::Symbiosis. To run it, a non-blocking Plack server based on AnyEvent is required, like Twiggy. All this module does is wrap Plack::App::WebSocket instance in Kelp's module, introduce a method to get this instance in Kelp and integrate it into running alongside Kelp using Symbiosis. An instance of this class will be available in Kelp under the websocket method.

METHODS INTRODUCED TO KELP

websocket

Returns the instance of this class (Kelp::Module::WebSocket::AnyEvent).

METHODS

name

        sig: name($self)

Reimplemented from Kelp::Module::Symbiosis::Base. Returns a name of a module that can be used in $symbiosis->loaded hash or when mounting by name. The return value is constant string 'websocket'.

Requires Symbiosis version 1.10 for name mounting to function.

connections

        sig: connections($self)

Returns a hashref containing all available Kelp::Module::WebSocket::AnyEvent::Connection instances (open connections) keyed by their unique id. An id is autoincremented from 1 and guaranteed not to change and not to be replaced by a different connection unless the server restarts.

A connection holds some additional data that can be used to hold custom data associated with that connection:

        # set / get data fields (it's an empty hash ref by default)
        $connection->data->{internal_id} = $internal_id;

        # get the entire hash reference
        $hash_ref = $connection->data;

        # replace the hash reference with something else
        $connection->data($something_else);

middleware

        sig: middleware($self)

Returns an arrayref of all middlewares in format: [ middleware_class, [ middleware_config ] ].

psgi

        sig: psgi($self)

Returns a ran instance of Plack::App::WebSocket.

run

        sig: run($self)

Same as psgi, but wraps the instance in all wanted middlewares.

add

        sig: add($self, $event, $handler)

Registers a $handler (coderef) for websocket $event (string). Handler will be passed an instance of Kelp::Module::WebSocket::AnyEvent::Connection and an incoming message. $event can be either one of: open close message error. You can only specify one handler for each event type.

EVENTS

All event handlers must be code references.

open

        open => sub ($new_connection, $env) { ... }

Optional. Called when a new connection opens. A good place to set up its variables.

message

        message => sub ($connection, $message) { ... }

Optional. This is where you handle all the incoming websocket messages. If a serializer is specified, $message will already be unserialized.

malformed_message

        message => sub ($connection, $message, $error) { ... }

Optional. This is where you handle the incoming websocket messages which could not be unserialized by a serializer. By default, an exception will be re-thrown, and effectively the connection will be closed.

If Kelp JSON module is initialized with 'allow_nonref' flag then this event will never occur.

$error will not be likely be fit for end user message, as it will contain file names and line numbers.

close

        close => sub ($connection) { ... }

Optional. Called when the connection is closing.

error

        error => $psgi_app

Optional. The code reference should be a psgi application. It will be called if an error occurs and the websocket connection have to be closed.

CONFIGURATION

middleware, middleware_init

See "middleware, middleware_init" in Kelp::Module::Symbiosis::Base.

mount

See "mount" in Kelp::Module::Symbiosis::Base.

serializer

Contains the name of the method that will be called to obtain an instance of serializer. Kelp instance must have that method registered. It must be able to ->encode and ->decode. Should also throw exception on error.

SEE ALSO

• Dancer2::Plugin::WebSocket, same integration for Dancer2 framework this module was inspired by

• Kelp, the framework

• Twiggy, a server capable of running this websocket

AUTHOR

Bartosz Jarzyna, <bbrtj.pro@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2020 - 2022 by Bartosz Jarzyna

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

cpanm Kelp::Module::WebSocket::AnyEvent

perl -MCPAN -e shell
install Kelp::Module::WebSocket::AnyEvent