HttpClientConnection.java

/**
 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 * SPDX-License-Identifier: Apache-2.0.
 */

package software.amazon.awssdk.crt.http;

import java.util.concurrent.CompletableFuture;
import java.util.Map;
import java.util.HashMap;

import software.amazon.awssdk.crt.CRT;
import software.amazon.awssdk.crt.CrtResource;
import software.amazon.awssdk.crt.CrtRuntimeException;
import software.amazon.awssdk.crt.http.HttpStreamResponseHandler;
import software.amazon.awssdk.crt.http.HttpStream;

import static software.amazon.awssdk.crt.CRT.awsLastError;

/**
 * This class wraps aws-c-http to provide the basic HTTP request/response functionality via the AWS Common Runtime.
 *
 * HttpClientConnection represents a single connection to a HTTP service endpoint.
 *
 * This class is not thread safe and should not be called from different threads.
 */
public class HttpClientConnection extends CrtResource {

    protected HttpClientConnection(long connectionBinding) {
        acquireNativeHandle(connectionBinding);
    }

    /**
     * Schedules an HttpRequest on the Native EventLoop for this HttpClientConnection specific to HTTP/1.1 connection.
     *
     * @param request The Request to make to the Server.
     * @param streamHandler The Stream Handler to be called from the Native EventLoop
     * @throws CrtRuntimeException if stream creation fails
     * @return The HttpStream that represents this Request/Response Pair. It can be closed at any time during the
     *          request/response, but must be closed by the user thread making this request when it's done.
     */
    public HttpStream makeRequest(HttpRequest request, HttpStreamResponseHandler streamHandler)
            throws CrtRuntimeException {
        return makeRequest(request, streamHandler, false);
    }

    /**
     * Schedules an HttpRequest on the Native EventLoop for this HttpClientConnection specific to HTTP/1.1 connection.
     *
     * @param request The Request to make to the Server.
     * @param streamHandler The Stream Handler to be called from the Native EventLoop
     * @param useManualDataWrites When {@code true}, request body data is provided via
     *        {@link HttpStreamBase#writeData} instead of from the request's
     *        {@link HttpRequestBodyStream}.
     *
     *        <p>By design, CRT does not support setting both a body stream and enabling
     *        manual writes for HTTP/1.1. Body streams are intended for requests whose
     *        payload is available in full at the time of sending. If the stream does not
     *        signal end-of-stream promptly, the event loop will busy-wait (hot-loop) for
     *        more data, wasting CPU time. Manual writes avoid this by letting the caller
     *        control when data is sent; the event loop only processes the request when
     *        {@link HttpStreamBase#writeData} is called and is free to service other
     *        requests in the meantime.
     *
     *        <p>If the request was created with an {@link HttpRequestBodyStream} and this
     *        parameter is {@code true}, an {@link IllegalStateException} is thrown
     *        immediately.
     * @throws CrtRuntimeException if stream creation fails
     * @return The HttpStream that represents this Request/Response Pair. It can be closed at any time during the
     *          request/response, but must be closed by the user thread making this request when it's done.
     */
    public HttpStream makeRequest(HttpRequest request, HttpStreamResponseHandler streamHandler,
            boolean useManualDataWrites) throws CrtRuntimeException, IllegalStateException {
        if (isNull()) {
            throw new IllegalStateException("HttpClientConnection has been closed, can't make requests on it.");
        }
        if (getVersion() == HttpVersion.HTTP_2) {
            throw new IllegalArgumentException("HTTP/1 only method called on an HTTP/2 connection.");
        }
        if (useManualDataWrites && request.getBodyStream() != null) {
            throw new IllegalStateException(
                "Cannot use manual data writes with a body stream on an HTTP/1.1 request. "
                + "Either remove the body stream or set useManualDataWrites to false.");
        }
        HttpStreamBase stream = httpClientConnectionMakeRequest(getNativeHandle(),
                request.marshalForJni(),
                request.getBodyStream(),
                new HttpStreamResponseHandlerNativeAdapter(streamHandler),
                useManualDataWrites);

        return (HttpStream)stream;
    }

    /**
     * Schedules an HttpRequestBase on the Native EventLoop for this HttpClientConnection. Applies to both HTTP/2 and HTTP/1.1 connections.
     *
     * @param request The Request to make to the Server.
     * @param streamHandler The Stream Handler to be called from the Native EventLoop
     * @throws CrtRuntimeException if stream creation fails
     * @return The HttpStream that represents this Request/Response Pair. It can be closed at any time during the
     *          request/response, but must be closed by the user thread making this request when it's done.
     */
    public HttpStreamBase makeRequest(HttpRequestBase request, HttpStreamBaseResponseHandler streamHandler) throws CrtRuntimeException {
        return makeRequest(request, streamHandler, false);
    }

