Scroll to navigation

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


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->{""}]];
            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
                    message => sub {
                        my ($conn, $msg) = @_;
                    finish => sub {
                        undef $conn;
                        warn "Bye!!\n";
        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.nonblocking" environment is true, and the server supports AnyEvent.
  • "" environment holds a valid raw IO socket object. See PSGI::Extensions.


$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->{""}" contains a string that briefly describes the error (See below).

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

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


Below is the list of possible values of "" 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->{""}" keeps the exception thrown by the handshake process.

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


$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.


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


Toshio Ito, "<toshioito at>"







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 for more information.

2020-05-10 perl v5.38.2