runnerharness

package
v0.2.12 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package runnerharness runs the runner against the Ptah image support/ptah.json pins, without a cluster, and holds what Ptah printed to the committed captures.

The runner's contract with Ptah is the arguments it builds, the documents it decodes, the exit statuses it reads and the standard error it reads or ignores. The harness builds each operation's Job through internal/workload, runs that Job's containers in Docker in the shape the Job declares, with the runner from this commit calling a recording runner.Executor inside the executor image, against PostgreSQL, MySQL, an OCI registry and the end-to-end Git server. Every document is decoded with internal/dataplane, every result is framed and parsed back with the manager's parser, and everything is compared with the captures under internal/dataplane/testdata. A write mode regenerates those captures, so a repin is one command and a reviewed diff:

DOCKER_CONTEXT=<context> make runner-harness        # compare
DOCKER_CONTEXT=<context> make runner-harness-write  # regenerate

CompareCaptures and Masker say what counts as a change of shape and which values are volatile. Declared is the set of operations and commands the run is counted against. Translate is the stand-in for the kubelet.

A run removes what it made when it ends. One that passes its -timeout or is killed cannot, so a second process it starts, the janitor, clears it from outside. RunRecord is what a later run on the same daemon reads to clear a run whose janitor could not finish.

It does not replace kind. Admission, RBAC, the Job and Pod lifecycle, NetworkPolicy and durable result delivery are proven there.

Index

Constants

View Source
const (
	// RequireVariable says the harness has to run: a missing prerequisite then
	// fails it rather than skipping it. The make targets set it, so the target
	// CI runs can only pass by running every row, as PTAH_REQUIRE_ENVTEST does
	// for envtest. Unset, a plain `go test ./...` skips the run and touches no
	// Docker daemon.
	RequireVariable = "PTAH_REQUIRE_RUNNER_HARNESS"
	// ContextVariable names the Docker context to use. It has no default: every
	// container goes to the daemon somebody named.
	ContextVariable = "DOCKER_CONTEXT"
	// WriteVariable regenerates the committed captures.
	WriteVariable = "RUNNER_HARNESS_WRITE"
	// ImageVariable runs another executor image than the pin, to see what it
	// breaks. It cannot write captures.
	ImageVariable = "RUNNER_HARNESS_IMAGE"
	// PrefixVariable starts the name of everything the run creates, and a random
	// part follows it. Unset, the names start with ptah-runner-harness.
	PrefixVariable = "RUNNER_HARNESS_PREFIX"
	// OutVariable keeps the fresh captures of a run in this directory.
	OutVariable = "RUNNER_HARNESS_OUT"
)

The variables a run reads.

View Source
const CapturesDirectory = "internal/dataplane/testdata"

CapturesDirectory holds every committed capture, relative to the repository root: documents at the paths the decoders' tests read them from, and the transcript that says which row printed each one.

View Source
const RunLabel = "operator.ptah.run/runner-harness"

RunLabel marks the network a run creates first and removes last. Its value is the run's RunRecord, so a network that outlived its run says what is left of that run and when nothing can still be using it.

Variables

View Source
var Declared = struct {
	Operations []OperationCase
	Commands   []string
}{
	Operations: []OperationCase{
		{runner.OperationResolve, SourceOCI},
		{runner.OperationResolve, SourceGit},
		{runner.OperationVerify, SourceOCI},
		{runner.OperationObserve, SourceOCI},
		{runner.OperationObserve, SourceGit},
		{runner.OperationPlan, SourceOCI},
		{runner.OperationPlan, SourceGit},
		{runner.OperationApply, SourceNone},
		{runner.OperationMigrationHistory, SourceOCI},
		{runner.OperationMigrationHistory, SourceGit},
		{runner.OperationMigrationApply, SourceOCI},
		{runner.OperationMigrationApply, SourceGit},
	},
	Commands: []string{
		"migrations pull",
		"migrations status",
		"migrations up",
		"oci inspect",
		"oci resolve",
		"oci verify",
		"schema apply",
		"schema apply --dry-run",
		"schema drift",
		"schema plan",
		"schema pull",
		"schema validate",
	},
}

