Merge pull request #1168 from grafana/jslib-aws/v0.8.0

[WIP] Add documentation for changes introduced by jslib-aws v0.8.0

Author: oleiade

.vale/Vocab/docs/accept.txt

@@ -68,6 +68,7 @@ Dynatrace
 enum
 errno
 erroring
+etag
 falsy
 flatlined
 fn

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 AwsConfig.md

@@ -41,7 +41,7 @@ import exec from 'k6/execution';
 
 // Note that you AWSConfig is also included in the dedicated service
 // client bundles such as `s3.js` and `secrets-manager.js`
-import { AWSConfig, SecretsManagerClient } from 'https://jslib.k6.io/aws/0.7.2/aws.js';
+import { AWSConfig, SecretsManagerClient } from 'https://jslib.k6.io/aws/0.8.0/aws.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 KMSClient.md

@@ -35,7 +35,7 @@ Both the dedicated `kms.js` jslib bundle and the all-encompassing `aws.js` bundl
 ```javascript
 import { textSummary } from 'https://jslib.k6.io/k6-summary/0.0.2/index.js';
 
-import { AWSConfig, KMSClient } from 'https://jslib.k6.io/aws/0.7.2/kms.js';
+import { AWSConfig, KMSClient } from 'https://jslib.k6.io/aws/0.8.0/kms.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 S3Client.md

@@ -13,13 +13,17 @@ S3Client is included in both the dedicated jslib `s3.js` bundle, and the `aws.js
 
 ### Methods
 
-| Function                                                                                         | Description                                           |
-| :----------------------------------------------------------------------------------------------- | :---------------------------------------------------- |
-| [listBuckets()](/javascript-api/jslib/aws/s3client/s3client-listbuckets)                         | List the buckets the authenticated user has access to |
-| [listObjects(bucketName, [prefix])](/javascript-api/jslib/aws/s3client/s3client-listobjects/)    | List the objects contained in a bucket                |
-| [getObject(bucketName, objectKey)](/javascript-api/jslib/aws/s3client/s3client-getobject/)       | Download an object from a bucket                      |
-| [putObject(bucketName, objectKey, data)](/javascript-api/jslib/aws/s3client/s3client-putobject/) | Upload an object to a bucket                          |
-| [deleteObject(bucketName, objectKey)](/javascript-api/jslib/aws/s3client/s3client-deleteobject/) | Delete an object from a bucket                        |
+| Function                                                                                                                                     | Description                                                  |
+| :------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------|
+| [listBuckets()](/javascript-api/jslib/aws/s3client/s3client-listbuckets)                                                                     | List the buckets the authenticated user has access to        |
+| [listObjects(bucketName, [prefix])](/javascript-api/jslib/aws/s3client/s3client-listobjects/)                                                | List the objects contained in a bucket                       |
+| [getObject(bucketName, objectKey)](/javascript-api/jslib/aws/s3client/s3client-getobject/)                                                   | Download an object from a bucket                             |
+| [putObject(bucketName, objectKey, data)](/javascript-api/jslib/aws/s3client/s3client-putobject/)                                             | Upload an object to a bucket                                 |
+| [deleteObject(bucketName, objectKey)](/javascript-api/jslib/aws/s3client/s3client-deleteobject/)                                             | Delete an object from a bucket                               |
+| [createMultipartUpload(bucketName, objectKey)](/javascript-api/jslib/aws/s3client/s3client-createmultipartupload/)                           | Create a multipart upload for a given objectKey to a bucket  |
+| [uploadPart(bucketName, objectKey, uploadId, partNumber, data)](/javascript-api/jslib/aws/s3client/s3client-uploadpart/)                     | Upload a part in a multipart upload                          |
+| [completeMultipartUpload(bucketName, objectKey, uploadId, parts)](/javascript-api/jslib/aws/s3client/s3client-completemultipartupload/)      | Complete a previously assembled multipart upload             |
+| [abortMultipartUpload(bucketName, objectKey, uploadId)](/javascript-api/jslib/aws/s3client/s3client-abortmultipartupload/)                   | Abort a multipart upload                                     |
 
 ### Throws
 
@@ -30,7 +34,7 @@ S3 Client methods will throw errors in case of failure.
 | InvalidSignatureError | when invalid credentials were provided.                    |
 | S3ServiceError        | when AWS replied to the requested operation with an error. |
 
-### Example
+### Examples
 
 <CodeGroup labels={[]}>
 
@@ -39,7 +43,7 @@ import { check } from 'k6';
 import exec from 'k6/execution';
 import http from 'k6/http';
 
