engine

package
v0.4.1 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package engine ties a project to one environment: it builds components lazily from the plugin registry, resolves svc:// addresses through the runtime, and runs the multi-service operations (up, down, status) every front end shares.

Index

Constants

View Source 
const (
	TestRunning = "run"
	TestPass    = "pass"
	TestFail    = "fail"
	TestSkip    = "skip"
	TestStopped = "stopped"
)

Test statuses; a test still going is TestRunning, one cut short by a stop TestStopped.

View Source 
const AllValue = "$__all"

AllValue is the "all" choice of a dashboard variable: a regex that matches anything.

Variables

View Source 
var DefaultAlerts = []spec.Alert{
	{Name: "memory", Source: "hosts", Metric: "memory", Warn: 90, Crit: 98, Unit: "%"},
	{Name: "cpu", Source: "hosts", Metric: "cpu", Warn: 90, Crit: 98, Unit: "%"},
	{Name: "disk", Source: "hosts", Metric: "disk", Warn: 97, Crit: 98, Unit: "%"},
}

DefaultAlerts watch the nodes when rig.yaml names no alerts: memory and CPU at 90% and 98%, disk at 97% and 98%.

View Source 
var ErrOverMax = errors.New("rate above the generator's max (pass force to exceed it)")
View Source 
var ErrProtected = errors.New("environment is protected: pass --yes to change it")

ErrProtected stops a mutating operation on a protected environment unless the caller confirmed.

View Source 
var NamespaceOverride string

NamespaceOverride, when set, replaces the namespace of a Kubernetes environment for this run (rig -n); otherwise the one `rig ns` picked, kept in .rig/<env>/namespace, does.

Functions

func All 

func All[T any](a *App, kind core.Kind) (map[string]T, map[string]error)

All builds every configured component of kind; failures come back per name.

func DefaultVar 

func DefaultVar(v *spec.DashVar, values []string) []string

DefaultVar is what a variable starts as: its default, else all (when offered), else the first value.

func ExpandQuery 

func ExpandQuery(q string, vars map[string][]string, rng, step time.Duration) string

ExpandQuery fills a panel query's $variables (several values become a|b, all becomes .*) and Grafana's $__range, $__interval and $__rate_interval for the time range and step.

func FillQuery 

func FillQuery(q *spec.Query, args map[string]string) (string, []string)

FillQuery replaces {{name}} placeholders with args, then the query's defaults; it reports placeholders left without a value.

func Get 

func Get[T any](a *App, kind core.Kind, name string) (T, string, error)

Get returns component name of kind as T; with name "" the only (or first) one of that kind, falling back to what the runtime itself provides (logs, hosts) or to a default adapter.

func MarshalTargets 

func MarshalTargets(ts []ScrapeTarget) ([]byte, error)

func Pattern 

func Pattern(names []string) string

Pattern is a -run expression that matches exactly these tests (full names, TestX/sub/...), level by level: every name of a level is allowed at that level, so a few more may run.

func Ready 

func Ready(st core.Status) bool

Ready is the one readiness rule every front end uses.

func SortedKeys 

func SortedKeys[V any](m map[string]V) []string

SortedKeys is a small helper front ends use for stable output.

func WriteReportFile 

func WriteReportFile(file string, write func(io.Writer)) error

Types

type App 

type App struct {
	Spec *spec.Project
	Env  *spec.Environment
	// Confirmed lets mutating operations run on a protected environment.
	Confirmed bool
	// contains filtered or unexported fields
}

func Open 

func Open(file, env string) (*App, error)

Open loads the project file (found from dir when file is "") for env.

func (*App) AI 

func (a *App) AI(sock string) (*ai.Runner, error)

AI is the assistant's runner for this project and environment; sock is the bridge that answers its approvals and UI actions ("" when nothing can).

func (*App) AIDir 

func (a *App) AIDir() string

AIDir is where the project's AI sessions live.

