core

Documentation

Overview

Package core defines what every component kind must do. Adapters in adapters/<kind>/<type> implement one of these interfaces; anything an adapter can do beyond it is offered through the optional interfaces at the bottom (Forwarder, Actioner, Querier, ...), found by type assertion.

Index

• Variables
• func Confirmed(ctx context.Context) bool
• func DebugPort(service string) int
• func ImageRef(s *spec.Service, registry, tag string) string
• func WithConfirmed(ctx context.Context) context.Context
• func Writable(env Env) error
• type Action
• type Actioner
• type Autoscaler
• type Bounds
• type Bridger
• type Browser
• type BuildOptions
• type Builder
• type Cache
• type Database
• type DebugSession
• type Debugger
• type Editor
• type Env
• type EnvReader
• type ExecOptions
• type Forwarder
• type Host
• type HostPod
• type Hosts
• type ImageLoader
• type Instance
• type KV
• type Kind
• type Latency
• type LoadConfigured
• type LoadGenerator
• type LoadScaler
• type LoadStatus
• type LogLine
• type LogOptions
• type LogQuery
  • func (q LogQuery) Matcher() (func(string) bool, error)
• type LogSource
• type Messaging
• type Metrics
• type PathQuerier
• type Pinger
• type Point
• type ProcessLocator
• type Profile
• type ProfileRequest
• type Profiler
• type Pusher
• type Querier
• type Queue
• type QueueInspector
• type Registrar
• type Relauncher
• type Release
• type Resourcer
• type Resources
• type RowQuerier
• type Runtime
• type Sample
• type Seeder
• type Series
• type Snapshotter
• type Span
• type State
• type StateStore
• type Status
• type StatusLister
• type Table
• type Target
• type TraceQuery
• type TraceSummary
• type Tracing
• type Workload

Variables

var ErrReadOnly = errors.New("environment is read-only (readonly: true in rig.yaml)")

ErrReadOnly refuses a change in an environment rig.yaml marks readonly: true, whatever confirms it.

var ErrTagExists = errors.New("tag already exists in the registry: pass --yes to overwrite it")

ErrTagExists stops a push that would replace an image tag already in the registry, unless confirmed.

var ErrUnsupported = errors.New("not supported by this adapter")

var Kinds = []Kind{KindRuntime, KindBuilder, KindMetrics, KindTracing, KindProfiler, KindDebugger, KindLogs,
	KindDatabase, KindCache, KindMessaging, KindKV, KindLoad, KindHosts, KindQuery}

Functions

func Confirmed

func Confirmed(ctx context.Context) bool

func DebugPort

func DebugPort(service string) int

DebugPort is the local port a service's debugger listens on: the same every time, so an IDE's remote-debug configuration written once keeps working.

func ImageRef

func ImageRef(s *spec.Service, registry, tag string) string

ImageRef names the image a builder produces for s: registry/repo:tag, repo being s.Image or s.Name.

func WithConfirmed

func WithConfirmed(ctx context.Context) context.Context

WithConfirmed marks ctx as carrying the user's go-ahead for destructive actions (--yes, a TUI confirm).

func Writable

func Writable(env Env) error

Writable refuses with ErrReadOnly when env's environment is read-only.

Types

type Action

type Action struct {
	Name   string
	Help   string
	Mutate bool
	Run    func(ctx context.Context, args []string, out io.Writer) error
}

Action is an adapter-specific operation, exposed as `rig do <component> <action>`.

type Actioner

type Actioner interface {
	Actions() []Action
}

type Autoscaler

type Autoscaler interface {
	SetAutoscale(ctx context.Context, s *spec.Service, b Bounds) error
}

Autoscaler is a runtime whose services can have an autoscaler (a Kubernetes HPA) bounding their scale. SetAutoscale moves an existing autoscaler's range, or creates one with b's targets.

type Bounds

type Bounds struct{ Min, Max, CPU, Memory int }

Bounds is an autoscaler's replica range; CPU and Memory are the average utilization (percent of requests) it scales on, used when SetAutoscale creates one (0: not a target).

type Bridger

type Bridger interface {
	Bridge(ctx context.Context, s *spec.Service, ports map[int]string) error
}

Bridger makes a service that runs elsewhere (on this machine, in docker) reachable inside the runtime under its own name, at the given host:port per service port.

type Browser

type Browser interface {
	Browse(ctx context.Context, path []string) (t Table, leaf bool, err error)
}

Querier answers ad hoc queries in its own language: SQL, PromQL, a redis command, ... Browser lets a data component be walked as a tree: the rows under a path, whose first column names each child, until a leaf (a table's rows, a key's value) ends it.

type BuildOptions

