why

Author: TingDaoK

include/aws/s3/private/s3_checksums.h

@@ -84,23 +84,44 @@ struct aws_input_stream *aws_checksum_stream_new(
 
 /**
  * TODO: properly support chunked encoding.
+ * Creates a chunked encoding stream that wraps an existing stream and adds checksum trailers.
  *
- * A stream that takes in a stream, encodes it to aws_chunked. Computes a running checksum as it is read and add the
- * checksum as trailer at the end of the stream. All of the added bytes will be counted to the length of the stream.
- * Note: seek this stream will immediately fail, as it would prevent an accurate calculation of the
- * checksum.
+ * This function creates a stream that:
+ * 1. Encodes the input stream using HTTP chunked transfer encoding
+ * 2. Calculates a checksum of the stream content (if not already calculated)
+ * 3. Appends the checksum as a trailer at the end of the chunked stream
  *
- * @param allocator
- * @param existing_stream   The data to be chunkified prepended by information on the stream length followed by a final
- *                          chunk and a trailing chunk containing a checksum of the existing stream. Destroying the
- *                          chunk stream will destroy the existing stream.
- * @param checksum_buffer   Optional.
- *                          - If the checksum_buffer is NULL, the checksum will still be calculated to append as
- *                          trailer.
- *                          - Empty buffer, the buffer will be initialized to the appropriate size and
- *                          filled with the checksum result when calculated. Callers responsibility to cleanup.
- *                          - Otherwise, the buffer will be used directly.
- *                          Caller takes the ownership of the buffer, error or not.
+ * The output format follows HTTP chunked encoding with checksum trailers:
+ * - For non-empty streams: [hex-length]\r\n[data]\r\n0\r\n[checksum-header]:[checksum-value]\r\n\r\n
+ * - For empty streams: 0\r\n[checksum-header]:[checksum-value]\r\n\r\n
+ *
+ * Note: This stream does not support seeking operations, as seeking would prevent
+ * accurate checksum calculation and corrupt the chunked encoding format.
+ *
+ * @param allocator Memory allocator to use for stream creation and internal buffers
+ * @param existing_stream The input stream to be chunked and checksummed. This stream
+ *                       will be acquired by the chunk stream and released when the
+ *                       chunk stream is destroyed. Must not be NULL.
+ * @param checksum_context Context containing checksum configuration and state. Must not be NULL.
+ *                        The context contains:
+ *                        - algorithm: The checksum algorithm to use (CRC32, CRC32C, etc.)
+ *                        - base64_checksum: Buffer for the calculated checksum result
+ *                        - checksum_calculated: Whether checksum is pre-calculated or needs calculation
+ *                        - encoded_checksum_size: Expected size of the base64-encoded checksum
+ *
+ *                        If checksum_calculated is false, the stream will wrap existing_stream
+ *                        with a checksum stream to calculate the checksum during reading.
+ *                        If checksum_calculated is true, the existing checksum value will be used.
+ *
+ * @return A new input stream that provides chunked encoding with checksum trailers,
+ *         or NULL if creation fails. The returned stream must be released with
+ *         aws_input_stream_release() when no longer needed.
+ *
+ * @note The total length of the returned stream includes:
+ *       - Chunk size header (hex representation + \r\n)
+ *       - Original stream content
+ *       - Final chunk marker (0\r\n or \r\n0\r\n)
+ *       - Checksum trailer (header name + : + base64 checksum + \r\n\r\n)
  */
 AWS_S3_API
 struct aws_input_stream *aws_chunk_stream_new(

source/s3_checksum_stream.c

@@ -122,9 +122,10 @@ struct aws_input_stream *aws_checksum_stream_new(
     enum aws_s3_checksum_algorithm algorithm,
     struct aws_byte_buf *checksum_output) {
     AWS_PRECONDITION(existing_stream);
+    AWS_PRECONDITION(checksum_output);
+    AWS_PRECONDITION(checksum_output->len == 0 && "Checksum output buffer is not empty");
 
     struct aws_checksum_stream *impl = aws_mem_calloc(allocator, 1, sizeof(struct aws_checksum_stream));
-
     impl->allocator = allocator;
     impl->base.vtable = &s_aws_input_checksum_stream_vtable;