File Coverage

=head1 NAME

App::FileSync::Protocol - the line-delimited JSON wire protocol

=head1 SYNOPSIS

        my $connection = App::FileSync::Protocol->new(in => $reader, out => $writer);
        $connection->send({ cmd => 'hello', proto => 2 });
        my $reply = $connection->recv();
        $connection->send_data({ cmd => 'chunk', p => $path }, $bytes);

=head1 DESCRIPTION

Each control message is one JSON object on one line.  A message announcing a
payload carries C<len> (the bytes on the wire) and, when the payload was
deflated, C<z>; the payload follows the line directly.  The connection counts
payload bytes in each direction for the transfer report.

When reading or writing fails because the pipe itself failed (the peer exited,
ssh was refused), L</transport_failed> becomes true, so a caller can show the
transport's own diagnostics instead of a protocol error.

=head1 METHODS

=head2 new

Purpose: wrap a pair of handles as a protocol connection.

Args: C<in> and C<out> (handles), optional C<language>.

Returns: the connection.

Side Effects: puts both handles in binary mode and makes C<out> autoflush.

Usage:

        my $connection = App::FileSync::Protocol->new(in => \*STDIN, out => \*STDOUT);

=head3 EXAMPLE

        my $connection = App::FileSync::Protocol->new(in => $transport->reader, out => $transport->writer);

=head3 API SPECIFICATION

=head4 INPUT

        {
                in       => { type => 'handle' },
                out      => { type => 'handle' },
                language => { type => 'string', optional => 1 },
        }

=head4 OUTPUT

        { type => 'object', isa => 'App::FileSync::Protocol' }

=head3 MESSAGES

        Key            Meaning                       Resolution
        args.invalid   a handle is missing           pass in and out

=head3 FORMAL SPECIFICATION

        new(in, out) = ⟨in, out, buffer ↦ ⟨⟩, closed ↦ false, sent ↦ 0, received ↦ 0⟩

=cut

=head2 send

Purpose: send one control message.

Args: C<\%message>.

Returns: 1.

Side Effects: writes one line.

Usage:

        $connection->send({ cmd => 'plan' });

=head3 EXAMPLE

        $connection->send({ ok => 1, off => $offset });

=head3 API SPECIFICATION

=head4 INPUT

        [
                { name => 'self',    type => 'object' },
                { name => 'message', type => 'hashref' },
        ]

=head4 OUTPUT

        { type => 'integer', min => 1, max => 1 }

=head3 MESSAGES

        Key                       Meaning                          Resolution
        protocol.closed           the connection was closed        a caller bug
        protocol.write_failed     the pipe would not take it       see the transport's stderr

=head3 FORMAL SPECIFICATION

        pre ¬closed
        out' = out ⁀ json(message) ⁀ "\n"

=cut

=head2 recv

Purpose: read one control message.

Args: none.

Returns: the decoded message hashref.

Side Effects: reads from C<in>; blocks until a whole line arrives.

Usage:

        my $reply = $connection->recv();

=head3 EXAMPLE

        my $hello = $connection->recv();
        die unless $hello->{ok};

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'self', type => 'object' } ]

=head4 OUTPUT

        { type => 'hashref' }

=head3 MESSAGES

        Key                   Meaning                        Resolution
        protocol.malformed    the line is not JSON           version mismatch or corrupt stream
        protocol.not_object   the JSON is not an object      version mismatch
        protocol.eof          the peer closed the connection see the peer's log
        protocol.read_failed  the pipe failed                see the transport's stderr

=head3 FORMAL SPECIFICATION

        in = line ⁀ "\n" ⁀ rest ⇒ recv = json⁻¹(line) ∧ in' = rest
        pre json⁻¹(line) ∈ OBJECT

=cut

=head2 send_bytes

Purpose: write raw bytes (the payload after a header).

Args: C<$bytes>; empty or undef writes nothing.

Returns: 1.

Side Effects: writes to C<out>.  Not counted in L</bytes_sent>; use
L</send_data> for counted payloads.

Usage:

        $connection->send_bytes($payload);

=head3 EXAMPLE

        $connection->send({ len => length $bytes });
        $connection->send_bytes($bytes);

=head3 API SPECIFICATION

=head4 INPUT

        [
                { name => 'self',  type => 'object' },
                { name => 'bytes', type => 'string', optional => 1 },
        ]

=head4 OUTPUT

        { type => 'integer', min => 1, max => 1 }

=head3 MESSAGES

        Key                       Meaning                          Resolution
        protocol.closed           the connection was closed        a caller bug
        protocol.write_failed     the pipe would not take it       see the transport's stderr

=head3 FORMAL SPECIFICATION

        out' = out ⁀ bytes

=cut

=head2 send_data

Purpose: send a header and its payload, compressing when worthwhile.

Args: C<\%header>, C<$bytes>.

Returns: 1.

Side Effects: writes the header (with C<len> and, if compressed, C<z>) and the
payload; adds the wire length to L</bytes_sent>.

Usage:

        $connection->send_data({ cmd => 'chunk', p => $path }, $bytes);

=head3 EXAMPLE

        $connection->send_data({ ok => 1, eof => 1 }, $last_chunk);

