| 1 | package App::FileSync::Protocol; | ||||||||||||||||||||||||||||
| 2 | |||||||||||||||||||||||||||||
| 3 | # One connection, strictly one request in flight at a time. Control messages | ||||||||||||||||||||||||||||
| 4 | # are JSON on one line; binary payloads are announced by "len" in a header and | ||||||||||||||||||||||||||||
| 5 | # follow it immediately. | ||||||||||||||||||||||||||||
| 6 | |||||||||||||||||||||||||||||
| 7 | 326 | ▶ | use App::FileSync::Platform; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 8 | |||||||||||||||||||||||||||||
| 9 | 326 | ▶ | use strict; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 10 | 326 | ▶ | use warnings; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 11 | # Not autodie qw(:all): this class has methods named send, recv and close, and | ||||||||||||||||||||||||||||
| 12 | # autodie installs wrappers under those names in the package, then deletes | ||||||||||||||||||||||||||||
| 13 | # them (taking the methods with them) when the file scope ends. Only the | ||||||||||||||||||||||||||||
| 14 | # builtins this file calls are covered. | ||||||||||||||||||||||||||||
| 15 | 326 | ▶ | use autodie qw(binmode sysread); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 16 | |||||||||||||||||||||||||||||
| 17 | 326 | ▶ | use Compress::Raw::Zlib (); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 18 | 326 | ▶ | use IO::Handle (); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 19 | 326 | ▶ | use Readonly; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 20 | 326 | ▶ | use Sub::Private { mode => 'enforce' }; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 21 | |||||||||||||||||||||||||||||
| 22 | 326 | ▶ | use parent -norequire, 'App::FileSync::Base'; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 23 | 326 | ▶ | use App::FileSync::Base; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 24 | |||||||||||||||||||||||||||||
| 25 | 326 | ▶ | use App::FileSync qw(json_encode json_decode); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 26 | 326 | ▶ | use App::FileSync::Args qw(named); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 27 | 326 | ▶ | use App::FileSync::I18N qw(os_error strip_location); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 28 | |||||||||||||||||||||||||||||
| 29 | 326 | ▶ | use version; our $VERSION = version->declare('0.002.1'); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 30 | |||||||||||||||||||||||||||||
| 31 | # Payloads are raw-deflated when that makes them smaller. Small payloads and | ||||||||||||||||||||||||||||
| 32 | # already-compressed data are left alone, so the flag costs more than it saves. | ||||||||||||||||||||||||||||
| 33 | 326 | our $COMPRESS_MIN = 256; | |||||||||||||||||||||||||||
| 34 | 326 | our $MAX_WIRE = 64 * 1024 * 1024; | |||||||||||||||||||||||||||
| 35 | 326 | our $MAX_INFLATED = 64 * 1024 * 1024; | |||||||||||||||||||||||||||
| 36 | |||||||||||||||||||||||||||||
| 37 | # zlib level: the default trade-off between speed and size. | ||||||||||||||||||||||||||||
| 38 | 326 | Readonly::Scalar my $DEFLATE_LEVEL => 6; | |||||||||||||||||||||||||||
| 39 | |||||||||||||||||||||||||||||
| 40 | # Bytes asked of the pipe per sysread. | ||||||||||||||||||||||||||||
| 41 | 326 | Readonly::Scalar my $READ_SIZE => 65_536; | |||||||||||||||||||||||||||
| 42 | |||||||||||||||||||||||||||||
| 43 | =encoding utf8 | ||||||||||||||||||||||||||||
| 44 | |||||||||||||||||||||||||||||
| 45 | =head1 NAME | ||||||||||||||||||||||||||||
| 46 | |||||||||||||||||||||||||||||
| 47 | App::FileSync::Protocol - the line-delimited JSON wire protocol | ||||||||||||||||||||||||||||
| 48 | |||||||||||||||||||||||||||||
| 49 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||
| 50 | |||||||||||||||||||||||||||||
| 51 | my $connection = App::FileSync::Protocol->new(in => $reader, out => $writer); | ||||||||||||||||||||||||||||
| 52 | $connection->send({ cmd => 'hello', proto => 2 }); | ||||||||||||||||||||||||||||
| 53 | my $reply = $connection->recv(); | ||||||||||||||||||||||||||||
| 54 | $connection->send_data({ cmd => 'chunk', p => $path }, $bytes); | ||||||||||||||||||||||||||||
| 55 | |||||||||||||||||||||||||||||
| 56 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||
| 57 | |||||||||||||||||||||||||||||
| 58 | Each control message is one JSON object on one line. A message announcing a | ||||||||||||||||||||||||||||
| 59 | payload carries C<len> (the bytes on the wire) and, when the payload was | ||||||||||||||||||||||||||||
| 60 | deflated, C<z>; the payload follows the line directly. The connection counts | ||||||||||||||||||||||||||||
| 61 | payload bytes in each direction for the transfer report. | ||||||||||||||||||||||||||||
| 62 | |||||||||||||||||||||||||||||
| 63 | When reading or writing fails because the pipe itself failed (the peer exited, | ||||||||||||||||||||||||||||
| 64 | ssh was refused), L</transport_failed> becomes true, so a caller can show the | ||||||||||||||||||||||||||||
| 65 | transport's own diagnostics instead of a protocol error. | ||||||||||||||||||||||||||||
| 66 | |||||||||||||||||||||||||||||
| 67 | =head1 METHODS | ||||||||||||||||||||||||||||
| 68 | |||||||||||||||||||||||||||||
| 69 | =head2 new | ||||||||||||||||||||||||||||
| 70 | |||||||||||||||||||||||||||||
| 71 | Purpose: wrap a pair of handles as a protocol connection. | ||||||||||||||||||||||||||||
| 72 | |||||||||||||||||||||||||||||
| 73 | Args: C<in> and C<out> (handles), optional C<language>. | ||||||||||||||||||||||||||||
| 74 | |||||||||||||||||||||||||||||
| 75 | Returns: the connection. | ||||||||||||||||||||||||||||
| 76 | |||||||||||||||||||||||||||||
| 77 | Side Effects: puts both handles in binary mode and makes C<out> autoflush. | ||||||||||||||||||||||||||||
| 78 | |||||||||||||||||||||||||||||
| 79 | Usage: | ||||||||||||||||||||||||||||
| 80 | |||||||||||||||||||||||||||||
| 81 | my $connection = App::FileSync::Protocol->new(in => \*STDIN, out => \*STDOUT); | ||||||||||||||||||||||||||||
| 82 | |||||||||||||||||||||||||||||
| 83 | =head3 EXAMPLE | ||||||||||||||||||||||||||||
| 84 | |||||||||||||||||||||||||||||
| 85 | my $connection = App::FileSync::Protocol->new(in => $transport->reader, out => $transport->writer); | ||||||||||||||||||||||||||||
| 86 | |||||||||||||||||||||||||||||
| 87 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 88 | |||||||||||||||||||||||||||||
| 89 | =head4 INPUT | ||||||||||||||||||||||||||||
| 90 | |||||||||||||||||||||||||||||
| 91 | { | ||||||||||||||||||||||||||||
| 92 | in => { type => 'handle' }, | ||||||||||||||||||||||||||||
| 93 | out => { type => 'handle' }, | ||||||||||||||||||||||||||||
| 94 | language => { type => 'string', optional => 1 }, | ||||||||||||||||||||||||||||
| 95 | } | ||||||||||||||||||||||||||||
| 96 | |||||||||||||||||||||||||||||
| 97 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 98 | |||||||||||||||||||||||||||||
| 99 | { type => 'object', isa => 'App::FileSync::Protocol' } | ||||||||||||||||||||||||||||
| 100 | |||||||||||||||||||||||||||||
| 101 | =head3 MESSAGES | ||||||||||||||||||||||||||||
| 102 | |||||||||||||||||||||||||||||
| 103 | Key Meaning Resolution | ||||||||||||||||||||||||||||
| 104 | args.invalid a handle is missing pass in and out | ||||||||||||||||||||||||||||
| 105 | |||||||||||||||||||||||||||||
| 106 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||
| 107 | |||||||||||||||||||||||||||||
| 108 | new(in, out) = ⟨in, out, buffer ↦ ⟨⟩, closed ↦ false, sent ↦ 0, received ↦ 0⟩ | ||||||||||||||||||||||||||||
| 109 | |||||||||||||||||||||||||||||
| 110 | =cut | ||||||||||||||||||||||||||||
| 111 | |||||||||||||||||||||||||||||
| 112 | 361 | ▶ | sub new { | ||||||||||||||||||||||||||
|
Subroutine
new: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||
| 113 | 361 | my $class = shift; | |||||||||||||||||||||||||||
| 114 | 361 | my $args = named(\@_, { | |||||||||||||||||||||||||||
| 115 | in => { type => 'handle' }, | ||||||||||||||||||||||||||||
| 116 | out => { type => 'handle' }, | ||||||||||||||||||||||||||||
| 117 | language => { type => 'string', optional => 1 }, | ||||||||||||||||||||||||||||
| 118 | }, 'Protocol->new'); | ||||||||||||||||||||||||||||
| 119 | |||||||||||||||||||||||||||||
| 120 | 361 | binmode $args->{in}; | |||||||||||||||||||||||||||
| 121 | 361 | binmode $args->{out}; | |||||||||||||||||||||||||||
| 122 | 361 | $args->{out}->autoflush(1); | |||||||||||||||||||||||||||
| 123 | |||||||||||||||||||||||||||||
| 124 | return bless { | ||||||||||||||||||||||||||||
| 125 | in => $args->{in}, | ||||||||||||||||||||||||||||
| 126 | out => $args->{out}, | ||||||||||||||||||||||||||||
| 127 | language => $args->{language}, | ||||||||||||||||||||||||||||
| 128 | 361 | buffer => '', | |||||||||||||||||||||||||||
| 129 | closed => 0, | ||||||||||||||||||||||||||||
| 130 | transport_failed => 0, | ||||||||||||||||||||||||||||
| 131 | # Payload bytes as they crossed the wire, headers and control | ||||||||||||||||||||||||||||
| 132 | # messages excluded: this is the number a transfer report means. | ||||||||||||||||||||||||||||
| 133 | sent_bytes => 0, | ||||||||||||||||||||||||||||
| 134 | received_bytes => 0, | ||||||||||||||||||||||||||||
| 135 | }, $class; | ||||||||||||||||||||||||||||
| 136 | } | ||||||||||||||||||||||||||||
| 137 | |||||||||||||||||||||||||||||
| 138 | =head2 send | ||||||||||||||||||||||||||||
| 139 | |||||||||||||||||||||||||||||
| 140 | Purpose: send one control message. | ||||||||||||||||||||||||||||
| 141 | |||||||||||||||||||||||||||||
| 142 | Args: C<\%message>. | ||||||||||||||||||||||||||||
| 143 | |||||||||||||||||||||||||||||
| 144 | Returns: 1. | ||||||||||||||||||||||||||||
| 145 | |||||||||||||||||||||||||||||
| 146 | Side Effects: writes one line. | ||||||||||||||||||||||||||||
| 147 | |||||||||||||||||||||||||||||
| 148 | Usage: | ||||||||||||||||||||||||||||
| 149 | |||||||||||||||||||||||||||||
| 150 | $connection->send({ cmd => 'plan' }); | ||||||||||||||||||||||||||||
| 151 | |||||||||||||||||||||||||||||
| 152 | =head3 EXAMPLE | ||||||||||||||||||||||||||||
| 153 | |||||||||||||||||||||||||||||
| 154 | $connection->send({ ok => 1, off => $offset }); | ||||||||||||||||||||||||||||
| 155 | |||||||||||||||||||||||||||||
| 156 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 157 | |||||||||||||||||||||||||||||
| 158 | =head4 INPUT | ||||||||||||||||||||||||||||
| 159 | |||||||||||||||||||||||||||||
| 160 | [ | ||||||||||||||||||||||||||||
| 161 | { name => 'self', type => 'object' }, | ||||||||||||||||||||||||||||
| 162 | { name => 'message', type => 'hashref' }, | ||||||||||||||||||||||||||||
| 163 | ] | ||||||||||||||||||||||||||||
| 164 | |||||||||||||||||||||||||||||
| 165 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 166 | |||||||||||||||||||||||||||||
| 167 | { type => 'integer', min => 1, max => 1 } | ||||||||||||||||||||||||||||
| 168 | |||||||||||||||||||||||||||||
| 169 | =head3 MESSAGES | ||||||||||||||||||||||||||||
| 170 | |||||||||||||||||||||||||||||
| 171 | Key Meaning Resolution | ||||||||||||||||||||||||||||
| 172 | protocol.closed the connection was closed a caller bug | ||||||||||||||||||||||||||||
| 173 | protocol.write_failed the pipe would not take it see the transport's stderr | ||||||||||||||||||||||||||||
| 174 | |||||||||||||||||||||||||||||
| 175 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||
| 176 | |||||||||||||||||||||||||||||
| 177 | pre ¬closed | ||||||||||||||||||||||||||||
| 178 | out' = out ⁀ json(message) ⁀ "\n" | ||||||||||||||||||||||||||||
| 179 | |||||||||||||||||||||||||||||
| 180 | =cut | ||||||||||||||||||||||||||||
| 181 | |||||||||||||||||||||||||||||
| 182 | 3057 | ▶ | sub send { ## no critic (Subroutines::ProhibitBuiltinHomonyms) | ||||||||||||||||||||||||||
|
Subroutine
send: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||
| 183 | 3057 | my ($self, $message) = @_; | |||||||||||||||||||||||||||
| 184 | |||||||||||||||||||||||||||||
| 185 | 3057 | $self->_write(json_encode($message) . "\n"); | |||||||||||||||||||||||||||
| 186 | 3053 | return 1; | |||||||||||||||||||||||||||
| 187 | } | ||||||||||||||||||||||||||||
| 188 | |||||||||||||||||||||||||||||
| 189 | =head2 recv | ||||||||||||||||||||||||||||
| 190 | |||||||||||||||||||||||||||||
| 191 | Purpose: read one control message. | ||||||||||||||||||||||||||||
| 192 | |||||||||||||||||||||||||||||
| 193 | Args: none. | ||||||||||||||||||||||||||||
| 194 | |||||||||||||||||||||||||||||
| 195 | Returns: the decoded message hashref. | ||||||||||||||||||||||||||||
| 196 | |||||||||||||||||||||||||||||
| 197 | Side Effects: reads from C<in>; blocks until a whole line arrives. | ||||||||||||||||||||||||||||
| 198 | |||||||||||||||||||||||||||||
| 199 | Usage: | ||||||||||||||||||||||||||||
| 200 | |||||||||||||||||||||||||||||
| 201 | my $reply = $connection->recv(); | ||||||||||||||||||||||||||||
| 202 | |||||||||||||||||||||||||||||
| 203 | =head3 EXAMPLE | ||||||||||||||||||||||||||||
| 204 | |||||||||||||||||||||||||||||
| 205 | my $hello = $connection->recv(); | ||||||||||||||||||||||||||||
| 206 | die unless $hello->{ok}; | ||||||||||||||||||||||||||||
| 207 | |||||||||||||||||||||||||||||
| 208 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 209 | |||||||||||||||||||||||||||||
| 210 | =head4 INPUT | ||||||||||||||||||||||||||||
| 211 | |||||||||||||||||||||||||||||
| 212 | [ { name => 'self', type => 'object' } ] | ||||||||||||||||||||||||||||
| 213 | |||||||||||||||||||||||||||||
| 214 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 215 | |||||||||||||||||||||||||||||
| 216 | { type => 'hashref' } | ||||||||||||||||||||||||||||
| 217 | |||||||||||||||||||||||||||||
| 218 | =head3 MESSAGES | ||||||||||||||||||||||||||||
| 219 | |||||||||||||||||||||||||||||
| 220 | Key Meaning Resolution | ||||||||||||||||||||||||||||
| 221 | protocol.malformed the line is not JSON version mismatch or corrupt stream | ||||||||||||||||||||||||||||
| 222 | protocol.not_object the JSON is not an object version mismatch | ||||||||||||||||||||||||||||
| 223 | protocol.eof the peer closed the connection see the peer's log | ||||||||||||||||||||||||||||
| 224 | protocol.read_failed the pipe failed see the transport's stderr | ||||||||||||||||||||||||||||
| 225 | |||||||||||||||||||||||||||||
| 226 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||
| 227 | |||||||||||||||||||||||||||||
| 228 | in = line ⁀ "\n" ⁀ rest ⇒ recv = json⁻¹(line) ∧ in' = rest | ||||||||||||||||||||||||||||
| 229 | pre json⁻¹(line) ∈ OBJECT | ||||||||||||||||||||||||||||
| 230 | |||||||||||||||||||||||||||||
| 231 | =cut | ||||||||||||||||||||||||||||
| 232 | |||||||||||||||||||||||||||||
| 233 | 3057 | ▶ | sub recv { ## no critic (Subroutines::ProhibitBuiltinHomonyms) | ||||||||||||||||||||||||||
|
Subroutine
recv: called CC=3 SCAR=11.2
Pod
documented
| |||||||||||||||||||||||||||||
| 234 | 3057 | my ($self) = @_; | |||||||||||||||||||||||||||
| 235 | |||||||||||||||||||||||||||||
| 236 | 3057 | my $line = $self->read_line(); | |||||||||||||||||||||||||||
| 237 | 3051 | my $message = eval { json_decode($line) }; | |||||||||||||||||||||||||||
| 238 | 3051 | ▶ | $self->_throw('protocol.malformed', { error => strip_location($@) }) if $@; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 239 | 3051 | ▶ | $self->_throw('protocol.not_object') unless ref($message) eq 'HASH'; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 240 | |||||||||||||||||||||||||||||
| 241 | 3051 | return $message; | |||||||||||||||||||||||||||
| 242 | } | ||||||||||||||||||||||||||||
| 243 | |||||||||||||||||||||||||||||
| 244 | =head2 send_bytes | ||||||||||||||||||||||||||||
| 245 | |||||||||||||||||||||||||||||
| 246 | Purpose: write raw bytes (the payload after a header). | ||||||||||||||||||||||||||||
| 247 | |||||||||||||||||||||||||||||
| 248 | Args: C<$bytes>; empty or undef writes nothing. | ||||||||||||||||||||||||||||
| 249 | |||||||||||||||||||||||||||||
| 250 | Returns: 1. | ||||||||||||||||||||||||||||
| 251 | |||||||||||||||||||||||||||||
| 252 | Side Effects: writes to C<out>. Not counted in L</bytes_sent>; use | ||||||||||||||||||||||||||||
| 253 | L</send_data> for counted payloads. | ||||||||||||||||||||||||||||
| 254 | |||||||||||||||||||||||||||||
| 255 | Usage: | ||||||||||||||||||||||||||||
| 256 | |||||||||||||||||||||||||||||
| 257 | $connection->send_bytes($payload); | ||||||||||||||||||||||||||||
| 258 | |||||||||||||||||||||||||||||
| 259 | =head3 EXAMPLE | ||||||||||||||||||||||||||||
| 260 | |||||||||||||||||||||||||||||
| 261 | $connection->send({ len => length $bytes }); | ||||||||||||||||||||||||||||
| 262 | $connection->send_bytes($bytes); | ||||||||||||||||||||||||||||
| 263 | |||||||||||||||||||||||||||||
| 264 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 265 | |||||||||||||||||||||||||||||
| 266 | =head4 INPUT | ||||||||||||||||||||||||||||
| 267 | |||||||||||||||||||||||||||||
| 268 | [ | ||||||||||||||||||||||||||||
| 269 | { name => 'self', type => 'object' }, | ||||||||||||||||||||||||||||
| 270 | { name => 'bytes', type => 'string', optional => 1 }, | ||||||||||||||||||||||||||||
| 271 | ] | ||||||||||||||||||||||||||||
| 272 | |||||||||||||||||||||||||||||
| 273 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 274 | |||||||||||||||||||||||||||||
| 275 | { type => 'integer', min => 1, max => 1 } | ||||||||||||||||||||||||||||
| 276 | |||||||||||||||||||||||||||||
| 277 | =head3 MESSAGES | ||||||||||||||||||||||||||||
| 278 | |||||||||||||||||||||||||||||
| 279 | Key Meaning Resolution | ||||||||||||||||||||||||||||
| 280 | protocol.closed the connection was closed a caller bug | ||||||||||||||||||||||||||||
| 281 | protocol.write_failed the pipe would not take it see the transport's stderr | ||||||||||||||||||||||||||||
| 282 | |||||||||||||||||||||||||||||
| 283 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||
| 284 | |||||||||||||||||||||||||||||
| 285 | out' = out ⁀ bytes | ||||||||||||||||||||||||||||
| 286 | |||||||||||||||||||||||||||||
| 287 | =cut | ||||||||||||||||||||||||||||
| 288 | |||||||||||||||||||||||||||||
| 289 | 282 | ▶ | sub send_bytes { | ||||||||||||||||||||||||||
|
Subroutine
send_bytes: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||||||||||||||||||||
| 290 | 282 | my ($self, $bytes) = @_; | |||||||||||||||||||||||||||
| 291 | |||||||||||||||||||||||||||||
| 292 | 282 | ▶ | $self->_write($bytes) if defined $bytes && length $bytes; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
defined $bytes and length $bytes
MC/DC50%1/2
defined $bytes and length $bytes
defined $bytes
length $bytes
Truth table66%2/3
A and B
A= defined $bytesB= length $bytes
| |||||||||||||||||||||||||||||
| 293 | 282 | return 1; | |||||||||||||||||||||||||||
| 294 | } | ||||||||||||||||||||||||||||
| 295 | |||||||||||||||||||||||||||||
| 296 | =head2 send_data | ||||||||||||||||||||||||||||
| 297 | |||||||||||||||||||||||||||||
| 298 | Purpose: send a header and its payload, compressing when worthwhile. | ||||||||||||||||||||||||||||
| 299 | |||||||||||||||||||||||||||||
| 300 | Args: C<\%header>, C<$bytes>. | ||||||||||||||||||||||||||||
| 301 | |||||||||||||||||||||||||||||
| 302 | Returns: 1. | ||||||||||||||||||||||||||||
| 303 | |||||||||||||||||||||||||||||
| 304 | Side Effects: writes the header (with C<len> and, if compressed, C<z>) and the | ||||||||||||||||||||||||||||
| 305 | payload; adds the wire length to L</bytes_sent>. | ||||||||||||||||||||||||||||
| 306 | |||||||||||||||||||||||||||||
| 307 | Usage: | ||||||||||||||||||||||||||||
| 308 | |||||||||||||||||||||||||||||
| 309 | $connection->send_data({ cmd => 'chunk', p => $path }, $bytes); | ||||||||||||||||||||||||||||
| 310 | |||||||||||||||||||||||||||||
| 311 | =head3 EXAMPLE | ||||||||||||||||||||||||||||
| 312 | |||||||||||||||||||||||||||||
| 313 | $connection->send_data({ ok => 1, eof => 1 }, $last_chunk); | ||||||||||||||||||||||||||||
| 314 | |||||||||||||||||||||||||||||
| 315 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 316 | |||||||||||||||||||||||||||||
| 317 | =head4 INPUT | ||||||||||||||||||||||||||||
| 318 | |||||||||||||||||||||||||||||
| 319 | [ | ||||||||||||||||||||||||||||
| 320 | { name => 'self', type => 'object' }, | ||||||||||||||||||||||||||||
| 321 | { name => 'message', type => 'hashref', optional => 1 }, | ||||||||||||||||||||||||||||
| 322 | { name => 'bytes', type => 'string', optional => 1 }, | ||||||||||||||||||||||||||||
| 323 | ] | ||||||||||||||||||||||||||||
| 324 | |||||||||||||||||||||||||||||
| 325 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 326 | |||||||||||||||||||||||||||||
| 327 | { type => 'integer', min => 1, max => 1 } | ||||||||||||||||||||||||||||
| 328 | |||||||||||||||||||||||||||||
| 329 | =head3 MESSAGES | ||||||||||||||||||||||||||||
| 330 | |||||||||||||||||||||||||||||
| 331 | As for L</send>. | ||||||||||||||||||||||||||||
| 332 | |||||||||||||||||||||||||||||
| 333 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||
| 334 | |||||||||||||||||||||||||||||
| 335 | let (w, z) = deflate(bytes) | ||||||||||||||||||||||||||||
| 336 | out' = out ⁀ json(header ⊕ {len ↦ #w} ⊕ (z ⇒ {z ↦ 1})) ⁀ "\n" ⁀ w | ||||||||||||||||||||||||||||
| 337 | sent' = sent + #w | ||||||||||||||||||||||||||||
| 338 | |||||||||||||||||||||||||||||
| 339 | =cut | ||||||||||||||||||||||||||||
| 340 | |||||||||||||||||||||||||||||
| 341 | 282 | ▶ | sub send_data { | ||||||||||||||||||||||||||
|
Subroutine
send_data: called CC=4 SCAR=13.9
Pod
documented
| |||||||||||||||||||||||||||||
| 342 | 282 | my ($self, $message, $bytes) = @_; | |||||||||||||||||||||||||||
| 343 | |||||||||||||||||||||||||||||
| 344 | 282 | ▶ | my ($wire, $compressed) = @{ _deflate(defined $bytes ? $bytes : '') }; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 345 | |||||||||||||||||||||||||||||
| 346 | # The header carries the wire length and a "z" flag, so a peer that does | ||||||||||||||||||||||||||||
| 347 | # not know the flag rejects the frame rather than misreading it. | ||||||||||||||||||||||||||||
| 348 | 282 | ▶ | my %header = %{ $message || {} }; | ||||||||||||||||||||||||||
|
Condition50%1/2
$message || {}
MC/DC0%0/1
$message || {}
$message
Truth table50%1/2
A
A= $message
| |||||||||||||||||||||||||||||
| 349 | 282 | $header{len} = length $wire; | |||||||||||||||||||||||||||
| 350 | 282 | ▶ | $header{z} = 1 if $compressed; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 351 | |||||||||||||||||||||||||||||
| 352 | 282 | $self->send(\%header); | |||||||||||||||||||||||||||
| 353 | 282 | $self->send_bytes($wire); | |||||||||||||||||||||||||||
| 354 | 282 | $self->{sent_bytes} += length $wire; | |||||||||||||||||||||||||||
| 355 | |||||||||||||||||||||||||||||
| 356 | 282 | return 1; | |||||||||||||||||||||||||||
| 357 | } | ||||||||||||||||||||||||||||
| 358 | |||||||||||||||||||||||||||||
| 359 | =head2 read_data | ||||||||||||||||||||||||||||
| 360 | |||||||||||||||||||||||||||||
| 361 | Purpose: read the payload a header announced. | ||||||||||||||||||||||||||||
| 362 | |||||||||||||||||||||||||||||
| 363 | Args: C<\%header> as returned by L</recv>. | ||||||||||||||||||||||||||||
| 364 | |||||||||||||||||||||||||||||
| 365 | Returns: the payload, decompressed if it was sent compressed. | ||||||||||||||||||||||||||||
| 366 | |||||||||||||||||||||||||||||
| 367 | Side Effects: reads C<len> bytes; adds them to L</bytes_received>. | ||||||||||||||||||||||||||||
| 368 | |||||||||||||||||||||||||||||
| 369 | Usage: | ||||||||||||||||||||||||||||
| 370 | |||||||||||||||||||||||||||||
| 371 | my $bytes = $connection->read_data($header); | ||||||||||||||||||||||||||||
| 372 | |||||||||||||||||||||||||||||
| 373 | =head3 EXAMPLE | ||||||||||||||||||||||||||||
| 374 | |||||||||||||||||||||||||||||
| 375 | my $reply = $connection->recv(); | ||||||||||||||||||||||||||||
| 376 | my $bytes = $connection->read_data($reply); | ||||||||||||||||||||||||||||
| 377 | |||||||||||||||||||||||||||||
| 378 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 379 | |||||||||||||||||||||||||||||
| 380 | =head4 INPUT | ||||||||||||||||||||||||||||
| 381 | |||||||||||||||||||||||||||||
| 382 | [ | ||||||||||||||||||||||||||||
| 383 | { name => 'self', type => 'object' }, | ||||||||||||||||||||||||||||
| 384 | { name => 'message', type => 'hashref' }, | ||||||||||||||||||||||||||||
| 385 | ] | ||||||||||||||||||||||||||||
| 386 | |||||||||||||||||||||||||||||
| 387 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 388 | |||||||||||||||||||||||||||||
| 389 | { type => 'string' } | ||||||||||||||||||||||||||||
| 390 | |||||||||||||||||||||||||||||
| 391 | =head3 MESSAGES | ||||||||||||||||||||||||||||
| 392 | |||||||||||||||||||||||||||||
| 393 | Key Meaning Resolution | ||||||||||||||||||||||||||||
| 394 | protocol.bad_length len is not a number or exceeds 64 MiB a peer bug | ||||||||||||||||||||||||||||
| 395 | protocol.inflate the payload cannot be decompressed a corrupt stream | ||||||||||||||||||||||||||||
| 396 | protocol.corrupt the compressed payload is corrupt a corrupt stream | ||||||||||||||||||||||||||||
| 397 | protocol.too_large it would inflate beyond 64 MiB a hostile or buggy peer | ||||||||||||||||||||||||||||
| 398 | |||||||||||||||||||||||||||||
| 399 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||
| 400 | |||||||||||||||||||||||||||||
| 401 | pre header.len ∈ 0 .. MAX_WIRE | ||||||||||||||||||||||||||||
| 402 | read_data(h) = inflate(take(h.len, in)) if h.z | ||||||||||||||||||||||||||||
| 403 | = take(h.len, in) otherwise | ||||||||||||||||||||||||||||
| 404 | received' = received + h.len | ||||||||||||||||||||||||||||
| 405 | |||||||||||||||||||||||||||||
| 406 | =cut | ||||||||||||||||||||||||||||
| 407 | |||||||||||||||||||||||||||||
| 408 | 282 | ▶ | sub read_data { | ||||||||||||||||||||||||||
|
Subroutine
read_data: called CC=6 SCAR=18.7
Pod
documented
| |||||||||||||||||||||||||||||
| 409 | 282 | my ($self, $message) = @_; | |||||||||||||||||||||||||||
| 410 | |||||||||||||||||||||||||||||
| 411 | 282 | ▶ | my $length = defined $message->{len} ? $message->{len} : 0; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 412 | 282 | ▶ | $self->_throw('protocol.bad_length') | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
$length =~ /\A\d+\z/ and $length <= $App::FileSync::Protocol::MAX_WIRE
MC/DC0%0/2
$length =~ /\A\d+\z/ and $length <= $App::FileSync::Protocol::MAX_WIRE
$length =~ /\A\d+\z/
$length <= $App::FileSync::Protocol::MAX_WIRE
Truth table33%1/3
A and B
A= $length =~ /\A\d+\z/B= $length <= $App::FileSync::Protocol::MAX_WIRE
| |||||||||||||||||||||||||||||
| 413 | unless $length =~ /\A\d+\z/ && $length <= $MAX_WIRE; | ||||||||||||||||||||||||||||
| 414 | |||||||||||||||||||||||||||||
| 415 | 282 | ▶ | my $wire = $length ? $self->read_bytes($length) : ''; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 416 | 282 | $self->{received_bytes} += length $wire; | |||||||||||||||||||||||||||
| 417 | |||||||||||||||||||||||||||||
| 418 | 282 | ▶ | return $message->{z} ? $self->_inflate($wire) : $wire; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 419 | } | ||||||||||||||||||||||||||||
| 420 | |||||||||||||||||||||||||||||
| 421 | =head2 read_line | ||||||||||||||||||||||||||||
| 422 | |||||||||||||||||||||||||||||
| 423 | Documented with L</read_bytes> below. | ||||||||||||||||||||||||||||
| 424 | |||||||||||||||||||||||||||||
| 425 | =head2 read_bytes | ||||||||||||||||||||||||||||
| 426 | |||||||||||||||||||||||||||||
| 427 | Purpose: read up to the next newline, or exactly C<$length> bytes. | ||||||||||||||||||||||||||||
| 428 | |||||||||||||||||||||||||||||
| 429 | Args: C<read_bytes($length)>. | ||||||||||||||||||||||||||||
| 430 | |||||||||||||||||||||||||||||
| 431 | Returns: the line (without its newline) or the bytes. | ||||||||||||||||||||||||||||
| 432 | |||||||||||||||||||||||||||||
| 433 | Side Effects: consumes them from the buffer, reading from C<in> as needed. | ||||||||||||||||||||||||||||
| 434 | |||||||||||||||||||||||||||||
| 435 | Usage: | ||||||||||||||||||||||||||||
| 436 | |||||||||||||||||||||||||||||
| 437 | my $line = $connection->read_line(); | ||||||||||||||||||||||||||||
| 438 | my $bytes = $connection->read_bytes(1024); | ||||||||||||||||||||||||||||
| 439 | |||||||||||||||||||||||||||||
| 440 | =head3 EXAMPLE | ||||||||||||||||||||||||||||
| 441 | |||||||||||||||||||||||||||||
| 442 | my $payload = $connection->read_bytes($header->{len}); | ||||||||||||||||||||||||||||
| 443 | |||||||||||||||||||||||||||||
| 444 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 445 | |||||||||||||||||||||||||||||
| 446 | =head4 INPUT | ||||||||||||||||||||||||||||
| 447 | |||||||||||||||||||||||||||||
| 448 | [ | ||||||||||||||||||||||||||||
| 449 | { name => 'self', type => 'object' }, | ||||||||||||||||||||||||||||
| 450 | { name => 'length', type => 'integer', min => 0 }, | ||||||||||||||||||||||||||||
| 451 | ] | ||||||||||||||||||||||||||||
| 452 | |||||||||||||||||||||||||||||
| 453 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 454 | |||||||||||||||||||||||||||||
| 455 | { type => 'string' } | ||||||||||||||||||||||||||||
| 456 | |||||||||||||||||||||||||||||
| 457 | =head3 MESSAGES | ||||||||||||||||||||||||||||
| 458 | |||||||||||||||||||||||||||||
| 459 | Key Meaning Resolution | ||||||||||||||||||||||||||||
| 460 | protocol.negative a negative length was asked for a caller bug | ||||||||||||||||||||||||||||
| 461 | protocol.eof the peer closed the connection see the peer's log | ||||||||||||||||||||||||||||
| 462 | protocol.read_failed the pipe failed see the transport's stderr | ||||||||||||||||||||||||||||
| 463 | |||||||||||||||||||||||||||||
| 464 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||
| 465 | |||||||||||||||||||||||||||||
| 466 | read_line: in = l ⁀ "\n" ⁀ r ∧ "\n" ∉ ran l ⇒ result = l ∧ in' = r | ||||||||||||||||||||||||||||
| 467 | read_bytes(n): in = b ⁀ r ∧ #b = n ⇒ result = b ∧ in' = r | ||||||||||||||||||||||||||||
| 468 | |||||||||||||||||||||||||||||
| 469 | =cut | ||||||||||||||||||||||||||||
| 470 | |||||||||||||||||||||||||||||
| 471 | 3057 | ▶ | sub read_line { | ||||||||||||||||||||||||||
|
Subroutine
read_line: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||
| 472 | 3057 | my ($self) = @_; | |||||||||||||||||||||||||||
| 473 | |||||||||||||||||||||||||||||
| 474 | 3057 | my $position; | |||||||||||||||||||||||||||
| 475 | 3057 | ▶ | $self->_fill() while ($position = index($self->{buffer}, "\n")) < 0; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 476 | |||||||||||||||||||||||||||||
| 477 | 3051 | my $line = substr($self->{buffer}, 0, $position); | |||||||||||||||||||||||||||
| 478 | 3051 | substr($self->{buffer}, 0, $position + 1, ''); | |||||||||||||||||||||||||||
| 479 | |||||||||||||||||||||||||||||
| 480 | 3051 | return $line; | |||||||||||||||||||||||||||
| 481 | } | ||||||||||||||||||||||||||||
| 482 | |||||||||||||||||||||||||||||
| 483 | 281 | ▶ | sub read_bytes { | ||||||||||||||||||||||||||
|
Subroutine
read_bytes: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||||||||||||||||||||
| 484 | 281 | my ($self, $length) = @_; | |||||||||||||||||||||||||||
| 485 | |||||||||||||||||||||||||||||
| 486 | 281 | ▶ | $self->_throw('protocol.negative') if $length < 0; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 487 | 281 | ▶ | $self->_fill() while length($self->{buffer}) < $length; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 488 | |||||||||||||||||||||||||||||
| 489 | 281 | return substr($self->{buffer}, 0, $length, ''); | |||||||||||||||||||||||||||
| 490 | } | ||||||||||||||||||||||||||||
| 491 | |||||||||||||||||||||||||||||
| 492 | =head2 bytes_sent | ||||||||||||||||||||||||||||
| 493 | |||||||||||||||||||||||||||||
| 494 | Documented with L</bytes_received> below. | ||||||||||||||||||||||||||||
| 495 | |||||||||||||||||||||||||||||
| 496 | =head2 bytes_received | ||||||||||||||||||||||||||||
| 497 | |||||||||||||||||||||||||||||
| 498 | Purpose: payload bytes that crossed the wire in each direction. | ||||||||||||||||||||||||||||
| 499 | |||||||||||||||||||||||||||||
| 500 | Args: none. | ||||||||||||||||||||||||||||
| 501 | |||||||||||||||||||||||||||||
| 502 | Returns: a byte count (headers and control messages excluded). | ||||||||||||||||||||||||||||
| 503 | |||||||||||||||||||||||||||||
| 504 | Side Effects: none. | ||||||||||||||||||||||||||||
| 505 | |||||||||||||||||||||||||||||
| 506 | Usage: | ||||||||||||||||||||||||||||
| 507 | |||||||||||||||||||||||||||||
| 508 | printf "sent %d bytes\n", $connection->bytes_sent; | ||||||||||||||||||||||||||||
| 509 | |||||||||||||||||||||||||||||
| 510 | =head3 EXAMPLE | ||||||||||||||||||||||||||||
| 511 | |||||||||||||||||||||||||||||
| 512 | my %summary = (bytes_sent => $connection->bytes_sent, bytes_received => $connection->bytes_received); | ||||||||||||||||||||||||||||
| 513 | |||||||||||||||||||||||||||||
| 514 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 515 | |||||||||||||||||||||||||||||
| 516 | =head4 INPUT | ||||||||||||||||||||||||||||
| 517 | |||||||||||||||||||||||||||||
| 518 | [ { name => 'self', type => 'object' } ] | ||||||||||||||||||||||||||||
| 519 | |||||||||||||||||||||||||||||
| 520 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 521 | |||||||||||||||||||||||||||||
| 522 | { type => 'integer', min => 0 } | ||||||||||||||||||||||||||||
| 523 | |||||||||||||||||||||||||||||
| 524 | =head3 MESSAGES | ||||||||||||||||||||||||||||
| 525 | |||||||||||||||||||||||||||||
| 526 | None. | ||||||||||||||||||||||||||||
| 527 | |||||||||||||||||||||||||||||
| 528 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||
| 529 | |||||||||||||||||||||||||||||
| 530 | bytes_sent = sent ; bytes_received = received | ||||||||||||||||||||||||||||
| 531 | |||||||||||||||||||||||||||||
| 532 | =cut | ||||||||||||||||||||||||||||
| 533 | |||||||||||||||||||||||||||||
| 534 | 156 | ▶ | sub bytes_sent { | ||||||||||||||||||||||||||
|
Subroutine
bytes_sent: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||
| 535 | 156 | my ($self) = @_; | |||||||||||||||||||||||||||
| 536 | |||||||||||||||||||||||||||||
| 537 | 156 | ▶ | return $self->{sent_bytes} || 0; | ||||||||||||||||||||||||||
|
Condition100%2/2
$self->{'sent_bytes'} || 0
MC/DC100%1/1
$self->{'sent_bytes'} || 0
$self->{'sent_bytes'}
Truth table100%2/2
A
A= $self->{'sent_bytes'}
| |||||||||||||||||||||||||||||
| 538 | } | ||||||||||||||||||||||||||||
| 539 | |||||||||||||||||||||||||||||
| 540 | 156 | ▶ | sub bytes_received { | ||||||||||||||||||||||||||
|
Subroutine
bytes_received: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||
| 541 | 156 | my ($self) = @_; | |||||||||||||||||||||||||||
| 542 | |||||||||||||||||||||||||||||
| 543 | 156 | ▶ | return $self->{received_bytes} || 0; | ||||||||||||||||||||||||||
|
Condition100%2/2
$self->{'received_bytes'} || 0
MC/DC100%1/1
$self->{'received_bytes'} || 0
$self->{'received_bytes'}
Truth table100%2/2
A
A= $self->{'received_bytes'}
| |||||||||||||||||||||||||||||
| 544 | } | ||||||||||||||||||||||||||||
| 545 | |||||||||||||||||||||||||||||
| 546 | =head2 transport_failed | ||||||||||||||||||||||||||||
| 547 | |||||||||||||||||||||||||||||
| 548 | Purpose: whether the last failure was the pipe rather than the protocol. | ||||||||||||||||||||||||||||
| 549 | |||||||||||||||||||||||||||||
| 550 | Args: none. | ||||||||||||||||||||||||||||
| 551 | |||||||||||||||||||||||||||||
| 552 | Returns: 1 after a read or write on the underlying handles failed, or the peer | ||||||||||||||||||||||||||||
| 553 | closed the connection; otherwise 0. | ||||||||||||||||||||||||||||
| 554 | |||||||||||||||||||||||||||||
| 555 | Side Effects: none. | ||||||||||||||||||||||||||||
| 556 | |||||||||||||||||||||||||||||
| 557 | Usage: | ||||||||||||||||||||||||||||
| 558 | |||||||||||||||||||||||||||||
| 559 | my $detail = $connection->transport_failed ? $transport->error_text : undef; | ||||||||||||||||||||||||||||
| 560 | |||||||||||||||||||||||||||||
| 561 | =head3 EXAMPLE | ||||||||||||||||||||||||||||
| 562 | |||||||||||||||||||||||||||||
| 563 | eval { $connection->recv() } or print "pipe failed\n" if $connection->transport_failed; | ||||||||||||||||||||||||||||
| 564 | |||||||||||||||||||||||||||||
| 565 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 566 | |||||||||||||||||||||||||||||
| 567 | =head4 INPUT | ||||||||||||||||||||||||||||
| 568 | |||||||||||||||||||||||||||||
| 569 | [ { name => 'self', type => 'object' } ] | ||||||||||||||||||||||||||||
| 570 | |||||||||||||||||||||||||||||
| 571 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 572 | |||||||||||||||||||||||||||||
| 573 | { type => 'integer', min => 0, max => 1 } | ||||||||||||||||||||||||||||
| 574 | |||||||||||||||||||||||||||||
| 575 | =head3 MESSAGES | ||||||||||||||||||||||||||||
| 576 | |||||||||||||||||||||||||||||
| 577 | None. | ||||||||||||||||||||||||||||
| 578 | |||||||||||||||||||||||||||||
| 579 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||
| 580 | |||||||||||||||||||||||||||||
| 581 | transport_failed ⇔ ∃ an I/O failure or end of file on in or out | ||||||||||||||||||||||||||||
| 582 | |||||||||||||||||||||||||||||
| 583 | =cut | ||||||||||||||||||||||||||||
| 584 | |||||||||||||||||||||||||||||
| 585 | 9 | ▶ | sub transport_failed { | ||||||||||||||||||||||||||
|
Subroutine
transport_failed: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||
| 586 | 9 | my ($self) = @_; | |||||||||||||||||||||||||||
| 587 | |||||||||||||||||||||||||||||
| 588 | 9 | ▶ | return $self->{transport_failed} ? 1 : 0; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 589 | } | ||||||||||||||||||||||||||||
| 590 | |||||||||||||||||||||||||||||
| 591 | =head2 close | ||||||||||||||||||||||||||||
| 592 | |||||||||||||||||||||||||||||
| 593 | Purpose: close both handles. | ||||||||||||||||||||||||||||
| 594 | |||||||||||||||||||||||||||||
| 595 | Args: none. | ||||||||||||||||||||||||||||
| 596 | |||||||||||||||||||||||||||||
| 597 | Returns: 1, or nothing if already closed. | ||||||||||||||||||||||||||||
| 598 | |||||||||||||||||||||||||||||
| 599 | Side Effects: closes C<in> and C<out>; later sends raise C<protocol.closed>. | ||||||||||||||||||||||||||||
| 600 | |||||||||||||||||||||||||||||
| 601 | Usage: | ||||||||||||||||||||||||||||
| 602 | |||||||||||||||||||||||||||||
| 603 | $connection->close; | ||||||||||||||||||||||||||||
| 604 | |||||||||||||||||||||||||||||
| 605 | =head3 EXAMPLE | ||||||||||||||||||||||||||||
| 606 | |||||||||||||||||||||||||||||
| 607 | $connection->send({ cmd => 'done' }); | ||||||||||||||||||||||||||||
| 608 | $connection->close; | ||||||||||||||||||||||||||||
| 609 | |||||||||||||||||||||||||||||
| 610 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 611 | |||||||||||||||||||||||||||||
| 612 | =head4 INPUT | ||||||||||||||||||||||||||||
| 613 | |||||||||||||||||||||||||||||
| 614 | [ { name => 'self', type => 'object' } ] | ||||||||||||||||||||||||||||
| 615 | |||||||||||||||||||||||||||||
| 616 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 617 | |||||||||||||||||||||||||||||
| 618 | { type => 'integer', optional => 1 } | ||||||||||||||||||||||||||||
| 619 | |||||||||||||||||||||||||||||
| 620 | =head3 MESSAGES | ||||||||||||||||||||||||||||
| 621 | |||||||||||||||||||||||||||||
| 622 | None; close errors are ignored, as the session is over. | ||||||||||||||||||||||||||||
| 623 | |||||||||||||||||||||||||||||
| 624 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||
| 625 | |||||||||||||||||||||||||||||
| 626 | closed' = true | ||||||||||||||||||||||||||||
| 627 | |||||||||||||||||||||||||||||
| 628 | =cut | ||||||||||||||||||||||||||||
| 629 | |||||||||||||||||||||||||||||
| 630 | 0 | ▶ | sub close { ## no critic (Subroutines::ProhibitBuiltinHomonyms, Subroutines::ProhibitAmbiguousNames) | ||||||||||||||||||||||||||
|
Subroutine
close: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||||||||||||||||||||
| 631 | 0 | my ($self) = @_; | |||||||||||||||||||||||||||
| 632 | |||||||||||||||||||||||||||||
| 633 | 0 | ▶ | return if $self->{closed}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 634 | 0 | $self->{closed} = 1; | |||||||||||||||||||||||||||
| 635 | |||||||||||||||||||||||||||||
| 636 | # The session is over; a pipe that reports an error on close has nothing | ||||||||||||||||||||||||||||
| 637 | # left to say that a caller could act on, so the result is not checked. | ||||||||||||||||||||||||||||
| 638 | 0 | CORE::close($self->{in}); | |||||||||||||||||||||||||||
| 639 | 0 | CORE::close($self->{out}); | |||||||||||||||||||||||||||
| 640 | |||||||||||||||||||||||||||||
| 641 | 0 | return 1; | |||||||||||||||||||||||||||
| 642 | } | ||||||||||||||||||||||||||||
| 643 | |||||||||||||||||||||||||||||
| 644 | # _write | ||||||||||||||||||||||||||||
| 645 | # Purpose: put bytes on the wire. | ||||||||||||||||||||||||||||
| 646 | # Entry: the connection is open. | ||||||||||||||||||||||||||||
| 647 | # Exit: returns 1. | ||||||||||||||||||||||||||||
| 648 | # Side effects: writes to out; on failure marks the transport as failed and | ||||||||||||||||||||||||||||
| 649 | # raises protocol.write_failed. print is outside autodie. | ||||||||||||||||||||||||||||
| 650 | 3338 | ▶ | sub _write :Private { | ||||||||||||||||||||||||||
|
Subroutine
_write: called CC=3 SCAR=12.0
| |||||||||||||||||||||||||||||
| 651 | 3338 | my ($self, $bytes) = @_; | |||||||||||||||||||||||||||
| 652 | |||||||||||||||||||||||||||||
| 653 | 3338 | ▶ | $self->_throw('protocol.closed') if $self->{closed}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 654 | 3334 | ▶ | unless (print { $self->{out} } $bytes) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 655 | 0 | my $error = "$!"; | |||||||||||||||||||||||||||
| 656 | 0 | $self->{transport_failed} = 1; | |||||||||||||||||||||||||||
| 657 | 0 | $self->_throw('protocol.write_failed', { error => $error }); | |||||||||||||||||||||||||||
| 658 | } | ||||||||||||||||||||||||||||
| 659 | |||||||||||||||||||||||||||||
| 660 | 3334 | return 1; | |||||||||||||||||||||||||||
| 661 | 326 | ▶ | } | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 662 | |||||||||||||||||||||||||||||
| 663 | # _fill | ||||||||||||||||||||||||||||
| 664 | # Purpose: read more bytes from the peer into the buffer. | ||||||||||||||||||||||||||||
| 665 | # Entry: the caller needs more than the buffer holds. | ||||||||||||||||||||||||||||
| 666 | # Exit: returns 1 after appending at least one byte. | ||||||||||||||||||||||||||||
| 667 | # Side effects: on end of file or a read error marks the transport as failed | ||||||||||||||||||||||||||||
| 668 | # (and closed, for end of file) and raises. | ||||||||||||||||||||||||||||
| 669 | 3220 | ▶ | sub _fill :Private { | ||||||||||||||||||||||||||
|
Subroutine
_fill: called CC=3 SCAR=11.3
| |||||||||||||||||||||||||||||
| 670 | 3220 | my ($self) = @_; | |||||||||||||||||||||||||||
| 671 | |||||||||||||||||||||||||||||
| 672 | 3220 | my $chunk; | |||||||||||||||||||||||||||
| 673 | 3220 | my $read = eval { sysread($self->{in}, $chunk, $READ_SIZE) }; | |||||||||||||||||||||||||||
| 674 | 3220 | ▶ | unless (defined $read) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 675 | 0 | my $error = os_error($@); | |||||||||||||||||||||||||||
| 676 | 0 | $self->{transport_failed} = 1; | |||||||||||||||||||||||||||
| 677 | 0 | $self->_throw('protocol.read_failed', { error => $error }); | |||||||||||||||||||||||||||
| 678 | } | ||||||||||||||||||||||||||||
| 679 | 3220 | ▶ | if ($read == 0) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 680 | 6 | @{$self}{qw(closed transport_failed)} = (1, 1); | |||||||||||||||||||||||||||
| 681 | 6 | $self->_throw('protocol.eof'); | |||||||||||||||||||||||||||
| 682 | } | ||||||||||||||||||||||||||||
| 683 | |||||||||||||||||||||||||||||
| 684 | 3214 | $self->{buffer} .= $chunk; | |||||||||||||||||||||||||||
| 685 | 3214 | return 1; | |||||||||||||||||||||||||||
| 686 | 326 | ▶ | } | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 687 | |||||||||||||||||||||||||||||
| 688 | # _deflate | ||||||||||||||||||||||||||||
| 689 | # Purpose: compress a payload when that makes it smaller. | ||||||||||||||||||||||||||||
| 690 | # Entry: $bytes may be empty. | ||||||||||||||||||||||||||||
| 691 | # Exit: returns [ $wire_bytes, $compressed_flag ]. | ||||||||||||||||||||||||||||
| 692 | # Side effects: none. Any zlib failure just sends the bytes as they are. | ||||||||||||||||||||||||||||
| 693 | 282 | ▶ | sub _deflate :Private { | ||||||||||||||||||||||||||
|
Subroutine
_deflate: called CC=7 SCAR=20.9
| |||||||||||||||||||||||||||||
| 694 | 282 | my ($bytes) = @_; | |||||||||||||||||||||||||||
| 695 | |||||||||||||||||||||||||||||
| 696 | 282 | ▶ | return [ $bytes, 0 ] if length($bytes) < $COMPRESS_MIN; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 697 | |||||||||||||||||||||||||||||
| 698 | 19 | my ($deflater, $status) = Compress::Raw::Zlib::Deflate->new( | |||||||||||||||||||||||||||
| 699 | -WindowBits => -Compress::Raw::Zlib::MAX_WBITS(), | ||||||||||||||||||||||||||||
| 700 | -Level => $DEFLATE_LEVEL, | ||||||||||||||||||||||||||||
| 701 | ); | ||||||||||||||||||||||||||||
| 702 | 19 | ▶ | my $ok = $deflater && $status == Compress::Raw::Zlib::Z_OK(); | ||||||||||||||||||||||||||
|
Condition33%1/3
$deflater && $status == Compress::Raw::Zlib::Z_OK()
MC/DC0%0/2
$deflater && $status == Compress::Raw::Zlib::Z_OK()
$deflater
$status == Compress::Raw::Zlib::Z_OK()
Truth table33%1/3
A && B
A= $deflaterB= $status == Compress::Raw::Zlib::Z_OK()
| |||||||||||||||||||||||||||||
| 703 | |||||||||||||||||||||||||||||
| 704 | 19 | my ($out, $tail) = ('', ''); | |||||||||||||||||||||||||||
| 705 | 19 | ▶ | $ok &&= $deflater->deflate($bytes, $out) == Compress::Raw::Zlib::Z_OK(); | ||||||||||||||||||||||||||
|
Condition33%1/3
$ok &&= $deflater->deflate($bytes, $out) == Compress::Raw::Zlib::Z_OK()
MC/DC0%0/2
$ok &&= $deflater->deflate($bytes, $out) == Compress::Raw::Zlib::Z_OK()
$ok
$deflater->deflate($bytes, $out) == Compress::Raw::Zlib::Z_OK()
Truth table33%1/3
A &&= B
A= $okB= $deflater->deflate($bytes, $out) == Compress::Raw::Zlib::Z_OK()
| |||||||||||||||||||||||||||||
| 706 | 19 | ▶ | $ok &&= $deflater->flush($tail) == Compress::Raw::Zlib::Z_OK(); | ||||||||||||||||||||||||||
|
Condition33%1/3
$ok &&= $deflater->flush($tail) == Compress::Raw::Zlib::Z_OK()
MC/DC0%0/2
$ok &&= $deflater->flush($tail) == Compress::Raw::Zlib::Z_OK()
$ok
$deflater->flush($tail) == Compress::Raw::Zlib::Z_OK()
Truth table33%1/3
A &&= B
A= $okB= $deflater->flush($tail) == Compress::Raw::Zlib::Z_OK()
| |||||||||||||||||||||||||||||
| 707 | 19 | $out .= $tail; | |||||||||||||||||||||||||||
| 708 | |||||||||||||||||||||||||||||
| 709 | 19 | ▶ | return ($ok && length($out) < length($bytes)) ? [ $out, 1 ] : [ $bytes, 0 ]; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
$ok and length $out < length $bytes
MC/DC50%1/2
$ok and length $out < length $bytes
$ok
length $out < length $bytes
Truth table66%2/3
A and B
A= $okB= length $out < length $bytes
| |||||||||||||||||||||||||||||
| 710 | 326 | ▶ | } | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 711 | |||||||||||||||||||||||||||||
| 712 | # _inflate | ||||||||||||||||||||||||||||
| 713 | # Purpose: decompress a payload sent with "z". | ||||||||||||||||||||||||||||
| 714 | # Entry: $wire is raw deflate data. | ||||||||||||||||||||||||||||
| 715 | # Exit: returns the original bytes. | ||||||||||||||||||||||||||||
| 716 | # Side effects: raises protocol.inflate, protocol.corrupt or protocol.too_large. | ||||||||||||||||||||||||||||
| 717 | 16 | ▶ | sub _inflate :Private { | ||||||||||||||||||||||||||
|
Subroutine
_inflate: called CC=6 SCAR=20.2
| |||||||||||||||||||||||||||||
| 718 | 16 | my ($self, $wire) = @_; | |||||||||||||||||||||||||||
| 719 | |||||||||||||||||||||||||||||
| 720 | 16 | my ($inflater, $status) = Compress::Raw::Zlib::Inflate->new( | |||||||||||||||||||||||||||
| 721 | -WindowBits => -Compress::Raw::Zlib::MAX_WBITS(), | ||||||||||||||||||||||||||||
| 722 | ); | ||||||||||||||||||||||||||||
| 723 | 16 | ▶ | $self->_throw('protocol.inflate') | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
$inflater and $status == Compress::Raw::Zlib::Z_OK()
MC/DC0%0/2
$inflater and $status == Compress::Raw::Zlib::Z_OK()
$inflater
$status == Compress::Raw::Zlib::Z_OK()
Truth table33%1/3
A and B
A= $inflaterB= $status == Compress::Raw::Zlib::Z_OK()
| |||||||||||||||||||||||||||||
| 724 | unless $inflater && $status == Compress::Raw::Zlib::Z_OK(); | ||||||||||||||||||||||||||||
| 725 | |||||||||||||||||||||||||||||
| 726 | 16 | my $out = ''; | |||||||||||||||||||||||||||
| 727 | 16 | $status = $inflater->inflate($wire, $out); | |||||||||||||||||||||||||||
| 728 | 16 | ▶ | $self->_throw('protocol.corrupt') | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
$status == Compress::Raw::Zlib::Z_OK() or $status == Compress::Raw::Zlib::Z_STREAM_END()
MC/DC0%0/2
$status == Compress::Raw::Zlib::Z_OK() or $status == Compress::Raw::Zlib::Z_STREAM_END()
$status == Compress::Raw::Zlib::Z_OK()
$status == Compress::Raw::Zlib::Z_STREAM_END()
Truth table33%1/3
A or B
A= $status == Compress::Raw::Zlib::Z_OK()B= $status == Compress::Raw::Zlib::Z_STREAM_END()
| |||||||||||||||||||||||||||||
| 729 | unless $status == Compress::Raw::Zlib::Z_OK() || $status == Compress::Raw::Zlib::Z_STREAM_END(); | ||||||||||||||||||||||||||||
| 730 | 16 | ▶ | $self->_throw('protocol.too_large') if length($out) > $MAX_INFLATED; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 731 | |||||||||||||||||||||||||||||
| 732 | 16 | return $out; | |||||||||||||||||||||||||||
| 733 | 326 | ▶ | } | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 734 | |||||||||||||||||||||||||||||
| 735 | 326 | 1; | |||||||||||||||||||||||||||
| 736 | |||||||||||||||||||||||||||||
| 737 | __END__ | ||||||||||||||||||||||||||||