Skip to content

Commit 8630ee9

Browse files
oleiadeoleiade
authored
Merge pull request #1979 from grafana/aws/v0.14.0
Document k6-jslib-aws v0.14.0
2 parents b3a425b + 5a2277b commit 8630ee9

File tree

322 files changed

+8207
-1278
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

322 files changed

+8207
-1278
lines changed

‎docs/sources/k6/_index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ cascade:
1919
github_branch: main
2020
github_dir: /docs/sources/k6
2121
replace_dir: docs/k6/
22-
JSLIB_AWS_VERSION: 0.13.0
22+
JSLIB_AWS_VERSION: 0.14.0
2323
JSLIB_PYROSCOPE_VERSION: 1.0.2
2424
JSLIB_TEMPO_VERSION: 1.0.1
2525
versioned: true

‎docs/sources/k6/next/javascript-api/jslib/aws/S3Client/S3UploadedObject.md

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
title: 'S3UploadedObject'
3+
head_title: 'S3UploadedObject'
4+
description: 'S3UploadedObject represents the response from S3 upload operations'
5+
weight: 20
6+
---
7+
8+
# S3UploadedObject
9+
10+
`S3UploadedObject` represents the response returned by S3 upload operations such as [`putObject`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/aws/s3client/putobject) and [`completeMultipartUpload`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/aws/s3client/completemultipartupload). It contains metadata about the uploaded object, including checksums and upload verification information.
11+
12+
## Properties
13+
14+
| Name | Type | Description |
15+
| :----------- | :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
16+
| eTag | string | The entity tag (ETag) of the uploaded object. This is a hash of the object that can be used to verify the integrity of the uploaded data. |
17+
| crc32 | string (optional) | The base64-encoded CRC32 checksum of the uploaded object, if available. |
18+
| crc32c | string (optional) | The base64-encoded CRC32C checksum of the uploaded object, if available. |
19+
| crc64nvme | string (optional) | The base64-encoded CRC64NVME checksum of the uploaded object, if available. |
20+
| sha1 | string (optional) | The base64-encoded SHA1 checksum of the uploaded object, if available. |
21+
| sha256 | string (optional) | The base64-encoded SHA256 checksum of the uploaded object, if available. |
22+
| checksumType | string (optional) | The type of checksum algorithm used. Can be "COMPOSITE" for multipart uploads or "FULL_OBJECT" for single-part uploads. |
23+
| size | number (optional) | The size of the uploaded object in bytes, if available. |
24+
25+
## Example
26+
27+
{{< code >}}
28+
29+
<!-- md-k6:skip -->
30+
31+
```javascript
32+
import {
33+
AWSConfig,
34+
S3Client,
35+
} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/s3.js';
36+
37+
const awsConfig = new AWSConfig({
38+
region: __ENV.AWS_REGION,
39+
accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
40+
secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
41+
});
42+
43+
const s3 = new S3Client(awsConfig);
44+
const testBucketName = 'test-jslib-aws';
45+
const testFileKey = 'test-file.txt';
46+
47+
export default async function () {
48+
const testData = 'Hello, World!';
49+
50+
// Upload the object and get the upload response
51+
const uploadResult = await s3.putObject(testBucketName, testFileKey, testData);
52+
53+
// Access the upload metadata
54+
console.log('Upload ETag:', uploadResult.eTag);
55+
console.log('Object size:', uploadResult.size);
56+
57+
// Check if checksums are available
58+
if (uploadResult.sha256) {
59+
console.log('SHA256 checksum:', uploadResult.sha256);
60+
}
61+
62+
if (uploadResult.checksumType) {
63+
console.log('Checksum type:', uploadResult.checksumType);
64+
}
65+
66+
// Verify the upload was successful
67+
if (uploadResult.eTag) {
68+
console.log('Upload successful, ETag received:', uploadResult.eTag);
69+
}
70+
}
71+
```
72+
73+
{{< /code >}}
74+
75+
## Usage in Multipart Uploads
76+
77+
For multipart uploads, the `S3UploadedObject` is returned by the `completeMultipartUpload` method:
78+
79+
{{< code >}}
80+
81+
<!-- md-k6:skip -->
82+
83+
```javascript
84+
import crypto from 'k6/crypto';
85+
import {
86+
AWSConfig,
87+
S3Client,
88+
} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/s3.js';
89+
90+
const awsConfig = new AWSConfig({
91+
region: __ENV.AWS_REGION,
92+
accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
93+
secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
94+
});
95+
96+
const s3 = new S3Client(awsConfig);
97+
98+
export default async function () {
99+
const testBucketName = 'test-jslib-aws';
100+
const testFileKey = 'large-file.txt';
101+
102+
// Create large file data
103+
const bigFile = crypto.randomBytes(12 * 1024 * 1024); // 12MB
104+
105+
// Initialize multipart upload
106+
const multipartUpload = await s3.createMultipartUpload(testBucketName, testFileKey);
107+
108+
// Upload parts
109+
const firstPart = await s3.uploadPart(
110+
testBucketName,
111+
testFileKey,
112+
multipartUpload.uploadId,
113+
1,
114+
bigFile.slice(0, 6 * 1024 * 1024)
115+
);
116+
117+
const secondPart = await s3.uploadPart(
118+
testBucketName,
119+
testFileKey,
120+
multipartUpload.uploadId,
121+
2,
122+
bigFile.slice(6 * 1024 * 1024)
123+
);
124+
125+
// Complete the multipart upload and get the result
126+
const uploadResult = await s3.completeMultipartUpload(
127+
testBucketName,
128+
testFileKey,
129+
multipartUpload.uploadId,
130+
[firstPart, secondPart]
131+
);
132+
133+
// Access the completed upload metadata
134+
console.log('Multipart upload ETag:', uploadResult.eTag);
135+
console.log('Checksum type:', uploadResult.checksumType); // Likely "COMPOSITE"
136+
137+
if (uploadResult.size) {
138+
console.log('Total object size:', uploadResult.size);
139+
}
140+
}
141+
```
142+
143+
{{< /code >}}

