The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
UniEvent-WebSocket-1.0.0
River stage zero No dependents
1 ++
/ UniEvent::WebSocket::Connection

NAME

UniEvent::WebSocket::Connection - Websocket connection base class

SYNOPSIS

    $conn->message_callback(sub {
        my ($conn, $message) = @_;
        say $message->payload;
    });
    
    $conn->peer_close_callback(sub {
        my ($conn, $message) = @_;
        say $message->close_code;
        say $message->close_message;
    });

    $conn->send_message($bin);
    $conn->send_text("hello");
    $conn->send_ping;
    
    $conn->send(
        payload => $data,
        opcode  => OPCODE_TEXT,
        deflate => 1,
        cb      => sub { log("message sent") },
    );
    
    $conn->close(UniEvent::WebSocket::CLOSE_DONE);

DESCRIPTION

UniEvent::WebSocket::Connection represents an abstract websocket connection. It can't be created directly, it is a base class for UniEvent::WebSocket::Client and UniEvent::WebSocket::ServerConnection.

METHODS

configure(\%config)

Configures websocket connection with new config. Can be called at any time, even if connection is already established; applied immediately.

config should be a hash reference with the following fields:

anything that Protocol::WebSocket::Fast::Parser's configure() supports.
shutdown_timeout [=5]

Maximum amount of time to wait after close() for actual connection shut down.

send(%params)

Sends a websocket message.

%params may include:

payload [required]

A string to send

opcode [=OPCODE_BINARY]

Message opcode (OPCODE_TEXT or OPCODE_BINARY).

deflate [=<default>]

If set to true will compress message. If set to false will not compress message. If not specified, it depends on client/server configuration (by default, compression on message size threshold will be used).

cb

If set, this callback will be called when the message is fully sent to network layer.

Callback signature:

    my ($connection, $error, $write_request) = @_;

Where $connection is the connection object itself.

$error is an optional XS::ErrorCode object if any error occured during sending.

$write_request is the underlying UniEvent::Request::Write object that was used for sending stream data.

send_ping([$payload])

Send ping control message. $payload is optional and will be sent along with the ping message if specified. Payload must not exceed 125 bytes or it will be truncated.

send_pong([$payload])

Send pong control message. $payload is optional and will be sent along with the pong message if specified. Payload must not exceed 125 bytes or it will be truncated.

send_message($payload)

Same as

    $connection->send(payload => $payload, opcode => OPCODE_BINARY);

send_text($payload)

Same as

    $connection->send(payload => $payload, opcode => OPCODE_TEXT);

close([$close_code = CLOSE_DONE], [$close_message = <default>])

Initiate connection shutdown. Sends websocket close control message to the peer with code $close_code. $close_message can be specified as a payload for close message. If not specified, the default message will be used that depends on specified close code. Message must not exceed 123 bytes or it will be truncated.

Immediately triggers close_event. When close message from peer will be received (if not yet received), will trigger peer_close_event.

message_callback($sub)

message_event()

Callbacks set via these methods will be invoked when a message is fully received from peer.

Callback signature:

    my ($connection, $message) = @_;

Where $connection is the connection object itself.

$message is a Protocol::WebSocket::Fast::Message object.

See "EVENT CALLBACKS" in UniEvent for differences between _callback and _event versions of methods.

error_callback($sub)

error_event()

Callbacks set via these methods will be invoked on i/o errors occurred in the connection. After calling callbacks, connection will be closed automatically (if not yet done by user in callback and if user didn't start new connection).

Callback signature:

    my ($connection, $error) = @_;

Where $connection is the connection object itself.

$error is an XS::ErrorCode object describing the error stack.

See "EVENT CALLBACKS" in UniEvent for differences between _callback and _event versions of methods.

close_callback($sub)

close_event()

Callbacks set via these methods will be invoked when connection is closing (either by local user or in response to peer's close message).

Callback signature:

    my ($connection, $close_code, $close_payload) = @_;

Where $connection is the connection object itself.

$close_code is a close code for close message.

$close_payload is a payload for close message.

These two is what is being sent to the peer, not the ones received from peer.

See "EVENT CALLBACKS" in UniEvent for differences between _callback and _event versions of methods.

peer_close_callback($sub)

peer_close_event()

Callbacks set via these methods will be invoked when close message from peer is received or connection is lost. If you don't close() the connection from your side, it will be closed automatically after callbacks. In this case default close code will be used (see Protocol::WebSocket::Fast::Parser, suggested_close_code()) and the same message that peer sent (or default message if no such one).

Callback signature:

    my ($connection, $close_message) = @_;

Where $connection is the connection object itself.

$close_message is a Protocol::WebSocket::Fast::Message object representing close message from peer. It will be undef if there were no close message from peer (i.e. when connection is lost suddenly).

See "EVENT CALLBACKS" in UniEvent for differences between _callback and _event versions of methods.

ping_callback($sub)

ping_event()

Callbacks set via these methods will be invoked when ping control frame is received from peer.

Callback signature:

    my ($connection, $message) = @_;

Where $connection is the connection object itself.

$message is a Protocol::WebSocket::Fast::Message object representing ping message.

See "EVENT CALLBACKS" in UniEvent for differences between _callback and _event versions of methods.

pong_callback($sub)

pong_event()

Callbacks set via these methods will be invoked when pong control frame is received from peer.

Callback signature:

    my ($connection, $message) = @_;

Where $connection is the connection object itself.

$message is a Protocol::WebSocket::Fast::Message object representing pong message.

See "EVENT CALLBACKS" in UniEvent for differences between _callback and _event versions of methods.

loop()

Returns UniEvent::Loop object in which this connection runs.

stream()

Returns underlying UniEvent::Stream object used for communication. It may be UniEvent::Tcp or UniEvent::Pipe. May be undef for clients before connect() is called or when connection is lost.

state()

Returns current state of the connection. It is one of the constants (in UniEvent::WebSocket::Connection::* namespace).

STATE_INITIAL

Idling connection

STATE_TCP_CONNECTING

Tcp connection is being established (including possible SSL layer)

STATE_CONNECTING

Websocket handshake in progress

STATE_CONNECTED

Connection is ready

STATE_HALT

Connection is halt due to error (only for client connection)

connected()

Returns true if state() is STATE_CONNECTED

connecting()

Returns true if state() is either STATE_TCP_CONNECTING or STATE_CONNECTING

sockaddr()

Returns local sockaddr as Net::SockAddr object. May be undef if no stream().

May return error

peeraddr()

Returns remote (peer) sockaddr as Net::SockAddr object. May be undef if no stream().

May return error