Documentation
¶
Overview ¶
Package xfs provides filesystem primitives for Nexss workspaces.
Three layers, two threat models:
WriteFile / WriteFileAtomic(path, ...) — trusted path, no validation. Use only for paths your code builds from constants (config dirs, cache roots, temp dirs). WriteFile is a thin wrapper over os.WriteFile; WriteFileAtomic is temp+fsync+rename.
Rel(p) — string-level validation of an untrusted path. Fast, typed errors. Rejects absolute paths, "..", ":", NUL, control chars, trailing dots, Windows reserved device names.
Root — kernel-enforced containment. Opens a directory handle via os.OpenRoot; every path goes through Rel first, then through the kernel, which refuses symlink escapes and TOCTOU races that Rel alone cannot see. Any path derived from user input, HTTP, config, or plugin manifests MUST go through Root.
Index ¶
- func Rel(p string) (string, error)
- func WriteFile(path string, data []byte, perm os.FileMode) error
- func WriteFileAtomic(path string, data []byte, perm os.FileMode) error
- type Root
- func (r *Root) Chmod(p string, mode os.FileMode) error
- func (r *Root) Chtimes(p string, atime, mtime time.Time) error
- func (r *Root) Close() error
- func (r *Root) Create(p string) (*os.File, error)
- func (r *Root) FS() fs.FS
- func (r *Root) Lstat(p string) (os.FileInfo, error)
- func (r *Root) Mkdir(p string, perm os.FileMode) error
- func (r *Root) MkdirAll(p string, perm os.FileMode) error
- func (r *Root) Name() string
- func (r *Root) Open(p string) (*os.File, error)
- func (r *Root) OpenFile(p string, flag int, perm os.FileMode) (*os.File, error)
- func (r *Root) ReadFile(p string) ([]byte, error)
- func (r *Root) Remove(p string) error
- func (r *Root) RemoveAll(p string) error
- func (r *Root) Rename(oldp, newp string) error
- func (r *Root) Stat(p string) (os.FileInfo, error)
- func (r *Root) WriteFile(p string, data []byte, perm os.FileMode) error
- func (r *Root) WriteFileAtomic(p string, data []byte, perm os.FileMode) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WriteFile ¶
WriteFile writes data to path non-atomically. A crash mid-write leaves path truncated or partially written.
The caller is responsible for supplying a trusted path. WriteFile performs no validation — for caller-supplied (untrusted) paths, open an xfs.Root and use Root.WriteFile instead.
func WriteFileAtomic ¶
WriteFileAtomic writes data to path atomically. A crash mid-write leaves path either at its previous content or at the new content; never in between.
The caller is responsible for supplying a trusted path. WriteFileAtomic performs no validation — for caller-supplied (untrusted) paths, open an xfs.Root and use Root.WriteFileAtomic instead.
On POSIX the rename is atomic within a filesystem. On Windows it is atomic within a volume and retries up to 5 times on transient sharing violations (a common interference on Windows hosts).
data is fsync'd before the rename. The parent directory is fsync'd after on POSIX; Windows does not expose directory fsync and the rename is atomic but not durable across power loss.
Types ¶
type Root ¶
type Root struct {
// contains filtered or unexported fields
}
Root confines file operations to a trusted directory. Every path argument is validated by Rel (fast, typed errors) and then opened through os.Root (kernel-level containment: symlinks cannot escape, TOCTOU on the resolved path is closed).
Rule for the codebase: any path derived from user input, HTTP requests, workspace config, or plugin manifests MUST go through Root. xfs.WriteFile is only for paths your code builds from trusted constants.
func (*Root) Chtimes ¶
Chtimes updates access and modification times.
NOTE: On Unix, Chmod/Chown/Chtimes are documented as racy — the stdlib may operate on a symlink if the target changes mid-call. Prefer writing through WriteFileAtomic over mutating in place.
func (*Root) FS ¶
FS returns an fs.FS view rooted at r's directory. Useful with fs.WalkDir, template.ParseFS, io/fs.ReadDir, etc.
func (*Root) OpenFile ¶
OpenFile opens with explicit flags. The path is validated by Rel; the kernel-level os.Root rejects symlink escapes even when O_CREATE is combined with a pre-existing symlink at the target.
func (*Root) WriteFile ¶
WriteFile writes data to p, confined to the root. Non-atomic: a crash mid-write leaves p truncated or partially written. Use only when the file is reconstructible (cache, generated artifact, spill file). For anything a reader will later trust (config, state, user data), use WriteFileAtomic.
func (*Root) WriteFileAtomic ¶
WriteFileAtomic writes data to p atomically: a crash mid-write leaves p either at its previous content or at the new content, never in between. Costs one extra file create + fsync + rename.
The temp file is created inside the root with O_EXCL so a pre-created file (attacker-controlled symlink, sibling race) cannot hijack the write. Symlink escapes are blocked by os.Root.
On Windows, the final rename retries up to 5 times to survive transient sharing violations (AV scanners, indexers) — mirroring the behavior of xfs.WriteFileAtomic.
Source Files