nodestorage

package
v1.0.40 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package nodestorage routes server file, configuration and content I/O through the node that owns the server (ADR 0005). The local accessor is confined to the server data root. Remote nodes on shared storage are served through the controller's mount of that storage; other remote nodes get a typed refusal until a remote adapter is wired, so a controller-local path is never silently mistaken for a remote node's storage.

Index

Constants

This section is empty.

Variables

View Source
var ErrEscape = errors.New("path escapes the data root")

ErrEscape reports a path that would leave the server data root.

View Source
var ErrSymlink = errors.New("cannot write through symbolic link")

ErrSymlink reports an attempt to write through a symbolic link. Writes must land on real files inside the data root.

View Source
var ErrUnavailable = errors.New("node-aware storage is not configured for this node")

ErrUnavailable reports that the owning node's storage adapter is not configured. Callers must treat it as a refusal, never fall back to local paths for a remote node.

Functions

func CreateZip added in v1.0.40

func CreateZip(ctx context.Context, acc Accessor, paths []string, destRel string, compress bool) (int, error)

CreateZip walks source paths through acc and writes a zip to destRel through the same accessor. The controller filesystem is never used as the destination, so a transport-only node cannot grow a local copy of the world (ADR 0005).

func DestRelFromArchive added in v1.0.40

func DestRelFromArchive(archiveRel string) string

DestRelFromArchive returns the extraction folder next to the archive, named after the archive without its extension (including .tar.gz).

func EnsureDataRoot

func EnsureDataRoot(node NodeInfo, dataRoot string) (string, error)

EnsureDataRoot resolves the mapped data root like MapDataPath and creates the server directory under it when missing, so restore can target a fresh directory on shared storage. The controller-side storage root itself must already exist: creating it could hide a missing mount and silently store server data on the controller's local disk.

func ExtractZip added in v1.0.40

func ExtractZip(ctx context.Context, acc Accessor, archiveRel, destRel string, counter *atomic.Int32) (int, error)

ExtractZip reads a zip through acc and writes its members through the same accessor. The controller filesystem is never used as the destination, so a transport-only node cannot grow a local copy of the world (ADR 0005).

func ExtractZipBytes added in v1.0.40

func ExtractZipBytes(ctx context.Context, acc Accessor, data []byte, destRel string, counter *atomic.Int32) (int, error)

ExtractZipBytes writes zip members through acc. data may come from a controller temp file (remote download, snapshot rollback); the destination is still only the accessor.

func IsEscape

func IsEscape(err error) bool

IsEscape reports whether err is a path-escape rejection.

func IsLegacyLocalNodeID

func IsLegacyLocalNodeID(nodeID string) bool

IsLegacyLocalNodeID reports whether a node ID designates the controller's own daemon on the legacy single-node deployment path. The aliases match the ones the Docker client pool accepts.

func IsSymlink(err error) bool

IsSymlink reports whether err is a symlink-write refusal.

func IsUnavailable

func IsUnavailable(err error) bool

IsUnavailable reports whether err is the typed remote-node refusal.

func MapDataPath

func MapDataPath(node NodeInfo, dataRoot string) (string, error)

MapDataPath maps a server data root to the controller-side directory that holds it. Local nodes keep the path unchanged. Remote nodes on shared storage are mapped through the controller's mount of that storage: the server directory keeps its name under the controller-side root. Other remote nodes are refused with ErrUnavailable.

func MapPath

func MapPath(node NodeInfo, dataRoot, p string) string

MapPath maps an arbitrary path under a server data root to its controller-side location (see MapDataPath). Paths outside the data root and nodes without reachable storage are returned unchanged.

func NodePath

func NodePath(node NodeInfo, dataRoot, p string) string

NodePath maps an arbitrary path under a server data root to the node-side location that holds it: the Docker bind source for containers on that node. Local nodes and nodes without a declared storage root see identical paths on both sides, so the path is returned unchanged.

func ReplaceTreeFromZip added in v1.0.40

func ReplaceTreeFromZip(ctx context.Context, acc Accessor, data []byte) (int, error)

