/ 
Linux-Event-WebSocket-0.002
/ Linux::Event::WebSocket::Client

NAME

Linux::Event::WebSocket::Client - callback-first WebSocket client

SYNOPSIS

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

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

my $client = Linux::Event::WebSocket::Client->new(
    loop => $loop,
    on_open => sub ($ws) {
        $ws->send_text('hello');
    },
    on_message => sub ($ws, $payload, $type) {
        say $payload if $type eq 'text';
    },
    on_close => sub ($ws, $code, $reason) {
        $loop->stop;
    },
);

$client->connect('wss://example.com/socket');
$loop->run;

DESCRIPTION

The Client uses Linux::Event::HTTP only for the opening HTTP/1.1 Upgrade. The same live connection object is then transitioned in place to Linux::Event::WebSocket::Client::Connection. The private handshake engine validates WebSocket-specific response fields, including Sec-WebSocket-Accept.

connect returns the live connection reference immediately. During the opening handshake its class is private HTTP machinery; after a successful Upgrade the same reference is reblessed to the configured WebSocket connection class. Application WebSocket work should begin in on_open.

ws:// and wss:// are supported. wss:// uses Linux::Event TLS and keeps that transport attached across the HTTP-to-WebSocket transition.

METHODS

connect(URL)

Starts one WebSocket connection and returns the live connection reference.

connection

Returns the current live connection reference.

send_text, send_binary, ping

Convenience methods that delegate to the established connection. They reject calls made before the WebSocket handshake completes.

close

Starts a graceful WebSocket close after the handshake. Before the handshake completes it closes the pending transport.

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 AND HEADERS

subprotocols is an array reference of protocols offered during the handshake. origin sets the Origin field. headers may contain additional HTTP fields, but fields owned by the WebSocket handshake cannot be overridden.

CONNECTION SUBCLASSES

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