view release on metacpan or  search on metacpan

lib/EV/Websockets.pm  view on Meta::CPAN

        headers          => { Authorization => 'Bearer token' },
        ssl_verify       => 1,                   # 0 to disable TLS verification
        max_message_size => 1048576,             # optional, 0 = unlimited
        connect_timeout  => 5.0,                 # optional, seconds
        on_connect  => sub { my ($conn, $headers) = @_; ... },
        on_message  => sub { my ($conn, $data, $is_binary) = @_; ... },
        on_close    => sub { my ($conn, $code, $reason) = @_; ... },
        on_error    => sub { my ($conn, $err) = @_; ... },
        on_pong     => sub { my ($conn, $payload) = @_; ... },
        on_drain    => sub { my ($conn) = @_; ... },
    );

Returns an L<EV::Websockets::Connection> object.

C<on_message> receives complete reassembled messages; fragmented frames are
buffered internally up to C<max_message_size>. For backwards compatibility a
fourth argument C<$is_final> is also passed but is always C<1>.

C<connect_timeout> sets a deadline (in seconds) for the WebSocket handshake.
If the connection is not established within this time, C<on_error> fires with
C<"connect timeout"> and the connection is closed.

C<$headers> in C<on_connect> is a hashref of response headers from the server
(Set-Cookie, Content-Type, Server, Sec-WebSocket-Protocol, and when available
Location, WWW-Authenticate).

C<on_drain> fires from the writeable callback when the send queue empties.
It will B<not> fire if C<close()> has already been queued - once closing is
in progress the connection short-circuits to teardown without emitting drain.
If you need to act after the queue empties, do so before calling C<close()>,
or rely on C<on_close> instead.

=head3 listen(%options)

Create a WebSocket listener. Returns the port number being listened on
(useful if port 0 was requested).

    my $port = $ctx->listen(
        port             => 0,          # 0 to let OS pick a port
        name             => 'server',   # optional vhost name (default: 'server')
        protocol         => 'chat',     # optional WebSocket subprotocol
        ssl_cert         => 'cert.pem', # optional, enables TLS
        ssl_key          => 'key.pem',  # required if ssl_cert is set
        ssl_ca           => 'ca.pem',   # optional CA chain
        max_message_size => 1048576,    # optional, 0 = unlimited
        headers          => { 'Set-Cookie' => 'session=abc123' }, # response headers
        on_handshake => sub { my ($headers) = @_; return { 'X-Custom' => 'val' } },
        on_connect  => sub { my ($conn, $headers) = @_; ... },
        on_message  => sub { my ($conn, $data, $is_binary) = @_; ... },
        on_close    => sub { my ($conn, $code, $reason) = @_; ... },
        on_error    => sub { my ($conn, $err) = @_; ... },
        on_pong     => sub { my ($conn, $payload) = @_; ... },
        on_drain    => sub { my ($conn) = @_; ... },
    );

C<protocol> sets the WebSocket subprotocol name advertised by the server vhost.
The vhost name C<default> is reserved and will croak if used.

C<$headers> in C<on_connect> is a hashref of client request headers
(Path, Host, Origin, Cookie, Authorization, Sec-WebSocket-Protocol,
User-Agent, X-Forwarded-For).
C<Path> is the request URI (e.g., C</chat>).

C<headers> is an optional hashref of headers to inject into the HTTP upgrade
response (e.g., C<Set-Cookie>).

C<on_handshake> fires before the 101 response is sent
(at C<LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION>). It receives a hashref of
request headers (same keys as C<on_connect>). Return a hashref to inject
per-connection response headers into the upgrade response. Return a false
value (C<undef>, C<0>, C<"">) to reject the connection (the client receives
a 403).

=head3 connections

Returns a list of Connection objects whose state is C<"connected"> or
C<"closing"> (i.e. the WebSocket handshake completed and the underlying
wsi still exists). Conns still in C<"connecting"> and conns already
C<"closed">/C<"destroyed"> are omitted.

    my @conns = $ctx->connections;
    $_->send("broadcast!") for @conns;

=head3 adopt(%options)

Adopt an existing IO handle (socket).

    my $conn = $ctx->adopt(
        fh               => $socket_handle,
        initial_data     => $already_read_bytes, # optional pre-read data
        max_message_size => 1048576,
        on_connect => sub { my ($conn, $headers) = @_; ... },
        on_message => sub { my ($conn, $data, $is_binary) = @_; ... },
        on_close   => sub { my ($conn, $code, $reason) = @_; ... },
        on_error   => sub { my ($conn, $err) = @_; ... },
        on_pong    => sub { my ($conn, $payload) = @_; ... },
        on_drain   => sub { my ($conn) = @_; ... },
    );

Once adopted, C<libwebsockets> takes ownership of the file descriptor.
The module holds a reference to the Perl handle until the connection is
destroyed, preventing premature fd closure. C<$headers> in C<on_connect>
is always C<undef> for adopted connections.

Adopted connections cannot select a WebSocket subprotocol: lws uses the first
protocol registered on the auto-created C<server> vhost. There is no
C<protocol> option (unlike C<connect> and C<listen>).

If you already read data from the socket (e.g., the HTTP upgrade request),
pass it via C<initial_data> so lws can process the handshake.

=head2 EV::Websockets::Connection

Represents a WebSocket connection.

=head3 send($data)

Queue a text frame. Croaks if the connection is not open.

=head3 send_binary($data)