func (*App) AlertRules 

func (a *App) AlertRules() []spec.Alert

func (*App) Build 

func (a *App) Build(ctx context.Context, s *spec.Service, tag string, out io.Writer) (string, error)

Build builds one service's image from the working tree and returns the reference.

func (*App) BuildFrom 

func (a *App) BuildFrom(ctx context.Context, s *spec.Service, tag, ref string, out io.Writer) (string, error)

BuildFrom builds one service's image with the builder its build section asks for, from a git ref when given, and returns the reference. Pushing over a tag the registry already has needs confirmation.

func (*App) CheckAlerts 

func (a *App) CheckAlerts(ctx context.Context) ([]Firing, []error)

CheckAlerts evaluates every rule once; the most severe firings come first. A rule that cannot be evaluated is reported as an error, not as a firing.

func (*App) Close 

func (a *App) Close() error

func (*App) Component 

func (a *App) Component(name string) (any, error)

Component builds (once) and returns the named component.

func (*App) CreateNamespace 

func (a *App) CreateNamespace(ctx context.Context, ns string) error

func (*App) DefaultImage 

func (a *App) DefaultImage(ctx context.Context, s *spec.Service) string

func (*App) DefaultTag 

func (a *App) DefaultTag(ctx context.Context, ref string) string

DefaultTag names a build: the branch (or ref) when it is short enough to read, then the time, e.g. feature-x-20261003-1907; a plain timestamp outside git or for long branch names.

func (*App) Deploy 

func (a *App) Deploy(ctx context.Context, name, tag string) error

Deploy rolls out a service. A tag deploys that tag of its image from the registry without building.

func (*App) Down 

func (a *App) Down(ctx context.Context, targets []string, out io.Writer) error

Down stops targets in reverse dependency order. With no targets it stops every app and load service: infrastructure, and services shared from another environment, stop only when named.

func (*App) EnvOverrides 

func (a *App) EnvOverrides(name string) map[string]string

EnvOverrides are the variables SetEnv gave a service.

func (*App) Environment 

func (a *App) Environment() *spec.Environment

func (*App) Exec 

func (a *App) Exec(ctx context.Context, name string, o core.ExecOptions) error

func (*App) Guard 

func (a *App) Guard() error

Guard refuses a mutating operation on a protected environment the caller did not confirm.

func (*App) ImageBased 

func (a *App) ImageBased() bool

ImageBased reports whether the runtime runs images (and so needs builds) rather than local processes.

func (*App) InfraApp 

func (a *App) InfraApp() (*App, error)

InfraApp opens (once) the environment that runs this one's shared services; nil when there is none.

func (*App) Kind 

func (a *App) Kind(name string) (core.Kind, string, error)

Kind tells which kind a configured component is, without building it.

func (*App) LoadLimits 

func (a *App) LoadLimits(name string) LoadLimits

func (*App) LoadState 

func (a *App) LoadState(ctx context.Context) (map[string]string, error)

func (*App) LoadTestRun 

func (a *App) LoadTestRun(id, suite string) (*TestRun, error)

LoadTestRun reads a saved run; id "" or "last" is the newest (of suite, when given).

func (*App) Logs 

func (a *App) Logs(ctx context.Context, name string, o core.LogOptions) (<-chan core.LogLine, error)

func (*App) ManifestDirs 

func (a *App) ManifestDirs() []string

ManifestDirs is where this project keeps Kubernetes manifests: the project's manifests:, else the runtime's manifests option, else the project directory.

func (*App) MeasureReport 

func (a *App) MeasureReport(ctx context.Context, name, source string, from, to time.Time) (*ReportResult, error)

MeasureReport runs a report's queries over [from, to] against source (default the report's own) and summarises every series they return.

func (*App) Names 

func (a *App) Names(kind core.Kind) []string

Names lists configured components of a kind, sorted.

func (*App) Namespace 

