Documentation
¶
Overview ¶
Package fsroot provides scoped filesystem roots.
All provider I/O flows through the Dir interface, confining reads and writes to a directory tree. Three implementations serve the three lifecycles: confined roots for execution, read-only roots for planning, and writable unconfined roots for tests.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Dir ¶
type Dir interface {
Chmod(p Path, mode os.FileMode) error
Chown(p Path, uid, gid int) error
Chtimes(p Path, atime, mtime time.Time) error
Close() error
Create(p Path) (*os.File, error)
CreateTemp(dir Path, pattern string) (*os.File, Path, error)
FS() fs.FS
Lchown(p Path, uid, gid int) error
Link(oldPath, newPath Path) error
Lstat(p Path) (fs.FileInfo, error)
Mkdir(p Path, perm os.FileMode) error
MkdirAll(p Path, perm os.FileMode) error
MkdirTemp(dir Path, pattern string) (Path, error)
Name() string
NewPath(name ...string) Path
Open(p Path) (*os.File, error)
OpenFile(p Path, flag int, perm os.FileMode) (*os.File, error)
OpenRoot(p Path) (Dir, error)
ReadFile(p Path) ([]byte, error)
Readlink(p Path) (string, error)
Remove(p Path) error
RemoveAll(p Path) error
Rename(oldPath, newPath Path) error
Stat(p Path) (fs.FileInfo, error)
Symlink(target string, link Path) error
WriteFile(p Path, data []byte, perm os.FileMode) error
}
Dir provides scoped filesystem operations. All path arguments are Path values created through Dir.NewPath.
Three concrete implementations provide different access modes:
- OpenConfined wraps *os.Dir for OS-enforced confinement (execution)
- OpenUnconfined delegates to os.* for unconfined read-only access (planning)
- OpenWritableUnconfined delegates to os.* for unconfined read-write access (testing)
Open constructs any of the three from a Mode value; OpenScratch constructs a confined root at a temporary directory that removes itself on Dir.Close.
The method set mirrors *os.Dir in full, so code that knows the standard library's root knows this one. Every filesystem mutation in the repository is expected to flow through this interface; a direct os.* call must carry a `// Confinement:` comment stating why the root cannot serve it.
Dir.CreateTemp and Dir.MkdirTemp go beyond the mirror: *os.Dir has no equivalent, and os.CreateTemp cannot be confined to a root. Choosing between a scratch root and this one is the whole of the decision — use the session's scratch unless the bytes must end up in this tree atomically, since a rename out of scratch can cross a device boundary and degrade to a copy.
func Open ¶
Open opens a Dir at dir in the given Mode.
The single mode-dispatched constructor. ModeConfined routes to OpenConfined — the only branch that can fail — while the unconfined modes construct handle-free roots that cannot.
Parameters:
- `dir`: the directory to anchor the root at.
- `mode`: the Mode selecting the implementation.
Returns:
- `Root`: the constructed root.
- `error`: any error from OpenConfined when mode is ModeConfined; nil for the unconfined modes.
func OpenConfined ¶
OpenConfined opens an OS-enforced confined Dir at dir.
Parameters:
- `dir`: the directory to confine all I/O within.
Returns:
- `Root`: a confined root backed by *os.Root.
- `error`: any error from os.OpenRoot.
func OpenScratch ¶
OpenScratch opens a confined Dir at a newly created temporary directory that removes itself.
Scratch is not an escape from confinement — it is its own confined tree with a self-destroying lifetime. Process scratch (spool files, staging trees) belongs here rather than in a direct os.CreateTemp call, so that scratch I/O flows through the same seam as every other mutation and inherits its platform behavior.
IMPORTANT: Dir.Close on a scratch root does two things — it releases the handle AND removes the directory tree. Closing early destroys the contents. This overload is deliberate: it makes cleanup impossible to forget, which a separate discard method would not.
Parameters:
- `pattern`: the os.MkdirTemp name pattern; a `*` in the pattern is replaced by a random string, otherwise the random string is appended.
Returns:
- `Root`: a confined root anchored at the new temporary directory.
- `error`: any error from os.MkdirTemp or OpenConfined. On an OpenConfined failure the temporary directory is removed before returning, so no tree is orphaned.
func OpenUnconfined ¶
OpenUnconfined creates a read-only Dir at dir. Write operations return [errReadOnly].
Parameters:
- `dir`: the base directory for all path resolution.
Returns:
- `Root`: a read-only, unconfined root.
func OpenWritableUnconfined ¶
OpenWritableUnconfined creates a read-write Dir at dir without OS-level confinement.
Parameters:
- `dir`: the base directory for all path resolution.
Returns:
- `Root`: a read-write, unconfined root.
type Mode ¶
type Mode int
Mode selects which Dir implementation Open constructs.
The zero value is ModeConfined, so a caller that never sets a mode gets OS-enforced confinement rather than silently widened access.
const ( // ModeConfined selects the OS-enforced confined implementation ([OpenConfined]). ModeConfined Mode = iota // ModeUnconfined selects the unconfined read-only implementation ([OpenUnconfined]). ModeUnconfined // ModeWritableUnconfined selects the unconfined read-write implementation ([OpenWritableUnconfined]). ModeWritableUnconfined )
type Path ¶
type Path struct {
// contains filtered or unexported fields
}
Path holds both root-relative and absolute forms of a filesystem path.
Created through Dir.NewPath to guarantee both fields are populated. The root field records which root directory Rel is relative to (matching os.Root.Name). Abs is derived as filepath.Join(root, rel) and is not serialized.
noinspection GoMixedReceiverTypes
func NewPath ¶
NewPath creates a Path from a root directory and a root-relative path.
Abs is derived via filepath.Join. Rel is stored in canonical slash form regardless of the input's separators — rel is the half that serializes, and equal logical paths must produce equal document bytes on every platform (the same rule the Merkle-root digest follows). Intended for tests and deserialization.
Parameters:
- `root`: the root directory that `rel` is relative to (matches os.Root.Name).
- `rel`: the root-relative path; any separator form.
Returns:
- `Path`: the constructed path, with `rel` canonicalized to slash form.
func (Path) Abs ¶
Abs returns the absolute path used for unconfined I/O, URIs, display, and logging.
Returns:
- `string`: the absolute path.
func (Path) MarshalJSON ¶
MarshalJSON serializes the canonical form {root, rel}. Abs is derived on deserialization.
Returns:
- `[]byte`: the JSON encoding of the {root, rel} form.
- `error`: any error returned by json.Marshal.
func (Path) MarshalYAML ¶
MarshalYAML serializes the canonical form {root, rel}. Abs is derived on deserialization.
Returns:
- `any`: the {root, rel} form for the YAML encoder to serialize.
- `error`: always nil; present to satisfy the yaml.Marshaler interface.
func (Path) Rel ¶
Rel returns the root-relative path used for confined I/O.
Always canonical slash form, on every platform: rel is the half that serializes, so equal logical paths produce equal document bytes and checksums everywhere, and it feeds io/fs APIs whose contract requires slash paths. Convert with filepath.FromSlash only where an OS-native rel is genuinely needed; direct filesystem I/O flows through Path.Abs, which stays OS-native.
Returns:
- `string`: the root-relative path, slash-separated.
func (Path) Root ¶
Root returns the root directory path that Rel is relative to. Matches os.Root.Name.
Returns:
- `string`: the root directory path.
func (*Path) UnmarshalJSON ¶
UnmarshalJSON deserializes {root, rel} and derives Abs.
Pointer receiver is required by the json.Unmarshaler contract — the method must mutate the receiver to populate fields from the JSON bytes. All other Path methods use value receivers since Path is an immutable value type.
Implementation note: A pointer receiver is required by the json.Unmarshaler contract. The method mutates the receiver in place to populate `root`, `rel`, and `abs` from the encoded document, so a value receiver would fill a discarded copy.
This is the deliberate exception to Path's value-receiver convention. The getters and the Marshal methods use value receivers so the value type Path — not just *Path — satisfies json.Marshaler / yaml.Marshaler and its accessors stay callable on non-addressable values (map elements, function returns). Unmarshaling always targets an addressable variable (json.Unmarshal(data, &p)), so the pointer receiver is safe. The resulting value/pointer mix is intentional, which is why the mixed-receivers inspection is suppressed.
Parameters:
- `data`: the JSON bytes to decode.
Returns:
- `error`: non-nil if the JSON is malformed.
func (*Path) UnmarshalYAML ¶
UnmarshalYAML deserializes {root, rel} and derives Abs.
Implementation note: A pointer receiver is required by the json.Unmarshaler contract. The method mutates the receiver in place to populate `root`, `rel`, and `abs` from the encoded document, so a value receiver would fill a discarded copy.
This is the deliberate exception to Path's value-receiver convention. The getters and the Marshal methods use value receivers so the value type Path — not just *Path — satisfies json.Marshaler / yaml.Marshaler and its accessors stay callable on non-addressable values (map elements, function returns). Unmarshaling always targets an addressable variable (json.Unmarshal(data, &p)), so the pointer receiver is safe. The resulting value/pointer mix is intentional, which is why the mixed-receivers inspection is suppressed.
Parameters:
- `value`: the YAML node to decode.
Returns:
- `error`: non-nil if the YAML is malformed.
Source Files