fs

package
v0.1.0 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 提供文件系统(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

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

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

FsDirEntry 是目录直接子项。

type FsEditOutcome

type FsEditOutcome struct {
	Version FsVersion
	Before  string
	After   string
}

FsEditOutcome 是一次字面编辑的结果。

type FsEditRequest

type FsEditRequest struct {
	// OldString 要替换的非空字面文本。
	OldString string
	// NewString 替换文本;空串删除匹配文本。
	NewString string
	// ReplaceAll 替换所有匹配(而非要求恰好一个)。
	ReplaceAll bool
}

FsEditRequest 是一次字面替换编辑请求。

type FsError

type FsError struct {
	Code FsErrorCode
	Msg  string
}

FsError 是携带稳定码的文件系统错误。

func (*FsError) Error

func (e *FsError) Error() string

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

func Code

func Code(err error) FsErrorCode

Code 返回错误码。

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

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

FsObservation 是一次权威观察:present 携带版本,absent 表示确认缺失。

type FsTarget

type FsTarget struct {
	// TargetKey 不透明键(本地后端用规范化绝对路径)。
	TargetKey FsTargetKey
	// DisplayPath 模型/UI 向展示路径。
	DisplayPath string
}

FsTarget 是后端解析后的稳定文件身份。

type FsTargetKey

type FsTargetKey string

FsTargetKey 是目标的不透明键(供陈旧守卫与查找)。

type FsVersion

type FsVersion string

FsVersion 是不透明文件版本令牌(write/edit 守卫用)。

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 NewLocal

func NewLocal(cwd string) *LocalFS

NewLocal 创建本地文件系统。

func (*LocalFS) Contains

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

Contains 判定 child 是 parent 或其后代(基于规范前缀)。

func (*LocalFS) EditText

func (l *LocalFS) EditText(t FsTarget, edit FsEditRequest, expected *FsVersion) (FsEditOutcome, error)

EditText 原子做字面替换编辑;expected 提供版本守卫(先验版本再匹配)。

func (*LocalFS) FileURL

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

FileURL 返回 file: URI。

func (*LocalFS) ListDir

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

ListDir 列出目录直接子项(稳定名序,仅元数据)。

func (*LocalFS) ObservedVersion

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

ObservedVersion 返回目标当前版本(供观察策略只读记录)。

func (*LocalFS) ProcessPath

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

ProcessPath 返回子进程可打开的目标规范绝对路径。

func (*LocalFS) ReadBytes

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

ReadBytes 读取原始字节,超过 maxBytes 报 FS_TOO_LARGE。

func (*LocalFS) ReadText

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

ReadText 读取整文件 UTF-8 文本。

func (*LocalFS) Resolve

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

Resolve 把路径解析成稳定目标(相对路径按 Cwd 解析,跟随符号链接得规范绝对路径)。

func (*LocalFS) Stat

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

Stat 返回目标元数据;目标不存在返回 (nil, FS_NOT_FOUND)。

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

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

ReflectObservation 读取后登记一次 present 观察(读/stat 调用方执行)。

func (*PolicyFS) Write

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

Write 经观察策略守卫的文件写。

Jump to

Keyboard shortcuts

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