xk6-epicchain

Overview

The xk6-epicchain extension integrates with the k6 performance testing tool, allowing you to extend its capabilities to interact with the EpicChain platform. This guide provides detailed instructions on how to build the k6 binary with this extension and offers comprehensive API documentation for both the native and S3 clients.

Build Instructions

To build the k6 binary with the xk6-epicchain extension, ensure that you have the following prerequisites installed on your system:

• Go: The Go programming language is necessary for building the k6 binary.
• Git: This version control system is needed to clone the repository.

Step 1: Clone the Repository

First, you need to clone the xk6-epicchain repository from GitHub. Open your terminal and execute:

git clone https://github.com/nspcc-dev/xk6-epicchain

After cloning, navigate to the directory:

cd xk6-epicchain

Step 2: Install xk6 Framework

The xk6 framework extends k6 with additional functionalities. Install the xk6 framework by running:

make install_xk6

This command will set up the xk6 framework, which is required for building the custom k6 binary.

Step 3: Build the Binary

With xk6 installed, you can now build the k6 binary with the EpicChain extension. Use the following command:

make build

This will compile the k6 binary along with the xk6-epicchain extension, preparing it for execution.

Step 4: Run k6 with the Extension

Once the binary is built, you can use it to run performance tests with EpicChain capabilities. Execute the following command, replacing test-script.js with your actual test script:

./xk6-epicchain run test-script.js

This command runs k6 with the xk6-epicchain extension, executing the specified test script.

API Documentation

Native Client

The native client allows direct interaction with EpicChain storage nodes. To create a native client, use the connect method with these parameters:

• epicchain storage node endpoint: The URL of the EpicChain storage node.
• hex encoded private key: A hexadecimal format private key. An empty value generates a random key.
• dial timeout: The connection timeout duration in seconds (0 for default).
• stream timeout: The streaming timeout duration in seconds (0 for default).

Here’s how to create a native client:

import native "k6/x/epicchain/native"
epicchain_cli := native.Connect("s01.epicchain.devenv:8080", "", 0, 0)

Methods

• PutContainer(params): Creates a new container. params is a dictionary with:

  • acl: Access control list (e.g., 'public-read-write').
  • placement_policy: Placement policy (e.g., 'REP 3').
  • name: Container name.
  • name_global_scope: Global scope flag ('true' or 'false').

  Returns a dictionary with:

  • success: Boolean indicating success.
  • container_id: ID of the created container.
  • error: Error message, if any.

• SetBufferSize(size): Sets the internal buffer size for data operations. Default is 64 KiB.

• Put(container_id, headers, payload): Uploads data to a specified container. Arguments are:

  • container_id: Container ID.
  • headers: Optional headers for the upload.
  • payload: Data to be uploaded.

  Returns a dictionary with:

  • success: Boolean indicating success.
  • object_id: ID of the uploaded object.
  • error: Error message, if any.

• Get(container_id, object_id): Retrieves data from a specified container. Arguments are:

  • container_id: Container ID.
  • object_id: Object ID.

  Returns a dictionary with:

  • success: Boolean indicating success.
  • error: Error message, if any.

• Onsite(container_id, payload): Prepares data for upload to EpicChain. Arguments are:

  • container_id: Container ID.
  • payload: Data to be uploaded.

  Returns an EpicChain object with prepared headers. Use the Put(headers) method on this object to upload data. Returns:

  • success: Boolean indicating success.
  • object_id: ID of the prepared object.
  • error: Error message, if any.

S3 Client

The S3 client facilitates interaction with EpicChain's S3-compatible gateway. To create an S3 client, use the connect method with:

• s3 gateway endpoint: URL of the S3-compatible gateway.

Credentials are automatically sourced from AWS configuration files and environment variables.

Here’s how to create an S3 client:

import s3 "k6/x/epicchain/s3"
s3_cli := s3.Connect("http://s3.epicchain.devenv:8080")

Additional options can be provided:

import s3 "k6/x/epicchain/s3"
s3_cli := s3.Connect("http://s3.epicchain.devenv:8080", map[string]interface{}{
    "no_verify_ssl": "true",
    "timeout": "60s",
})

Additional options include:

• no_verify_ssl: Boolean. If true, skips SSL certificate verification (useful for self-signed certificates).
• timeout: Duration. Sets request timeout in the HTTP client. If omitted or zero, the timeout is infinite.

Methods

• CreateBucket(bucket, params): Creates a new bucket. Arguments are:

  • bucket: Bucket name.
  • params: Dictionary with optional parameters:
    • acl: Access control list (e.g., 'private').
    • lock_enabled: Bucket lock status ('true' or 'false').
    • location_constraint: Location constraint (e.g., 'ru').

  Returns a dictionary with:

  • success: Boolean indicating success.
  • error: Error message, if any.

• Put(bucket, key, payload): Uploads data to a specified bucket. Arguments are:

  • bucket: Bucket name.
  • key: Key for the data.
  • payload: Data to be uploaded.

  Returns a dictionary with:

  • success: Boolean indicating success.
  • error: Error message, if any.

• Get(bucket, key): Retrieves data from a specified bucket. Arguments are:

  • bucket: Bucket name.
  • key: Key for the data.

  Returns a dictionary with:

  • success: Boolean indicating success.
  • error: Error message, if any.

Examples

For practical examples and sample code demonstrating the use of the native protocol and S3 client, refer to the examples directory in this repository. These examples illustrate various use cases and provide guidance on how to leverage the extension effectively.

License

The xk6-epicchain extension is licensed under the GNU General Public License v3.0. This license allows for free use, modification, and distribution of the software in accordance with its terms.