NAME

Linux::Event::WebSocket::Server - callback-first WebSocket server

SYNOPSIS

use v5.36;
use Linux::Event::Loop;
use Linux::Event::WebSocket::Server;

my $loop = Linux::Event::Loop->new;

my $server = Linux::Event::WebSocket::Server->new(
    loop => $loop,
    host => '127.0.0.1',
    port => 8080,

    on_open => sub ($ws) {
        $ws->send_text('hello');
    },

    on_message => sub ($ws, $payload, $type) {
        $ws->send_text("echo: $payload") if $type eq 'text';
    },

    on_close => sub ($ws, $code, $reason) {
        ...;
    },
);

$loop->run;

DESCRIPTION

Linux::Event::WebSocket::Server owns a Linux::Event::HTTP::Server for the opening HTTP/1.1 Upgrade. A successful handshake transitions the same live Linux::Event stream in place to Linux::Event::WebSocket::Server::Connection.

The socket, TLS transport, queued output, backpressure state, and already-read post-HTTP bytes remain on that same connection object.

CALLBACKS

on_open receives the established WebSocket connection. on_message receives the connection, payload, and type (text or binary). Text payloads are decoded UTF-8 Perl strings; binary payloads remain bytes.

on_close receives the connection, peer close code, and reason. on_error receives the connection and an error. on_drain follows Linux::Event output backpressure semantics.

on_handshake is optional and receives the parsed HTTP Request before WebSocket validation. Return true to continue or false to reject the Upgrade with HTTP 403.

LIMITS

max_message_size defaults to 16 MiB and may be set to another positive byte limit. The same bound also protects the frame reader from allocating an unreasonably large single frame.

SUBPROTOCOLS

my $server = Linux::Event::WebSocket::Server->new(
    loop => $loop,
    port => 8080,
    subprotocols => [qw(chat superchat)],
    on_message => sub ($ws, $payload, $type) { ... },
);

The established connection exposes the negotiated value through $ws->subprotocol.

TLS

Pass the normal Linux::Event::HTTP server tls policy to serve wss://. TLS remains attached when the HTTP connection transitions to WebSocket.

CONNECTION SUBCLASSES

connection_class may name a subclass of Linux::Event::WebSocket::Server::Connection. The hierarchy remains ordinary single inheritance.

Callback options take precedence over optional subclass hooks named websocket_open, websocket_message, websocket_close, websocket_error, and websocket_drain.