Declared is the set a complete run is held to. A row that runs anything else fails the run, and so does anything here that no row ran. A runner operation or a Ptah command added without a row here fails TestDeclaredCommandsAreTheOnesInTheSource, and a row reaching a new command fails the run: adding it is one line here and the row that runs it.

Functions

func CheckCount

func CheckCount(operations []OperationCase, commands []string, ran Ran) error

CheckCount holds what ran to the declared set, and fails on a declared case nothing ran, on a case nobody declared, and on a run of no rows.

func CommandWords

func CommandWords(args []string) string

CommandWords names a Ptah command by its first two arguments. The plan validation is a command of its own: it reads the same report at another outcome, and a release can change one and not the other.

func DecodeDocument

func DecodeDocument(args []string, exit int, stdout []byte) error

DecodeDocument reads what a child printed with the decoder the runner uses for that command, so a release that moves a contract fails here as it would in a Pod. A command that prints no document under this runner's arguments, the OCI fetch and a refused Git pull, has nothing to read.

func DocumentPath

func DocumentPath(row string, index int, command string, document []byte) string

DocumentPath is where a row's document is stored when the row names no other path: under the row's own name, numbered by the child that printed it.

func DrivenImages

func DrivenImages(driver []byte) (postgres, mysql, registry string, err error)

DrivenImages reads the database and registry images the lifecycle driver pins.

func MatchSourceCommands

func MatchSourceCommands(source, declared []string) error

MatchSourceCommands compares what the sources write down with the declared commands. "*" in a source command matches any word there.

func PinnedExecutor

func PinnedExecutor(catalog []byte) (image, commit, release string, err error)

PinnedExecutor reads the image, commit and release support/ptah.json pins for edge. The catalog is what a repin edits, so nothing here names a version.

func Scrub

func Scrub(document []byte) ([]byte, error)

Scrub removes the scrubbed fields from a document Ptah printed with two spaces of indentation, keeping every other byte. A document without them is returned as it came, and one that still holds them afterwards is an error.

func SourceCommands

func SourceCommands(directory string) ([]string, error)

SourceCommands reads the Ptah commands a package's sources write down: every []string literal assigned to Args or args whose first element is not a flag. An element that is not a string literal reads as "*", which stands for whichever verb or family the code computes.

func SourceOperations

func SourceOperations(source []byte) ([]runner.Operation, error)

SourceOperations reads the Operation constants a runner source declares.

func StrayFiles

func StrayFiles(root string, captures Captures) ([]string, error)

StrayFiles names the files under root that no row of the set names: a document the run no longer prints, which no test would ever read again.

func WriteCaptures

func WriteCaptures(root string, masker *Masker, committed, fresh Captures) error

WriteCaptures stores fresh as the committed captures under root.

A document whose only differences from the committed one are volatile values stays as it is, so a repin's diff holds what the release changed and nothing else. A file under root that no row names is removed.

Types

type Captures

type Captures struct {
	Rows       []Row
	Documents  map[string][]byte
	Provenance Provenance
}

Captures is a complete set: the rows, every document they name by its path under CapturesDirectory, and what they were captured from.

func LoadCaptures

func LoadCaptures(root string) (Captures, error)

LoadCaptures reads every committed capture.

type Change

type Change struct {
	Row        string
	Difference Difference
}

Change is one way a fresh run differs from the committed captures.

func CompareCaptures

func CompareCaptures(masker *Masker, committed, fresh Captures) []Change

CompareCaptures reports every change of shape between two sets, and a row or a document in one and not the other. What it compares under each row is the whole record, so an exit status, an argument, a line of standard error and the frame's payload are held exactly as a document's fields are.

func (Change) String

func (c Change) String() string

type Child

