nodefile

Documentation

Overview

Package nodefile reads and atomically rewrites files on a PVE node over non-interactive ssh. It knows nothing about cobra, cli.Deps, or config: callers hand it an already-resolved host and finished ssh flags. Its only dependencies are internal/exec (the shell-out Runner) and internal/sshcmd (the argv builder), keeping it a leaf package free of the cli/config web.

Index

• Constants
• Variables
• type Conn
  • func (c Conn) Exec(script string) (stdout, stderr string, err error)
  • func (c Conn) Read(path string) (content, sha string, err error)
  • func (c Conn) Write(path, content, expectSHA, lockPath string) error

Constants

const MaxFileSize = 256 * 1024

MaxFileSize bounds the bytes Read will return and Write will send. It sits far below the pmxcfs per-file limit yet far above any sane guest config, and keeps a runaway remote file from being slurped wholesale into memory.

Variables

var (
	// ErrNotFound reports that the remote file does not exist.
	ErrNotFound = errors.New("remote file does not exist")
	// ErrConflict reports that the remote file changed since it was read, so
	// the optimistic sha256 guard rejected the write.
	ErrConflict = errors.New("remote file changed since it was read")
	// ErrLockTimeout reports that the PVE config lock could not be acquired
	// within the bounded wait.
	ErrLockTimeout = errors.New("timed out waiting for the PVE config lock")
	// ErrTooLarge reports that the content exceeds MaxFileSize.
	ErrTooLarge = errors.New("remote file exceeds the size limit")
)

Sentinel errors, matched with errors.Is by the command layer.

Types

type Conn

type Conn struct {
	Runner exec.Runner
	Flags  *sshcmd.Flags
	Host   string
}

Conn describes one PVE node reachable over ssh. Runner is the shell-out interface (deps.Runner), Flags are the connection flags after context defaults have been applied, and Host is the resolved management address.

func (Conn) Exec

func (c Conn) Exec(script string) (stdout, stderr string, err error)

Exec runs script under `sh -ec` on the node and returns captured stdout and stderr. Callers use it for post-write validation (e.g. `pct config <vmid>`) and for read-only probes. A non-zero exit is returned as the error with both captured streams available for the caller to fold into its own message.

func (Conn) Read

func (c Conn) Read(path string) (content, sha string, err error)

Read returns the exact bytes of path and the hex sha256 of those bytes, which is the guard token a later Write passes as expectSHA. The remote invocation is a plain `cat` of the ShellQuoted path; stdout is captured client-side and refused if it exceeds MaxFileSize. A non-zero exit yields a generic error carrying the remote stderr (cat cannot distinguish a missing file from other failures by exit code, so no sentinel is mapped here).

func (Conn) Write

func (c Conn) Write(path, content, expectSHA, lockPath string) error

Write replaces path with content, but only if the remote file's current sha256 still equals expectSHA (optimistic lock; ErrConflict otherwise). The whole check-and-write runs as one remote critical section under flock(1) on lockPath, and the replacement is a tmp-file-plus-rename in the same directory so readers never observe a partial file. content is piped via stdin, never embedded in the argv, so it faces no quoting hazard. Content larger than MaxFileSize is refused client-side before any ssh call. The distinguishable remote exits map to ErrLockTimeout, ErrConflict, and ErrNotFound; any other non-zero exit (including ssh's own 255 transport failure) becomes a wrapped error carrying the remote stderr.