Plack:...bSocket(3pm)

💖 NAME 💖

okay bestie, welcome to the Plack::App::WebSocket(3pm) manual page from the User Contributed Perl Documentation collection. This is Plack::App::WebSocket — a WebSocket server as a PSGI application. no cap, that's the whole NAME vibe. periodt. 🫶

✨ 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. literally its whole job, and it's giving main character energy. 💅

🧚 Prerequisites 🧚

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

• 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. slay.

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.

bestie, highkey do not lose that $connection reference. not me watching the WebSocket connection (and its underlying transport connection) go closed 😭 keep it alive as long as you need it.

"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 🚨

ngl, 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 👀

obsessed with these alternatives, iykyk:

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

---

that's the whole page, bestie. signed off with perl v5.42.0 energy, dated 2020-05-10. bye!! 💖✨