-import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.7.2/s3.js';
+import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.8.0/s3.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,
@@ -92,3 +96,75 @@ export function handleSummary(data) {
 ```
 
 </CodeGroup>
+
+<CodeGroup labels={[]}>
+
+```javascript
+import crypto from 'k6/crypto';
+import exec from 'k6/execution';
+
+import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.8.0/s3.js';
+
+const awsConfig = new AWSConfig({
+    region: __ENV.AWS_REGION,
+    accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
+    secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
+    sessionToken: __ENV.AWS_SESSION_TOKEN,
+});
+
+const s3 = new S3Client(awsConfig);
+
+const testBucketName = 'test-jslib-aws';
+const testFileKey = 'multipart.txt';
+
+export default function () {
+    // List the buckets the AWS authentication configuration
+    // gives us access to.
+    const buckets = s3.listBuckets();
+
+    // If our test bucket does not exist, abort the execution.
+    if (buckets.filter((b) => b.name === testBucketName).length == 0) {
+        exec.test.abort();
+    }
+
+    // Produce random bytes to upload of size ~12MB, that
+    // we will upload in two 6MB parts. This is done as the
+    // minimum part size supported by S3 is 5MB.
+    const bigFile = crypto.randomBytes(12 * 1024 * 1024);
+
+    // Initialize a multipart upload
+    const multipartUpload = s3.createMultipartUpload(testBucketName, testFileKey);
+
+    // Upload the first part
+    const firstPartData = bigFile.slice(0, 6 * 1024 * 1024);
+    const firstPart = s3.uploadPart(
+        testBucketName,
+        testFileKey,
+        multipartUpload.uploadId,
+        1,
+        firstPartData
+    );
+
+    // Upload the second part
+    const secondPartData = bigFile.slice(6 * 1024 * 1024, 12 * 1024 * 1024);
+    const secondPart = s3.uploadPart(
+        testBucketName,
+        testFileKey,
+        multipartUpload.uploadId,
+        2,
+        secondPartData
+    );
+
+    // Complete the multipart upload
+    s3.completeMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId, [
+        firstPart,
+        secondPart,
+    ]);
+
+    // Let's redownload it verify it's correct, and delete it
+    const obj = s3.getObject(testBucketName, testFileKey);
+    s3.deleteObject(testBucketName, testFileKey);
+}
+```
+
+</CodeGroup>

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 SQSClient.md

@@ -34,7 +34,7 @@ Both the dedicated `sqs.js` jslib bundle and the all-encompassing `aws.js` bundl
 ```javascript
 import exec from 'k6/execution'
 
-import { AWSConfig, SQSClient } from 'https://jslib.k6.io/aws/0.7.2/sqs.js'
+import { AWSConfig, SQSClient } from 'https://jslib.k6.io/aws/0.8.0/sqs.js'
 
 const awsConfig = new AWSConfig({
     region: __ENV.AWS_REGION,

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 SecretsManagerClient.md

@@ -37,7 +37,7 @@ S3 Client methods will throw errors in case of failure.
 ```javascript
 import exec from 'k6/execution';
 
-import { AWSConfig, SecretsManagerClient } from 'https://jslib.k6.io/aws/0.7.2/secrets-manager.js';
+import { AWSConfig, SecretsManagerClient } from 'https://jslib.k6.io/aws/0.8.0/secrets-manager.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 SignatureV4.md

@@ -44,7 +44,7 @@ SignatureV4 methods throw errors on failure.
 ```javascript
 import http from 'k6/http.js'
 
-import { AWSConfig, SignatureV4 } from 'https://jslib.k6.io/aws/0.7.2/aws.js'
+import { AWSConfig, SignatureV4 } from 'https://jslib.k6.io/aws/0.8.0/aws.js'
 
 const awsConfig = new AWSConfig({
     region: __ENV.AWS_REGION,

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 SystemsManagerClient.md

@@ -34,7 +34,7 @@ Both the dedicated `ssm.js` jslib bundle and the all-encompassing `aws.js` bundl
 ```javascript
 import exec from 'k6/execution';
 
-import { AWSConfig, SystemsManagerClient } from 'https://jslib.k6.io/aws/0.7.2/ssm.js';
+import { AWSConfig, SystemsManagerClient } from 'https://jslib.k6.io/aws/0.8.0/ssm.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

src/data/markdown/docs/20 jslib/01 jslib/01 aws/KMSClient/00 generateDataKey.md

@@ -26,7 +26,7 @@ excerpt: 'KMSClient.generateDataKey generates a symmetric data key for use outsi
 ```javascript
 import exec from 'k6/execution';
 
-import { AWSConfig, KMSClient } from 'https://jslib.k6.io/aws/0.7.2/kms.js';
+import { AWSConfig, KMSClient } from 'https://jslib.k6.io/aws/0.8.0/kms.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

src/data/markdown/docs/20 jslib/01 jslib/01 aws/KMSClient/00 listKeys.md

@@ -19,7 +19,7 @@ excerpt: "KMSClient.listKeys lists all the KMS keys in the caller's AWS account
 ```javascript
 import exec from 'k6/execution';
 
-import { AWSConfig, KMSClient } from 'https://jslib.k6.io/aws/0.7.2/kms.js';
+import { AWSConfig, KMSClient } from 'https://jslib.k6.io/aws/0.8.0/kms.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,