Skip to content

Commit 9ff3f8a

Browse files
oleiadeoleiade
committed
Update jslib-aws S3Client's documentation to reflect new async syntax
1 parent a34f1cd commit 9ff3f8a

15 files changed

+129
-83
lines changed

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

Lines changed: 22 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,11 @@ excerpt: 'S3Client class allows interacting with AWS S3 buckets and objects'
77

88
<BlockingAwsBlockquote />
99

10-
S3Client allows interacting with AWS S3's buckets and objects. Namely, it allows the user to list buckets and the objects they contain, as well as download, uploading, and deleting objects. The S3Client operations are blocking, and we recommend reserving their usage to the [`setup`](/using-k6/test-lifecycle/) and [`teardown`](/using-k6/test-lifecycle/) functions as much as possible.
10+
`S3Client` interacts with the AWS Simple Storage Service (S3).
1111

12-
S3Client is included in both the dedicated jslib `s3.js` bundle, and the `aws.js` one, containing all the services clients.
12+
With it, the user can list buckets, list objects in a bucket, download objects from a bucket, upload objects to a bucket, delete objects from a bucket, copy objects from one bucket to another, create multipart uploads, upload parts in a multipart upload, complete multipart uploads, and abort multipart uploads.
13+
14+
Both the dedicated `s3.js` jslib bundle and the all-encompassing `aws.js` bundle include the `S3Client`.
1315

1416
### Methods
1517

@@ -57,21 +59,21 @@ const testBucketName = 'test-jslib-aws';
5759
const testInputFileKey = 'productIDs.json';
5860
const testOutputFileKey = `results-${Date.now()}.json`;
5961