    /**
     * Schedules an HttpRequestBase on the Native EventLoop for this HttpClientConnection. Applies to both HTTP/2 and HTTP/1.1 connections.
     *
     * @param request The Request to make to the Server.
     * @param streamHandler The Stream Handler to be called from the Native EventLoop
     * @param useManualDataWrites When true, request body data will be provided via
     *        {@link HttpStreamBase#writeData} instead of from the request's body stream.
     * @throws CrtRuntimeException if stream creation fails
     * @return The HttpStream that represents this Request/Response Pair. It can be closed at any time during the
     *          request/response, but must be closed by the user thread making this request when it's done.
     */
    public HttpStreamBase makeRequest(HttpRequestBase request, HttpStreamBaseResponseHandler streamHandler,
            boolean useManualDataWrites) throws CrtRuntimeException {
        if (isNull()) {
            throw new IllegalStateException("HttpClientConnection has been closed, can't make requests on it.");
        }
        HttpStreamBase stream = httpClientConnectionMakeRequest(getNativeHandle(),
                request.marshalForJni(),
                request.getBodyStream(),
                new HttpStreamResponseHandlerNativeAdapter(streamHandler),
                useManualDataWrites);

        return stream;
    }

    /**
     * Determines whether a resource releases its dependencies at the same time the native handle is released or if it waits.
     * Resources that wait are responsible for calling releaseReferences() manually.
     */
    @Override
    protected boolean canReleaseReferencesImmediately() { return true; }

    /**
     * Releases this HttpClientConnection back into the Connection Pool, and allows another Request to acquire this connection.
     */
    @Override
    protected void releaseNativeHandle() {
        if (!isNull()){
            httpClientConnectionReleaseManaged(getNativeHandle());
        }
    }

    /**
     * Shuts down the underlying http connection.  Even if this function is called, you still need to properly close
     * the connection as well in order to release the native resources.
     */
    public void shutdown() {
        if (isNull()) {
            throw new IllegalStateException("HttpClientConnection has been closed and released back to the pool, cannot shutdown the connection.");
        }
        httpClientConnectionShutdown(getNativeHandle());
    }

    /**
     * Check the underlying http connection is still open or not.
     *
     * @return true unless the underlying http connection is shutting down, or has been shutdown.
     */
    public boolean isOpen() {
        if (isNull()) {
            throw new IllegalStateException("HttpClientConnection has been closed.");
        }
        return httpClientConnectionIsOpen(getNativeHandle());
    }

    public HttpVersion getVersion() {
        if (isNull()) {
            throw new IllegalStateException("HttpClientConnection has been closed.");
        }
        short version = httpClientConnectionGetVersion(getNativeHandle());
        return HttpVersion.getEnumValueFromInteger((int) version);
    };

    /** Called from Native when a new connection is acquired **/
    private static void onConnectionAcquired(CompletableFuture<HttpClientConnection> acquireFuture, long nativeConnectionBinding, int errorCode) {
        if (errorCode != CRT.AWS_CRT_SUCCESS) {
            acquireFuture.completeExceptionally(new HttpException(errorCode));
            return;
        }
        if (HttpVersion.getEnumValueFromInteger(
                (int) httpClientConnectionGetVersion(nativeConnectionBinding)) == HttpVersion.HTTP_2) {
            HttpClientConnection h2Conn = new Http2ClientConnection(nativeConnectionBinding);
            if (!acquireFuture.complete(h2Conn)) {
                // future was already completed/cancelled, return it immediately to the pool to not leak it
                h2Conn.close();
            }
        } else {
            HttpClientConnection conn = new HttpClientConnection(nativeConnectionBinding);
            if (!acquireFuture.complete(conn)) {
                // future was already completed/cancelled, return it immediately to the pool to not leak it
                conn.close();
            }
        }
    }

    /**
     * Certain exceptions thrown by this HTTP API are from invalid boundary conditions
     * that, if the request isn't altered, will never succeed. This function returns
     * false if the exception is caused by such a condition.
     * <p>
     * It does not mean the request that generated the error SHOULD be retried:
     * only that as far as this client is concerned, the request might,
     * possibly succeed with a subsequent attempt.
     *
     * @param exception, an exception thrown by the CRT HTTP API--for any reason.
     * @return true if the error that generated the exception makes sense for a retry, and
     * false otherwise.
     */
    public static boolean isErrorRetryable(HttpException exception) {
        // why take an exception rather than an error code directly?
        // to give us breathing room for changing our mind later about how we convey
        // retry information on the exceptions we throw.
        return isErrorRetryable(exception.getErrorCode());
    }

    /*******************************************************************************
     * Native methods
     ******************************************************************************/
    private static native HttpStreamBase httpClientConnectionMakeRequest(long connectionBinding,
                                                                     byte[] marshalledRequest,
                                                                     HttpRequestBodyStream bodyStream,
                                                                     HttpStreamResponseHandlerNativeAdapter responseHandler,
                                                                     boolean useManualDataWrites) throws CrtRuntimeException;

    private static native void httpClientConnectionShutdown(long connectionBinding) throws CrtRuntimeException;
    private static native boolean httpClientConnectionIsOpen(long connectionBinding) throws CrtRuntimeException;

    private static native void httpClientConnectionReleaseManaged(long connectionBinding) throws CrtRuntimeException;
    private static native short httpClientConnectionGetVersion(long connectionBinding) throws CrtRuntimeException;

    private static native boolean isErrorRetryable(int errorCode);
}