type BuildOptions struct {
	Tag      string
	Registry string
	Push     bool
	Out      io.Writer
	// Dir is the source tree to build from; empty means the project directory.
	Dir string
}

type Builder

type Builder interface {
	Build(ctx context.Context, s *spec.Service, o BuildOptions) (image string, err error)
}

type Cache

type Cache interface {
	Do(ctx context.Context, args ...string) (string, error)
	Info(ctx context.Context) (map[string]string, error)
}

type Database

type Database interface {
	Query(ctx context.Context, db, query string) (Table, error)
	Exec(ctx context.Context, db, query string) (int64, error)
	Databases(ctx context.Context) ([]string, error)
	CreateDatabase(ctx context.Context, name string) error
	DropDatabase(ctx context.Context, name string) error
}

type DebugSession

type DebugSession struct {
	Addr  string
	Hint  string
	Close func() error
}

type Debugger

type Debugger interface {
	Attach(ctx context.Context, s *spec.Service, instance string) (DebugSession, error)
}

type Editor

type Editor interface {
	Delete(ctx context.Context, path []string, t Table, rows []int) error
	Set(ctx context.Context, path []string, t Table, row, col int, value string) error
}

Editor changes what a Browse of path returned in t: Delete removes rows (indexes into t.Rows), Set writes one cell. Each refuses a level it cannot change safely.

type Env

type Env interface {
	Project() *spec.Project
	Environment() *spec.Environment
	Runtime() Runtime
	Resolve(ctx context.Context, addr string) (string, error)
	Component(name string) (any, error)
	StateDir() string
	// DefaultImage is what to run for s when no release names one: the image last built for it, else its image field.
	DefaultImage(ctx context.Context, s *spec.Service) string
	// Owner is the runtime a service runs on (another environment's, for shared infrastructure).
	Owner(service string) (Runtime, *spec.Service, error)
}

Env is what an adapter can reach: the project, the runtime of the active environment, address resolution through that runtime, and the other components.

type EnvReader

type EnvReader interface {
	LiveEnv(ctx context.Context, s *spec.Service) (map[string]string, error)
}

EnvReader is a runtime that reads the environment variables a service's workload runs with.

type ExecOptions

type ExecOptions struct {
	Command  []string
	Instance string
	TTY      bool
	Stdin    io.Reader
	Stdout   io.Writer
	Stderr   io.Writer
}

type Forwarder

type Forwarder interface {
	Forward(ctx context.Context, t Target) (string, error)
}

Forwarder makes a port of a service reachable from this machine and returns host:port. Forwards live until the runtime is closed.

type Host

type Host struct {
	Name  string
	Addr  string
	Roles []string
	Ready bool
	// Reason says why Ready is false, when the adapter knows (e.g. a probe error); empty otherwise.
	Reason   string
	OS       string
	Kernel   string
	CPUs     int
	CPUUsed  float64 // 0..1
	MemTotal int64
	MemUsed  int64
	// DiskTotal and DiskUsed are the root (or kubelet) filesystem's, when the adapter knows them.
	DiskTotal int64
	DiskUsed  int64
	Load1     float64
	Labels    map[string]string
	// Pods are what runs on the host, when the adapter knows (Kubernetes nodes).
	Pods []HostPod
}

type HostPod

type HostPod struct {
	Namespace string
	Name      string
	CPU       float64 // cores
	Mem       int64
	Started   time.Time
}

type Hosts

type Hosts interface {
	Hosts(ctx context.Context) ([]Host, error)
	// Shell returns a command that opens a shell (or runs command) on the host, ready to attach to a terminal.
	Shell(ctx context.Context, host string, command []string) (*exec.Cmd, error)
}

type ImageLoader

type ImageLoader interface {
	LoadImage(ctx context.Context, image string) error
}

ImageLoader puts a locally built image where the runtime can run it without a registry.

type Instance

type Instance struct {
	ID       string
	Host     string
	IP       string
	State    State
	Ready    bool
	Restarts int
	Started  time.Time
	CPU      float64 // cores
	Memory   int64   // bytes
}

type KV

type KV interface {
	Get(ctx context.Context, key string) ([]byte, bool, error)
	Put(ctx context.Context, key string, value []byte) error
	Delete(ctx context.Context, key string) error
	List(ctx context.Context, prefix string) ([]string, error)
}

type Kind

type Kind string

const (
	KindRuntime   Kind = "runtime"
	KindBuilder   Kind = "builder"
	KindMetrics   Kind = "metrics"
	KindTracing   Kind = "tracing"
	KindProfiler  Kind = "profiler"
	KindDebugger  Kind = "debugger"
	KindLogs      Kind = "logs"
	KindDatabase  Kind = "database"
	KindCache     Kind = "cache"
	KindMessaging Kind = "messaging"
	KindKV        Kind = "kv"
	KindLoad      Kind = "loadgen"
	KindHosts     Kind = "hosts"
	KindQuery     Kind = "query"
)

