Documentation
¶
Overview ¶
Package fs provides a policy-controlled filesystem module for QuickJS.
Index ¶
- Constants
- func Module(options ...Option) module.Definition
- func PromisesModule(options ...Option) module.Definition
- type Config
- type Operation
- type Option
- func WithPathResolver(resolver PathResolver) Option
- func WithPolicy(policy Policy) Option
- func WithResourceLimits(resourceLimits *limits.Runtime) Option
- func WithRoot(root string) Option
- func WithSymlinkPolicy(policy SymlinkPolicy) Option
- func WithSync(enabled bool) Option
- func WithUnrestrictedAccess() Option
- type PathResolver
- type Policy
- type Request
- type SymlinkPolicy
Constants ¶
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 ¶
WithPolicy installs the host authorization callback. A nil policy denies all operations.
func WithResourceLimits ¶
WithResourceLimits applies one shared runtime-local byte policy to fs.
func WithRoot ¶
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 ¶
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 ¶
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 ¶
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 ¶
Request describes a normalized filesystem operation. In root mode Path and Destination are root-relative; in unrestricted mode they are host-absolute.
type SymlinkPolicy ¶
SymlinkPolicy decides whether an operation that encounters a symbolic link may proceed. It runs after Policy and receives the same normalized request.