Skip to content

Commit e52583a

Browse files
immavallsoleiade
immavalls
authored and
oleiade
committed
add docs for jslib aws S3 multipart upload
1 parent 4812c58 commit e52583a

7 files changed

+481
-8
lines changed

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

Lines changed: 84 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,17 @@ S3Client is included in both the dedicated jslib `s3.js` bundle, and the `aws.js
1313

1414
### Methods
1515

16-
| Function | Description |
17-
| :----------------------------------------------------------------------------------------------- | :---------------------------------------------------- |
18-
| [listBuckets()](/javascript-api/jslib/aws/s3client/s3client-listbuckets) | List the buckets the authenticated user has access to |
19-
| [listObjects(bucketName, [prefix])](/javascript-api/jslib/aws/s3client/s3client-listobjects/) | List the objects contained in a bucket |
20-
| [getObject(bucketName, objectKey)](/javascript-api/jslib/aws/s3client/s3client-getobject/) | Download an object from a bucket |
21-
| [putObject(bucketName, objectKey, data)](/javascript-api/jslib/aws/s3client/s3client-putobject/) | Upload an object to a bucket |
22-
| [deleteObject(bucketName, objectKey)](/javascript-api/jslib/aws/s3client/s3client-deleteobject/) | Delete an object from a bucket |
16+
| Function | Description |
17+
| :------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------|
18+
| [listBuckets()](/javascript-api/jslib/aws/s3client/s3client-listbuckets) | List the buckets the authenticated user has access to |
19+
| [listObjects(bucketName, [prefix])](/javascript-api/jslib/aws/s3client/s3client-listobjects/) | List the objects contained in a bucket |
20+
| [getObject(bucketName, objectKey)](/javascript-api/jslib/aws/s3client/s3client-getobject/) | Download an object from a bucket |
21+
| [putObject(bucketName, objectKey, data)](/javascript-api/jslib/aws/s3client/s3client-putobject/) | Upload an object to a bucket |
22+
| [deleteObject(bucketName, objectKey)](/javascript-api/jslib/aws/s3client/s3client-deleteobject/) | Delete an object from a bucket |
23+
| [createMultipartUpload(bucketName, objectKey)](/javascript-api/jslib/aws/s3client/s3client-createmultipartupload/) | Create a multipart upload for a given objectKey to a bucket |
24+
| [uploadPart(bucketName, objectKey, uploadId, partNumber, data)](/javascript-api/jslib/aws/s3client/s3client-uploadpart/) | Upload a part in a multipart upload |
25+
| [completeMultipartUpload(bucketName, objectKey, uploadId, parts)](/javascript-api/jslib/aws/s3client/s3client-completemultipartupload/) | Complete a previously assembled multipart upload |
26+
| [abortMultipartUpload(bucketName, objectKey, uploadId)](/javascript-api/jslib/aws/s3client/s3client-abortmultipartupload/) | Abort a multipart upload |
2327

2428
### Throws
2529

@@ -30,7 +34,7 @@ S3 Client methods will throw errors in case of failure.
3034
| InvalidSignatureError | when invalid credentials were provided. |
3135
| S3ServiceError | when AWS replied to the requested operation with an error. |
3236

33-
### Example
37+
### Examples
3438

3539
<CodeGroup labels={[]}>
3640

@@ -92,3 +96,75 @@ export function handleSummary(data) {
9296
```
9397

