Documentation
¶
Overview ¶
Package fsroot provides scoped filesystem roots.
All provider I/O flows through the Root 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 Mode ¶
type Mode int
Mode selects which Root 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 Root.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.
type Root ¶
type Root 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)
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
Name() string
NewPath(path string) Path
Open(p Path) (*os.File, error)
OpenFile(p Path, flag int, perm os.FileMode) (*os.File, error)
OpenRoot(p Path) (Root, 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
}
Root provides scoped filesystem operations. All path arguments are Path values created through Root.NewPath.
Three concrete implementations provide different access modes:
- OpenConfined wraps *os.Root 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 Root.Close.
The method set mirrors *os.Root 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.
func Open ¶
Open opens a Root 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 Root 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 Root 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: Root.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 Root 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 Root at dir without OS-level confinement.
Parameters:
- `dir`: the base directory for all path resolution.
Returns:
- `Root`: a read-write, unconfined root.
Source Files