fs

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 7 Imported by: 0

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

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

type FsDirEntry struct {
	Name   string
	Type   string
	Target FsTarget
	Size   int64
}

FsDirEntry describes an immediate directory child.

type FsEditOutcome

type FsEditOutcome struct {
	Version FsVersion
	Before  string
	After   string
}

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.

func (*FsError) Error

func (e *FsError) Error() string

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.

func Code

func Code(err error) FsErrorCode

Code returns the error code.

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

type FsObservation struct {
	Kind    string // "present" | "absent"
	Version FsVersion
}

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 NewLocal

func NewLocal(cwd string) *LocalFS

NewLocal creates a local filesystem.

func (*LocalFS) Contains

func (l *LocalFS) Contains(parent, child FsTarget) bool

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) FileURL

func (l *LocalFS) FileURL(t FsTarget) string

FileURL returns a file URI.

func (*LocalFS) ListDir

func (l *LocalFS) ListDir(t FsTarget) ([]FsDirEntry, error)

ListDir returns immediate children as metadata in stable name order.

func (*LocalFS) ObservedVersion

func (l *LocalFS) ObservedVersion(t FsTarget) (FsVersion, bool)

ObservedVersion returns the current target version for observation tracking.

func (*LocalFS) ProcessPath

func (l *LocalFS) ProcessPath(t FsTarget) string

ProcessPath returns a canonical absolute path accessible to subprocesses.

func (*LocalFS) ReadBytes

func (l *LocalFS) ReadBytes(t FsTarget, maxBytes int) ([]byte, error)

ReadBytes reads raw bytes, returning FS_TOO_LARGE above maxBytes.

func (*LocalFS) ReadText

func (l *LocalFS) ReadText(t FsTarget) (string, error)

ReadText reads an entire file as UTF-8 text.

func (*LocalFS) Resolve

func (l *LocalFS) Resolve(path string) (FsTarget, error)

Resolve resolves relative paths against Cwd and follows symlinks to a canonical target.

func (*LocalFS) Stat

func (l *LocalFS) Stat(t FsTarget) (*FsInfo, error)

Stat returns metadata, or nil and FS_NOT_FOUND for a missing 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

func (p *PolicyFS) ReflectObservation(owner string, t FsTarget)

ReflectObservation records presence after a caller performs read or stat.

func (*PolicyFS) Write

func (p *PolicyFS) Write(owner string, t FsTarget, content string) (FsWriteOutcome, error)

Write writes a file using observation guards.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL