vfs

Documentation

Overview

Package vfs bridges an afero.Fs to wazero's experimental/sys.FS so a WebAssembly guest's WASI filesystem syscalls (path_open, fd_read, fd_write, fd_seek, …) read and write the caller's afero filesystem — including a fully in-memory MemMapFs — with no host disk access. It is the core of afmpeg (spec 0003); the guest only ever sees the afero.Fs it is given.

Two synthetic locations the guest ffmpeg expects are overlaid on top of the caller's filesystem: a writable /tmp backed by an isolated in-memory fs (so scratch writes never pollute the caller's fs) and /dev/null (a discard sink).

The adapter is invocation-agnostic: it implements the sys.FS and sys.File contracts wazero calls and holds no runtime state of its own. The wazero module wiring that mounts it (WithSysFSMount) lives in the afmpeg runtime (spec 0004), which composes this package with the embedded ffmpeg.wasm.

See docs/explanation/components/vfs-bridge.md for the design narrative.

Index

• type FS
  • func New(afs afero.Fs, opts ...Option) *FS
  • func (f *FS) Lstat(name string) (wsys.Stat_t, experimentalsys.Errno)
  • func (f *FS) Mkdir(name string, perm fs.FileMode) experimentalsys.Errno
  • func (f *FS) OpenFile(name string, flag experimentalsys.Oflag, perm fs.FileMode) (experimentalsys.File, experimentalsys.Errno)
  • func (f *FS) Rename(from, to string) experimentalsys.Errno
  • func (f *FS) Rmdir(name string) experimentalsys.Errno
  • func (f *FS) Stat(name string) (wsys.Stat_t, experimentalsys.Errno)
  • func (f *FS) Unlink(name string) experimentalsys.Errno
• type Option
  • func WithProgressSink(sink func([]byte)) Option
  • func WithTmpFs(tmp afero.Fs) Option

Types

type FS

type FS struct {
	experimentalsys.UnimplementedFS
	// contains filtered or unexported fields
}

FS adapts an afero.Fs to experimental/sys.FS. Construct it with New; the zero value is not usable. Embedding UnimplementedFS keeps the implementation forward-compatible: operations afmpeg does not provide return ENOSYS.

func New

func New(afs afero.Fs, opts ...Option) *FS

New returns a sys.FS backed by afs. Every guest read and write resolves against afs, so handing it an afero.NewMemMapFs keeps the whole pipeline in memory with no host filesystem access (R-AF-2). /tmp and /dev/null are overlaid automatically.

func (*FS) Lstat

func (f *FS) Lstat(name string) (wsys.Stat_t, experimentalsys.Errno)

Lstat returns file status for path without following symlinks. The afero backends afmpeg targets (MemMapFs in particular) do not model symlinks, so this is equivalent to Stat.

func (*FS) Mkdir

func (f *FS) Mkdir(name string, perm fs.FileMode) experimentalsys.Errno

Mkdir creates a directory at path.

func (*FS) OpenFile

func (f *FS) OpenFile(
	name string, flag experimentalsys.Oflag, perm fs.FileMode,
) (experimentalsys.File, experimentalsys.Errno)

OpenFile opens path relative to the resolved backend, or returns the null device for /dev/null.

func (*FS) Rename

func (f *FS) Rename(from, to string) experimentalsys.Errno

Rename moves a file or directory from one path to another within the same backend.

func (*FS) Rmdir

func (f *FS) Rmdir(name string) experimentalsys.Errno

Rmdir removes an empty directory; POSIX rmdir rejects non-directories.

func (*FS) Stat

func (f *FS) Stat(name string) (wsys.Stat_t, experimentalsys.Errno)

Stat returns file status for path.

func (*FS) Unlink

func (f *FS) Unlink(name string) experimentalsys.Errno

Unlink removes a non-directory file; POSIX unlink rejects directories.

type Option

type Option func(*FS)

Option configures an FS.

func WithProgressSink

func WithProgressSink(sink func([]byte)) Option

WithProgressSink serves /dev/afmpeg-progress as a write-only device that hands each complete NDJSON line the engine writes to it to sink (spec 0032, D-B1). Absent this option the device is not overlaid, so the path behaves like any other backing-fs path (D-B3). A nil sink is a no-op.

func WithTmpFs

func WithTmpFs(tmp afero.Fs) Option

WithTmpFs overrides the in-memory filesystem backing the overlaid /tmp. The default is a fresh afero.NewMemMapFs; supplying one lets a caller (or a test) inspect what the guest wrote to scratch.