1 /**
2  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3  * SPDX-License-Identifier: Apache-2.0.
4  */
5 
6 package software.amazon.awssdk.crt.http;
7 
8 /**
9  * Interface that Native code knows how to call when handling Http Responses
10  *
11  * Maps 1-1 to the Native Http API here:
12  * https://github.com/awslabs/aws-c-http/blob/master/include/aws/http/request_response.h
13  */
14 public interface HttpStreamBaseResponseHandler {
15 
16     /**
17      * Called from Native when new Http Headers have been received.
18      * Note that this function may be called multiple times as HTTP headers are
19      * received.
20      *
21      * @param stream             The HttpStreamBase object
22      * @param responseStatusCode The HTTP Response Status Code
23      * @param blockType          The HTTP header block type
24      * @param nextHeaders        The headers received in the latest IO event.
25      */
onResponseHeaders(HttpStreamBase stream, int responseStatusCode, int blockType, HttpHeader[] nextHeaders)26     void onResponseHeaders(HttpStreamBase stream, int responseStatusCode, int blockType, HttpHeader[] nextHeaders);
27 
28     /**
29      * Called from Native once all HTTP Headers are processed. Will not be called if
30      * there are no Http Headers in the
31      * response. Guaranteed to be called exactly once if there is at least 1 Header.
32      *
33      * @param stream    The HttpStreamBase object
34      * @param blockType The type of the header block, corresponds to
35      *                  {@link HttpHeaderBlock}
36      */
onResponseHeadersDone(HttpStreamBase stream, int blockType)37     default void onResponseHeadersDone(HttpStreamBase stream, int blockType) {
38         /* Optional Callback, do nothing by default */
39     }
40 
41     /**
42      * Called when new Response Body bytes have been received. Note that this
43      * function may be called multiple times over
44      * the lifetime of an HttpClientConnection as bytes are received.
45      *
46      * Users must read all data from bodyBytesIn before returning. If
47      * "bodyBytesIn.remaining() > 0" after this method
48      * returns, then Native will assume there was a processing failure and abort the
49      * connection.
50      *
51      * Do NOT keep a reference to this ByteBuffer past the lifetime of this function
52      * call. The CommonRuntime reserves
53      * the right to use DirectByteBuffers pointing to memory that only lives as long
54      * as the function call.
55      *
56      * Sliding Window:
57      * The Native HttpClientConnection EventLoop will keep sending data until the
58      * end of the sliding Window is reached.
59      * The user application is responsible for setting the initial Window size
60      * appropriately when creating the
61      * HttpClientConnection, and for incrementing the sliding window appropriately
62      * throughout the lifetime of the HttpStream.
63      *
64      * For more info, see:
65      * - https://en.wikipedia.org/wiki/Sliding_window_protocol
66      *
67      * @param stream      The HttpStreamBase the body was delivered to
68      * @param bodyBytesIn The HTTP Body Bytes received in the last IO Event.
69      * @return The number of bytes to move the sliding window by. Repeatedly
70      *         returning zero will eventually cause the
71      *         sliding window to fill up and data to stop flowing until the user
72      *         slides the window back open.
73      */
onResponseBody(HttpStreamBase stream, byte[] bodyBytesIn)74     default int onResponseBody(HttpStreamBase stream, byte[] bodyBytesIn) {
75         /*
76          * Optional Callback, ignore incoming response body by default unless user wants
77          * to capture it.
78          */
79         return bodyBytesIn.length;
80     }
81 
82     /**
83      * Called right before stream is complete, whether successful or unsuccessful.
84      * @param stream The HTTP stream to which the metrics apply
85      * @param metrics The [HttpStreamMetrics] containing metrics for the given stream
86      */
onMetrics(HttpStreamBase stream, HttpStreamMetrics metrics)87     default void onMetrics(HttpStreamBase stream, HttpStreamMetrics metrics) {
88         /* Optional callback, nothing to do by default */
89     }
90 
91     /**
92      * Called from Native when the Response has completed.
93      *
94      * @param stream    completed HttpStreamBase
95      * @param errorCode resultant errorCode for the response
96      */
onResponseComplete(HttpStreamBase stream, int errorCode)97     void onResponseComplete(HttpStreamBase stream, int errorCode);
98 }
99