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

Amon2::Plugin::Web::WebSocket

WebSocket implementation for Amon2 Web application framework.

Mojo::Transaction::WebSocket

WebSocket implementation for Mojolicious Web application framework.

PocketIO

Socket.io implementation as a PSGI application.

SockJS

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.

cpanm Plack::App::WebSocket

perl -MCPAN -e shell
install Plack::App::WebSocket