sourcecontent

package
v0.2.9 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package sourcecontent defines the content digest of a delivered source: the files a schema or a migration directory is read from, whatever carried them.

The digest names the bytes, not the carrier. The same files give the same digest from a ConfigMap snapshot, a Git tree or a directory on disk, so a plan can bind the content it was computed from and every later operation can refuse anything else.

The manifest has one line per file, sorted by the path's bytes:

<lowercase hex SHA-256 of the file> <size in bytes, decimal> <path>\n

and the digest is "sha256:" followed by the lowercase hex SHA-256 of the manifest. File bytes are never normalized: line endings, encoding and the order inside a file stay as delivered. A path is slash-separated and relative; the rules below keep every line unambiguous and every path the same file on every operating system that reads it.

testdata/sourcecontent holds the cases any other implementation, such as Ptah's Git pull, is held to.

Index

Constants

View Source
const (
	// ManifestKey is the key the manifest is stored under.
	ManifestKey = "manifest"
	// MaxSnapshotBytes is the most a snapshot's files and manifest may take
	// together: the limit the API server puts on a ConfigMap's values.
	MaxSnapshotBytes = 1 << 20
)

A snapshot is the set of files a ConfigMap source selected, stored as ConfigMap keys: the manifest under ManifestKey, and the file on manifest line i under SnapshotFileKey(i). Keys cannot hold "/", so the path lives in the manifest and the key only says which line a file belongs to.

View Source
const (
	// MaxFiles is the most files one source may select. It bounds the
	// manifest and the volume an operation mounts.
	MaxFiles = 1000
	// MaxPathElementBytes is the longest name one path element may have, the
	// limit ordinary file systems keep.
	MaxPathElementBytes = 255
)

Variables

View Source
var (
	ErrEmpty        = errors.New("source selects no file")
	ErrTooManyFiles = errors.New("source selects too many files")
	ErrInvalidPath  = errors.New("invalid source path")
	ErrDuplicate    = errors.New("duplicate source path")
	ErrPathConflict = errors.New("source path is both a file and a directory")
	ErrInvalidEntry = errors.New("invalid manifest entry")
)

The refusals, matched with errors.Is. Each names the rule a source broke; the message says which path.

View Source
var ErrContentMismatch = errors.New("snapshot does not hold the bound content")

ErrContentMismatch is the refusal of a snapshot whose manifest or files no longer give the content digest the operation was bound to.

View Source
var ErrNotRegular = errors.New("source tree holds something other than a regular file or a directory")

ErrNotRegular refuses a tree that holds anything but directories and regular files.

Functions

func Digest

func Digest(files []File) (string, error)

Digest returns the content digest of files: "sha256:" and the hex SHA-256 of their manifest.

func DigestOf

func DigestOf(manifest []byte) string

DigestOf returns the content digest a manifest names.

func DigestOfEntries

func DigestOfEntries(entries []Entry) (string, error)

DigestOfEntries returns the content digest a set of manifest entries gives, refusing a set the rules do not admit. A report that lists its files can be held to the digest it names without the files themselves.

func Manifest

func Manifest(files []File) ([]byte, error)

Manifest returns the canonical manifest of files, refusing a set the rules do not admit. The input order does not matter.

func Materialize

func Materialize(snapshotDir, destination, contentDigest string) error

Materialize copies the snapshot mounted at snapshotDir into destination, which must be an empty directory or not exist yet, and refuses unless the snapshot holds exactly the content contentDigest names: the manifest gives the digest, every file has the size and SHA-256 its line names, the manifest is the one Manifest computes for those files, and the snapshot holds no other key.

It reads every byte before it writes any, so a refused snapshot leaves destination as it found it.

func SnapshotFileKey

func SnapshotFileKey(index int) string

SnapshotFileKey is the key the file on manifest line index is stored under.

func ValidatePath

func ValidatePath(path string) error

ValidatePath reports whether path is admitted as a source path.

func Write

func Write(destination string, files []File) error

Write creates every file under destination, which has to be empty or absent, and refuses to replace one.

Types

type Entry

type Entry struct {
	Path   string
	Size   int64
	SHA256 string
}

Entry is one line of a manifest as a report states it: the path, the size and the SHA-256 of the file's bytes, without the bytes.

type File

type File struct {
	Path string
	Data []byte
}

File is one selected file: its path inside the source and its exact bytes.

func Canonical

func Canonical(files []File) ([]File, []byte, string, error)

Canonical returns files sorted by path, with their manifest and digest, refusing a set the rules do not admit. The sorted order is the order the manifest lists them in, so file i is stored under SnapshotFileKey(i).

func Files

func Files(manifest []byte, read func(index int, size int64) ([]byte, error)) ([]File, error)

Files checks every file a snapshot holds against its manifest and returns them in manifest order. read returns the bytes stored for manifest line index, reading no more than size and one byte; a file whose size or SHA-256 is not the one its line names, a manifest that is not canonical, or one that is not the manifest Manifest computes for the files is refused with ErrContentMismatch. The caller compares the manifest's digest with the one it expects.

func ReadFile

func ReadFile(file, name string, maxBytes int64) ([]File, error)

ReadFile reads one regular file as the source file name, refusing a symbolic link and more than maxBytes.

func ReadTree

func ReadTree(root string, maxBytes int64) ([]File, error)

ReadTree reads every file under root, with its path relative to root. It refuses a symbolic link, a device or any other entry that is not a regular file or a directory, more than MaxFiles files, and more than maxBytes of file content in total. A tree Ptah wrote is read back this way before its digest is compared, so the bytes an operation reads are the ones that gave the digest.

Jump to

Keyboard shortcuts

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