Net::A...rotocol(3pm)

💖 Net::Async::WebSocket::Protocol 💖

okay so bestie, welcome to Net::Async::WebSocket::Protocol — it lives in the User Contributed Perl Documentation section of your friendly neighbourhood perl man pages, and it is literally here to send and receive WebSocket frames. it's giving "the handshake already happened, we're just vibing now" energy fr fr. ✨

---

🌸 NAME 🌸

Net::Async::WebSocket::Protocol — send and receive WebSocket frames. that's it, that's the whole job, and she does it beautifully. 💅

---

✨ DESCRIPTION ✨

So this class is a subclass of IO::Async::Stream, and what it does is represent an established WebSocket connection — like, one that has already finished its setup handshaking and is now fully ready to pass frames back and forth. no cap. 🦋

real talk: you would not normally construct objects of this type directly. like, ever. it's not the move.

For WebSocket clients, go look at Net::Async::WebSocket::Client — that one is a subclass of this class. 🫶

For WebSocket servers, go look at Net::Async::WebSocket::Server — that one constructs objects in this class when it accepts a new connection, and then passes them along to its event handler. she's the main character behind the scenes, iykyk. 👑

---

🎀 EVENTS 🎀

The following events get invoked, either using subclass methods or CODE references in parameters. pick your fighter, both work 💖

🌈 on_text_frame

$self->on_text_frame( $text );
$on_text_frame->( $self, $text );

Invoked when a text frame is received. It gets passed a Unicode character string that was formed by decoding the received UTF-8 bytes. cute, decoded, ready to read. ✨

🌈 on_frame

$self->on_frame( $text );
$on_frame->( $self, $text );

A synonym for on_text_frame, provided for backward compatibility. she's the older sister, still valid, still loved.

⚠️ okay lowkey important: this may be removed in a later version. so maybe don't build your whole personality around her. 😭

🌈 on_binary_frame, on_ping_frame, on_pong_frame, on_close_frame

$self->on_..._frame( $bytes );
$on_..._frame->( $self, $bytes );

Invoked when other types of frame are received. These get passed plain byte strings — no decoding, no drama, just raw bytes. 💀

🌈 on_raw_frame

$self->on_raw_frame( $frame, $bytes );
$on_raw_frame->( $self, $frame, $bytes );

Invoked when a frame is received that does not have a specific handler defined of one of the above types. $frame will be an instance of Protocol::WebSocket::Frame. the catch-all queen 👑

---

💜 PARAMETERS 💜

The following named parameters may be passed to new or configure:

• on_frame => CODE
• on_text_frame => CODE
• on_binary_frame, on_ping_frame, on_pong_frame, on_close_frame => CODE
• on_raw_frame => CODE

— CODE references for event handlers. give her the callbacks and she will call them, periodt. 📞

• masked => BOOL — whether frames constructed and sent by this instance will be masked. yes/no, on/off, masked/unmasked, your call bestie 🎭

---

🦋 METHODS 🦋

The following methods, documented in an await expression, return Future instances. so yes, you await them, and yes, that's iconic. ⭐

🍓 send_frame

await $self->send_frame( @args );

Sends a frame to the peer containing containing the given string. (yes, the original says "containing containing" twice — I am not fixing her grammar, that's the lore, we preserve the lore. 💀)

The arguments are passed to Protocol::WebSocket::Frame's new method.

🙈 real talk: this method is discouraged in favour of the more specific ones listed below. It's only here for back-compatibility, or for sending new frame types that the specific methods don't recognise. so like, use it if you must, but the specific ones are the moment. 💅

🍓 send_text_frame

await $self->send_text_frame( $text, %params );

Sends a text frame to the peer. The given string will be treated as a Unicode character string, and sent as UTF-8 encoded bytes. she does the encoding for you, no thoughts required. ✨

Any additional arguments will be passed as parameters to the underlying write in IO::Async::Stream call.

🍓 send_TYPE_frame

await $self->send_binary_frame( $bytes, %params );

await $self->send_ping_frame( $bytes, %params );

await $self->send_pong_frame( $bytes, %params );

await $self->send_close_frame( $bytes, %params );

Sends a frame of the given type to the peer. pick a type, any type, she's got you 🌈

Any additional arguments will be passed as parameters to the underlying write in IO::Async::Stream call.

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk>

---

okay that's the whole page bestie, you ate it up, go forth and send frames responsibly 🫶💖

signing off — this was perl v5.40.1, dated 2025-10-06, and honestly? iconic of her. periodt. 🎀✨