worldstore

package
v1.0.39 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: MIT Imports: 15 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var (
	ErrIdentity = errors.New("worldstore: identity mismatch")
	ErrPath     = errors.New("worldstore: invalid or unsafe path")
)

Functions

func HasWorldstoreManifest

func HasWorldstoreManifest(path string) bool

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 Archive

type Archive struct {
	Data   []byte `json:"data"`
	SHA256 string `json:"sha256"`
}

Archive is a deterministic ZIP backup and its whole-archive SHA-256.

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

func ServerIdentity(owner, serverID, nodeID string) Identity

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

func NewLocal(identity Identity, authorizedRoot, journalDir string) (*Local, error)

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

func OpenServerWorlds(owner, serverID, nodeID, journalRoot, dataPath string) (*Local, error)

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

func (l *Local) Backup(id Identity) (Archive, error)

func (*Local) BackupTo

func (l *Local) BackupTo(id Identity, destPath string, skip func(rel string) bool) (string, error)

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

func (l *Local) Close() error

Close releases the root handle owned by this local worker.

func (*Local) Identity

func (l *Local) Identity() Identity

Identity returns the canonical identity bound to this worker.

func (*Local) List

func (l *Local) List(id Identity) ([]Entry, error)

func (*Local) Read

func (l *Local) Read(id Identity, path string) ([]byte, error)

func (*Local) Recover

func (l *Local) Recover() error

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

func (l *Local) Restore(id Identity, data []byte) error

func (*Local) RestoreFrom

func (l *Local) RestoreFrom(id Identity, archivePath string) error

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.

func (*Local) Upload

func (l *Local) Upload(id Identity, path string, data []byte) error

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.

Jump to

Keyboard shortcuts

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