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 attaches the standalone Unblock::HTTP1 engine to a Linux::Event listener for the 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.

listener returns the native Linux::Event listener. The older http_server accessor is retained as an alias to the listener; it no longer returns an HTTP Server object, because opening handshakes run directly through Unblock::HTTP1.

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 Linux::Event listener tls options 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.