func (a *App) Namespace() string

Namespace is the namespace the environment works in, "" when it is not on Kubernetes.

func (*App) Namespaces 

func (a *App) Namespaces(ctx context.Context) ([]string, error)

Namespaces lists the cluster's namespaces.

func (*App) NewTestRun 

func (a *App) NewTestRun(suite string, o TestOptions) *TestRun

NewTestRun starts the record of a run of suite.

func (*App) Nudge 

func (a *App) Nudge(ctx context.Context, name string, dir int) (float64, error)

Nudge moves a generator's rate one step up (dir > 0) or down and returns the new rate.

func (*App) Owner 

func (a *App) Owner(name string) (core.Runtime, *spec.Service, error)

Owner returns the runtime that runs the named service and that environment's view of it.

func (*App) PreviousBenches 

func (a *App) PreviousBenches(r *TestRun) map[string]Bench

PreviousBenches are the benchmarks of the newest saved run of suite before r that has any, by package and name.

func (*App) Project 

func (a *App) Project() *spec.Project

func (*App) Queriers 

func (a *App) Queriers() map[string]core.Querier

Queriers lists every component that answers ad hoc queries, the runtime included.

func (*App) Queries 

func (a *App) Queries() map[string]*spec.Query

Queries are the project's saved queries with this environment's replacing those of the same name.

func (*App) QueryNames 

func (a *App) QueryNames() []string

func (*App) ReportFile 

func (a *App) ReportFile(name string, at time.Time) string

ReportFile is where a measured report is saved unless the caller names a file: the project's data directory, outside the repository.

func (*App) ReportNames 

func (a *App) ReportNames() []string

func (*App) Resolve 

func (a *App) Resolve(ctx context.Context, addr string) (string, error)

Resolve turns svc://service:port[/path] into an address reachable from here; anything else is returned as is.

func (*App) Resources 

func (a *App) Resources(ctx context.Context, name string) ([]core.Resources, error)

Resources reads the requests and limits of a service's containers.

func (*App) Restart 

func (a *App) Restart(ctx context.Context, name string) error

func (*App) RunQuery 

func (a *App) RunQuery(ctx context.Context, comp, text string) (core.Table, error)

RunQuery runs an ad hoc query against a component (or "runtime").

func (*App) RunSaved 

func (a *App) RunSaved(ctx context.Context, name string, args map[string]string) (core.Table, error)

RunSaved runs a saved query with placeholder values.

func (*App) RunTask 

func (a *App) RunTask(ctx context.Context, name string, args []string, out io.Writer) error

RunTask runs a task's steps in order with sh -c from the project directory, stopping at the first failure. svc:// addresses in a step become a host:port reachable from here, and a nested `rig` inherits this project, environment and confirmation. A NAME=value arg sets that env var for the steps (overriding any manifest var or pre-set shell env of the same name) instead of requiring it pre-set; every other arg reaches every step positionally as $1... and $RIG_ARGS.

func (*App) RunTests 

func (a *App) RunTests(ctx context.Context, s *spec.TestSuite, run *TestRun, jobs []TestJob) error

RunTests runs the jobs of a suite one after another into run, stopping at ctx's end, and saves the run when done. Every job but the first keeps the results the earlier ones reported.

func (*App) Runtime 

func (a *App) Runtime() core.Runtime

func (*App) SaveTestRun 

func (a *App) SaveTestRun(r *TestRun) error

func (*App) Scale 

func (a *App) Scale(ctx context.Context, name string, n int) error

func (*App) ScaleBy 

func (a *App) ScaleBy(ctx context.Context, names []string, delta int, set bool) error

ScaleBy moves each service's replica count by delta (or sets it, when set is true).

func (*App) ScrapeTargets 

func (a *App) ScrapeTargets(ctx context.Context, host string) ([]ScrapeTarget, error)

