view release on metacpan or  search on metacpan

README  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 EV::Websockets::Connection object.

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

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

    $headers in "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).

    "on_drain" fires from the writeable callback when the send queue
    empties. It will not fire if 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 close(), or rely on "on_close" instead.

   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) = @_; ... },
        );

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

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

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

    "on_handshake" fires before the 101 response is sent (at
    "LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION"). It receives a hashref of
    request headers (same keys as "on_connect"). Return a hashref to inject
    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.