type Child struct {
	Command string   `json:"command"`
	Args    []string `json:"args"`
	Exit    int      `json:"exit"`
	Stderr  string   `json:"stderr,omitempty"`
	// Stdout is the file holding what it printed, under CapturesDirectory. A
	// child that printed nothing has none.
	Stdout string `json:"stdout,omitempty"`
}

Child is what one Ptah command did, in the form it is committed: arguments, standard error and status in the transcript, with the volatile values masked, and standard output in a file of its own, as printed.

type Cluster

type Cluster struct {
	Secrets    map[string]map[string][]byte
	ConfigMaps map[string]map[string][]byte
}

Cluster is the Secrets and ConfigMaps a Job's Pod reads, by name and key.

type Container

type Container struct {
	Name, Image    string
	Command, Args  []string
	WorkingDir     string
	Env            []EnvVar
	User           string
	ReadOnlyRoot   bool
	NoNewPrivilege bool
	DropCapability []string
	Mounts         []Mount
}

Container is one container of a Pod.

func (Container) RunArgs

func (c Container) RunArgs(name, network string, mounts func(Mount) ([]string, error), extraArgs ...string) ([]string, error)

RunArgs is the docker run command line for a container of the Pod. A Secret's value goes by name, so that it is on no command line: the caller sets it in the docker client's own environment (see SecretEnv).

mounts resolves each of the container's mounts to its --mount or --tmpfs flags.

func (Container) SecretEnv

func (c Container) SecretEnv() []string

SecretEnv is what the docker client's environment has to hold for RunArgs.

type Difference

type Difference struct {
	Path string
	// Kind is added, removed, retyped or changed.
	Kind      string
	Committed string
	Fresh     string
}

Difference is one change of shape, at a path inside a capture.

func CompareDocuments

func CompareDocuments(masker *Masker, committed, fresh []byte) []Difference

CompareDocuments reports every change of shape between two documents a child printed. JSON is compared as a tree and anything else line by line.

func CompareLines

func CompareLines(masker *Masker, committed, fresh string) []Difference

CompareLines reports every line of text that differs, by its number.

func CompareValues

func CompareValues(masker *Masker, committed, fresh any) []Difference

CompareValues reports every change of shape between two decoded JSON values.

func (Difference) String

func (d Difference) String() string

type EnvVar

type EnvVar struct {
	Name, Value string
	Secret      bool
}

EnvVar is a resolved environment variable. Secret says the value came from a Secret: the Job's literals are not secrets, and these are.

type Gate

type Gate struct {
	Required bool
	Context  string
	Write    bool
	Image    string
	Prefix   string
	Out      string
}

Gate is what a run was asked to do.

func ReadGate

func ReadGate(lookup func(string) string) (Gate, error)

ReadGate reads the variables. A required run with no Docker context is an error rather than a skip.

type Masker

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

Masker masks the volatile values and counts what each rule matched, so a run can refuse a rule that masked nothing. It is safe for concurrent use: the rows of a run share one.

func NewMasker

func NewMasker() *Masker

NewMasker is a Masker holding the declared rules.

func (*Masker) Text

func (m *Masker) Text(text string) string

Text masks the volatile parts of a string.

func (*Masker) UnusedRules

func (m *Masker) UnusedRules() []string

UnusedRules names the declared rules that masked nothing yet.

func (*Masker) Value

func (m *Masker) Value(value any) any

Value masks a decoded JSON value. A volatile key keeps its value's type and loses the value.

type Mount

type Mount struct {
	Volume, Path string
	ReadOnly     bool
}

Mount is one volume in a container.

type OperationCase

type OperationCase struct {
	Operation runner.Operation
	Source    Source
}

OperationCase is one operation from one source.

type Pod

type Pod struct {
	// InstallTo is where the Job installs the runner. The harness puts the
	// recorder there instead of running the install container.
	InstallTo string
	// Containers are the init containers after the runner's install, then the
	// operation container, in order.
	Containers []Container
	Volumes    []Volume
}

Pod is an operation Job's Pod, as the harness runs it. It carries the values the Job declares rather than a second statement of them: the user, the read- only root file system, the dropped capabilities, the environment, the mounts, the command and its arguments all come from the Job the builder made.

