sysfs

Documentation

Overview

Package sysfs includes a low-level filesystem interface and utilities needed for WebAssembly host functions (ABI) such as WASI and runtime.GOOS=js.

The name sysfs was chosen because wazero's public API has a "sys" package, which was named after https://github.com/golang/sys.

This tracked in https://github.com/AR1011/wazero/issues/1013

Index

• func DirFS(dir string) experimentalsys.FS
• type AdaptFS
• type FSConfig
• type ReadFS

Examples

• AdaptFS
• DirFS
• ReadFS

Functions

func DirFS

func DirFS(dir string) experimentalsys.FS

DirFS is like os.DirFS except it returns sys.FS, which has more features.

Example

This example shows how to configure a sysfs.DirFS

package main

import (
	"github.com/AR1011/wazero"
	"github.com/AR1011/wazero/experimental/sysfs"
)

var moduleConfig wazero.ModuleConfig

func main() {
	root := sysfs.DirFS(".")

	moduleConfig = wazero.NewModuleConfig().
		WithFSConfig(wazero.NewFSConfig().(sysfs.FSConfig).WithSysFSMount(root, "/"))
}

Types

type AdaptFS

type AdaptFS = sysfs.AdaptFS

AdaptFS adapts the input to sys.FS. Use DirFS instead of adapting an os.DirFS as it handles interop issues such as windows support.

Note: This performs no flag verification on OpenFile. sys.FS cannot read flags as there is no parameter to pass them through with. Moreover, sys.FS documentation does not require the file to be present. In summary, we can't enforce flag behavior.

Example

This example shows how to adapt a fs.FS to a sys.FS

package main

import (
	"io/fs"
	"testing/fstest"

	"github.com/AR1011/wazero"
	"github.com/AR1011/wazero/experimental/sysfs"
)

var moduleConfig wazero.ModuleConfig

func main() {
	m := fstest.MapFS{
		"a/b.txt": &fstest.MapFile{Mode: 0o666},
		".":       &fstest.MapFile{Mode: 0o777 | fs.ModeDir},
	}
	root := &sysfs.AdaptFS{FS: m}

	moduleConfig = wazero.NewModuleConfig().
		WithFSConfig(wazero.NewFSConfig().(sysfs.FSConfig).WithSysFSMount(root, "/"))
}

type FSConfig

type FSConfig interface {
	// WithSysFSMount assigns a sys.FS file system for any paths beginning at
	// `guestPath`.
	//
	// This is an alternative to WithFSMount, allowing more features.
	WithSysFSMount(fs experimentalsys.FS, guestPath string) wazero.FSConfig
}

FSConfig extends wazero.FSConfig, allowing access to the experimental sys.FS until it is moved to the "sys" package.

type ReadFS

type ReadFS = sysfs.ReadFS

ReadFS is used to mask an existing sys.FS for reads. Notably, this allows the CLI to do read-only mounts of directories the host user can write, but doesn't want the guest wasm to. For example, Python libraries shouldn't be written to at runtime by the python wasm file.

Note: This implements read-only by returning sys.EROFS or sys.EBADF, depending on the operation that require write access.

Example

This example shows how to configure a sysfs.ReadFS

package main

import (
	"github.com/AR1011/wazero"
	"github.com/AR1011/wazero/experimental/sysfs"
)

var moduleConfig wazero.ModuleConfig

func main() {
	root := sysfs.DirFS(".")
	readOnly := &sysfs.ReadFS{FS: root}

	moduleConfig = wazero.NewModuleConfig().
		WithFSConfig(wazero.NewFSConfig().(sysfs.FSConfig).WithSysFSMount(readOnly, "/"))
}