Documentation
¶
Overview ¶
Package worldstore provides a node-scoped local filesystem implementation for server world operations. The package is transport-neutral; callers pass the complete node and ownership identity on every operation so a worker can be attached to a container or another remote transport later.
Index ¶
- Variables
- func HasWorldstoreManifest(path string) bool
- type Archive
- type Entry
- type Identity
- type Local
- func (l *Local) Backup(id Identity) (Archive, error)
- func (l *Local) BackupTo(id Identity, destPath string, skip func(rel string) bool) (string, error)
- func (l *Local) Close() error
- func (l *Local) Identity() Identity
- func (l *Local) List(id Identity) ([]Entry, error)
- func (l *Local) Read(id Identity, path string) ([]byte, error)
- func (l *Local) Recover() error
- func (l *Local) Restore(id Identity, data []byte) error
- func (l *Local) RestoreFrom(id Identity, archivePath string) error
- func (l *Local) Upload(id Identity, path string, data []byte) error
- type Store
Constants ¶
This section is empty.
Variables ¶
var ( ErrIdentity = errors.New("worldstore: identity mismatch") ErrPath = errors.New("worldstore: invalid or unsafe path") )
Functions ¶
func HasWorldstoreManifest ¶
HasWorldstoreManifest reports whether a zip archive carries the worldstore manifest, i.e. was produced by Backup/BackupTo and belongs on the atomic restore path.
Types ¶
type Entry ¶
type Entry struct {
Path string `json:"path"`
Size int64 `json:"size"`
SHA256 string `json:"sha256"`
}
Entry describes one regular file in an authorized server data tree. Directories are implicit.
type Identity ¶
type Identity struct {
Server string `json:"server"`
Node string `json:"node"`
Daemon string `json:"daemon"`
Owner string `json:"owner"`
Generation uint64 `json:"generation"`
AuthorizedRoot string `json:"authorized_root"`
}
Identity binds an operation to one server, node, daemon, owner, generation, and authorized root. AuthorizedRoot is canonicalized to an absolute path by NewLocal. Generation is part of equality, so workers from an older server assignment fail closed after reassignment.
func ServerIdentity ¶
ServerIdentity builds the canonical world-data identity for a server owned by one controller installation. Backup and restore must construct identities the same way, so both call this helper. The node stands in for the daemon locator: in this panel each node names one Docker daemon.
type Local ¶
type Local struct {
// contains filtered or unexported fields
}
func NewLocal ¶
NewLocal opens the parent of authorizedRoot as an os.Root and pins the authorized root's basename. User paths are opened only below that basename; this also lets restore stage and rename sibling trees without allowing a request to select an arbitrary host path. The journal directory must be outside authorizedRoot and private to this worker instance.
func OpenServerWorlds ¶
OpenServerWorlds opens the world-data seam for one server. journalRoot must live outside every server data root; a per-server subdirectory is created under it.
func (*Local) BackupTo ¶
BackupTo streams a deterministic worldstore archive of the authorized tree to destPath and returns the whole-archive SHA-256. skip may exclude paths (it receives the same relative paths List returns). The write is staged to destPath+".partial" and renamed into place, so a failed backup never leaves a truncated artifact behind. Unlike Backup, it streams from disk and is intended for large worlds.
func (*Local) Recover ¶
Recover replays local restore journals. An operation recorded as new_moved commits by deleting the old tree. Earlier phases roll back to the original tree, including crashes between a rename and the following journal update. Invalid or mismatched journals fail closed and are left for operator review.
func (*Local) RestoreFrom ¶
RestoreFrom verifies a worldstore archive on disk and swaps it in through the same journaled, atomic restore as Restore. It streams file contents and verifies them against the manifest while extracting, so it handles large worlds that exceed the in-memory API's limits.
type Store ¶
type Store interface {
List(identity Identity) ([]Entry, error)
Read(identity Identity, path string) ([]byte, error)
Upload(identity Identity, path string, data []byte) error
Backup(identity Identity) (Archive, error)
Restore(identity Identity, archive []byte) error
Recover() error
}
Store exposes filesystem operations against the single authorized root captured at construction. Each method requires the caller's complete identity; no operation accepts a host path. ZIP restore accepts only regular files with safe relative names and a verified manifest. Limits are fixed to bound memory and decompression work. Restore replaces the complete data root through sibling renames and a recoverable journal. Journals are atomically replaced, but this implementation does not claim power-loss durability because it does not fsync files/directories.