Documentation
¶
Overview ¶
Package domain implements root-scoped file operations and version history.
Index ¶
- Constants
- Variables
- func CleanPath(p string) (string, error)
- func FileMode(mode uint32) os.FileMode
- func Retained(vs []Version, keep Keep, now time.Time) map[string]bool
- func UnixMode(mode os.FileMode) uint32
- func ValidateMetadata(m Metadata) error
- func ValidateOptions(o WriteOptions) error
- type ACL
- type ACLEntry
- type ACLPermissions
- type ACLScope
- type ACLTag
- type Change
- type DirectoryACLs
- type DirectoryOptions
- type Files
- type IndexStatus
- type Keep
- type Metadata
- type Node
- type Ownership
- type Page
- type Root
- func (r *Root) AbortSession(id string) error
- func (r *Root) ArchiveStat(p string) (os.FileInfo, error)
- func (r *Root) CleanupSessions(ctx context.Context) error
- func (r *Root) ClearDefaultACL(p string) error
- func (r *Root) CommitSession(ctx context.Context, id string) (Node, error)
- func (r *Root) CreateSession(p string, size int64, o WriteOptions) (Session, error)
- func (r *Root) DeleteVersion(p, id string) error
- func (r *Root) GetACL(p string, scope ACLScope) (ACL, error)
- func (r *Root) Info() (RootInfo, error)
- func (r *Root) List(p, after string, limit int) (Page, error)
- func (r *Root) Mkdir(p string, o DirectoryOptions) (Node, error)
- func (r *Root) Move(p, to string) (Node, error)
- func (r *Root) Open(p string) (*os.File, error)
- func (r *Root) OpenVersion(p, id string) (*os.File, error)
- func (r *Root) Prune(ctx context.Context) (int, error)
- func (r *Root) Put(ctx context.Context, p string, body io.Reader, o WriteOptions) (Node, error)
- func (r *Root) PutSegment(ctx context.Context, id string, index int, body io.Reader) (Session, error)
- func (r *Root) Rebuild(ctx context.Context) (err error)
- func (r *Root) RefreshStats(ctx context.Context, maxEntries int) (Stats, error)
- func (r *Root) Remove(p string, recursive bool) error
- func (r *Root) Resolve(id string) (Node, error)
- func (r *Root) Restore(p, id string) (Node, error)
- func (r *Root) Search(ctx context.Context, query, base, after string, limit, maxEntries int) (Page, error)
- func (r *Root) Session(id string) (Session, error)
- func (r *Root) SetACL(p string, scope ACLScope, acl ACL) (ACL, error)
- func (r *Root) SetOwnership(p string, o *Ownership) (Node, error)
- func (r *Root) Snapshot(p string, pinned bool, m Metadata) (Version, error)
- func (r *Root) Stat(p string) (Node, error)
- func (r *Root) UpdateVersion(p, id string, pinned bool, m Metadata) (Version, error)
- func (r *Root) Versions(p string) ([]Version, error)
- func (r *Root) WalkArchive(ctx context.Context, p string, directory bool, maxDepth int, scanBudget *int, ...) error
- type RootConfig
- type RootInfo
- type Session
- type SessionState
- type State
- type Stats
- type Version
- type Versioning
- type WriteOptions
Constants ¶
const ACLMaxEntries = 256
const ChunkSize int64 = 8 << 20
const MaxSegments = 10000
const MetadataLimit = 8192
const SessionLifetime = 24 * time.Hour
const SessionRetention = 7 * 24 * time.Hour
Variables ¶
var ( ErrInvalid = errors.New("invalid argument") ErrConflict = errors.New("conflict") ErrDisabled = errors.New("feature disabled") ErrLimit = errors.New("limit exceeded") ErrACLUnsupported = errors.New("POSIX ACLs are not supported by this filesystem") ErrInvalidACL = fmt.Errorf("%w: invalid ACL", ErrInvalid) )
var ( ErrSessionCommitted = errors.New("session already committed") ErrSessionAborted = errors.New("session aborted") ErrSessionExpired = errors.New("session expired") )
var ErrCrossDevice = errors.New("root staging and target must be on the same filesystem")
Functions ¶
func ValidateMetadata ¶
func ValidateOptions ¶
func ValidateOptions(o WriteOptions) error
Types ¶
type ACL ¶
type ACL struct {
Entries []ACLEntry `json:"entries"`
}
func ACLFromMode ¶
ACLFromMode returns the minimal access ACL represented by permission bits.
func NormalizeACL ¶
NormalizeACL validates a complete ACL and returns entries in POSIX order. Empty default ACLs are represented by reads, but removed through ClearDefaultACL.
type ACLEntry ¶
type ACLEntry struct {
Tag ACLTag `json:"tag"`
ID *uint32 `json:"id,omitempty"`
Permissions ACLPermissions `json:"permissions"`
}
type ACLPermissions ¶
type ACLPermissions string
type DirectoryACLs ¶
type DirectoryOptions ¶
type DirectoryOptions struct {
Ownership *Ownership `json:"ownership,omitempty"`
ACL *DirectoryACLs `json:"acl,omitempty"`
}
type Files ¶
type Files interface {
SecurePrivate() error
Open(string, int, os.FileMode) (*os.File, error)
Stat(string) (os.FileInfo, error)
Mkdir(string, os.FileMode) error
Rename(string, string, bool) error
Remove(string, bool) error
Sync(string) error
ID(*os.File) (string, error)
SetID(*os.File, string) error
GetACL(*os.File, ACLScope) (ACL, error)
SetACL(*os.File, ACLScope, ACL) error
ClearDefaultACL(*os.File) error
Identity(os.FileInfo) (uint64, uint64, uint32, uint32, uint64)
Clone(*os.File, *os.File) (bool, error)
Capacity() (string, uint64, uint64, error)
Close() error
}
Files only opens beneath its root, rejecting symbolic links in every component.
type IndexStatus ¶
type Metadata ¶
func (*Metadata) UnmarshalJSON ¶
type Node ¶
type Node struct {
Root string `json:"root"`
Path string `json:"path"`
ID string `json:"id,omitempty"`
Directory bool `json:"directory"`
Size int64 `json:"size"`
Modified time.Time `json:"modified"`
Mode string `json:"mode"`
UID uint32 `json:"uid"`
GID uint32 `json:"gid"`
}
func Transfer ¶
func Transfer(ctx context.Context, src *Root, p string, dst *Root, to string, move bool, o WriteOptions) (Node, error)
Cross-root transfer holds both roots in name order through source removal. A failed transfer may leave copied destination files, but never removes newer source bytes.
type Root ¶
type Root struct {
Config RootConfig
Files Files
State State
MaxBytes int64
// contains filtered or unexported fields
}
func (*Root) AbortSession ¶
func (*Root) ArchiveStat ¶
ArchiveStat reads filesystem metadata without assigning an indexed identity.
func (*Root) ClearDefaultACL ¶
func (*Root) CommitSession ¶
func (*Root) CreateSession ¶
func (*Root) DeleteVersion ¶
func (*Root) Mkdir ¶
func (r *Root) Mkdir(p string, o DirectoryOptions) (Node, error)
Mkdir publishes one fully configured directory. Its parent must already exist; existing destinations are never modified, including when their type differs.
func (*Root) PutSegment ¶
func (*Root) RefreshStats ¶
func (*Root) UpdateVersion ¶
func (*Root) WalkArchive ¶
func (r *Root) WalkArchive(ctx context.Context, p string, directory bool, maxDepth int, scanBudget *int, visit func(string, os.FileInfo) error) error
WalkArchive visits a selected object and, only for a selected directory, its descendants. Directory reads are batched; scanBudget counts every encountered object, including private entries, and may be shared across selections. Visit must separately enforce the output entry and byte budgets. Private metadata is omitted, while symlinks and special files fail closed.
type RootConfig ¶
type RootConfig struct {
Name string `json:"name"`
Path string `json:"-"`
Index bool `json:"index"`
Versioning Versioning `json:"versioning"`
}
type RootInfo ¶
type RootInfo struct {
Name string `json:"name"`
Index IndexStatus `json:"index"`
Stats *Stats `json:"stats"`
Versioning Versioning `json:"versioning"`
Cooldown string `json:"cooldown"`
Versions int64 `json:"versions"`
VersionBytes int64 `json:"versionBytes"`
Filesystem string `json:"filesystem"`
Capacity uint64 `json:"capacity"`
Available uint64 `json:"available"`
ActiveUploads int64 `json:"activeUploads"`
StagingBytes int64 `json:"stagingBytes"`
}
type Session ¶
type Session struct {
State SessionState `json:"state"`
TerminalAt *time.Time `json:"terminalAt,omitempty"`
RetainUntil *time.Time `json:"retainUntil,omitempty"`
ID string `json:"id"`
Root string `json:"root"`
Path string `json:"path"`
Size int64 `json:"size"`
ChunkSize int64 `json:"chunkSize"`
Expires time.Time `json:"expires"`
Options WriteOptions `json:"options"`
Segments map[int]string `json:"segments"`
Received int64 `json:"received"`
Result *Node `json:"result,omitempty"`
}
type SessionState ¶
type SessionState string
const ( SessionOpen SessionState = "open" SessionCommitted SessionState = "committed" SessionAborted SessionState = "aborted" SessionExpired SessionState = "expired" )
type State ¶
type State interface {
Get(string, any) error
Put(string, any) error
Delete(string) error
Batch([]Change) error
Scan(string, func(string, []byte) error) error
Close() error
}
State keeps separate key families for derived index rows and durable records.