domain

package
v5.1.0 Latest Latest
Warning

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

Go to latest
Published: Sep 17, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package domain implements root-scoped file operations and version history.

Index

Constants

View Source
const ACLMaxEntries = 256
View Source
const ChunkSize int64 = 8 << 20
View Source
const MaxSegments = 10000
View Source
const MetadataLimit = 8192
View Source
const SessionLifetime = 24 * time.Hour
View Source
const SessionRetention = 7 * 24 * time.Hour

Variables

View Source
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)
)
View Source
var (
	ErrSessionCommitted = errors.New("session already committed")
	ErrSessionAborted   = errors.New("session aborted")
	ErrSessionExpired   = errors.New("session expired")
)
View Source
var ErrCrossDevice = errors.New("root staging and target must be on the same filesystem")

Functions

func CleanPath

func CleanPath(p string) (string, error)

func FileMode

func FileMode(mode uint32) os.FileMode

FileMode translates Unix permission bits, excluding the file type, to Go.

func Retained

func Retained(vs []Version, keep Keep, now time.Time) map[string]bool

Retained returns the union of newest calendar buckets, recent versions and pins.

func UnixMode

func UnixMode(mode os.FileMode) uint32

UnixMode translates Go's special mode flags to their Unix octal positions.

func ValidateMetadata

func ValidateMetadata(m Metadata) error

func ValidateOptions

func ValidateOptions(o WriteOptions) error

Types

type ACL

type ACL struct {
	Entries []ACLEntry `json:"entries"`
}

func ACLFromMode

func ACLFromMode(mode os.FileMode) ACL

ACLFromMode returns the minimal access ACL represented by permission bits.

func NormalizeACL

func NormalizeACL(acl ACL) (ACL, error)

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 ACLScope

type ACLScope string
const (
	AccessACL  ACLScope = "access"
	DefaultACL ACLScope = "default"
)

type ACLTag

type ACLTag string
const (
	ACLOwner       ACLTag = "owner"
	ACLUser        ACLTag = "user"
	ACLOwningGroup ACLTag = "owningGroup"
	ACLGroup       ACLTag = "group"
	ACLMask        ACLTag = "mask"
	ACLOther       ACLTag = "other"
)

type Change

type Change struct {
	Key    string
	Value  []byte
	Delete bool
}

type DirectoryACLs

type DirectoryACLs struct {
	Access  *ACL `json:"access,omitempty"`
	Default *ACL `json:"default,omitempty"`
}

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 IndexStatus struct {
	Enabled    bool       `json:"enabled"`
	Rebuilding bool       `json:"rebuilding"`
	Scanned    int64      `json:"scanned"`
	LastBuilt  *time.Time `json:"lastBuilt"`
	DurationMS int64      `json:"durationMs"`
	Error      string     `json:"error,omitempty"`
}

type Keep

type Keep struct {
	Last    int `json:"last" yaml:"last"`
	Hourly  int `json:"hourly" yaml:"hourly"`
	Daily   int `json:"daily" yaml:"daily"`
	Weekly  int `json:"weekly" yaml:"weekly"`
	Monthly int `json:"monthly" yaml:"monthly"`
}

type Metadata

type Metadata map[string]any

func (*Metadata) UnmarshalJSON

func (m *Metadata) UnmarshalJSON(b []byte) error

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 Ownership

type Ownership struct {
	UID     *int   `json:"uid,omitempty"`
	GID     *int   `json:"gid,omitempty"`
	Mode    string `json:"mode,omitempty"`
	DirMode string `json:"dirMode,omitempty"`
}

type Page

type Page struct {
	Items []Node `json:"items"`
	Next  string `json:"next,omitempty"`
}

type Root

type Root struct {
	Config   RootConfig
	Files    Files
	State    State
	MaxBytes int64
	// contains filtered or unexported fields
}

func NewRoot

func NewRoot(cfg RootConfig, f Files, s State, maxBytes int64) (*Root, error)

func (*Root) AbortSession

func (r *Root) AbortSession(id string) error

func (*Root) ArchiveStat

