NAME

Net::Libwebsockets::WebSocket::Courier - Interact with a WebSocket connection

SYNOPSIS

See Net::Libwebsockets.

DESCRIPTION

This class handles interactions with an established WebSocket connection. It acts as a “messenger” (i.e., a “courier”) between the Perl application and the WebSocket peer.

METHODS

(NB: There’s no constructor; this class is instantiated internally.)

OBJ->on_text( \&CALLBACK )

Registers a callback to fire on reception of every complete WebSocket text message. The callback receives the (character-decoded) message text.

OBJ->on_binary( \&CALLBACK )

Like on_text() but for binary messages. (The callback argument is not character-decoded, of course.)

OBJ->send_text( $CHARACTERS )

Enqueues a text message to be sent. $CHARACTERS is a character string.

OBJ->send_binary( $BINARY_STRING )

Like send_text() but sends a binary string.

$promise = OBJ->close( [ $CODE [, $REASON_CHARS ] ] )

Initiates a shutdown of the WebSocket connection. ($REASON_CHARS is a text/decoded string.)

$pause_obj = OBJ->pause()

Returns an opaque object during whose lifetime OBJ will not accept incoming WebSocket messages.

This is useful for handling/applying backpressure in case the received messages overwhelm the system. For example, if you can process 100 messages per second, but you receive 1,000 messages per second, you’ll need to stop accepting new messages periodically to allow your local processing to “catch up”. (Thus, you effectively limit your sender to 100 messages per second as well.)