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) = @_; ## Plack::App::WebSocket::Connection object
                $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)

where $connection is a Plack::App::WebSocket::Connection object. 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.

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.

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>

REPOSITORY

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

LICENSE AND COPYRIGHT

Copyright 2013 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