/ 
Unblock-WebSocket-0.02
/ Unblock::WebSocket::Server

NAME

Unblock::WebSocket::Server - server side of an established WebSocket connection

SYNOPSIS

use Unblock::WebSocket::Server;

# The opening HTTP handshake must already be complete.
my $ws = Unblock::WebSocket::Server->new(
    on_message => sub {
        my ($ws, $message, $type) = @_;
        $ws->send_text("echo:$message");
    },
);

# Receive WebSocket bytes from a connection:
$ws->input($bytes);

# Manual mode: move outgoing bytes to the transport write queue.
while ($ws->want_write) {
    $host->write($ws->output);
}

DESCRIPTION

Server handles the WebSocket protocol for a server-side connection. It expects incoming client frames to be masked and sends unmasked frames back.

It does not create a listener, accept sockets, perform TLS, or send the opening HTTP response.

First validate the incoming HTTP request with "server_accept" in Unblock::WebSocket::Handshake and send its server_response() through your HTTP implementation. Once the HTTP connection has switched to WebSocket, create Server:

my $ws = Unblock::WebSocket::Server->new(
    %{ $handshake->connection_options },
    on_message => sub {
        my ($ws, $message, $type) = @_;
        $ws->send_text($message);
    },
);

The connection options include negotiated compression, if any.

CHOOSING OUTPUT MODE

The manual mode uses input($bytes) to receive data and output() while want_write() is true to retrieve wire bytes. The caller writes the bytes to its ordered transport queue.

In attached mode:

my $ws = Unblock::WebSocket::Server->new(
    transport => $host,
    on_message => sub {
        my ($ws, $message, $type) = @_;
        $ws->send_text($message);
    },
);

The host implements unblock_send($bytes), unblock_finish() and unblock_abort($reason). The engine automatically sends outgoing WebSocket bytes through unblock_send().

The host must accept the entire buffer or throw. If it returns a defined false value, every byte was accepted but the host is congested. Call $ws->resume_output() when the host is ready to accept more.

In attached mode output() is not available. The transport must remain alive while the WebSocket connection is in use; the engine holds only a weak reference to it.

MESSAGES AND CLOSE

on_message receives ($ws, $payload, $type) where $type is text or binary. Use send_text() and send_binary() to reply. Received Ping frames are answered automatically.

Other callbacks are on_ping, on_pong, on_close, on_error and on_drain.

A false send return means the message was accepted but the producer should pause until on_drain.

close() starts a WebSocket Close handshake. In attached mode unblock_finish() is called after the peer Close and pending protocol output are handled. The host must drain its own write queue before shutting down. Use input_eof() on read-side EOF or transport_error($reason) for a transport failure.

See "ESTABLISHED CONNECTION API" in Unblock::WebSocket for the method reference and docs/INTEGRATION.md for HTTP/1, HTTP/2 and HTTP/3 integration.