fs

package
v0.0.0-...-e62627f Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 31, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package fs provides a policy-controlled filesystem module for QuickJS.

Index

Constants

View Source
const (
	// ModuleName is the canonical Node-compatible filesystem module name.
	ModuleName = "fs"
	// PromisesModuleName is the canonical Promise filesystem module name.
	PromisesModuleName = "fs/promises"

	// ErrCodeAccessDenied is assigned to JavaScript errors when the root jail
	// or host policy rejects an operation.
	ErrCodeAccessDenied = "ERR_FS_ACCESS_DENIED"
	// ErrCodeIO is assigned to JavaScript errors returned by the host filesystem.
	ErrCodeIO = "ERR_FS_IO"
)

Variables

This section is empty.

Functions

func Module

func Module(options ...Option) module.Definition

Module returns the fs and node:fs ESM definition. It always exports promises and exports synchronous methods only when configured with WithSync(true).

func PromisesModule

func PromisesModule(options ...Option) module.Definition

PromisesModule returns the fs/promises and node:fs/promises ESM definition.

Types

type Config

type Config struct {
	Root               string
	Policy             Policy
	PathResolver       PathResolver
	SymlinkPolicy      SymlinkPolicy
	UnrestrictedAccess bool
	Sync               bool
	ResourceLimits     *limits.Runtime
}

type Operation

type Operation string

Operation identifies one filesystem capability that a Policy may approve.

const (
	OperationReadFile  Operation = "readFile"
	OperationWriteFile Operation = "writeFile"
	OperationMkdir     Operation = "mkdir"
	OperationReadDir   Operation = "readdir"
	OperationStat      Operation = "stat"
	OperationLstat     Operation = "lstat"
	OperationUnlink    Operation = "unlink"
	OperationRename    Operation = "rename"
)

type Option

type Option func(*Config)

Option configures one fs module instance.

func WithPathResolver

func WithPathResolver(resolver PathResolver) Option

WithPathResolver installs an optional host virtual-path resolver. The returned path remains subject to root-jail validation and Policy.

func WithPolicy

func WithPolicy(policy Policy) Option

WithPolicy installs the host authorization callback. A nil policy denies all operations.

func WithResourceLimits

func WithResourceLimits(resourceLimits *limits.Runtime) Option

WithResourceLimits applies one shared runtime-local byte policy to fs.

func WithRoot

func WithRoot(root string) Option

WithRoot confines every operation to root. An empty or unreadable root denies all operations.

func WithSymlinkPolicy

func WithSymlinkPolicy(policy SymlinkPolicy) Option

WithSymlinkPolicy installs authorization for operations that encounter a symbolic link. Unrestricted access denies those operations when unset.

func WithSync

func WithSync(enabled bool) Option

WithSync controls whether fs exposes its synchronous methods. Promise APIs remain available regardless of this setting.

func WithUnrestrictedAccess

func WithUnrestrictedAccess() Option

WithUnrestrictedAccess removes the root jail. It is intended only for trusted host configurations and remains subject to Policy.

type PathResolver

type PathResolver func(path string) (string, error)

PathResolver converts a host virtual path to a root-relative path. It runs on the QuickJS calling thread before a Promise operation starts.

type Policy

type Policy func(Request) error

Policy decides whether one root-contained filesystem operation is allowed. Promise operations invoke Policy on a worker goroutine; implementations must be safe for concurrent calls.

type Request

type Request struct {
	Operation   Operation
	Path        string
	Destination string
	Sync        bool
}

Request describes a normalized filesystem operation. In root mode Path and Destination are root-relative; in unrestricted mode they are host-absolute.

type SymlinkPolicy

type SymlinkPolicy func(Request) error

SymlinkPolicy decides whether an operation that encounters a symbolic link may proceed. It runs after Policy and receives the same normalized request.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL