File Coverage

blib/lib/Net/WebSocket/Streamer.pm

Criterion	Covered	Total	%
statement	37	39	94.8
branch	6	8	75.0
condition	1	3	33.3
subroutine	10	10	100.0
pod	0	3	0.0
total	54	63	85.7

package Net::WebSocket::Streamer;

=encoding utf-8

=head1 NAME

Net::WebSocket::Streamer - Send a stream easily over WebSocket

=head1 SYNOPSIS

Here’s the gist of it:

    my $streamer = Net::WebSocket::Streamer->new('binary');

    my $frame = $streamer->create_chunk($buf);

    my $last_frame = $streamer->create_final($buf);

… but a more complete example might be this: streaming a file
of arbitrary size in 64-KiB chunks:

    my $size = -s $rfh;

    while ( read $rfh, my $buf, 65536 ) {
        my $frame;

        if (tell($rfh) == $size) {
            $frame = $streamer->create_final($buf);
        }
        else {
            $frame = $streamer->create_chunk($buf);
        }

        syswrite $wfh, $frame->to_bytes();
    }

You can, of course, create/send an empty final frame for cases where you’re
not sure how much data will actually be sent.

=head1 EXTENSION SUPPORT

To stream custom frame types (or overridden classes), you can subclass
this module and define C constants, where C<*> is the
frame type, e.g., C, C.

=cut

use strict;
use warnings;

use Net::WebSocket::Frame::continuation ();
use Net::WebSocket::X ();

use constant {

    #These can be overridden in subclasses.
    frame_class_text => 'Net::WebSocket::Frame::text',
    frame_class_binary => 'Net::WebSocket::Frame::binary',

    FINISHED_INDICATOR => __PACKAGE__ . '::__ALREADY_SENT_FINAL',
};

sub new {
    my ($class, $type) = @_;

    my $frame_class = $class->_load_frame_class($type);

    return bless { class => $frame_class, pid => $$ }, $class;
}

sub create_chunk {
    my $self = shift;

    my $frame = $self->{'class'}->new(
        fin => 0,
        $self->FRAME_MASK_ARGS(),
        payload_sr => \$_[0],
    );

    #The first $frame we create needs to be text/binary, but all
    #subsequent ones must be continuation.
    if ($self->{'class'} ne 'Net::WebSocket::Frame::continuation') {
        $self->{'class'} = 'Net::WebSocket::Frame::continuation';
    }

    return $frame;
}

sub create_final {
    my $self = shift;

    my $frame = $self->{'class'}->new(
        fin => 1,
        $self->FRAME_MASK_ARGS(),
        payload_sr => \$_[0],
    );

    $self->{'finished'} = 1;

    return $frame;
}

sub _load_frame_class {
    my ($class, $type) = @_;

    my $frame_class = $class->can("frame_class_$type");
    if (!$frame_class) {
        die "Unknown frame type: “$type”!";
    }

    $frame_class = $frame_class->();
    if (!$frame_class->can('new')) {
        Module::Load::load($frame_class);
    }

    return $frame_class;
}

sub DESTROY {
    my ($self) = @_;

    if (($self->{'pid'} == $$) && !$self->{'finished'}) {
        die Net::WebSocket::X->create('UnfinishedStream', $self);
    }

    return;
}

1;