modules

Documentation

Overview

Package modules defines interfaces used for developing k6's JavaScript modules.

Index

• func ExportGloballyModule(rt *sobek.Runtime, modSys *ModuleSystem, moduleName string)
• func Register(name string, mod interface{})
• type Exports
• type FileLoader
• type Instance
• type Module
• type ModuleResolver
  • func NewModuleResolver(goModules map[string]any, loadCJS FileLoader, c *compiler.Compiler, ...) *ModuleResolver
  • func (mr *ModuleResolver) Imported() []string
  • func (mr *ModuleResolver) Lock()
• type ModuleSystem
  • func NewModuleSystem(resolver *ModuleResolver, vu VU) *ModuleSystem
  • func (ms *ModuleSystem) CurrentlyRequiredModule() (*url.URL, error)
  • func (ms *ModuleSystem) Require(specifier string) (*sobek.Object, error)
  • func (ms *ModuleSystem) Resolve(mr sobek.ModuleRecord, specifier string) (*url.URL, error)
  • func (ms *ModuleSystem) RunSourceData(source *loader.SourceData) (sobek.ModuleRecord, error)
• type VU

Functions

func ExportGloballyModule

func ExportGloballyModule(rt *sobek.Runtime, modSys *ModuleSystem, moduleName string)

ExportGloballyModule sets all exports of the provided module name on the globalThis. effectively making them globally available

func Register

func Register(name string, mod interface{})

Register the given mod as an external JavaScript module that can be imported by name. The name must be unique across all registered modules and must be prefixed with "k6/x/", otherwise this function will panic.

Types

type Exports

type Exports struct {
	// Default is what will be the `default` export of a module
	Default interface{}
	// Named is the named exports of a module
	Named map[string]interface{}
}

Exports is representation of ESM exports of a module

type FileLoader

type FileLoader func(specifier *url.URL, name string) ([]byte, error)

FileLoader is a type alias for a function that returns the contents of the referenced file.

type Instance

type Instance interface {
	Exports() Exports
}

Instance is what a module needs to return

type Module

type Module interface {
	// NewModuleInstance will get modules.VU that should provide the module with a way to interact with the VU
	// This method will be called for *each* require/import and should return an unique instance for each call
	NewModuleInstance(VU) Instance
}

Module is the interface js modules should implement in order to get access to the VU

type ModuleResolver

type ModuleResolver struct {
	// contains filtered or unexported fields
}

ModuleResolver knows how to get base Module that can be initialized

func NewModuleResolver

func NewModuleResolver(
	goModules map[string]any, loadCJS FileLoader, c *compiler.Compiler, base *url.URL,
	u *usage.Usage, logger logrus.FieldLogger,
) *ModuleResolver

NewModuleResolver returns a new module resolution instance that will resolve. goModules is map of import file to a go module loadCJS is used to load commonjs files

func (*ModuleResolver) Imported

func (mr *ModuleResolver) Imported() []string

Imported returns the list of imported and resolved modules. Each string represents the path as used for importing.

func (*ModuleResolver) Lock

func (mr *ModuleResolver) Lock()

Lock locks the module's resolution from any further new resolving operation. It means that it relays only its internal cache and on the fact that it has already seen previously the module during the initialization. It is the same approach used for opening file operations.

type ModuleSystem

type ModuleSystem struct {
	// contains filtered or unexported fields
}

ModuleSystem is implementing an ESM like module system to resolve js modules for k6 usage

func NewModuleSystem

func NewModuleSystem(resolver *ModuleResolver, vu VU) *ModuleSystem

NewModuleSystem returns a new ModuleSystem for the provide VU using the provided resoluter

func (*ModuleSystem) CurrentlyRequiredModule

func (ms *ModuleSystem) CurrentlyRequiredModule() (*url.URL, error)

CurrentlyRequiredModule returns the module that is currently being required. It is mostly used for old and somewhat buggy behaviour of the `open` call

func (*ModuleSystem) Require

func (ms *ModuleSystem) Require(specifier string) (*sobek.Object, error)

Require is the actual call that implements require

func (*ModuleSystem) Resolve

func (ms *ModuleSystem) Resolve(mr sobek.ModuleRecord, specifier string) (*url.URL, error)

Resolve returns what the provided specifier will get resolved to if it was to be imported To be used by other parts to get the path

func (*ModuleSystem) RunSourceData

func (ms *ModuleSystem) RunSourceData(source *loader.SourceData) (sobek.ModuleRecord, error)

RunSourceData runs the provided sourceData and adds it to the cache. If a module with the same specifier as the source is already cached it will be used instead of reevaluating the source from the provided SourceData.

TODO: this API will likely change as native ESM support will likely not let us have the exports as one big sobek.Value that we can manipulate

type VU

type VU interface {
	// Context return the context.Context about the current VU
	Context() context.Context

	// Events allows subscribing to global k6 execution events, such as Init and
	// Exit, and to local (per-VU) events, such as IterStart and IterEnd.
	// NOTE: This API is EXPERIMENTAL and may be changed, renamed or
	// completely removed in a later k6 release.
	// FIXME: Subscribing to global events shouldn't be part of this VU (local)
	// interface.
	Events() common.Events

	// InitEnv returns common.InitEnvironment instance if present
	InitEnv() *common.InitEnvironment

	// State returns lib.State if any is present
	State() *lib.State

	// Runtime returns the sobek.Runtime for the current VU
	Runtime() *sobek.Runtime

	// RegisterCallback lets a JS module declare that it wants to run a function
	// on the event loop *at a later point in time*. See the documentation for
	// `EventLoop.RegisterCallback()` in the `k6/js/eventloop` Go module for
	// the very important details on its usage and restrictions.
	RegisterCallback() (enqueueCallback func(func() error))
}

VU gives access to the currently executing VU to a module Instance