9498
</CodeGroup>
99+
100+
<CodeGroup labels={[]}>
101+
102+
```javascript
103+
import crypto from 'k6/crypto';
104+
import exec from 'k6/execution';
105+
106+
import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.8.0/s3.js';
107+
108+
const awsConfig = new AWSConfig({
109+
region: __ENV.AWS_REGION,
110+
accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
111+
secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
112+
sessionToken: __ENV.AWS_SESSION_TOKEN,
113+
});
114+
115+
const s3 = new S3Client(awsConfig);
116+
117+
const testBucketName = 'test-jslib-aws';
118+
const testFileKey = 'multipart.txt';
119+
120+
export default function () {
121+
// List the buckets the AWS authentication configuration
122+
// gives us access to.
123+
const buckets = s3.listBuckets();
124+
125+
// If our test bucket does not exist, abort the execution.
126+
if (buckets.filter((b) => b.name === testBucketName).length == 0) {
127+
exec.test.abort();
128+
}
129+
130+
// Produce random bytes to upload of size ~12MB, that
131+
// we will upload in two 6MB parts. This is done as the
132+
// minimum part size supported by S3 is 5MB.
133+
const bigFile = crypto.randomBytes(12 * 1024 * 1024);
134+
135+
// Initialize a multipart upload
136+
const multipartUpload = s3.createMultipartUpload(testBucketName, testFileKey);
137+
138+
// Upload the first part
139+
const firstPartData = bigFile.slice(0, 6 * 1024 * 1024);
140+
const firstPart = s3.uploadPart(
141+
testBucketName,
142+
testFileKey,
143+
multipartUpload.uploadId,
144+
1,
145+
firstPartData
146+
);
147+
148+
// Upload the second part
149+
const secondPartData = bigFile.slice(6 * 1024 * 1024, 12 * 1024 * 1024);
150+
const secondPart = s3.uploadPart(
151+
testBucketName,
152+
testFileKey,
153+
multipartUpload.uploadId,
154+
2,
155+
secondPartData
156+
);
157+
158+
// Complete the multipart upload
159+
s3.completeMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId, [
160+
firstPart,
161+
secondPart,
162+
]);
163+
164+
// Let's redownload it verify it's correct, and delete it
165+
const obj = s3.getObject(testBucketName, testFileKey);
166+
s3.deleteObject(testBucketName, testFileKey);
167+
}
168+
```
169+
170+
</CodeGroup>

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

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: 'S3Client.abortMultipartUpload(bucketName, objectKey, uploadId)'
3+
description: 'S3Client.abortMultipartUpload aborts a multipart upload to a bucket'
4+
excerpt: 'S3Client.abortMultipartUpload aborts a multipart upload to a bucket'
5+
---
6+
7+
`S3Client.abortMultipartUpload` aborts a multipart upload to an S3 bucket.
8+
9+
| Parameter | Type | Description |
10+
| :--------- | :-------------------- | :----------------------------------------------------- |
11+
| bucketName | string | Name of the bucket to delete the multipart object from.|
12+
| objectKey | string | Name of the multipart object to delete. |
13+
| uploadId | number | UploadId of the multipart upload to abort. |
14+
15+
### Example
16+
17+
<CodeGroup labels={[]}>
18+
19+
```javascript
20+
import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.8.0/s3.js';
21+
22+
const awsConfig = new AWSConfig({
23+
region: __ENV.AWS_REGION,
24+
accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
25+
secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
26+
sessionToken: __ENV.AWS_SESSION_TOKEN,
27+
});
28+
29+
const s3 = new S3Client(awsConfig);
30+
31+
const testBucketName = 'test-jslib-aws';
32+
const testFileKey = 'multipart.txt';
33+
34+
export default function () {
35+
// Initialize a multipart upload
36+
const multipartUpload = s3.createMultipartUpload(testBucketName, testFileKey);
37+
38+
// Abort multipart upload
39+
s3.abortMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId);
40+
}
41+
```
42+
43+
_A k6 script that will create a multipart upload and abort the multipart_
44+
45+
</CodeGroup>

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

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: 'S3Client.completeMultipartUpload(bucketName, objectKey, uploadId, parts)'
3+
description: 'S3Client.completeMultipartUpload uploads a multipar object to a bucket'
4+
excerpt: 'S3Client.completeMultipartUpload uploads a multipart object to a bucket'
5+
---
6+
7+
`S3Client.completeMultipartUpload` uploads a multipart object to an S3 bucket.
8+
9+
| Parameter | Type | Description |
10+
| :--------- | :------------------------------------------------------------- | :--------------------------------------------------------------------- |
11+
| bucketName | string | Name of the bucket to delete the object to. |
12+
| objectKey | string | Name of the uploaded object. |
13+
| uploadId | number | UploadId of the multipart upload to complete. |
14+
| parts | Array<[S3Part](/javascript-api/jslib/aws/s3client/s3part)> | The [S3Part](/javascript-api/jslib/aws/s3client/s3part)s to assemble. |
15+
16+
### Example
17+
18+
<CodeGroup labels={[]}>
19+
20+
```javascript
21+
import crypto from 'k6/crypto';
22+
import exec from 'k6/execution';
23+
24+
import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.8.0/s3.js';
25+
26+
const awsConfig = new AWSConfig({
27+
region: __ENV.AWS_REGION,
28+
accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
29+
secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
30+
sessionToken: __ENV.AWS_SESSION_TOKEN,
31+
});
32+
33+
const s3 = new S3Client(awsConfig);
34+
35+
const testBucketName = 'test-jslib-aws';
36+
const testFileKey = 'multipart.txt';
37+
38+
export default function () {
39+
// List the buckets the AWS authentication configuration
40+
// gives us access to.
41+
const buckets = s3.listBuckets();
42+
43+
// If our test bucket does not exist, abort the execution.
44+
if (buckets.filter((b) => b.name === testBucketName).length == 0) {
45+
exec.test.abort();
46+
}
47+
48+
// Produce random bytes to upload of size ~12MB, that
49+
// we will upload in two 6MB parts. This is done as the
50+
// minimum part size supported by S3 is 5MB.
51+
const bigFile = crypto.randomBytes(12 * 1024 * 1024);
52+
53+
// Initialize a multipart upload
54+
const multipartUpload = s3.createMultipartUpload(testBucketName, testFileKey);
55+
56+
// Upload the first part
57+
const firstPartData = bigFile.slice(0, 6 * 1024 * 1024);
58+
const firstPart = s3.uploadPart(
59+
testBucketName,
60+
testFileKey,
61+
multipartUpload.uploadId,
62+
1,
63+
firstPartData
64+
);
65+
66+
// Upload the second part
67+
const secondPartData = bigFile.slice(6 * 1024 * 1024, 12 * 1024 * 1024);
68+
const secondPart = s3.uploadPart(
69+
testBucketName,
70+
testFileKey,
71+
multipartUpload.uploadId,
72+
2,
73+
secondPartData
74+
);
75+
76+
// Complete the multipart upload
77+
s3.completeMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId, [
78+
firstPart,
79+
secondPart,
80+
]);
81+
82+
// Let's redownload it verify it's correct, and delete it
83+
const obj = s3.getObject(testBucketName, testFileKey);
84+
s3.deleteObject(testBucketName, testFileKey);
85+
}
86+
```
87+
88+
_A k6 script that will upload a multipart upload to an S3 bucket_
89+
90+
</CodeGroup>

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

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: 'S3Client.createMultipartUpload(bucketName, objectKey)'
3+
description: 'S3Client.createMultipartUpload creates a multipart upload for an object key to a bucket'
4+
excerpt: 'S3Client.createMultipartUpload creates a multipart upload to a bucket'
5+
---
6+
7+
`S3Client.createMultipartUpload` creates a new multipart upload for a given an object key in a bucket.
8+
9+
| Parameter | Type | Description |
10+
| :--------- | :-------------------- | :------------------------------------------- |
11+
| bucketName | string | Name of the bucket to upload the object to. |
12+
| objectKey | string | Name of the uploaded object. |
13+
14+
### Returns
15+
16+
| Type | Description |
17+
| :----------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
18+
| [S3MultipartUpload](/javascript-api/jslib/aws/s3client/s3multipartupload) | An [S3MultipartUpload](/javascript-api/jslib/aws/s3client/s3multipartupload) representing a S3 Multipart Upload. |
19+
20+
### Example
21+
22+
<CodeGroup labels={[]}>
23+
24+
```javascript
25+
import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.8.0/s3.js';
26+
27+
const awsConfig = new AWSConfig({
28+
region: __ENV.AWS_REGION,
29+
accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
30+
secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
31+
sessionToken: __ENV.AWS_SESSION_TOKEN,
32+
});
33+
34+
const s3 = new S3Client(awsConfig);
35+
36+
const testBucketName = 'test-jslib-aws';
37+
const testFileKey = 'multipart.txt';
38+
39+
export default function () {
40+
// Initialize a multipart upload
41+
const multipartUpload = s3.createMultipartUpload(testBucketName, testFileKey);
42+
43+
// Abort multipart upload
44+
s3.abortMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId);
45+
}
46+
```
47+
48+
_A k6 script that will create a multipart upload to an S3 bucket_
49+
50+
</CodeGroup>

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

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: 'S3Client.uploadPart(bucketName, objectKey, uploadId,partNumber, data)'
3+
description: 'S3Client.uploadPart a part in a multipart upload to a bucket'
4+
excerpt: 'S3Client.uploadPart a part in a multipart upload to a bucket'
5+
---
6+
7+
`S3Client.uploadPart` uploads a part to multipart upload in a bucket.
8+
9+
| Parameter | Type | Description |
10+
| :--------- | :-------------------- | :------------------------------------------- |
11+
| bucketName | string | Name of the bucket to upload the object to. |
12+
| objectKey | string | Name of the object to upload. |
13+
| uploadId | string | UploadId of the multipart upload. |
14+
| partNumber | number | The Part number of the Part to upload. |
15+
| data | string \| ArrayBuffer | Content of the part to upload. |
16+
17+
### Returns
18+
19+
| Type | Description |
20+
| :---------------------------------------------------- | :--------------------------------------------------------------------------------------- |
21+
| [S3Part](/javascript-api/jslib/aws/s3client/s3part) | An [S3Part](/javascript-api/jslib/aws/s3client/s3part) representing a S3 Part Upload. |
22+
23+
### Example
24+
25+
<CodeGroup labels={[]}>
26+
27+
```javascript
28+
import crypto from 'k6/crypto';
29+
import exec from 'k6/execution';
30+
31+
import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.8.0/s3.js';
32+
33+
const awsConfig = new AWSConfig({
34+
region: __ENV.AWS_REGION,
35+
accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
36+
secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
37+
sessionToken: __ENV.AWS_SESSION_TOKEN,
38+
});
39+
40+
const s3 = new S3Client(awsConfig);
41+
42+
const testBucketName = 'test-jslib-aws';
43+
const testFileKey = 'multipart.txt';
44+
45+
export default function () {
46+
// Produce random bytes to upload of size ~12MB, that
47+
// we will upload in two 6MB parts. This is done as the
48+
// minimum part size supported by S3 is 5MB.
49+
const bigFile = crypto.randomBytes(12 * 1024 * 1024);
50+
51+
// Initialize a multipart upload
52+
const multipartUpload = s3.createMultipartUpload(testBucketName, testFileKey);
53+
54+
// Upload the first part
55+
const firstPartData = bigFile.slice(0, 6 * 1024 * 1024);
56+
const firstPart = s3.uploadPart(
57+
testBucketName,
58+
testFileKey,
59+
multipartUpload.uploadId,
60+
1,
61+
firstPartData
62+
);
63+
64+
// Upload the second part
65+
const secondPartData = bigFile.slice(6 * 1024 * 1024, 12 * 1024 * 1024);
66+
const secondPart = s3.uploadPart(
67+
testBucketName,
68+
testFileKey,
69+
multipartUpload.uploadId,
70+
2,
71+
secondPartData
72+
);
73+
74+
// Complete the multipart upload
75+
s3.completeMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId, [
76+
firstPart,
77+
secondPart,
78+
]);
79+
80+
// Let's redownload it verify it's correct, and delete it
81+
const obj = s3.getObject(testBucketName, testFileKey);
82+
s3.deleteObject(testBucketName, testFileKey);
83+
}
84+
```
85+
86+
_A k6 script that will upload a part in a multipart upload to an S3 bucket_
87+
88+
</CodeGroup>

0 commit comments

Comments
 (0)