view release on metacpan or  search on metacpan

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

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)

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

=head3 send_ping([$payload])

Queue a Ping frame. C<$payload> is optional; if supplied it is silently
truncated to 125 bytes per RFC 6455 §5.5. Croaks if the connection is not
open.

=head3 send_pong([$payload])

Queue a Pong frame. Same payload rules as C<send_ping>. Most peers send Pong
automatically in response to Ping; you only need this to send an unsolicited
Pong (e.g. as a one-way keepalive).

=head3 send_fragment($data, $is_binary = 0, $is_final = 1)

Send one fragment of a streaming message. The first call starts a new
fragmented message (text or binary per C<$is_binary>); subsequent calls send
continuation frames. Set C<$is_final> true on the last fragment.

    $conn->send_fragment("part1", 0, 0);   # text, not final
    $conn->send_fragment("part2", 0, 0);   # continuation, not final
    $conn->send_fragment("part3", 0, 1);   # continuation, final

C<$is_binary> is honoured only on the first fragment, which fixes the message
type; it is ignored on continuation frames (they are always sent as
continuations), per RFC 6455 §5.4.

Use this only if you need to interleave outbound writes with other I/O while
streaming a single message. For ordinary sends, prefer C<send>/C<send_binary>.

=head3 send_queue_size

Returns the number of payload bytes currently queued for sending (excludes
WebSocket framing overhead). Useful for backpressure monitoring; pair with
C<on_drain> to gate further sends. Returns C<0> on a closed connection (it
does not croak), so it is safe to poll from cleanup paths.

=head3 stash

Returns a hashref for storing arbitrary per-connection metadata. The hashref
is lazily created on first access and lives until the connection is freed.

    $conn->stash->{user_id} = 42;
    my $uid = $conn->stash->{user_id};

=head3 get_protocol

Returns the negotiated C<Sec-WebSocket-Protocol> value, or C<undef> if no
subprotocol was negotiated or the connection is closed.

=head3 peer_address

Returns the peer's IP address as a printable string (IPv4 dotted-quad or
IPv6 colon notation, no brackets, no port), or C<undef> if unavailable.

=head3 close([$code = 1000], [$reason])

Initiate a clean WebSocket close. Sends a Close frame with C<$code> (default
1000, normal closure) and an optional UTF-8 C<$reason> (truncated by lws to
fit the frame). Pending sends are drained first, then the connection is torn
down and C<on_close> fires.

This is a no-op (does not croak) if the connection is already closed,
closing, or destroyed. It is also a no-op while the connection is still
in the C<"connecting"> state - calling C<close()> before the handshake
completes does not cancel the in-flight connect; use C<connect_timeout>
to bound the handshake instead.

=head3 pause_recv

Stop reading frames from this connection (TCP flow control). New incoming
frames will back up in the kernel's socket buffer until C<resume_recv> is
called. Silently does nothing on a closed or destroyed connection.

=head3 resume_recv

Resume receiving after C<pause_recv>. Silently does nothing on a closed or
destroyed connection.

=head3 is_connected

Returns true while C<state> is C<"connected">.

=head3 is_connecting

Returns true while C<state> is C<"connecting">. Returns false once the
connection is established, closing, closed, or destroyed.

=head3 state