Documentation
¶
Overview ¶
Package fs 提供文件系统(Filesystem)接缝。
对齐上游:packages/fs/fs + fs-local + fs-observation-policy(M35)
本文件实现:FsTarget/FsVersion/FsInfo/FsEditRequest/FsWriteIntent 类型 + LocalFS 提供者 + 稳定错误码(FS_*)。观察策略见 policy.go。
设计要点:
- resolve() 把用户路径解析成稳定身份 FsTarget(targetKey 不透明,displayPath 供展示);
- 版本令牌 FsVersion 由 stat 身份+新鲜度派生,作为 write/edit 的陈旧守卫;
- writeText/editText 的 expected 是可选的守卫:省略则为无约束覆盖,提供则按意图校验 (createIfAbsent / replaceIfVersion / 版本匹配);
- 所有失败用稳定 FsErrorCode(FS_NOT_FOUND / FS_STALE_VERSION / FS_NOT_OBSERVED / FS_AMBIGUOUS_EDIT / FS_EDIT_NOT_FOUND / FS_TOO_LARGE ...)。
文件系统观察策略(fs-observation-policy):先读后写/编辑的新鲜度守卫。
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 写守卫(WriteDecision 用)。
WriteIntent *FsWriteIntent
// EditVersion 编辑守卫版本(EditDecision 用)。
EditVersion *FsVersion
// Deny 决策是否拒绝(edit 未观察/缺失时)。
Deny bool
// DenyCode 拒绝稳定码。
DenyCode FsErrorCode
}
Decision 是一次写/编辑的决策。
type FsDirEntry ¶
FsDirEntry 是目录直接子项。
type FsEditOutcome ¶
FsEditOutcome 是一次字面编辑的结果。
type FsEditRequest ¶
type FsEditRequest struct {
// OldString 要替换的非空字面文本。
OldString string
// NewString 替换文本;空串删除匹配文本。
NewString string
// ReplaceAll 替换所有匹配(而非要求恰好一个)。
ReplaceAll bool
}
FsEditRequest 是一次字面替换编辑请求。
type FsErrorCode ¶
type FsErrorCode string
FsErrorCode 是文件系统失败稳定码。
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" )
错误码枚举(对齐上游 FsErrorCode)。
type FsInfo ¶
type FsInfo struct {
// Version 当前新鲜度令牌。
Version FsVersion `json:"version"`
// Type 文件类型。
Type string `json:"type"` // file / directory / other
// Size 常规文件字节数。
Size int64 `json:"size,omitempty"`
}
FsInfo 是 stat 返回的元数据(不含内容)。
type FsObservation ¶
FsObservation 是一次权威观察:present 携带版本,absent 表示确认缺失。
type FsTarget ¶
type FsTarget struct {
// TargetKey 不透明键(本地后端用规范化绝对路径)。
TargetKey FsTargetKey
// DisplayPath 模型/UI 向展示路径。
DisplayPath string
}
FsTarget 是后端解析后的稳定文件身份。
type FsWriteIntent ¶
type FsWriteIntent struct {
// Kind:createIfAbsent 拒绝已存在;replaceIfVersion 按版本替换。
Kind string
// Version replaceIfVersion 期望的版本。
Version FsVersion
}
FsWriteIntent 是带守卫的写意图。
type FsWriteOutcome ¶
type FsWriteOutcome struct {
Operation string // create / update
Version FsVersion
Before string
After string
}
FsWriteOutcome 是一次整文件写的结果。
type LocalFS ¶
type LocalFS struct {
// Cwd 相对路径解析基准(可选)。
Cwd string
}
LocalFS 是本地磁盘文件系统实现。
func (*LocalFS) EditText ¶
func (l *LocalFS) EditText(t FsTarget, edit FsEditRequest, expected *FsVersion) (FsEditOutcome, error)
EditText 原子做字面替换编辑;expected 提供版本守卫(先验版本再匹配)。
func (*LocalFS) ListDir ¶
func (l *LocalFS) ListDir(t FsTarget) ([]FsDirEntry, error)
ListDir 列出目录直接子项(稳定名序,仅元数据)。
func (*LocalFS) ObservedVersion ¶
ObservedVersion 返回目标当前版本(供观察策略只读记录)。
func (*LocalFS) ProcessPath ¶
ProcessPath 返回子进程可打开的目标规范绝对路径。
func (*LocalFS) WriteText ¶
func (l *LocalFS) WriteText(t FsTarget, content string, expected *FsWriteIntent) (FsWriteOutcome, error)
WriteText 原子创建/替换文件;expected 提供守卫。
type ObservationPolicy ¶
type ObservationPolicy struct {
// contains filtered or unexported fields
}
ObservationPolicy 记录每个 owner 对每个 target 的观察状态,并决定写/编辑守卫。
规则(对齐上游):
- 未见 / absent → 写用 createIfAbsent;edit 未观察 → FS_NOT_OBSERVED,absent → FS_NOT_FOUND;
- present(读/写/编辑观察过某版本)→ 写用 replaceIfVersion,edit 用该版本守卫;
- 不执行任何文件 I/O。
func NewObservationPolicy ¶
func NewObservationPolicy() *ObservationPolicy
NewObservationPolicy 创建观察策略。
func (*ObservationPolicy) DecideEdit ¶
func (p *ObservationPolicy) DecideEdit(owner string, key FsTargetKey) Decision
DecideEdit 决定编辑守卫:
present → 版本守卫;未见 → FS_NOT_OBSERVED;absent → FS_NOT_FOUND。
func (*ObservationPolicy) DecideWrite ¶
func (p *ObservationPolicy) DecideWrite(owner string, key FsTargetKey) Decision
DecideWrite 决定写意图:
未见/absent → createIfAbsent;present → replaceIfVersion。
func (*ObservationPolicy) DropOwner ¶
func (p *ObservationPolicy) DropOwner(owner string)
DropOwner 丢弃某 owner 的全部观察(HMR/销毁安全)。
func (*ObservationPolicy) Record ¶
func (p *ObservationPolicy) Record(owner string, key FsTargetKey, obs FsObservation)
Record 记录一次观察。
type PolicyFS ¶
type PolicyFS struct {
Local *LocalFS
Obs *ObservationPolicy
}
PolicyFS 把观察策略应用到 LocalFS:先读后写/编辑成为默认行为。
func NewPolicyFS ¶
func NewPolicyFS(local *LocalFS, obs *ObservationPolicy) *PolicyFS
NewPolicyFS 创建带观察策略的文件系统门面。
func (*PolicyFS) Edit ¶
func (p *PolicyFS) Edit(owner string, t FsTarget, edit FsEditRequest) (FsEditOutcome, error)
Edit 经观察策略守卫的文件编辑。
func (*PolicyFS) ReflectObservation ¶
ReflectObservation 读取后登记一次 present 观察(读/stat 调用方执行)。