=pod

=encoding utf-8

=head1 NAME

Net::BitTorrent::Transport::TCP - TCP Transport Layer

=head1 SYNOPSIS

    use Net::BitTorrent::Transport::TCP;

    my $transport = Net::BitTorrent::Transport::TCP->new(
        socket => $socket_handle
    );

    $transport->on(data => sub ( $emitter, $data ) {
        $protocol->receive_data($data);
    });

=head1 DESCRIPTION

C<Net::BitTorrent::Transport::TCP> provides a standardized, non-blocking interface for handling TCP-based peer
connections within the loop-agnostic L<Net::BitTorrent> framework.

It acts as an abstraction layer between the high-level L<Net::BitTorrent::Peer> and the physical network socket. This
allows the library to handle different connection types (TCP vs uTP) using the same high-level logic. It supports
pluggable filters for encryption (MSE/PE).

=head1 METHODS

=head2 C<new( %params )>

Creates a new TCP transport object.

    my $transport = Net::BitTorrent::Transport::TCP->new(
        socket     => $socket,
        connecting => 1
    );

Expected parameters:

=over

=item C<socket>

The underlying L<IO::Socket> (or compatible) object.

=item C<connecting> - optional

Boolean indicating if the socket is still in the process of connecting. Defaults to 1.

=back

=head2 C<set_filter( $filter )>

Sets a stream filter (e.g., MSE/PE).

    $transport->set_filter( $mse_obj );

Expected parameters:

=over

=item C<$filter>

An object that implements the MSE protocol.

=back

=head2 C<send_data( $data )>

Sends data through the transport, applying filters if necessary.

    $transport->send_data( $payload );

Expected parameters:

=over

=item C<$data>

The plaintext data to send.

=back

=head2 C<send_raw( $data )>

Sends data directly through the transport, bypassing filters.

    $transport->send_raw( $handshake );

Expected parameters:

=over

=item C<$data>

The raw data to send.

=back

=head2 C<tick( )>

Processes I/O events.

    $transport->tick();

This method handles connection establishment, reads incoming data, and flushes the write buffer.

=head2 C<receive_data( $data )>

Emits a 'data' event.

    $transport->receive_data( $plaintext );

Expected parameters:

=over

=item C<$data>

The received data.

=back

=head2 C<close( )>

Closes the socket.

    $transport->close();

=head2 C<state( )>

Returns the connection state ('CONNECTED' or 'CLOSED').

    my $s = $transport->state();

=head2 C<socket( )>

Returns the underlying socket object.

    my $sock = $transport->socket();

=head2 C<filter( )>

Returns the current filter object.

    my $f = $transport->filter();

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=head1 COPYRIGHT

Copyright (C) 2008-2026 by Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

=cut
