Documentation
¶
Overview ¶
Package fs implements the filesystem interface, matching fs/fs, fs-local, and fs-observation-policy (M35). It defines targets, versions, metadata, edits, write intents, LocalFS, and stable FS_* errors; observation rules are in policy.go. Resolve produces an opaque stable target identity and a display path. Versions derived from stat identity and freshness guard writes and edits. An omitted expected value allows unconditional overwrite; supplied intents enforce create-if-absent or version matching. All failures use stable FsErrorCode values.
Filesystem observation policy: read-before-write/edit freshness guards.
Index ¶
- type Decision
- type FsDirEntry
- type FsEditOutcome
- type FsEditRequest
- type FsError
- type FsErrorCode
- type FsInfo
- type FsObservation
- type FsTarget
- type FsTargetKey
- type FsVersion
- type FsWriteIntent
- type FsWriteOutcome
- type LocalFS
- func (l *LocalFS) Contains(parent, child FsTarget) bool
- func (l *LocalFS) EditText(t FsTarget, edit FsEditRequest, expected *FsVersion) (FsEditOutcome, error)
- func (l *LocalFS) FileURL(t FsTarget) string
- func (l *LocalFS) ListDir(t FsTarget) ([]FsDirEntry, error)
- func (l *LocalFS) ObservedVersion(t FsTarget) (FsVersion, bool)
- func (l *LocalFS) ProcessPath(t FsTarget) string
- func (l *LocalFS) ReadBytes(t FsTarget, maxBytes int) ([]byte, error)
- func (l *LocalFS) ReadText(t FsTarget) (string, error)
- func (l *LocalFS) Resolve(path string) (FsTarget, error)
- func (l *LocalFS) Stat(t FsTarget) (*FsInfo, error)
- func (l *LocalFS) WriteText(t FsTarget, content string, expected *FsWriteIntent) (FsWriteOutcome, error)
- type ObservationPolicy
- type PolicyFS
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Decision ¶
type Decision struct {
// WriteIntent is the write guard used by WriteDecision.
WriteIntent *FsWriteIntent
// EditVersion is the version guard used by EditDecision.
EditVersion *FsVersion
// Deny rejects edits of unobserved or absent targets.
Deny bool
// DenyCode is the stable rejection code.
DenyCode FsErrorCode
}
Decision describes a write or edit decision.
type FsDirEntry ¶
FsDirEntry describes an immediate directory child.
type FsEditOutcome ¶
FsEditOutcome reports a literal edit result.
type FsEditRequest ¶
type FsEditRequest struct {
// OldString is the nonempty literal text to replace.
OldString string
// NewString replaces the match; empty deletes it.
NewString string
// ReplaceAll replaces all matches instead of requiring exactly one.
ReplaceAll bool
}
FsEditRequest describes a literal text replacement.
type FsError ¶
type FsError struct {
Code FsErrorCode
Msg string
}
FsError carries a stable filesystem error code.
type FsErrorCode ¶
type FsErrorCode string
FsErrorCode is a stable filesystem failure code.
const ( FSErrNotFound FsErrorCode = "FS_NOT_FOUND" FSErrNotDirectory FsErrorCode = "FS_NOT_DIRECTORY" FSErrNotText FsErrorCode = "FS_NOT_TEXT" FSErrNotRegularFile FsErrorCode = "FS_NOT_REGULAR_FILE" FSErrTooLarge FsErrorCode = "FS_TOO_LARGE" FSErrPermission FsErrorCode = "FS_PERMISSION_DENIED" FSErrSandboxDenied FsErrorCode = "FS_SANDBOX_DENIED" FSErrIO FsErrorCode = "FS_IO_ERROR" FSErrStaleVersion FsErrorCode = "FS_STALE_VERSION" FSErrNotObserved FsErrorCode = "FS_NOT_OBSERVED" FSErrAmbiguousEdit FsErrorCode = "FS_AMBIGUOUS_EDIT" FSErrEditNotFound FsErrorCode = "FS_EDIT_NOT_FOUND" )
Error codes aligned with upstream FsErrorCode.
type FsInfo ¶
type FsInfo struct {
// Version is the current freshness token.
Version FsVersion `json:"version"`
// Type identifies the file type.
Type string `json:"type"` // file / directory / other
// Size is the regular-file size in bytes.
Size int64 `json:"size,omitempty"`
}
FsInfo contains stat metadata without contents.
type FsObservation ¶
FsObservation records an authoritative version when present, or confirmed absence.
type FsTarget ¶
type FsTarget struct {
// TargetKey is opaque; the local backend uses a canonical absolute path.
TargetKey FsTargetKey
// DisplayPath is the path shown to the model or UI.
DisplayPath string
}
FsTarget is the stable file identity resolved by a backend.
type FsTargetKey ¶
type FsTargetKey string
FsTargetKey is an opaque lookup and stale-write guard key.
type FsVersion ¶
type FsVersion string
FsVersion is an opaque file-version token for write/edit guards.
type FsWriteIntent ¶
type FsWriteIntent struct {
// Kind is createIfAbsent or replaceIfVersion.
Kind string
// Version is the expected version for replaceIfVersion.
Version FsVersion
}
FsWriteIntent describes a guarded write.
type FsWriteOutcome ¶
type FsWriteOutcome struct {
Operation string // create / update
Version FsVersion
Before string
After string
}
FsWriteOutcome reports a whole-file write result.
type LocalFS ¶
type LocalFS struct {
// Cwd optionally anchors relative-path resolution.
Cwd string
}
LocalFS implements a local disk filesystem.
func (*LocalFS) Contains ¶
Contains checks whether child equals parent or lies beneath its canonical path.
func (*LocalFS) EditText ¶
func (l *LocalFS) EditText(t FsTarget, edit FsEditRequest, expected *FsVersion) (FsEditOutcome, error)
EditText applies a literal replacement atomically, checking the expected version first.
func (*LocalFS) ListDir ¶
func (l *LocalFS) ListDir(t FsTarget) ([]FsDirEntry, error)
ListDir returns immediate children as metadata in stable name order.
func (*LocalFS) ObservedVersion ¶
ObservedVersion returns the current target version for observation tracking.
func (*LocalFS) ProcessPath ¶
ProcessPath returns a canonical absolute path accessible to subprocesses.
func (*LocalFS) Resolve ¶
Resolve resolves relative paths against Cwd and follows symlinks to a canonical target.
func (*LocalFS) WriteText ¶
func (l *LocalFS) WriteText(t FsTarget, content string, expected *FsWriteIntent) (FsWriteOutcome, error)
WriteText atomically creates or replaces a file with an optional expected guard.
type ObservationPolicy ¶
type ObservationPolicy struct {
// contains filtered or unexported fields
}
ObservationPolicy tracks observations per owner and target without file I/O. Unseen or absent targets use createIfAbsent for writes; edits fail with FS_NOT_OBSERVED or FS_NOT_FOUND respectively. Present observations use replaceIfVersion for writes and the observed version for edit guards.
func NewObservationPolicy ¶
func NewObservationPolicy() *ObservationPolicy
NewObservationPolicy creates an observation policy.
func (*ObservationPolicy) DecideEdit ¶
func (p *ObservationPolicy) DecideEdit(owner string, key FsTargetKey) Decision
DecideEdit guards present targets by version; unseen and absent targets return FS_NOT_OBSERVED and FS_NOT_FOUND respectively.
func (*ObservationPolicy) DecideWrite ¶
func (p *ObservationPolicy) DecideWrite(owner string, key FsTargetKey) Decision
DecideWrite uses createIfAbsent for unseen/absent targets and replaceIfVersion for present ones.
func (*ObservationPolicy) DropOwner ¶
func (p *ObservationPolicy) DropOwner(owner string)
DropOwner removes all observations for an owner during disposal or hot reload.
func (*ObservationPolicy) Record ¶
func (p *ObservationPolicy) Record(owner string, key FsTargetKey, obs FsObservation)
Record records an observation.
type PolicyFS ¶
type PolicyFS struct {
Local *LocalFS
Obs *ObservationPolicy
}
PolicyFS makes read-before-write/edit guards the default over LocalFS.
func NewPolicyFS ¶
func NewPolicyFS(local *LocalFS, obs *ObservationPolicy) *PolicyFS
NewPolicyFS creates a filesystem facade with observation guards.
func (*PolicyFS) Edit ¶
func (p *PolicyFS) Edit(owner string, t FsTarget, edit FsEditRequest) (FsEditOutcome, error)
Edit edits a file using observation guards.
func (*PolicyFS) ReflectObservation ¶
ReflectObservation records presence after a caller performs read or stat.