(Client): Introduce the ApiChannel interface

- Add the `ApiChannel` low-level interface for writing and reading encoded bytes to API connection
- Add code for obtaining ApiChannel instances from PCloudAPIClient
- Update related unit tests

Author: georgi-neykov-hub

binapi-client/src/main/java/com/pcloud/networking/client/ApiChannel.java

@@ -0,0 +1,64 @@
+package com.pcloud.networking.client;
+
+import com.pcloud.networking.protocol.ProtocolRequestWriter;
+import com.pcloud.networking.protocol.ProtocolResponseReader;
+import okio.BufferedSink;
+
+import java.io.Closeable;
+
+/**
+ * A low-level contract for interfacing with an pCloud API Host via
+ * binary protocol-encoded messages.
+ * <p>
+ * The {@linkplain ApiChannel} interface exposes the lowest possible level
+ * of detail when writing/reading messages from the API by still abstracting away
+ * the details of connection establishment, TLS handshaking and so on.
+ * <p>
+ * The interface can be used in the cases where the flows using the {@linkplain Call} and {@linkplain MultiCall}
+ * abstractions may yield a considerable amount of memory allocations, usually when making a chain
+ * of repeating requests. The contract does not restrict in any way how the requests will be written, so
+ * request pipelining can be implemented by writing multiple requests at once, without immediately reading the
+ * responses, which may result in considerable speed improvements.
+ * <p>
+ * If otherwise stated, instances of this interface will not be thread-safe and reading/writing at the same time
+ * from multiple threads will result in undetermined behavior. All implementations should allow calling
+ * {@linkplain #close()} from multiple threads multiple times.
+ * <p>
+ * Calling {@linkplain #close()} on an idle {@linkplain ApiChannel} instance will result in connection recycling,
+ * for other cases the underlying socket will be closed.
+ * <br>
+ * A {@linkplain ApiChannel} instance is considered idle when the number of sent requests is equal
+ * to the number of fully read responses.
+ * <br>
+ * Each successful call to {@linkplain ProtocolRequestWriter#endRequest()} is counted as a sent request.
+ * <br>
+ * A fully read response is counted after each successful call to {@linkplain ProtocolResponseReader#endResponse()}
+ * for non-data responses or to {@linkplain ProtocolResponseReader#readData(BufferedSink)} for data-containing responses.
+ * <p>
+ * Instances can be obtained via the {@linkplain PCloudAPIClient#newChannel(Endpoint)} and
+ * {@linkplain PCloudAPIClient#newChannel()} methods.
+ */
+public interface ApiChannel extends Closeable, AutoCloseable {
+    /**
+     * @return the non-null {@linkplain Endpoint} to which this channel is connected.
+     */
+    Endpoint endpoint();
+
+    /**
+     * @return a non-null {@linkplain ProtocolResponseReader} for reading data.
+     */
+    ProtocolResponseReader reader();
+
+    /**
+     * @return a non-null {@linkplain ProtocolRequestWriter} for writing data.
+     */
+    ProtocolRequestWriter writer();
+
+    /**
+     * @return {@code true} if the channel is not closed, {@code false} otherwise.
+     */
+    boolean isOpen();
+
+    @Override
+    void close();
+}

binapi-client/src/main/java/com/pcloud/networking/client/PCloudAPIClient.java

@@ -21,6 +21,7 @@
 import javax.net.SocketFactory;
 import javax.net.ssl.HostnameVerifier;
 import javax.net.ssl.SSLSocketFactory;
+import java.io.IOException;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Collections;
@@ -192,6 +193,37 @@ public MultiCall newCall(Collection<Request> requests, Endpoint endpoint) {
                 connectionProvider, endpoint);
     }
 
+    /**
+     * Create a new {@linkplain ApiChannel} for a given {@linkplain Endpoint}.
+     *<p>
+     * Same as calling {@linkplain #newChannel(Endpoint)} with the endpoint returned
+     * by this client's {@linkplain EndpointProvider} instance.
+     *
+     * @see ApiChannel
+     * @see #newChannel(Endpoint)
+     * @see EndpointProvider
+     * @return a non-null {@linkplain ApiChannel} instance
+     * @throws IOException on a connection error
+     */
+    public ApiChannel newChannel() throws IOException {
+        return new RealApiChannel(connectionProvider, endpointProvider.endpoint());
+    }
+
+    /**
+     * Create a new {@linkplain ApiChannel} for a given {@linkplain Endpoint}.
+     *<p>
+     * The call will create and initialize an {@linkplain ApiChannel} instance to a given endpoint,
+     * or throw an {@linkplain IOException} on error.
+     *
+     * @see ApiChannel
+     * @param endpoint a target {@linkplain Endpoint}
+     * @return a non-null {@linkplain ApiChannel} instance
+     * @throws IOException on a connection error
+     */
+    public ApiChannel newChannel(Endpoint endpoint) throws IOException {
+        return new RealApiChannel(connectionProvider, endpoint);
+    }
+
     /**
      * Returns the maximum amount of time a connection should take to establish itself in milliseconds as an int
      *
@@ -255,7 +287,6 @@ public ConnectionPool connectionPool() {
         return connectionPool;
     }
 
-
     /**
      * Returns the {@linkplain ExecutorService} for this client
      *