layout

Documentation

Overview

Package layout computes the normative target runtime layout (docs/spec/runtime-layout.md §1) and proves every path stays inside its root. It contains no I/O; the deployment engine consumes the resolved paths.

<deployRoot>/
  current                            -> releases/<realizationID>
  releases/<realizationID>/resources/
  releases/<realizationID>/runtime/fxvcs.cfg
  releases/<realizationID>/runtime/config/
  materialized/<aa>/<sha256>
  shared/cache/
  shared/persistent/<repositoryID>/<resource-path>/
  state/

Index

• Constants
• Variables
• func Current(deployRoot string) string
• func DistinctDeployRoots(roots ...string) error
• func HookDestination(realizationDir, allowedRoot, destination string) (string, error)
• func MaterializedPath(deployRoot, digest string) (string, error)
• func PersistentPath(deployRoot, repositoryID, resourcePath, declared string) (string, error)
• func Realization(deployRoot, realizationID string) (string, error)
• func RealizationTarget(realizationID string) (string, error)
• func Releases(deployRoot string) string
• func ResourceFile(realizationDir, mount, relPath string) (string, error)
• func RuntimeFile(realizationDir, relPath string) (string, error)
• func ServerDataLinks(r Roots) map[string]string
• type Roots
  • func (r Roots) Validate() error

Constants

const (
	CurrentLink     = "current"
	ReleasesDir     = "releases"
	MaterializedDir = "materialized"
	SharedDir       = "shared"
	SharedCache     = "cache"
	SharedPersist   = "persistent"
	StateDir        = "state"
	ResourcesDir    = "resources"
	RuntimeDir      = "runtime"
	RuntimeCfg      = "fxvcs.cfg"
	RuntimeConfig   = "config"
)

Deploy-root relative segments (OS-independent names).

Variables

var (
	ErrInvalidRoot          = errors.New("layout: root must be absolute and clean")
	ErrInvalidRealizationID = errors.New("layout: invalid realization ID")
	ErrOverlap              = errors.New("layout: roots overlap")
	ErrEscape               = errors.New("layout: path escapes its root")
	ErrInvalidDigest        = errors.New("layout: invalid digest")
)

Errors.

Functions

func Current

func Current(deployRoot string) string

Current returns <deployRoot>/current.

func DistinctDeployRoots

func DistinctDeployRoots(roots ...string) error

DistinctDeployRoots rejects duplicate or nested deploy roots across targets.

func HookDestination

func HookDestination(realizationDir, allowedRoot, destination string) (string, error)

HookDestination validates a hook's requested destination against the allowlisted destination root (both realization-relative) and resolves it. A destination inside resources/ is refused: secret-bearing output must stay outside the FTP/SFTP-exposed resource tree.

func MaterializedPath

func MaterializedPath(deployRoot, digest string) (string, error)

MaterializedPath returns <deployRoot>/materialized/<aa>/<hex> for a digest.

func PersistentPath

func PersistentPath(deployRoot, repositoryID, resourcePath, declared string) (string, error)

PersistentPath resolves <deployRoot>/shared/persistent/<repositoryID>/<resourcePath>/<declared>. The declared path must be relative, normalized, and is validated for containment; overlap between declared paths is the catalog validator's job.

func Realization

func Realization(deployRoot, realizationID string) (string, error)

Realization returns <deployRoot>/releases/<realizationID> after validating the ID.

func RealizationTarget

func RealizationTarget(realizationID string) (string, error)

RealizationTarget is the relative symlink/junction target for `current`.

func Releases

func Releases(deployRoot string) string

Releases returns <deployRoot>/releases.

func ResourceFile

func ResourceFile(realizationDir, mount, relPath string) (string, error)

ResourceFile resolves a component-mounted file inside a realization: <realization>/<mount>/<relPath>. mount must be a normalized path under "resources/"; relPath must be normalized. Containment is proven.

func RuntimeFile

func RuntimeFile(realizationDir, relPath string) (string, error)

RuntimeFile resolves <realization>/runtime/<relPath> (fxvcs.cfg, config/...).

func ServerDataLinks

func ServerDataLinks(r Roots) map[string]string

ServerDataLinks lists the indirections installed under <serverData>: each entry maps a serverData-relative name to its target under deployRoot.

Types

type Roots

type Roots struct {
	DeployRoot string
	ServerData string
	TxData     string // may be empty for non-txAdmin
}

Roots are the agent-local absolute directories for one target.

func (Roots) Validate

func (r Roots) Validate() error

Validate proves the roots are absolute, clean, and mutually non-overlapping. Two targets on one host must use distinct, non-nested deploy roots.