=head3 API SPECIFICATION

=head4 INPUT

        [
                { name => 'self',    type => 'object' },
                { name => 'message', type => 'hashref', optional => 1 },
                { name => 'bytes',   type => 'string', optional => 1 },
        ]

=head4 OUTPUT

        { type => 'integer', min => 1, max => 1 }

=head3 MESSAGES

As for L</send>.

=head3 FORMAL SPECIFICATION

        let (w, z) = deflate(bytes)
        out' = out ⁀ json(header ⊕ {len ↦ #w} ⊕ (z ⇒ {z ↦ 1})) ⁀ "\n" ⁀ w
        sent' = sent + #w

=cut

=head2 read_data

Purpose: read the payload a header announced.

Args: C<\%header> as returned by L</recv>.

Returns: the payload, decompressed if it was sent compressed.

Side Effects: reads C<len> bytes; adds them to L</bytes_received>.

Usage:

        my $bytes = $connection->read_data($header);

=head3 EXAMPLE

        my $reply = $connection->recv();
        my $bytes = $connection->read_data($reply);

=head3 API SPECIFICATION

=head4 INPUT

        [
                { name => 'self',    type => 'object' },
                { name => 'message', type => 'hashref' },
        ]

=head4 OUTPUT

        { type => 'string' }

=head3 MESSAGES

        Key                      Meaning                                 Resolution
        protocol.bad_length      len is not a number or exceeds 64 MiB   a peer bug
        protocol.inflate         the payload cannot be decompressed      a corrupt stream
        protocol.corrupt         the compressed payload is corrupt       a corrupt stream
        protocol.too_large       it would inflate beyond 64 MiB          a hostile or buggy peer

=head3 FORMAL SPECIFICATION

        pre header.len ∈ 0 .. MAX_WIRE
        read_data(h) = inflate(take(h.len, in))   if h.z
                     = take(h.len, in)            otherwise
        received' = received + h.len

=cut

=head2 read_line

Documented with L</read_bytes> below.

=head2 read_bytes

Purpose: read up to the next newline, or exactly C<$length> bytes.

Args: C<read_bytes($length)>.

Returns: the line (without its newline) or the bytes.

Side Effects: consumes them from the buffer, reading from C<in> as needed.

Usage:

        my $line = $connection->read_line();
        my $bytes = $connection->read_bytes(1024);

=head3 EXAMPLE

        my $payload = $connection->read_bytes($header->{len});

=head3 API SPECIFICATION

=head4 INPUT

        [
                { name => 'self',   type => 'object' },
                { name => 'length', type => 'integer', min => 0 },
        ]

=head4 OUTPUT

        { type => 'string' }

=head3 MESSAGES

        Key                       Meaning                          Resolution
        protocol.negative         a negative length was asked for  a caller bug
        protocol.eof              the peer closed the connection   see the peer's log
        protocol.read_failed      the pipe failed                  see the transport's stderr

=head3 FORMAL SPECIFICATION

        read_line: in = l ⁀ "\n" ⁀ r ∧ "\n" ∉ ran l ⇒ result = l ∧ in' = r
        read_bytes(n): in = b ⁀ r ∧ #b = n ⇒ result = b ∧ in' = r

=cut

=head2 bytes_sent

Documented with L</bytes_received> below.

=head2 bytes_received

Purpose: payload bytes that crossed the wire in each direction.

Args: none.

Returns: a byte count (headers and control messages excluded).

Side Effects: none.

Usage:

        printf "sent %d bytes\n", $connection->bytes_sent;

=head3 EXAMPLE

        my %summary = (bytes_sent => $connection->bytes_sent, bytes_received => $connection->bytes_received);

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'self', type => 'object' } ]

=head4 OUTPUT

        { type => 'integer', min => 0 }

=head3 MESSAGES

None.

=head3 FORMAL SPECIFICATION

        bytes_sent = sent ; bytes_received = received

=cut

=head2 transport_failed

Purpose: whether the last failure was the pipe rather than the protocol.

Args: none.

Returns: 1 after a read or write on the underlying handles failed, or the peer
closed the connection; otherwise 0.

Side Effects: none.

Usage:

        my $detail = $connection->transport_failed ? $transport->error_text : undef;

=head3 EXAMPLE

        eval { $connection->recv() } or print "pipe failed\n" if $connection->transport_failed;

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'self', type => 'object' } ]

=head4 OUTPUT

        { type => 'integer', min => 0, max => 1 }

=head3 MESSAGES

None.

=head3 FORMAL SPECIFICATION

        transport_failed ⇔ ∃ an I/O failure or end of file on in or out

=cut

=head2 close

Purpose: close both handles.

Args: none.

Returns: 1, or nothing if already closed.

Side Effects: closes C<in> and C<out>; later sends raise C<protocol.closed>.

Usage:

        $connection->close;

=head3 EXAMPLE

        $connection->send({ cmd => 'done' });
        $connection->close;

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'self', type => 'object' } ]

=head4 OUTPUT

        { type => 'integer', optional => 1 }

=head3 MESSAGES

None; close errors are ignored, as the session is over.

=head3 FORMAL SPECIFICATION

        closed' = true

=cut