V0.4.0

[szkiba]

Main new features:

• Builder Service #17
• Filter Extension Registry #20
• Build Cache Location Override #18
• Module replacement #19

Builder Service

The k6x builder service is an HTTP service that generates a k6 binary with the extensions specified in the request. The service is included in the k6x binary, so it can be started using the k6x service command.

The k6x builder service can be used independently, from the command line (e.g. using curl or wget commands), from a web browser, or from different subcommands of the k6x launcher as a builder called service.

Usage from the command line

The k6 binary can be easily built using wget , curl or other command-line http client by retrieving the appropriate builder service URL:

using wget

wget --content-disposition https://example.com/linux/amd64/k6@v0.46.0,dashboard@v0.6.0,k6/x/faker@v0.2.2,top@v0.1.1

using curl

curl -OJ https://example.com/linux/amd64/k6@v0.46.0,dashboard@v0.6.0,k6/x/faker@v0.2.2,top@v0.1.1

Usage from k6x

The builder service can be used from k6x using the --builder service flag:

k6x run --builder service script.js

k6x expects the address of the builder service in the environment variable called K6X_BUILDER_SERVICE. There is currently no default, it must be specified.

Simplified command line usage

In order to simplify use from the command line, the service also accepts version dependencies in any order. In this case, after unlocking the latest versions and sorting, the response will be an HTTP redirect.

using wget

wget --content-disposition https://example.com/linux/amd64/top,k6/x/faker,dashboard

using curl

curl -OJL https://example.com/linux/amd64/top,k6/x/faker,dashboard

How It Works

The service serves HTTP GET requests, with a well-defined path structure:

htps://example.com/goos/goarch/dependency-list

Where goos is the usual operating system name in the go language (e.g. linux, windows, darwin), goarch is the usual processor architecture in the go language (e.g. amd64, arm64). The dependency-list is a comma-separated list of dependencies, in the following form:

name@version

Where name is the name of the dependency and version is the version number according to semver (with an optional leading v character). The first item in the list is always the dependency named k6, and the other items are sorted alphabetically by name. For example:

https://example.com/linux/amd64/k6@v0.46.0,dashboard@v0.6.0,k6/x/faker@v0.2.2,top@v0.1.1

Based on the platform parameters (goos, goarch) and dependencies, the service prepares the k6 binary.

Since the response (the k6 binary) depends only on the request path, it can be easily cached. The service therefore sets a sufficiently long caching period (at least one year) in the response, as well as the usual cache headers (e.g. ETag). By placing a caching proxy in front of the service, it can be ensured that the actual k6 binary build takes place only once for each parameter combination.

The advantage of the solution is that the k6 binary is created on the fly, only for the parameter combinations that are actually used. Since the service preserves the go cache between builds, a specific build happens quickly enough.

Filter Extension Registry

In certain runtime environments, the use of arbitrary extensions is not allowed. There is a need to limit the extensions that can be used.

This use case can be solved most flexibly by narrowing down the extension registry. The content of the extension registry can be narrowed using a jmespath syntax filter expression. Extensions can be filtered based on any property.

allow only officially supported extensions

k6x --filter "[?contains(tiers,'Official')]" run script.js

allow only cloud enabled extensions

k6x --filter "[?cloudEnabled == true]" run script.js

Build Cache Location Override

Reusable artifacts (k6 binary, HTTP responses) are stored in the subdirectory k6x under the directory defined by the XDG_CACHE_HOME environment variable. The default of XDG_CACHE_HOME depends on the operating system (Windows: %LOCALAPPDATA%\cache, Linux: ~/.cache, macOS: ~/Library/Caches). The default cache directory now can be changed using the K6X_CACHE_DIR environment variable or the --cache-dir flag.

Module Replacement

In some cases, it can be useful to use another path instead of the module path registered in the extension registry. For example, using a forked repository, or using a local file-system path in the case of a native builder. These use cases can be solved by the module replacement feature.

Usage:

--replace name=path replaces the module path, where name is the dependency/module name and path is a remote module path (version should be appended with @) or an absolute local file-system path (a path starting with . can also be used, which will be resolved to an absolute path). It implies the use of the native builder (--builder native) and clean flag (--clean)

with local file-system path

k6x --replace k6/x/faker=../xk6-faker run script.js

with remote path

k6x --replace k6/x/faker=github.com/my-user/xk6-faker@latest run script.js