type Latency

type Latency struct {
	P50, P95, P99 time.Duration
}

type LoadConfigured

type LoadConfigured interface {
	ConfigKey() (store, key string)
	Services() []string
}

LoadConfigured is a load generator whose settings live in a KV key and that runs as services: the Load screen edits that key and those services' env.

type LoadGenerator

type LoadGenerator interface {
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
	SetRate(ctx context.Context, rps float64) error
	Status(ctx context.Context) (LoadStatus, error)
}

type LoadScaler

type LoadScaler interface {
	Replicas(ctx context.Context) (int, error)
	SetReplicas(ctx context.Context, n int) error
}

LoadScaler is a load generator that runs as replicas: more replicas, more load.

type LoadStatus

type LoadStatus struct {
	Running bool
	Rate    float64 // configured requests per second
	Sent    int64
	Failed  int64
	Latency Latency
	Extra   map[string]string
	// PerInstance is each generator instance's sent counter, when the generator reports one.
	PerInstance map[string]int64
}

type LogLine

type LogLine struct {
	Time     time.Time
	Service  string
	Instance string
	Stream   string
	Text     string
}

type LogOptions

type LogOptions struct {
	Follow   bool
	Since    time.Duration
	Tail     int
	Instance string
}

type LogQuery

type LogQuery struct {
	Services []string
	// Instance narrows a single-service query to one instance (pod, container).
	Instance string
	Since    time.Duration
	Tail     int
	Follow   bool
	Match    string
	// Regex makes Match an RE2 regular expression ((?i) for any case) instead of plain text.
	Regex bool
}

func (LogQuery) Matcher

func (q LogQuery) Matcher() (func(string) bool, error)

Matcher is q's line filter; an invalid regular expression is an error.

type LogSource

type LogSource interface {
	Logs(ctx context.Context, q LogQuery) (<-chan LogLine, error)
}

type Messaging

type Messaging interface {
	Queues(ctx context.Context) ([]Queue, error)
	Purge(ctx context.Context, queue string) error
	Publish(ctx context.Context, target string, body []byte) error
}

type Metrics

type Metrics interface {
	Instant(ctx context.Context, query string) ([]Sample, error)
	Range(ctx context.Context, query string, start, end time.Time, step time.Duration) ([]Series, error)
}

type PathQuerier

type PathQuerier interface {
	QueryAt(ctx context.Context, path []string, q string) (Table, error)
	SuggestQuery(ctx context.Context, path []string) string
}

PathQuerier runs a query where a Browser walk stands (the database of path[0], say) and suggests one for a path: the Data screen's "query this" (a procedure's call with its parameters to fill, say).

type Pinger

type Pinger interface {
	Ping(ctx context.Context) error
}

Pinger reports whether a component is reachable.

type Point

type Point struct {
	T time.Time
	V float64
}

type ProcessLocator

type ProcessLocator interface {
	PID(service string) (int, bool)
}

ProcessLocator gives the host pid of a service, for runtimes whose services are local processes.

type Profile

type Profile struct {
	Kind    string
	Format  string
	File    string
	Summary string
}

type ProfileRequest

type ProfileRequest struct {
	Service  *spec.Service
	Instance string
	Kind     string
	Duration time.Duration
	OutDir   string
}

type Profiler

type Profiler interface {
	Kinds() []string
	Capture(ctx context.Context, r ProfileRequest) (Profile, error)
}

type Pusher

type Pusher interface {
	Push(ctx context.Context, image string, out io.Writer) error
}

Pusher is a builder that can push an image already in the local Docker daemon; without one, rig runs docker push.

type Querier

type Querier interface {
	QueryLanguage() string
	RunQuery(ctx context.Context, q string) (Table, error)
}

type Queue

type Queue struct {
	Name      string
	Messages  int
	Ready     int
	Unacked   int
	Consumers int
	InRate    float64
	OutRate   float64
}

type QueueInspector

type QueueInspector interface {
	QueueInfo(ctx context.Context, queue string) (Table, error)
	Peek(ctx context.Context, queue string, n int) (Table, error)
	DeleteQueue(ctx context.Context, queue string) error
}

QueueInspector shows one queue in depth on the Data screen: its settings, bindings and consumers as field/value rows, a peek at its messages (they stay queued), and deleting it.

type Registrar

type Registrar interface {
	Registry() string
}

Registrar tells builders where this environment pulls images from.

type Relauncher