func (r *Root) ArchiveStat(p string) (os.FileInfo, error)

ArchiveStat reads filesystem metadata without assigning an indexed identity.

func (*Root) CleanupSessions

func (r *Root) CleanupSessions(ctx context.Context) error

func (*Root) ClearDefaultACL

func (r *Root) ClearDefaultACL(p string) error

func (*Root) CommitSession

func (r *Root) CommitSession(ctx context.Context, id string) (Node, error)

func (*Root) CreateSession

func (r *Root) CreateSession(p string, size int64, o WriteOptions) (Session, error)

func (*Root) DeleteVersion

func (r *Root) DeleteVersion(p, id string) error

func (*Root) GetACL

func (r *Root) GetACL(p string, scope ACLScope) (ACL, error)

func (*Root) Info

func (r *Root) Info() (RootInfo, error)

func (*Root) List

func (r *Root) List(p, after string, limit int) (Page, error)

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

func (r *Root) Move(p, to string) (Node, error)

func (*Root) Open

func (r *Root) Open(p string) (*os.File, error)

func (*Root) OpenVersion

func (r *Root) OpenVersion(p, id string) (*os.File, error)

func (*Root) Prune

func (r *Root) Prune(ctx context.Context) (int, error)

func (*Root) Put

func (r *Root) Put(ctx context.Context, p string, body io.Reader, o WriteOptions) (Node, error)

Put streams outside the root lock; only publication waits for a rebuild.

func (*Root) PutSegment

func (r *Root) PutSegment(ctx context.Context, id string, index int, body io.Reader) (Session, error)

func (*Root) Rebuild

func (r *Root) Rebuild(ctx context.Context) (err error)

func (*Root) RefreshStats

func (r *Root) RefreshStats(ctx context.Context, maxEntries int) (Stats, error)

func (*Root) Remove

func (r *Root) Remove(p string, recursive bool) error

func (*Root) Resolve

func (r *Root) Resolve(id string) (Node, error)

func (*Root) Restore

func (r *Root) Restore(p, id string) (Node, error)

func (*Root) Search

func (r *Root) Search(ctx context.Context, query, base, after string, limit, maxEntries int) (Page, error)

func (*Root) Session

func (r *Root) Session(id string) (Session, error)

func (*Root) SetACL

func (r *Root) SetACL(p string, scope ACLScope, acl ACL) (ACL, error)

func (*Root) SetOwnership

func (r *Root) SetOwnership(p string, o *Ownership) (Node, error)

func (*Root) Snapshot

func (r *Root) Snapshot(p string, pinned bool, m Metadata) (Version, error)

func (*Root) Stat

func (r *Root) Stat(p string) (Node, error)

func (*Root) UpdateVersion

func (r *Root) UpdateVersion(p, id string, pinned bool, m Metadata) (Version, error)

func (*Root) Versions

func (r *Root) Versions(p string) ([]Version, error)

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.

type Stats

type Stats struct {
	Files       int64     `json:"files"`
	Directories int64     `json:"directories"`
	Bytes       int64     `json:"bytes"`
	Updated     time.Time `json:"updated"`
	Source      string    `json:"source"`
}

type Version

type Version struct {
	ID       string    `json:"id"`
	FileID   string    `json:"fileId"`
	Created  time.Time `json:"created"`
	Size     int64     `json:"size"`
	Pinned   bool      `json:"pinned"`
	Metadata Metadata  `json:"metadata,omitempty"`
	CopyMode string    `json:"copyMode"`
}

type Versioning

type Versioning struct {
	Enabled  bool          `json:"enabled" yaml:"enabled"`
	Cooldown time.Duration `json:"-" yaml:"-"`
	Keep     Keep          `json:"keep" yaml:"keep"`
}

type WriteOptions

type WriteOptions struct {
	OnConflict string     `json:"onConflict,omitempty"`
	Ownership  *Ownership `json:"ownership,omitempty"`
	Metadata   Metadata   `json:"metadata,omitempty"`
}

Jump to

Keyboard shortcuts

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