ReplaceTreeFromZip extracts a controller-side zip through acc and swaps it over the existing tree. Staging stays inside the accessor so a transport-only node cannot grow a controller-local copy (ADR 0005).

func RequiresRemoteTransport added in v1.0.40

func RequiresRemoteTransport(node NodeInfo) bool

RequiresRemoteTransport reports whether the node owns storage only on the remote host and the controller must reach it through the worker channel. Shared-storage nodes (controller mount present or node root visible locally) keep the existing mapped local accessor.

func SetTransport added in v1.0.40

func SetTransport(t Transport)

SetTransport installs the process-wide remote storage transport. A nil transport leaves remote nodes without shared storage refused.

func SwapAccessorTree added in v1.0.40

func SwapAccessorTree(acc Accessor, stageRel, oldRel string) error

SwapAccessorTree moves live top-level entries aside, promotes stageRel to the accessor root, then drops the staging directories.

func WriteZip added in v1.0.40

func WriteZip(ctx context.Context, acc Accessor, paths []string, w io.Writer, compress bool) (int, error)

WriteZip walks source paths through acc and writes a zip to w. Source bytes come only from the accessor; w may be a controller download temp file.

Types

type Accessor

type Accessor interface {
	Stat(rel string) (os.FileInfo, error)
	ReadFile(rel string) ([]byte, error)
	WriteFile(rel string, data []byte) error
	ReadDir(rel string) ([]os.DirEntry, error)
	MkdirAll(rel string) error
	Remove(rel string) error
	RemoveAll(rel string) error
	Rename(oldRel, newRel string) error
	Root() string
	// Close releases the accessor's handle on the data root. Callers must
	// close accessors they open.
	Close() error
}

Accessor performs file operations inside one server's data root on the node that owns the server. All paths are relative to the root; every operation is confined to it.

func ForNode

func ForNode(node NodeInfo, dataRoot string) (Accessor, error)

ForNode returns the accessor for a server data root owned by a node. Local nodes (the controller's own daemon) use the confined local accessor rooted at the server's data path. Remote nodes on shared storage are served through the controller's mount of that storage (see MapDataPath). Remote nodes without shared storage are refused until their storage adapter is wired.

func NewLocal

func NewLocal(dataRoot string) (Accessor, error)

NewLocal returns the accessor for a server data root on this controller.

type NodeInfo

type NodeInfo struct {
	ID                    string
	Name                  string
	IsLocal               bool
	StorageRoot           string
	ControllerStorageRoot string
}

NodeInfo is the storage-relevant view of a server's node. StorageRoot is the node-side root of the shared storage that holds server data directories; ControllerStorageRoot is where the controller mounts the same storage (empty when the paths are identical on both sides).

func LocalNode

func LocalNode() NodeInfo

LocalNode returns the storage view of the controller's own daemon.

type ProcessTransport added in v1.0.40

type ProcessTransport struct {
	Bin string
}

ProcessTransport runs the carbon-storage accessor worker as a subprocess.

func (*ProcessTransport) Open added in v1.0.40

func (p *ProcessTransport) Open(ctx context.Context, node NodeInfo, dataRoot string) (Accessor, error)

Open implements Transport.

type Resolver added in v1.0.40

type Resolver struct {
	// contains filtered or unexported fields
}

Resolver owns the transport used for node-aware storage access.

func NewResolver added in v1.0.40

func NewResolver(transport Transport) *Resolver

NewResolver constructs an independent node storage resolver.

func (*Resolver) ForNode added in v1.0.40

func (r *Resolver) ForNode(ctx context.Context, node NodeInfo, dataRoot string) (Accessor, error)

ForNode opens node-owned storage using the resolver's transport and context.

type Transport added in v1.0.40

type Transport interface {
	Open(ctx context.Context, node NodeInfo, dataRoot string) (Accessor, error)
}

Transport opens a confined accessor for a server data root on a remote node without shared controller storage (OSS-281).

Jump to

Keyboard shortcuts

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