type Relauncher interface {
	Relaunch(ctx context.Context, s *spec.Service, wrap func(argv []string) []string) error
}

Relauncher restarts a local service with its command wrapped, e.g. under a debugger.

type Release

type Release struct {
	Image    string
	Env      map[string]string
	Replicas int
}

Release is what Deploy rolls out; empty fields keep what the service already runs.

type Resourcer

type Resourcer interface {
	Resources(ctx context.Context, s *spec.Service) ([]Resources, error)
	SetResources(ctx context.Context, s *spec.Service, r Resources) error
}

Resourcer is a runtime whose services' containers have requests and limits to read and change.

type Resources

type Resources struct {
	Container                                  string
	CPURequest, CPULimit, MemRequest, MemLimit string
}

Resources are one container's requests and limits, as Kubernetes quantities ("" leaves one unset).

type RowQuerier

type RowQuerier interface {
	SuggestRowQuery(ctx context.Context, path []string, t Table, row int) string
}

RowQuerier suggests a query that reads one row of what a Browse of path returned (Q on a row of the Data screen), e.g. a SELECT by its primary key.

type Runtime

type Runtime interface {
	Discover(ctx context.Context) ([]Workload, error)
	Start(ctx context.Context, s *spec.Service) error
	Stop(ctx context.Context, s *spec.Service) error
	Restart(ctx context.Context, s *spec.Service) error
	Status(ctx context.Context, s *spec.Service) (Status, error)
	Scale(ctx context.Context, s *spec.Service, replicas int) error
	Logs(ctx context.Context, s *spec.Service, o LogOptions) (<-chan LogLine, error)
	Exec(ctx context.Context, s *spec.Service, o ExecOptions) error
	Deploy(ctx context.Context, s *spec.Service, r Release) error
}

type Sample

type Sample struct {
	Labels map[string]string
	Value  float64
}

type Seeder

type Seeder interface {
	Seed(ctx context.Context, log io.Writer) error
	Fresh(ctx context.Context) (bool, error)
	Host() string
}

Seeder fills a database with its seed (SQL files or commands). Fresh tells whether it holds no tables yet; Host is the rig service it runs in ("" for none), which rig up seeds when it starts empty.

type Series

type Series struct {
	Labels map[string]string
	Points []Point
}

type Snapshotter

type Snapshotter interface {
	Snapshot(ctx context.Context, file string, log io.Writer) error
	Restore(ctx context.Context, file string, log io.Writer) error
}

Snapshotter saves a data component's contents to a file and puts them back, with the server's own tools. Restore replaces what is there.

type Span

type Span struct {
	TraceID  string
	ID       string
	Parent   string
	Service  string
	Name     string
	Start    time.Time
	Duration time.Duration
	Error    bool
	Tags     map[string]string
}

type State

type State string

const (
	StateRunning  State = "running"
	StateStarting State = "starting"
	StateDegraded State = "degraded"
	StateStopped  State = "stopped"
	StateFailed   State = "failed"
	StateAbsent   State = "absent"
	StateUnknown  State = "unknown"
)

type StateStore

type StateStore interface {
	LoadState(ctx context.Context) (map[string]string, error)
	SaveState(ctx context.Context, state map[string]string) error
}

StateStore keeps small run state (current tag, rates, databases) where the whole team sees it.

type Status

type Status struct {
	Service   string
	State     State
	Ready     int
	Desired   int
	Image     string
	Message   string
	Instances []Instance
	// Autoscale is the range an autoscaler keeps the replica count in, nil when none does.
	Autoscale *Bounds
}

type StatusLister

type StatusLister interface {
	StatusAll(ctx context.Context, services []*spec.Service) ([]Status, error)
}

StatusLister answers the status of many services in one round trip (one kubectl or docker call).

type Table

type Table struct {
	Columns []string
	Rows    [][]string
	Note    string
}

type Target

type Target struct {
	Service  string
	Instance string
	Port     int
}

type TraceQuery

type TraceQuery struct {
	Service     string
	Operation   string
	MinDuration time.Duration
	Lookback    time.Duration
	Limit       int
}

type TraceSummary

type TraceSummary struct {
	ID       string
	Root     string
	Start    time.Time
	Duration time.Duration
	Spans    int
	Services []string
	Error    bool
}

type Tracing

type Tracing interface {
	Services(ctx context.Context) ([]string, error)
	Search(ctx context.Context, q TraceQuery) ([]TraceSummary, error)
	Trace(ctx context.Context, id string) ([]Span, error)
}

type Workload

type Workload struct {
	Name    string
	Kind    string
	Service string // the rig service it belongs to, "" when unmanaged
	Status  Status
}

Workload is something running in the environment, managed by rig or not.