CLDSRV-902: document validateXAmzChecksums and getChecksumDataFromHeaders

Author: leif-scality

lib/api/apiUtils/integrity/validateChecksums.js

@@ -153,6 +153,14 @@ const algorithms = Object.freeze({
     },
 });
 
+/**
+ * Validate the x-amz-checksum-<algo> header against a buffered body.
+ *
+ * @param {object} headers - HTTP request headers (lowercased keys)
+ * @param {Buffer} body - the entire buffered request body
+ * @returns {Promise<null | { error: string, details: object }>} -
+ *   null on success; otherwise a ChecksumError with details.
+ */
 async function validateXAmzChecksums(headers, body) {
     const checksumHeaders = Object.keys(headers).filter(header => header.startsWith('x-amz-checksum-'));
     const xAmzChecksumCnt = checksumHeaders.length;
@@ -206,6 +214,14 @@ async function validateXAmzChecksums(headers, body) {
     return null;
 }
 
+/**
+ * Extract checksum data from request headers.
+ *
+ * @param {object} headers - HTTP request headers (lowercased keys)
+ * @returns {null
+ *   | { algorithm: string, isTrailer: boolean, expected: string|undefined }
+ *   | { error: string, details: object }}
+ */
 function getChecksumDataFromHeaders(headers) {
     const checkSdk = algo => {
         if (!('x-amz-sdk-checksum-algorithm' in headers)) {