| 1 | package Net::WebSocket::Streamer; | ||||||||||||||||||||||||||||
| 2 | |||||||||||||||||||||||||||||
| 3 | =encoding utf-8 | ||||||||||||||||||||||||||||
| 4 | |||||||||||||||||||||||||||||
| 5 | =head1 NAME | ||||||||||||||||||||||||||||
| 6 | |||||||||||||||||||||||||||||
| 7 | Net::WebSocket::Streamer - Stream a WebSocket message easily | ||||||||||||||||||||||||||||
| 8 | |||||||||||||||||||||||||||||
| 9 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||
| 10 | |||||||||||||||||||||||||||||
| 11 | Here’s the gist of it: | ||||||||||||||||||||||||||||
| 12 | |||||||||||||||||||||||||||||
| 13 | #Use the ::Client or ::Server subclass as needed. | ||||||||||||||||||||||||||||
| 14 | my $streamer = Net::WebSocket::Streamer::Client->new('binary'); | ||||||||||||||||||||||||||||
| 15 | |||||||||||||||||||||||||||||
| 16 | my $frame = $streamer->create_chunk($buf); | ||||||||||||||||||||||||||||
| 17 | |||||||||||||||||||||||||||||
| 18 | my $last_frame = $streamer->create_final($buf); | ||||||||||||||||||||||||||||
| 19 | |||||||||||||||||||||||||||||
| 20 | … but a more complete example might be this: streaming a file | ||||||||||||||||||||||||||||
| 21 | of arbitrary size in 64-KiB chunks: | ||||||||||||||||||||||||||||
| 22 | |||||||||||||||||||||||||||||
| 23 | my $size = -s $rfh; | ||||||||||||||||||||||||||||
| 24 | |||||||||||||||||||||||||||||
| 25 | while ( read $rfh, my $buf, 65536 ) { | ||||||||||||||||||||||||||||
| 26 | my $frame; | ||||||||||||||||||||||||||||
| 27 | |||||||||||||||||||||||||||||
| 28 | if (tell($rfh) == $size) { | ||||||||||||||||||||||||||||
| 29 | $frame = $streamer->create_final($buf); | ||||||||||||||||||||||||||||
| 30 | } | ||||||||||||||||||||||||||||
| 31 | else { | ||||||||||||||||||||||||||||
| 32 | $frame = $streamer->create_chunk($buf); | ||||||||||||||||||||||||||||
| 33 | } | ||||||||||||||||||||||||||||
| 34 | |||||||||||||||||||||||||||||
| 35 | syswrite $wfh, $frame->to_bytes(); | ||||||||||||||||||||||||||||
| 36 | } | ||||||||||||||||||||||||||||
| 37 | |||||||||||||||||||||||||||||
| 38 | You can, of course, create/send an empty final frame for cases where you’re | ||||||||||||||||||||||||||||
| 39 | not sure how much data will actually be sent. | ||||||||||||||||||||||||||||
| 40 | |||||||||||||||||||||||||||||
| 41 | Note that the receiving application won’t necessarily have access to the | ||||||||||||||||||||||||||||
| 42 | individual message fragments (i.e., frames) that you send. Web browsers, | ||||||||||||||||||||||||||||
| 43 | for example, only expose messages, not frames. You may thus be better off | ||||||||||||||||||||||||||||
| 44 | sending full messages rather than frames. | ||||||||||||||||||||||||||||
| 45 | |||||||||||||||||||||||||||||
| 46 | =head1 EXTENSION SUPPORT | ||||||||||||||||||||||||||||
| 47 | |||||||||||||||||||||||||||||
| 48 | To stream custom frame types (or overridden classes), you can pass in | ||||||||||||||||||||||||||||
| 49 | a full package name to C<new()> rather than merely C<text> or C<binary>. | ||||||||||||||||||||||||||||
| 50 | |||||||||||||||||||||||||||||
| 51 | =cut | ||||||||||||||||||||||||||||
| 52 | |||||||||||||||||||||||||||||
| 53 | 1 | ▶ | use strict; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 54 | 1 | ▶ | use warnings; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 55 | |||||||||||||||||||||||||||||
| 56 | 1 | ▶ | use Module::Runtime (); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 57 | |||||||||||||||||||||||||||||
| 58 | 1 | ▶ | use Net::WebSocket::Frame::continuation (); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 59 | 1 | ▶ | use Net::WebSocket::X (); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 60 | |||||||||||||||||||||||||||||
| 61 | 1 | ▶ | use constant { | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 62 | |||||||||||||||||||||||||||||
| 63 | #The old way of doing this. No longer documented, | ||||||||||||||||||||||||||||
| 64 | #but still supported. | ||||||||||||||||||||||||||||
| 65 | 1 | frame_class_text => 'Net::WebSocket::Frame::text', | |||||||||||||||||||||||||||
| 66 | frame_class_binary => 'Net::WebSocket::Frame::binary', | ||||||||||||||||||||||||||||
| 67 | |||||||||||||||||||||||||||||
| 68 | FINISHED_INDICATOR => __PACKAGE__ . '::__ALREADY_SENT_FINAL', | ||||||||||||||||||||||||||||
| 69 | 1 | }; | |||||||||||||||||||||||||||
| 70 | |||||||||||||||||||||||||||||
| 71 | 18 | ▶ | sub new { | ||||||||||||||||||||||||||
|
Subroutine
new: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 72 | 18 | my ($class, $type) = @_; | |||||||||||||||||||||||||||
| 73 | |||||||||||||||||||||||||||||
| 74 | 18 | my $frame_class = $class->_load_frame_class($type); | |||||||||||||||||||||||||||
| 75 | |||||||||||||||||||||||||||||
| 76 | 18 | return bless { class => $frame_class, pid => $$ }, $class; | |||||||||||||||||||||||||||
| 77 | } | ||||||||||||||||||||||||||||
| 78 | |||||||||||||||||||||||||||||
| 79 | 35 | ▶ | sub create_chunk { | ||||||||||||||||||||||||||
|
Subroutine
create_chunk: called CC=2 SCAR=6.9
Pod
undocumented
| |||||||||||||||||||||||||||||
| 80 | 35 | my $self = shift; | |||||||||||||||||||||||||||
| 81 | |||||||||||||||||||||||||||||
| 82 | 35 | my $frame = $self->{'class'}->new( | |||||||||||||||||||||||||||
| 83 | fin => 0, | ||||||||||||||||||||||||||||
| 84 | $self->FRAME_MASK_ARGS(), | ||||||||||||||||||||||||||||
| 85 | payload => \$_[0], | ||||||||||||||||||||||||||||
| 86 | ); | ||||||||||||||||||||||||||||
| 87 | |||||||||||||||||||||||||||||
| 88 | #The first $frame we create needs to be typed (e.g., text or binary), | ||||||||||||||||||||||||||||
| 89 | #but all subsequent ones must be continuation. | ||||||||||||||||||||||||||||
| 90 | 35 | ▶ | if ($self->{'class'} ne 'Net::WebSocket::Frame::continuation') { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 91 | 18 | $self->{'class'} = 'Net::WebSocket::Frame::continuation'; | |||||||||||||||||||||||||||
| 92 | } | ||||||||||||||||||||||||||||
| 93 | |||||||||||||||||||||||||||||
| 94 | 35 | return $frame; | |||||||||||||||||||||||||||
| 95 | } | ||||||||||||||||||||||||||||
| 96 | |||||||||||||||||||||||||||||
| 97 | 18 | ▶ | sub create_final { | ||||||||||||||||||||||||||
|
Subroutine
create_final: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 98 | 18 | my $self = shift; | |||||||||||||||||||||||||||
| 99 | |||||||||||||||||||||||||||||
| 100 | 18 | my $frame = $self->{'class'}->new( | |||||||||||||||||||||||||||
| 101 | fin => 1, | ||||||||||||||||||||||||||||
| 102 | $self->FRAME_MASK_ARGS(), | ||||||||||||||||||||||||||||
| 103 | payload => \$_[0], | ||||||||||||||||||||||||||||
| 104 | ); | ||||||||||||||||||||||||||||
| 105 | |||||||||||||||||||||||||||||
| 106 | 18 | $self->{'finished'} = 1; | |||||||||||||||||||||||||||
| 107 | |||||||||||||||||||||||||||||
| 108 | 18 | return $frame; | |||||||||||||||||||||||||||
| 109 | } | ||||||||||||||||||||||||||||
| 110 | |||||||||||||||||||||||||||||
| 111 | 18 | ▶ | sub _load_frame_class { | ||||||||||||||||||||||||||
|
Subroutine
_load_frame_class: called CC=3 SCAR=11.4
| |||||||||||||||||||||||||||||
| 112 | 18 | my ($class, $type) = @_; | |||||||||||||||||||||||||||
| 113 | |||||||||||||||||||||||||||||
| 114 | #The old, legacy way of doing this. No longer documented, | ||||||||||||||||||||||||||||
| 115 | #but it shipped in production so we’ll keep supporting it. | ||||||||||||||||||||||||||||
| 116 | 18 | my $frame_class = $class->can("frame_class_$type"); | |||||||||||||||||||||||||||
| 117 | |||||||||||||||||||||||||||||
| 118 | 18 | ▶ | if ($frame_class) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 119 | 18 | $frame_class = $frame_class->(); | |||||||||||||||||||||||||||
| 120 | } | ||||||||||||||||||||||||||||
| 121 | else { | ||||||||||||||||||||||||||||
| 122 | 0 | require Net::WebSocket::FrameTypeName; | |||||||||||||||||||||||||||
| 123 | 0 | $frame_class = Net::WebSocket::FrameTypeName::get_module($type); | |||||||||||||||||||||||||||
| 124 | } | ||||||||||||||||||||||||||||
| 125 | |||||||||||||||||||||||||||||
| 126 | 18 | ▶ | Module::Runtime::require_module($frame_class) if !$frame_class->can('new'); | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 127 | |||||||||||||||||||||||||||||
| 128 | 18 | return $frame_class; | |||||||||||||||||||||||||||
| 129 | } | ||||||||||||||||||||||||||||
| 130 | |||||||||||||||||||||||||||||
| 131 | 18 | ▶ | sub DESTROY { | ||||||||||||||||||||||||||
|
Subroutine
DESTROY: called CC=3 SCAR=13.3
| |||||||||||||||||||||||||||||
| 132 | 18 | my ($self) = @_; | |||||||||||||||||||||||||||
| 133 | |||||||||||||||||||||||||||||
| 134 | 18 | ▶ | if (($self->{'pid'} == $$) && !$self->{'finished'}) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
$self->{"pid"} == $$ and not $self->{"finished"}
MC/DC0%0/2
$self->{"pid"} == $$ and not $self->{"finished"}
$self->{"pid"} == $$
not $self->{"finished"}
Truth table33%1/3
A and not(B)
A= $self->{"pid"} == $$B= not $self->{"finished"}
| |||||||||||||||||||||||||||||
| 135 | 0 | die Net::WebSocket::X->create('UnfinishedStream', $self); | |||||||||||||||||||||||||||
| 136 | } | ||||||||||||||||||||||||||||
| 137 | |||||||||||||||||||||||||||||
| 138 | 18 | return; | |||||||||||||||||||||||||||
| 139 | } | ||||||||||||||||||||||||||||
| 140 | |||||||||||||||||||||||||||||
| 141 | 1 | 1; | |||||||||||||||||||||||||||