Plack::App::WebSocket - WebSocket server as a PSGI application
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; };
This module is a PSGI application that creates an endpoint for WebSocket connections.
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.streaming
psgi.nonblocking environment is true, and the server supports AnyEvent.
psgi.nonblocking
psgix.io environment holds a valid raw IO socket object. See PSGI::Extensions.
psgix.io
The constructor.
Fields in %args are:
%args
on_establish
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.
$connection
$psgi_env
\@handshake_results
websocket_server
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
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.
$psgi_response
When $code is called, $psgi_env->{"plack.app.websocket.error"} contains a string that briefly describes the error (See below).
$code
$psgi_env->{"plack.app.websocket.error"}
By default, it returns a simple non-200 HTTP response according to $psgi_env->{"plack.app.websocket.error"}. See below for detail.
The backend AnyEvent::WebSocket::Server instance. By default, AnyEvent::WebSocket::Server->new() is used.
AnyEvent::WebSocket::Server->new()
plack.app.websocket.error
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.
$psgi_env->{"plack.app.websocket.error.handshake"}
By default, 400 "Bad Request" response is returned for this error.
Process the PSGI environment ($psgi_env) and returns a PSGI response ($psgi_response).
Return a PSGI application subroutine reference.
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.
Toshio Ito, <toshioito at cpan.org>
<toshioito at cpan.org>
leedo
yanick
https://github.com/debug-ito/Plack-App-WebSocket
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.
To install Plack::App::WebSocket, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Plack::App::WebSocket
CPAN shell
perl -MCPAN -e shell install Plack::App::WebSocket
For more information on module installation, please visit the detailed CPAN module installation guide.