func Translate

func Translate(job *batchv1.Job, cluster Cluster) (Pod, error)

Translate turns a Job into the Pod the harness runs, and refuses anything it does not know how to run faithfully: a stand-in that ignored a new volume kind or a weakened security context would go on reporting what the Job no longer does.

type Provenance

type Provenance struct {
	PtahRelease string `json:"ptahRelease"`
	PtahCommit  string `json:"ptahCommit"`
	PtahImage   string `json:"ptahImage"`
}

Provenance is the Ptah build a set of captures was taken from.

type Ran

type Ran struct {
	Rows       int
	Operations map[OperationCase]int
	Commands   map[string]int
}

Ran is what a complete run counted.

type Row

type Row struct {
	Name      string `json:"name"`
	Operation string `json:"operation,omitempty"`
	Source    Source `json:"source,omitempty"`
	// Engine is the engine the row's target runs, as a plan's decoder is told it.
	Engine   string  `json:"engine,omitempty"`
	Children []Child `json:"children"`
	// Refusal is the error a fetch or a guard returned.
	Refusal string `json:"refusal,omitempty"`
	// Result is the frame's payload as the manager's parser read it.
	Result any `json:"result,omitempty"`
	// SavedPlan is the file holding the plan a Plan operation saved.
	SavedPlan string `json:"savedPlan,omitempty"`
}

Row is one operation's run, or one command a row ran on its own.

type RunRecord

type RunRecord struct {
	// Prefix starts the name of everything the run made.
	Prefix string `json:"prefix"`
	// Expires is a time after the run's own deadline. Until then the run may
	// still be alive, so another run on the same daemon leaves it alone.
	Expires time.Time `json:"expires"`
	// Pulled names the images the host did not hold when the run started.
	Pulled []string `json:"pulled,omitempty"`
}

RunRecord is what a later run needs to clear a run that died and whose janitor could not finish.

func ParseRunRecord

func ParseRunRecord(label string) (RunRecord, error)

ParseRunRecord reads the label's value. It refuses a record that does not say whose objects these are or when they expire, so a sweep removes nothing on the strength of it.

func (RunRecord) Expired

func (r RunRecord) Expired(now time.Time) bool

Expired says that no live run can still be using what the record names.

func (RunRecord) Label

func (r RunRecord) Label() (string, error)

Label is the record as the label's value.

type Source

type Source string

Source says where an operation read its artifact.

const (
	SourceOCI Source = "oci"
	SourceGit Source = "git"
	// SourceNone is an operation that reads no artifact: a schema Apply reads
	// its plan's bytes.
	SourceNone Source = "none"
)

type Volume

type Volume struct {
	Name  string
	Empty bool
	// SizeBytes bounds an empty volume.
	SizeBytes int64
	Files     []volumes.Entry
	// Group is the Pod's fsGroup.
	Group int
}

Volume is one volume of a Pod. A volume with Empty set starts empty and writable by the Pod's group; otherwise it holds Files.

Directories

Path Synopsis
Command runner-harness-recorder is the runner from this commit, in the form the harness runs inside the executor image.
Command runner-harness-recorder is the runner from this commit, in the form the harness runs inside the executor image.
Package recording is what the runner harness keeps of a run inside the executor image: a runner.Executor that records every child it starts, and the transcript test/runnerharness/recorder prints for the harness to read.
Package recording is what the runner harness keeps of a run inside the executor image: a runner.Executor that records every child it starts, and the transcript test/runnerharness/recorder prints for the harness to read.
Package volumes writes and unpacks what the harness's stand-in for the kubelet puts on a Pod's volumes: the directories an emptyDir starts as, and the files a Secret or a ConfigMap projects, with their owners and modes.
Package volumes writes and unpacks what the harness's stand-in for the kubelet puts on a Pod's volumes: the directories an emptyDir starts as, and the files a Secret or a ConfigMap projects, with their owners and modes.

Jump to

Keyboard shortcuts

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