Protoc...:Frame(3pm)

💅 Protocol::WebSocket::Frame — WebSocket Frame (Perl 3pm page) 🦋

okay so this is the Protocol::WebSocket::Frame page from the User Contributed Perl Documentation, and bestie, it's literally the whole toolkit for building and reading WebSocket frames. let's get into it ✨

---

🌸 SYNOPSIS 🌸

no cap, here's the vibe:

# Create frame
my $frame = Protocol::WebSocket::Frame->new('123');
$frame->to_bytes;

# Parse frames
my $frame = Protocol::WebSocket::Frame->new;
$frame->append(...);
$f->next; # get next message
$f->next; # get another next message

see how you can go either way? make a frame, or slurp bytes in and pull messages out one at a time 🫶 (and yeah it's $f there, not $frame — that's literally how the original has it, iykyk, not my typo 💀)

---

🎀 DESCRIPTION 🎀

Construct or parse a WebSocket frame. that's it, that's the whole thing — it's giving main character energy for the entire WebSocket protocol tbh 👑

---

🔥 RANDOM MASK GENERATION 🔥

so by default it uses the built-in rand for random mask generation, and bestie… that is not secure. literally not secure at all 😭

but good news: if Math::Random::Secure is installed, it gets used instead. so installing it is lowkey the slay move 🔐✨

---

💖 METHODS 💖

⭐ new

Protocol::WebSocket::Frame->new('data');   # same as (buffer => 'data')
Protocol::WebSocket::Frame->new(buffer => 'data', type => 'close');

Create a new Protocol::WebSocket::Frame instance. it automatically detects whether the data you passed is a Perl string (UTF-8 flag) or bytes — it just knows 🔍💅

when you call it with more than one argument, it takes these named arguments. all of them are optional, no pressure:

• buffer => STR (default: "") — the payload of the frame. 🍓
• type => TYPE_STR (default: "text") — the type of the frame. accepted values are:

continuation
text
binary
ping
pong
close

• opcode => INT (default: 1) — the opcode of the frame. heads up: if the type field is set to a valid string, this field is ignored. sorry, opcode, type wins 👑
• fin => BOOL (default: 1) — the fin flag of the frame. fin flag must be 1 in the ending frame of fragments. not optional, that's the rule 📌
• masked => BOOL (default: 0) — if set to true, the frame will be masked. 🎭
• version => VERSION_STR (default: 'draft-ietf-hybi-17') — WebSocket protocol version string. check Protocol::WebSocket for valid version strings, iykyk 📖

⭐ is_continuation

Check if frame is of continuation type. 🔁

⭐ is_text

Check if frame is of text type. 📝

⭐ is_binary

Check if frame is of binary type. 💾

⭐ is_ping

Check if frame is a ping request. 🏓

⭐ is_pong

Check if frame is a pong response. 🏓 back atcha

⭐ is_close

Check if frame is of close type. 🚪

⭐ opcode

$opcode = $frame->opcode;
$frame->opcode(8);

Get/set opcode of the frame. dual-purpose icon ✨

⭐ masked

$masked = $frame->masked;
$frame->masked(1);

Get/set masking of the frame. 🎭

⭐ append

$frame->append($chunk);

Append a frame chunk.

⚠️ beware bestie — this method is destructive. it makes $chunk empty unless $chunk is read-only. like it literally eats your chunk 😭 don't say i didn't warn you.

⭐ next

$frame->append(...);

$frame->next; # next message

Return the next message as a Perl string (UTF-8 decoded). 🎁

⭐ next_bytes

Return the next message as is. no decoding, raw bytes, exactly as delivered 🧊

⭐ to_bytes

Construct a WebSocket message. 🔨

⭐ max_payload_size

The maximum size of the payload. you may set this to 0 or undef to disable checking the payload size. so like, set it to nothing if you want no limit — your call, live your truth 🦋

---

🌈 sign-off 🌈

that's the whole page, bestie! 🫶 this was perl v5.42.0, dated 2019-03-13, straight from the User Contributed Perl Documentation, and the title up top is Protoc...:Frame(3pm) in case anyone asks. now go parse some frames and slay 💅👑✨