‎docs/sources/k6/next/javascript-api/jslib/aws/S3Client/completeMultipartUpload.md

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -20,14 +20,16 @@ weight: 10
2020

2121
### Returns
2222

23-
| Type | Description |
24-
| :-------------- | :-------------------------------------------------------------------- |
25-
| `Promise<void>` | A Promise that fulfills when the multipart upload has been completed. |
23+
| Type | Description |
24+
| :----------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
25+
| Promise<[S3UploadedObject](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/aws/s3client/s3uploadedobject)> | A Promise that fulfills with an [S3UploadedObject](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/aws/s3client/s3uploadedobject) containing metadata about the completed multipart upload, including ETag and optional checksums. |
2626

2727
### Example
2828

2929
{{< code >}}
3030

31+
<!-- md-k6:skip -->
32+
3133
```javascript
3234
import crypto from 'k6/crypto';
3335
import exec from 'k6/execution';
@@ -88,10 +90,24 @@ export default async function () {
8890
);
8991

9092
// Complete the multipart upload
91-
await s3.completeMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId, [
92-
firstPart,
93-
secondPart,
94-
]);
93+
const uploadResult = await s3.completeMultipartUpload(
94+
testBucketName,
95+
testFileKey,
96+
multipartUpload.uploadId,
97+
[firstPart, secondPart]
98+
);
99+
100+
// Access the upload metadata
101+
console.log('Multipart upload completed! ETag:', uploadResult.eTag);
102+
103+
if (uploadResult.size) {
104+
console.log('Total object size:', uploadResult.size);
105+
}
106+
107+
// For multipart uploads, the checksum type will typically be "COMPOSITE"
108+
if (uploadResult.checksumType) {
109+
console.log('Checksum type:', uploadResult.checksumType);
110+
}
95111

96112
// Let's redownload it verify it's correct, and delete it
97113
const obj = await s3.getObject(testBucketName, testFileKey);

‎docs/sources/k6/next/javascript-api/jslib/aws/S3Client/putObject.md

Lines changed: 31 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -11,33 +11,35 @@ weight: 10
1111

1212
### Parameters
1313

14-
| Parameter | Type | Description |
15-
| :----------- | :--------------------------------------------- | :------------------------------------------ |
16-
| `bucketName` | string | Name of the bucket to upload the object to. |
17-
| `objectKey` | string | Name of the uploaded object. |
18-
| `data` | string \| ArrayBuffer | Content of the object to upload. |
19-
| `params` | [PutObjectParams](#putobjectparams) (optional) | Options for the request. |
14+
| Parameter | Type | Description |
15+
| :--------- | :--------------------------------------------- | :------------------------------------------ |
16+
| bucketName | string | Name of the bucket to upload the object to. |
17+
| objectKey | string | Name of the uploaded object. |
18+
| data | string \| ArrayBuffer | Content of the object to upload. |
19+
| params | [PutObjectParams](#putobjectparams) (optional) | Options for the request. |
2020

2121
#### PutObjectParams
2222

23-
| Name | Type | Description |
24-
| :------------------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
25-
| `contentDisposition` | string (optional) | Specifies presentational information for the object. For more information, see [RFC 6266](https://tools.ietf.org/html/rfc6266). |
26-
| `contentEncoding` | string (optional) | Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field. For more information, see [RFC 2616](https://tools.ietf.org/html/rfc2616). |
27-
| `contentLength` | number (optional) | Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically. |
28-
| `contentMD5` | string (optional) | The base64-encoded 128-bit MD5 digest of the message (without the headers) according to RFC 1864. This header can be used as a message integrity check to verify that the received message is identical to the message that was sent. |
29-
| `contentType` | string (optional) | A standard MIME type describing the format of the object data. For more information, see [RFC 2616](https://tools.ietf.org/html/rfc2616). |
23+
| Name | Type | Description |
24+
| :----------------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
25+
| contentDisposition | string (optional) | Specifies presentational information for the object. For more information, see [RFC 6266](https://tools.ietf.org/html/rfc6266). |
26+
| contentEncoding | string (optional) | Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field. For more information, see [RFC 2616](https://tools.ietf.org/html/rfc2616). |
27+
| contentLength | number (optional) | Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically. |
28+
| contentMD5 | string (optional) | The base64-encoded 128-bit MD5 digest of the message (without the headers) according to RFC 1864. This header can be used as a message integrity check to verify that the received message is identical to the message that was sent. |
29+
| contentType | string (optional) | A standard MIME type describing the format of the object data. For more information, see [RFC 2616](https://tools.ietf.org/html/rfc2616). |
3030

3131
### Returns
3232

33-
| Type | Description |
34-
| :-------------- | :-------------------------------------------------------------------------- |
35-
| `Promise<void>` | A Promise that fulfills when the object has been uploaded to the S3 bucket. |
33+
| Type | Description |
34+
| :----------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
35+
| Promise<[S3UploadedObject](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/aws/s3client/s3uploadedobject)> | A Promise that fulfills with an [S3UploadedObject](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/aws/s3client/s3uploadedobject) containing metadata about the uploaded object, including ETag and optional checksums. |
3636

3737
### Example
3838

3939
{{< code >}}
4040

41+
<!-- md-k6:skip -->
42+
4143
```javascript
4244
import {
4345
AWSConfig,
@@ -57,11 +59,23 @@ const testFile = open('./bonjour.txt', 'r');
5759

5860
export default async function () {
5961
// Let's upload our test file to the bucket
60-
await s3.putObject(testBucketName, testFileKey, testFile, {
62+
const uploadResult = await s3.putObject(testBucketName, testFileKey, testFile, {
6163
contentType: 'text/plain',
6264
contentLength: testFile.length,
6365
});
6466

67+
// Access the upload metadata
68+
console.log('Upload successful! ETag:', uploadResult.eTag);
69+
70+
if (uploadResult.size) {
71+
console.log('Object size:', uploadResult.size);
72+
}
73+
74+
// Check if checksums are available
75+
if (uploadResult.sha256) {
76+
console.log('SHA256 checksum:', uploadResult.sha256);
77+
}
78+
6579
// And let's redownload it to verify it's correct
6680
const obj = await s3.getObject(testBucketName, testFileKey);
6781
console.log(JSON.stringify(obj));

‎docs/sources/k6/next/javascript-api/jslib/aws/SQSClient/_index.md

Lines changed: 24 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,16 +10,19 @@ weight: 00
1010

1111
`SQSClient` interacts with the AWS Simple Queue Service (SQS).
1212

13-
With it, the user can send messages to specified queues and list available queues in the current region.
13+
With it, the user can send messages to specified queues, receive messages from queues, delete processed messages, and list available queues in the current region.
1414

1515
`SQSClient` is included in both the dedicated `sqs.js` jslib bundle and the all-encompassing `aws.js` one, containing all the services clients.
1616

1717
### Methods
1818

19-
| Function | Description |
20-
| :------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |
21-
| [`sendMessage`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/aws/sqsclient/sendmessage) | Delivers a message to the specified queue. |
22-
| [`listQueues`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/aws/sqsclient/listqueues) | Returns a list of your queues in the current region. |
19+
| Function | Description |
20+
| :--------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |
21+
| [sendMessage](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/aws/sqsclient/sendmessage) | Delivers a message to the specified queue. |
22+
| [sendMessageBatch](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/aws/sqsclient/sendmessagebatch) | Delivers up to ten messages to the specified queue. |
23+
| [receiveMessages](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/aws/sqsclient/receivemessages) | Receives messages from the specified queue. |
24+
| [deleteMessage](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/aws/sqsclient/deletemessage) | Deletes a message from the specified queue. |
25+
| [listQueues](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/aws/sqsclient/listqueues) | Returns a list of your queues in the current region. |
2326

2427
### Throws
2528

@@ -34,6 +37,8 @@ With it, the user can send messages to specified queues and list available queue
3437

3538
{{< code >}}
3639

40+
<!-- md-k6:skip -->
41+
3742
```javascript
3843
import exec from 'k6/execution';
3944

@@ -61,6 +66,20 @@ export default async function () {
6166

6267
// Send message to test queue
6368
await sqs.sendMessage(testQueue, JSON.stringify({ value: '123' }));
69+
70+
// Receive messages from the queue
71+
const messages = await sqs.receiveMessages(testQueue, {
72+
maxNumberOfMessages: 10,
73+
waitTimeSeconds: 2,
74+
});
75+
76+
// Process and delete each received message
77+
for (const message of messages) {
78+
console.log('Processing message:', message.body);
79+
80+
// Delete the message after processing
81+
await sqs.deleteMessage(testQueue, message.receiptHandle);
82+
}
6483
}
6584
```
6685

0 commit comments

Comments
 (0)