fs

Documentation

Overview

Package fs provides a k6 module that allows users to interact with files from the local filesystem as per the File API design document.

Index

• Constants
• type File
  • func (f *File) Read(into sobek.Value) (*sobek.Promise, error)
  • func (f *File) Seek(offset sobek.Value, whence sobek.Value) (*sobek.Promise, error)
  • func (f *File) Stat() *sobek.Promise
• type FileInfo
• type ModuleInstance
  • func (mi *ModuleInstance) Exports() modules.Exports
  • func (mi *ModuleInstance) Open(path sobek.Value) *sobek.Promise
• type ReadSeekStater
• type RootModule
  • func New() *RootModule
  • func (rm *RootModule) NewModuleInstance(vu modules.VU) modules.Instance
• type SeekMode
• type Stater

Constants

const (
	// NotFoundError is emitted when a file is not found.
	NotFoundError errorKind = iota + 1

	// InvalidResourceError is emitted when a resource is invalid: for
	// instance when attempting to open a directory, which is not supported.
	InvalidResourceError

	// ForbiddenError is emitted when an operation is forbidden.
	ForbiddenError

	// TypeError is emitted when an incorrect type has been used.
	TypeError

	// EOFError is emitted when the end of a file has been reached.
	EOFError
)

const (
	// SeekModeStart sets the offset relative to the start of the file.
	SeekModeStart SeekMode = 0

	// SeekModeCurrent seeks relative to the current offset.
	SeekModeCurrent = 1

	// SeekModeEnd seeks relative to the end of the file.
	//
	// When using this mode the seek operation will move backwards from
	// the end of the file.
	SeekModeEnd = 2
)

Types

type File

type File struct {
	// Path holds the name of the file, as presented to [Open].
	Path string `json:"path"`

	// ReadSeekStater contains the actual implementation of the file logic, and
	// interacts with the underlying file system.
	//
	// Note that we explicitly omit exposing this to JS to avoid leaking
	// implementation details, but keep it public so that we can access it
	// from other modules that would want to leverage its implementation of
	// io.Reader and io.Seeker.
	ReadSeekStater ReadSeekStater `js:"-"`
	// contains filtered or unexported fields
}

File represents a file and exposes methods to interact with it.

It is a wrapper around the [file] struct, which is meant to be directly exposed to the JS runtime.

func (*File) Read

func (f *File) Read(into sobek.Value) (*sobek.Promise, error)

Read the file's content, and writes it into the provided Uint8Array.

Resolves to either the number of bytes read during the operation or EOF (null) if there was nothing more to read.

It is possible for a read to successfully return with 0 bytes. This does not indicate EOF.

func (*File) Seek

func (f *File) Seek(offset sobek.Value, whence sobek.Value) (*sobek.Promise, error)

Seek seeks to the given `offset` in the file, under the given `whence` mode.

The returned promise resolves to the new `offset` (position) within the file, which is expressed in bytes from the selected start, current, or end position depending the provided `whence`.

func (*File) Stat

func (f *File) Stat() *sobek.Promise

Stat returns a promise that will resolve to a FileInfo instance describing the file.

type FileInfo

type FileInfo struct {
	// Name holds the base name of the file.
	Name string `json:"name"`

	// Size holds the size of the file in bytes.
	Size int64 `json:"size"`
}

FileInfo holds information about a file.

type ModuleInstance

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

ModuleInstance represents an instance of the fs module for a single VU.

func (*ModuleInstance) Exports

func (mi *ModuleInstance) Exports() modules.Exports

Exports implements the modules.Module interface and returns the exports of our module.

func (*ModuleInstance) Open

func (mi *ModuleInstance) Open(path sobek.Value) *sobek.Promise

Open opens a file and returns a promise that will resolve to a File instance

type ReadSeekStater

type ReadSeekStater interface {
	io.Reader
	io.Seeker
	Stater
}

ReadSeekStater is an interface that combines the io.ReadSeeker and Stater interfaces and ensure that structs implementing it have the necessary methods to interact with files.

type RootModule

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

RootModule is the global module instance that will create instances of our module for each VU.

func New

func New() *RootModule

New returns a pointer to a new RootModule instance.

func (*RootModule) NewModuleInstance

func (rm *RootModule) NewModuleInstance(vu modules.VU) modules.Instance

NewModuleInstance implements the modules.Module interface and returns a new instance of our module for the given VU.

type SeekMode

type SeekMode = int

SeekMode is used to specify the seek mode when seeking in a file.

type Stater

type Stater interface {
	// Stat returns a FileInfo describing the named file.
	Stat() *FileInfo
}

Stater is an interface that provides information about a file.

Although in the context of this module we have a single implementation of this interface, it is defined to allow exposing the `file`'s behavior to other module through the `ReadSeekStater` interface without having to leak our internal abstraction.