view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    per-connection response headers into the upgrade response. Return a
    false value ("undef", 0, "") to reject the connection (the client
    receives a 403).

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

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

   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, "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. $headers in "on_connect" is
    always "undef" for adopted connections.

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

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

  EV::Websockets::Connection
    Represents a WebSocket connection.

   send($data)
    Queue a text frame. Croaks if the connection is not open.

   send_binary($data)
    Queue a binary frame. Croaks if the connection is not open.

   send_ping([$payload])
    Queue a Ping frame. $payload is optional; if supplied it is silently
    truncated to 125 bytes per RFC 6455 §5.5. Croaks if the connection is
    not open.

   send_pong([$payload])
    Queue a Pong frame. Same payload rules as "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).

   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 $is_binary); subsequent calls
    send continuation frames. Set $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

    $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
    "send"/"send_binary".

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

   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};

   get_protocol
    Returns the negotiated "Sec-WebSocket-Protocol" value, or "undef" if no
    subprotocol was negotiated or the connection is closed.

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

   close([$code = 1000], [$reason])
    Initiate a clean WebSocket close. Sends a Close frame with $code
    (default 1000, normal closure) and an optional UTF-8 $reason (truncated
    by lws to fit the frame). Pending sends are drained first, then the
    connection is torn down and "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 "connecting" state - calling close() before the handshake
    completes does not cancel the in-flight connect; use "connect_timeout"
    to bound the handshake instead.

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

   resume_recv
    Resume receiving after "pause_recv". Silently does nothing on a closed
    or destroyed connection.

   is_connected
    Returns true while "state" is "connected".

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

   state
    Returns the current state as one of:

    "connecting" - TCP/TLS handshake or HTTP upgrade in progress
    "connected" - open and ready to send/receive
    "closing" - close() has been called; pending sends still draining