ScrapeTargets lists the environment's services with metrics as a Prometheus container on the docker runtime's network sees them: containers by name, local processes through host (the container's name for the host, host.docker.internal say).

func (*App) Service 

func (a *App) Service(name string) (*spec.Service, error)

func (*App) SetAutoscale 

func (a *App) SetAutoscale(ctx context.Context, name string, b core.Bounds) error

SetAutoscale moves the autoscaler bounds of a service.

func (*App) SetEnv 

func (a *App) SetEnv(ctx context.Context, names []string, kv map[string]string) error

SetEnv sets (an empty value removes) environment variables of services in this environment's state, so every later deploy keeps them, and redeploys the services that run so they take effect.

func (*App) SetRate 

func (a *App) SetRate(ctx context.Context, name string, rps float64, force bool) error

SetRate sets a generator's rate within its max, unless force, and records it in the run state.

func (*App) SetResources 

func (a *App) SetResources(ctx context.Context, name string, r core.Resources) error

SetResources changes one container's requests and limits (which restarts its pods).

func (*App) SetState 

func (a *App) SetState(ctx context.Context, kv map[string]string) error

SetState merges kv into the state; an empty value deletes the key.

func (*App) SharedElsewhere 

func (a *App) SharedElsewhere(name string) bool

SharedElsewhere reports whether the service runs in the infra environment rather than this one.

func (*App) Source 

func (a *App) Source(ctx context.Context, ref string) (string, error)

Source exports a git ref of the project's repository into the user cache (rig/src/<commit>, once per commit) and returns the directory that corresponds to the project directory inside it.

func (*App) Start 

func (a *App) Start(ctx context.Context, name string) error

func (*App) StartInOrder 

func (a *App) StartInOrder(ctx context.Context, names []string, wait time.Duration) error

StartInOrder starts names layer by layer in dependency order, waiting for a layer to be ready before the next: marking a whole chain and starting it never races its own dependencies.

func (*App) StateDir 

func (a *App) StateDir() string

func (*App) Status 

func (a *App) Status(ctx context.Context, name string) (core.Status, error)

func (*App) StatusAll 

func (a *App) StatusAll(ctx context.Context, names []string) []core.Status

StatusAll asks for every named service, in one call per runtime when the runtime can; errors become StateUnknown rows.

func (*App) Stop 

func (a *App) Stop(ctx context.Context, name string) error

func (*App) Suite 

func (a *App) Suite(name string) (*spec.TestSuite, error)

Suite is a test suite of rig.yaml by name.

func (*App) SuiteNames 

func (a *App) SuiteNames() []string

SuiteNames are the test suites in rig.yaml's order.

func (*App) TagImage 

func (a *App) TagImage(s *spec.Service, tag string) string

TagImage is the reference of s's image at tag in this environment's registry.

func (*App) Targets 

func (a *App) Targets(targets []string, deps bool) ([]string, error)

Targets expands names, groups and roles; unknown targets are an error.

func (*App) TaskHelp 

func (a *App) TaskHelp(name string) string

TaskHelp is a task's help, or its steps' first lines when it has none.

func (*App) TaskNames 

func (a *App) TaskNames() []string

func (*App) Tasks 

func (a *App) Tasks() map[string]spec.Task

Tasks are the project's tasks with this environment's replacing those of the same name.

func (*App) TestRuns 

func (a *App) TestRuns(suite string) []string

TestRuns are the saved runs' ids, newest first; suite "" is every suite.

func (*App) Up 

func (a *App) Up(ctx context.Context, targets []string, o UpOptions) error

Up builds (when asked) and deploys targets layer by layer in dependency order, waiting for each layer to be ready before the next starts. Dependencies pulled in by the targets, and infrastructure when no target is given, are only started when not already running, never redeployed.

func (*App) UseNamespace 

func (a *App) UseNamespace(ns string) error

UseNamespace makes ns this environment's namespace from now on; "" goes back to rig.yaml's.

func (*App) VarValues 

func (a *App) VarValues(ctx context.Context, v *spec.DashVar) ([]string, error)

VarValues are the choices of a dashboard variable: its fixed values, or the values of its label over the series its query returns now.

func (*App) Vars 

func (a *App) Vars(ctx context.Context) (map[string]Var, error)

Vars are the runtime's manifest variables: rig.yaml's, with `rig vars set` overrides from the environment's state on top.

func (*App) Wait 

func (a *App) Wait(ctx context.Context, name string, timeout time.Duration) (core.Status, error)

Wait polls the service until it is ready or timeout passes.

type Bench 

type Bench struct {
	Package string             `json:"package"`
	Name    string             `json:"name"`
	Procs   int                `json:"procs,omitempty"`
	N       int64              `json:"n"`
	Metrics map[string]float64 `json:"metrics"` // ns/op, B/op, allocs/op, MB/s and custom units
}

Bench is one benchmark result line.

type Firing 

type Firing struct {
	Alert   string
	Subject string
	Value   float64
	Unit    string
	Level   Level
}

Firing is one alert over a threshold, on one subject (a node, a queue, a row of its query).

func (Firing) String 

func (f Firing) String() string

type Level 

type Level int
const (
	LevelOK Level = iota
	LevelWarn
	LevelCrit
)

type LoadLimits 

type LoadLimits struct {
	Max  float64 `yaml:"max"`
	Step float64 `yaml:"step"`
}

type ReportResult 

type ReportResult struct {
	Name  string      `json:"name"`
	Env   string      `json:"env"`
	From  time.Time   `json:"from"`
	To    time.Time   `json:"to"`
	Stats []string    `json:"stats"`
	Rows  []ReportRow `json:"rows"`
}

ReportResult is a reports: entry measured over one window.

func (*ReportResult) Markdown 

func (r *ReportResult) Markdown(w io.Writer)

Markdown writes the report as a table, one row per series.

type ReportRow 

type ReportRow struct {
	Metric string             `json:"metric"`
	Series string             `json:"series,omitempty"`
	Unit   string             `json:"unit,omitempty"`
	Values map[string]float64 `json:"values"`
	Err    string             `json:"err,omitempty"`
}

ReportRow is one series of one metric, summarised.

type ScrapeTarget 

type ScrapeTarget struct {
	Targets []string          `json:"targets"`
	Labels  map[string]string `json:"labels"`
}

ScrapeTarget is one entry of a Prometheus file_sd file.

type TestCase 

type TestCase struct {
	Package  string    `json:"package"`
	Name     string    `json:"name,omitempty"`
	Status   string    `json:"status"`
	Elapsed  float64   `json:"elapsed,omitempty"`
	Parallel bool      `json:"parallel,omitempty"`
	Started  time.Time `json:"started"`
	Output   []string  `json:"output,omitempty"`
}

TestCase is one package (Name "") or test as go test -json reported it.

func (*TestCase) Depth 

func (c *TestCase) Depth() int

Depth is how many levels deep a test is: 1 for TestX, 2 for TestX/sub, 0 for a package.

type TestJob 

type TestJob struct {
	Options TestOptions
}

TestJob is one go test invocation of a run: these options, perhaps narrowed to some tests.

func RerunFailed 

func RerunFailed(r *TestRun, base TestOptions) []TestJob

RerunFailed are the jobs that run a run's failures again. Each failed test is cut back to its deepest parallel ancestor (a case that stands on its own, like one mode of an integration case), else to its top-level test, so the steps before it run too; tests cut to the same depth share a job.

type TestOptions 

type TestOptions struct {
	Packages  []string      `json:"packages,omitempty"`
	Run       string        `json:"run,omitempty"`
	Skip      string        `json:"skip,omitempty"`
	Race      bool          `json:"race,omitempty"`
	Cover     bool          `json:"cover,omitempty"`
	Short     bool          `json:"short,omitempty"`
	Failfast  bool          `json:"failfast,omitempty"`
	Shuffle   bool          `json:"shuffle,omitempty"`
	Count     int           `json:"count,omitempty"`
	Parallel  int           `json:"parallel,omitempty"`
	CPU       string        `json:"cpu,omitempty"`
	Timeout   time.Duration `json:"timeout,omitempty"`
	Bench     string        `json:"bench,omitempty"`
	Benchtime string        `json:"benchtime,omitempty"`
	Benchmem  bool          `json:"benchmem,omitempty"`
}

TestOptions are the go test flags of one run; Suite fills them from rig.yaml and the caller changes them.

func Only 

func Only(base TestOptions, pkg string, names ...string) TestOptions

Only narrows options to these tests of one package.

func OptionsFor 

func OptionsFor(s *spec.TestSuite) TestOptions

OptionsFor is what a suite runs with unless changed.

func (TestOptions) Args 

func (o TestOptions) Args(s *spec.TestSuite) []string

Args are the go test arguments for these options and the suite's fixed ones.

type TestRun 

type TestRun struct {
	ID       string             `json:"id"`
	Suite    string             `json:"suite"`
	Env      string             `json:"env"`
	Options  TestOptions        `json:"options"`
	Commands [][]string         `json:"commands"`
	Started  time.Time          `json:"started"`
	Ended    time.Time          `json:"ended"`
	Err      string             `json:"err,omitempty"`
	Tests    []*TestCase        `json:"tests"`
	Benches  []Bench            `json:"benches,omitempty"`
	Coverage map[string]float64 `json:"coverage,omitempty"`
	// Stderr is what go test printed outside its JSON: build errors, mostly.
	Stderr []string `json:"stderr,omitempty"`
	// Metrics is the suite's report: measured over the run.
	Metrics *ReportResult `json:"metrics,omitempty"`
	// contains filtered or unexported fields
}

TestRun is one go test invocation (or several, for a rerun of failures at different depths) and everything it reported. It is safe to read with Read while the run goes on.

func (*TestRun) Counts 

func (r *TestRun) Counts() map[string]int

Counts are the tests (not packages) per status.

func (*TestRun) Done 

func (r *TestRun) Done() bool

Done reports whether the run has ended.

func (*TestRun) FailedPackages 

func (r *TestRun) FailedPackages() int

FailedPackages are packages that failed on their own (a build failure, a panic in TestMain), not through a failed test.

func (*TestRun) Read 

func (r *TestRun) Read(f func(*TestRun))

Read calls f with the run locked.

func (*TestRun) Summary 

func (r *TestRun) Summary() string

Summary is one line about a run: counts, time, coverage.

func (*TestRun) WriteJUnit 

func (r *TestRun) WriteJUnit(w io.Writer) error

WriteJUnit writes the run as JUnit XML (one testsuite per package), for CI.

func (*TestRun) WriteReport 

func (r *TestRun) WriteReport(w io.Writer, failedOnly bool)

WriteReport writes a plain-text report: the summary, failures with their output, the slowest tests, benchmarks and coverage. failedOnly leaves out everything but the failures.

type UpOptions 

type UpOptions struct {
	Build bool
	// Tag names the images: what builds produce, or without Build, the tag to deploy from the registry.
	Tag string
	// Ref builds from a git ref (branch, tag, commit) instead of the working tree.
	Ref    string
	NoDeps bool
	Wait   time.Duration
	// Settle is how long up watches what it deployed after the last phase: a service that turned
	// ready and then crashed (a missing config key, say) fails the up instead of passing silently.
	Settle time.Duration
	// DryRun prints the phases and what each service would get, changing nothing.
	DryRun bool
	Out    io.Writer
}

type Var 

type Var struct {
	Value, From string
}

Var is a manifest variable and where its value comes from.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.