/ 
Punk-0.30
/ Punk::Test::WS

NAME

Punk::Test::WS - a pure-Perl RFC 6455 codec for testing WebSocket servers

SYNOPSIS

use Punk::Test::WS qw(encode_client decode_ref accept_key);

syswrite $sock, encode_client(opcode => 1, payload => 'hello');
my $frame = decode_ref($bytes);   # { fin, opcode, payload, ... }

DESCRIPTION

An independent pure-Perl implementation of the WebSocket wire format, used by Punk::Test to drive websocket routes and by Punk's own test suite to cross-check the C codec in punk_ws.h - two implementations of the spec, written separately, so a shared misunderstanding cannot hide. It depends only on core modules (Digest::SHA, MIME::Base64).

Nothing here touches Punk's C: this is deliberately the client's view of the protocol.

FUNCTIONS

All exported on request.

encode_client(%args)

One client frame - always masked, per RFC 6455 5.3. Arguments: payload (default empty), opcode (default 1, text), fin (default 1), mask (4 random bytes unless given). Returns the wire bytes.

encode_server(%args)

One server frame - never masked. Same arguments minus mask. Useful for sending a deliberately unmasked frame at a server that must refuse it.

decode_ref($bytes)

Decode one frame off the front of $bytes. Returns a hashref (consumed, fin, opcode, payload, masked), or undef when more bytes are needed, or a string error name (rsv, control-fragmented, control-too-long, length-msb) for a protocol violation.

accept_key($key)

The Sec-WebSocket-Accept digest for a Sec-WebSocket-Key, per the RFC.

handshake_request(%args)

A complete client upgrade request for a live TCP test. Arguments: path, host, key (pass an empty string to send no key - the case a server must reject), version (default 13), protocol, extra (an arrayref of additional raw header lines). In list context returns ($request, $key).

upgrade_env(%args)

The PSGI env of an upgrade request, for driving a compiled app in-process: Punk's C handshake validates env headers, not raw bytes. Arguments: path, query, protocol. Returns ($env, $key); the caller adds psgix.io and any cookies.

SEE ALSO

Punk::Test::WS::Conn - a client-side connection over any socket, built on this codec. Punk::Test, Punk::WebSocket.

AUTHOR

LNATION <email@lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION <email@lnation.org>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)