1. Manuals
  2. Tumbleweed
  3. perl-Plack-App-WebSocket
  4. Plack::App::WebSocket(3pm)

Scroll to navigation

Plack::App::WebSocket(3pm) User Contributed Perl Documentation Plack::App::WebSocket(3pm)

NAME

Plack::App::WebSocket - WebSocket server as a PSGI application

SYNOPSIS

    use Plack::App::WebSocket;
    use Plack::Builder;
    
    builder {
        mount "/websocket" => Plack::App::WebSocket->new(
            on_error => sub {
                my $env = shift;
                return [500,
                        ["Content-Type" => "text/plain"],
                        ["Error: " . $env->{"plack.app.websocket.error"}]];
            },
            on_establish => sub {
                my $conn = shift;   ## Plack::App::WebSocket::Connection object
                my $env = shift;    ## PSGI env
                my $hs_res = shift; ## extra results from the handshake callback
                $conn->on(
                    message => sub {
                        my ($conn, $msg) = @_;
                        $conn->send($msg);
                    },
                    finish => sub {
                        undef $conn;
                        warn "Bye!!\n";
                    },
                );
            }
        )->to_app;
        
        mount "/" => $your_app;
    };

DESCRIPTION

This module is a PSGI application that creates an endpoint for WebSocket connections.

Prerequisites

To use Plack::App::WebSocket, your PSGI server must meet the following requirements. (Twiggy meets all of them, for example)

  • "psgi.streaming" environment is true.
  • "psgi.nonblocking" environment is true, and the server supports AnyEvent.
  • "psgix.io" environment holds a valid raw IO socket object. See PSGI::Extensions.

CLASS METHODS

$app = Plack::App::WebSocket->new(%args)

The constructor.

Fields in %args are:

"on_establish" => CODE (mandatory)
A subroutine reference that is called each time it establishes a new WebSocket connection to a client.

The code is called like

    $code->($connection, $psgi_env, \@handshake_results)

where $connection is a Plack::App::WebSocket::Connection object, $psgi_env is the PSGI environment object for the connection request, and "\@handshake_results" are extra results from the backend AnyEvent::WebSocket::Server instance's handshake callback (which can be defined by passing a configured AnyEvent::WebSocket::Server to the "websocket_server" constructor parameter). You can use the $connection to communicate with the client.

Make sure you keep $connection object as long as you need it. If you lose reference to $connection object and it's destroyed, the WebSocket connection (and its underlying transport connection) is closed.

"on_error" => PSGI_APP (optional)
A subroutine reference that is called when some error happens while processing a request.

The code is a PSGI app, so it's called like

    $psgi_response = $code->($psgi_env)

$psgi_response is returned to the client instead of a valid WebSocket handshake response.

When $code is called, "$psgi_env->{"plack.app.websocket.error"}" contains a string that briefly describes the error (See below).

By default, it returns a simple non-200 HTTP response according to "$psgi_env->{"plack.app.websocket.error"}". See below for detail.

"websocket_server" => AnyEvent::WebSocket::Server (optional)
The backend AnyEvent::WebSocket::Server instance. By default, "AnyEvent::WebSocket::Server->new()" is used.

"plack.app.websocket.error" ENVIRONMENT STRINGS

Below is the list of possible values of "plack.app.websocket.error" PSGI environment parameter. It is set in the "on_error" callback.

"not supported by the PSGI server"
The PSGI server does not support Plack::App::WebSocket. See "Prerequisites".

By default, 500 "Internal Server Error" response is returned for this error.

"invalid request"
The client sent an invalid request. In this case, "$psgi_env->{"plack.app.websocket.error.handshake"}" keeps the exception thrown by the handshake process.

By default, 400 "Bad Request" response is returned for this error.

OBJECT METHODS

$psgi_response = $app->call($psgi_env)

Process the PSGI environment ($psgi_env) and returns a PSGI response ($psgi_response).

$app_code = $app->to_app

Return a PSGI application subroutine reference.

SEE ALSO

WebSocket implementation for Amon2 Web application framework.
WebSocket implementation for Mojolicious Web application framework.
Socket.io implementation as a PSGI application.
SockJS implementation as a PSGI application.

AUTHOR

Toshio Ito, "<toshioito at cpan.org>"

CONTRIBUTORS

leedo

yanick

REPOSITORY

<https://github.com/debug-ito/Plack-App-WebSocket>

LICENSE AND COPYRIGHT

Copyright 2014 Toshio Ito.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

2020-05-10 perl v5.40.0