view release on metacpan or  search on metacpan

lib/Net/WebSocket/Frame/close.pm  view on Meta::CPAN

package Net::WebSocket::Frame::close;

=encoding utf-8

=head1 NAME

Net::WebSocket::Frame::close

=head1 SYNOPSIS

    my $frm = Net::WebSocket::Frame::close->new(

        #Optional, can be either empty (default) or four random bytes
        mask => q<>,

        code => 'SUCCESS',      #See below

        reason => 'yeah, baby', #See below
    );

    $frm->get_type();           #"close"

    $frm->is_control_frame();   #1

    my $mask = $frm->get_mask_bytes();

    my ($code, $reason) = $frm->get_code_and_reason();

    #If, for some reason, you need the raw payload:
    my $payload = $frm->get_payload();

    my $serialized = $frm->to_bytes();

Note that, L<as per RFC 6455|https://tools.ietf.org/html/rfc6455#section-5.5>,
close messages can have any of:

=over

=item * no code, and no reason

Returned as undef (for the code) and an empty string. This diverges
from the RFC’s described behavior of returning code 1005.

=item * a code, and no reason

Returned as the code number and an empty string.

=item * a code, and a reason that cannot exceed 123 bytes

=back

The code (i.e., C<$code>) is subject to
L<the limitations that RFC 6445 describes|https://tools.ietf.org/html/rfc6455#section-7.4>.
You can also, in lieu of a numeric constant, use the following string
constants that derive from L<Microsoft’s WebSocket API|https://msdn.microsoft.com/en-us/library/windows/desktop/hh449350(v=vs.85).aspx>:

=over

=item * C<SUCCESS> (1000)

=item * C<ENDPOINT_UNAVAILABLE> (1001)

=item * C<PROTOCOL_ERROR> (1002)

=item * C<INVALID_DATA_TYPE> (1003)

=item * C<INVALID_PAYLOAD> (1007)

=item * C<POLICY_VIOLATION> (1008)

=item * C<MESSAGE_TOO_BIG> (1009)

=item * C<UNSUPPORTED_EXTENSIONS> (1010)

=item * C<INTERNAL_ERROR>, aka C<SERVER_ERROR> (1011)

This appears as C<SERVER_ERROR> in Microsoft’s documentation; however,
L<erratum 3227|https://www.rfc-editor.org/errata_search.php?rfc=6455> updates
the RFC to have this status encompass client errors as well.

Net::WebSocket recognizes either string, but its parsing logic will return
only C<INTERNAL_ERROR>.

=back

The following additional status constants derive from
L<the official registry of status codes|http://www.iana.org/assignments/websocket/websocket.xhtml#close-code-number>
and are newer than either RFC 6455 or Microsoft’s API:

=over

=item * C<SERVICE_RESTART> (1012)

=item * C<TRY_AGAIN_LATER> (1013)

=item * C<BAD_GATEWAY> (1014)

=back

It is hoped that a future update to the WebSocket specification
can include these or similar constant names.

=cut

use strict;
use warnings;

use parent qw(
    Net::WebSocket::Base::ControlFrame
);

use Call::Context ();

use Net::WebSocket::Constants ();
use Net::WebSocket::X ();