60-
export function setup() {
62+
export async function setup() {
6163
// If our test bucket does not exist, abort the execution.
62-
const buckets = s3.listBuckets();
64+
const buckets = await s3.listBuckets();
6365
if (buckets.filter((b) => b.name === testBucketName).length == 0) {
6466
exec.test.abort();
6567
}
6668

6769
// If our test object does not exist, abort the execution.
68-
const objects = s3.listObjects(testBucketName);
70+
const objects = await s3.listObjects(testBucketName);
6971
if (objects.filter((o) => o.key === testInputFileKey).length == 0) {
7072
exec.test.abort();
7173
}
7274

7375
// Download the S3 object containing our test data
74-
const inputObject = s3.getObject(testBucketName, testInputFileKey);
76+
const inputObject = await s3.getObject(testBucketName, testInputFileKey);
7577

7678
// Let's return the downloaded S3 object's data from the
7779
// setup function to allow the default function to use it.
@@ -80,24 +82,26 @@ export function setup() {
8082
};
8183
}
8284

83-
export default function (data) {
85+
export default async function (data) {
8486
// Pick a random product ID from our test data
8587
const randomProductID = data.productIDs[Math.floor(Math.random() * data.productIDs.length)];
8688

8789
// Query our ecommerce website's product page using the ID
88-
const res = http.get(`http://your.website.com/product/${randomProductID}/`);
90+
const res = await http.asyncRequest("GET", `http://your.website.com/product/${randomProductID}/`);
8991
check(res, { 'is status 200': res.status === 200 });
9092
}
9193

92-
export function handleSummary(data) {
94+
export async function handleSummary(data) {
9395
// Once the load test is over, let's upload the results to our
9496
// S3 bucket. This is executed after teardown.
95-
s3.putObject(testBucketName, testOutputFileKey, JSON.stringify(data));
97+
await s3.putObject(testBucketName, testOutputFileKey, JSON.stringify(data));
9698
}
9799
```
98100

99101
</CodeGroup>
100102

103+
#### Multipart uploads
104+
101105
<CodeGroup labels={[]}>
102106

103107
```javascript
@@ -118,10 +122,10 @@ const s3 = new S3Client(awsConfig);
118122
const testBucketName = 'test-jslib-aws';
119123
const testFileKey = 'multipart.txt';
120124

121-
export default function () {
125+
export default async function () {
122126
// List the buckets the AWS authentication configuration
123127
// gives us access to.
124-
const buckets = s3.listBuckets();
128+
const buckets = await s3.listBuckets();
125129

126130
// If our test bucket does not exist, abort the execution.
127131
if (buckets.filter((b) => b.name === testBucketName).length == 0) {
@@ -134,11 +138,11 @@ export default function () {
134138
const bigFile = crypto.randomBytes(12 * 1024 * 1024);
135139

136140
// Initialize a multipart upload
137-
const multipartUpload = s3.createMultipartUpload(testBucketName, testFileKey);
141+
const multipartUpload = await s3.createMultipartUpload(testBucketName, testFileKey);
138142

139143
// Upload the first part
140144
const firstPartData = bigFile.slice(0, 6 * 1024 * 1024);
141-
const firstPart = s3.uploadPart(
145+
const firstPart = await s3.uploadPart(
142146
testBucketName,
143147
testFileKey,
144148
multipartUpload.uploadId,
@@ -148,7 +152,7 @@ export default function () {
148152

149153
// Upload the second part
150154
const secondPartData = bigFile.slice(6 * 1024 * 1024, 12 * 1024 * 1024);
151-
const secondPart = s3.uploadPart(
155+
const secondPart = await s3.uploadPart(
152156
testBucketName,
153157
testFileKey,
154158
multipartUpload.uploadId,
@@ -157,14 +161,14 @@ export default function () {
157161
);
158162

159163
// Complete the multipart upload
160-
s3.completeMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId, [
164+
await s3.completeMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId, [
161165
firstPart,
162166
secondPart,
163167
]);
164168

165169
// Let's redownload it verify it's correct, and delete it
166-
const obj = s3.getObject(testBucketName, testFileKey);
167-
s3.deleteObject(testBucketName, testFileKey);
170+
const obj = await s3.getObject(testBucketName, testFileKey);
171+
await s3.deleteObject(testBucketName, testFileKey);
168172
}
169173
```
170174

‎src/data/markdown/docs/20 jslib/01 jslib/01 aws/S3Client/00 abortMultipartUpload(bucketName, objectKey, uploadId).md‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,20 @@ excerpt: 'S3Client.abortMultipartUpload aborts a multipart upload to a bucket'
66

77
`S3Client.abortMultipartUpload` aborts a multipart upload to an S3 bucket.
88

9+
### Parameters
10+
911
| Parameter | Type | Description |
1012
| :--------- | :-------------------- | :----------------------------------------------------- |
1113
| bucketName | string | Name of the bucket to delete the multipart object from.|
1214
| objectKey | string | Name of the multipart object to delete. |
1315
| uploadId | number | UploadId of the multipart upload to abort. |
1416

17+
### Returns
18+
19+
| Type | Description |
20+
| :-------------- | :------------------------------------------------------------------ |
21+
| `Promise<void>` | A promise that fulfills when the multipart upload has been aborted. |
22+
1523
### Example
1624

1725
<CodeGroup labels={[]}>
@@ -31,12 +39,12 @@ const s3 = new S3Client(awsConfig);
3139
const testBucketName = 'test-jslib-aws';
3240
const testFileKey = 'multipart.txt';
3341

34-
export default function () {
42+
export default async function () {
3543
// Initialize a multipart upload
36-
const multipartUpload = s3.createMultipartUpload(testBucketName, testFileKey);
44+
const multipartUpload = await s3.createMultipartUpload(testBucketName, testFileKey);
3745

3846
// Abort multipart upload
39-
s3.abortMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId);
47+
await s3.abortMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId);
4048
}
4149
```
4250

‎src/data/markdown/docs/20 jslib/01 jslib/01 aws/S3Client/00 completeMultipartUpload(bucketName, objectKey, uploadId, parts).md‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,21 @@ excerpt: 'S3Client.completeMultipartUpload uploads a multipart object to a bucke
66

77
`S3Client.completeMultipartUpload` uploads a multipart object to an S3 bucket.
88

9+
### Parameters
10+
911
| Parameter | Type | Description |
1012
| :--------- | :------------------------------------------------------------- | :--------------------------------------------------------------------- |
1113
| bucketName | string | Name of the bucket to delete the object to. |
1214
| objectKey | string | Name of the uploaded object. |
1315
| uploadId | number | UploadId of the multipart upload to complete. |
1416
| parts | Array<[S3Part](/javascript-api/jslib/aws/s3client/s3part)> | The [S3Part](/javascript-api/jslib/aws/s3client/s3part)s to assemble. |
1517

18+
### Returns
19+
20+
| Type | Description |
21+
| :-------------- | :-------------------------------------------------------------------- |
22+
| `Promise<void>` | A Promise that fulfills when the multipart upload has been completed. |
23+
1624
### Example
1725

1826
<CodeGroup labels={[]}>
@@ -35,10 +43,10 @@ const s3 = new S3Client(awsConfig);
3543
const testBucketName = 'test-jslib-aws';
3644
const testFileKey = 'multipart.txt';
3745

38-
export default function () {
46+
export default async function () {
3947
// List the buckets the AWS authentication configuration
4048
// gives us access to.
41-
const buckets = s3.listBuckets();
49+
const buckets = await s3.listBuckets();
4250

4351
// If our test bucket does not exist, abort the execution.
4452
if (buckets.filter((b) => b.name === testBucketName).length == 0) {
@@ -51,11 +59,11 @@ export default function () {
5159
const bigFile = crypto.randomBytes(12 * 1024 * 1024);
5260

5361
// Initialize a multipart upload
54-
const multipartUpload = s3.createMultipartUpload(testBucketName, testFileKey);
62+
const multipartUpload = await s3.createMultipartUpload(testBucketName, testFileKey);
5563

5664
// Upload the first part
5765
const firstPartData = bigFile.slice(0, 6 * 1024 * 1024);
58-
const firstPart = s3.uploadPart(
66+
const firstPart = await s3.uploadPart(
5967
testBucketName,
6068
testFileKey,
6169
multipartUpload.uploadId,
@@ -65,7 +73,7 @@ export default function () {
6573

6674
// Upload the second part
6775
const secondPartData = bigFile.slice(6 * 1024 * 1024, 12 * 1024 * 1024);
68-
const secondPart = s3.uploadPart(
76+
const secondPart = await s3.uploadPart(
6977
testBucketName,
7078
testFileKey,
7179
multipartUpload.uploadId,
@@ -74,14 +82,14 @@ export default function () {
7482
);
7583

7684
// Complete the multipart upload
77-
s3.completeMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId, [
85+
await s3.completeMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId, [
7886
firstPart,
7987
secondPart,
8088
]);
8189

8290
// Let's redownload it verify it's correct, and delete it
83-
const obj = s3.getObject(testBucketName, testFileKey);
84-
s3.deleteObject(testBucketName, testFileKey);
91+
const obj = await s3.getObject(testBucketName, testFileKey);
92+
await s3.deleteObject(testBucketName, testFileKey);
8593
}
8694
```
8795

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

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,12 @@ excerpt: 'S3Client.copyObject copies an object from a bucket to another'
1515
| destinationBucket | string | Name of the bucket to copy the object to. |
1616
| destinationKey | string | Name of the destination object. |
1717

18+
### Returns
19+
20+
| Type | Description |
21+
| :-------------- | :---------------------------------------------------------------------------------- |
22+
| `Promise<void>` | A Promise that fulfills when the object has been copied from one bucket to another. |
23+
1824
### Example
1925

2026
<CodeGroup labels={[]}>
@@ -37,12 +43,12 @@ const testBucketName = 'test-jslib-aws';
3743
const testFileKey = 'bonjour.txt';
3844
const testDestinationBucketName = 'test-jslib-aws-destination';
3945

40-
export default function () {
46+
export default async function () {
4147
// Let's upload our test file to the bucket
42-
s3.putObject(testBucketName, testFileKey, testFile);
48+
await s3.putObject(testBucketName, testFileKey, testFile);
4349

4450
// Let's create our destination bucket
45-
s3.copyObject(testBucketName, testFileKey, testDestinationBucketName, testFileKey);
51+
await s3.copyObject(testBucketName, testFileKey, testDestinationBucketName, testFileKey);
4652
}
4753
```
4854

‎src/data/markdown/docs/20 jslib/01 jslib/01 aws/S3Client/00 createMultipartUpload(bucketName, objectKey).md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ excerpt: 'S3Client.createMultipartUpload creates a multipart upload to a bucket'
1515

1616
| Type | Description |
1717
| :----------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
18-
| [S3MultipartUpload](/javascript-api/jslib/aws/s3client/s3multipartupload) | An [S3MultipartUpload](/javascript-api/jslib/aws/s3client/s3multipartupload) representing a S3 Multipart Upload. |
18+
| Promise<[S3MultipartUpload](/javascript-api/jslib/aws/s3client/s3multipartupload)> | A Promise that fulfills with a [S3MultipartUpload](/javascript-api/jslib/aws/s3client/s3multipartupload) representing a S3 Multipart Upload. |
1919

2020
### Example
2121

@@ -36,12 +36,12 @@ const s3 = new S3Client(awsConfig);
3636
const testBucketName = 'test-jslib-aws';
3737
const testFileKey = 'multipart.txt';
3838

39-
export default function () {
39+
export default async function () {
4040
// Initialize a multipart upload
41-
const multipartUpload = s3.createMultipartUpload(testBucketName, testFileKey);
41+
const multipartUpload = await s3.createMultipartUpload(testBucketName, testFileKey);
4242

4343
// Abort multipart upload
44-
s3.abortMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId);
44+
await s3.abortMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId);
4545
}
4646
```
4747

‎src/data/markdown/docs/20 jslib/01 jslib/01 aws/S3Client/00 deleteObject(bucketName, objectKey).md‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,19 @@ excerpt: 'S3Client.deleteObject deletes an object from a bucket'
66

77
`S3Client.deleteObject` deletes an object from a bucket.
88

9+
### Parameters
10+
911
| Parameter | Type | Description |
1012
| :--------- | :-------------------- | :------------------------------------------- |
1113
| bucketName | string | Name of the bucket to delete the object from.|
1214
| objectKey | string | Name of the object to delete. |
1315

16+
### Returns
17+
18+
| Type | Description |
19+
| :-------------- | :------------------------------------------------------------------ |
20+
| `Promise<void>` | A promise that fulfills when the object has been deleted from S3. |
21+
1422
### Example
1523

1624
<CodeGroup labels={[]}>
@@ -30,12 +38,12 @@ const s3 = new S3Client(awsConfig);
3038
const testBucketName = 'test-jslib-aws';
3139
const testFileKey = 'bonjour.txt';
3240

33-
export default function () {
41+
export default async function () {
3442
// Let's delete our test object
35-
s3.deleteObject(testBucketName, testFileKey);
43+
await s3.deleteObject(testBucketName, testFileKey);
3644

3745
// And make sure it was indeed deleted
38-
const objects = s3.listObjects();
46+
const objects = await s3.listObjects();
3947
if (objects.filter((o) => o.name === testBucketName).length != 0) {
4048
exec.test.abort();
4149
}

‎src/data/markdown/docs/20 jslib/01 jslib/01 aws/S3Client/00 getObject(bucketName, objectKey).md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,18 @@ excerpt: 'S3Client.getObject downloads an object from a bucket'
66

77
`S3Client.getObject` downloads an object from a bucket.
88

9+
### Parameters
10+
911
| Parameter | Type | Description |
1012
| :--------- | :----- | :------------------------------------------- |
1113
| bucketName | string | Name of the bucket to fetch the object from. |
1214
| objectKey | string | Name of the object to download. |
1315

1416
### Returns
1517

16-
| Type | Description |
17-
| :-------------------------------------------------- | :---------------------------------------------------------------------------------------------------- |
18-
| [Object](/javascript-api/jslib/aws/s3client/object) | An [Object](/javascript-api/jslib/aws/s3client/object) describing and holding the downloaded content. |
18+
| Type | Description |
19+
| :----------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
20+
| Promise<[Object](/javascript-api/jslib/aws/s3client/object)> | A Promise that fulfills with an [Object](/javascript-api/jslib/aws/s3client/object) describing and holding the downloaded content. |
1921

2022
### Example
2123

@@ -36,16 +38,16 @@ const s3 = new S3Client(awsConfig);
3638
const testBucketName = 'test-jslib-aws';
3739
const testFileKey = 'bonjour.txt';
3840

39-
export default function () {
40-
const objects = s3.listObjects(testBucketName);
41+
export default async function () {
42+
const objects = await s3.listObjects(testBucketName);
4143

4244
// If our test object does not exist, abort the execution.
4345
if (objects.filter((o) => o.key === testFileKey).length == 0) {
4446
exec.test.abort();
4547
}
4648

4749
// Let's download our test object and print its content
48-
const object = s3.getObject(testBucketName, testFileKey);
50+
const object = await s3.getObject(testBucketName, testFileKey);
4951
console.log(JSON.stringify(object));
5052
}
5153
```

‎src/data/markdown/docs/20 jslib/01 jslib/01 aws/S3Client/00 listBuckets().md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@ excerpt: 'S3Client.listBuckets lists the buckets the authenticated user has acce
88

99
### Returns
1010

11-
| Type | Description |
12-
| :-------------- | :----------------------------------------------------------------------- |
13-
| Array<[Bucket](/javascript-api/jslib/aws/s3client/bucket)> | An array of [Bucket](/javascript-api/jslib/aws/s3client/bucket) objects. |
11+
| Type | Description |
12+
| :------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------- |
13+
| Promise<Array<[Bucket](/javascript-api/jslib/aws/s3client/bucket)>> | A Promise that fulfills with an array of [Bucket](/javascript-api/jslib/aws/s3client/bucket) objects. |
1414

1515
### Example
1616

@@ -30,10 +30,10 @@ const awsConfig = new AWSConfig({
3030
const s3 = new S3Client(awsConfig);
3131
const testBucketName = 'test-jslib-aws';
3232

33-
export default function () {
33+
export default async function () {
3434
// List the buckets the AWS authentication configuration
3535
// gives us access to.
36-
const buckets = s3.listBuckets();
36+
const buckets = await s3.listBuckets();
3737

3838
// If our test bucket does not exist, abort the execution.
3939
if (buckets.filter((b) => b.name === testBucketName).length == 0) {

0 commit comments

Comments
 (0)