Documentation
¶
Overview ¶
Package ops implements the App Ops Interface contract v1 (plan §4): discovery, the versioned descriptor, Terminus-style health normalization, queues, the pluggable adapter seam, and the per-app prober. All app responses are treated as hostile input: size-capped (by opsclient), schema-checked, and on ANY parse failure the app degrades to BASIC — never a crash (plan §4.3).
Index ¶
- Variables
- func Register(a Adapter)
- func ValidateBaseURL(raw string) error
- type Adapter
- type Config
- type ConfigStore
- type Descriptor
- type Discovery
- type Doer
- type Indicator
- type MetricGroup
- type MetricItem
- type Mode
- type Prober
- type Queue
- type QueueCount
- type Result
- type ServiceResolver
- type SetInput
- type SnapshotPoint
- type Status
- type Target
Constants ¶
This section is empty.
Variables ¶
var ( ErrBadQueueAction = errors.New("ops: invalid queue action") ErrBadQueueName = errors.New("ops: invalid queue name") ErrOpsNotEnabled = errors.New("ops: not enabled for this app") ErrQueueFailed = errors.New("ops: queue action failed") )
ErrBadQueueAction / ErrBadQueueName guard the server-side queue proxy.
Functions ¶
func ValidateBaseURL ¶
ValidateBaseURL enforces the pinned-origin rules (plan §4.1): http(s) scheme, a host, NO path/query/fragment, and not a loopback literal (loopback can't be distinguished from the control plane, which is loopback-bound).
Types ¶
type Adapter ¶
type Adapter interface {
Name() string
// Discover classifies the app (RICH/BASIC) and returns its capabilities.
Discover(ctx context.Context, c Doer, t Target) Discovery
// Probe fetches and normalizes the live record for a RICH app.
Probe(ctx context.Context, c Doer, t Target, d Discovery) Result
}
Adapter is the §4.4 plugin seam: ops.v1 is built in; others (Prometheus, plain /healthz) can register so non-Terminus apps light up RICH panels too.
type Config ¶
type Config struct {
Project string
Enabled bool
BaseURL string
SecretHeader string
Secret secret.Redacted
HasSecret bool
OpsMode string // auto | rich | basic
BasePath string
Adapter string
}
Config is one app's ops coordinates. The decrypted Secret lives only in memory (Redacted); it is never sent to the browser and never logged (plan §4.1/§5.5).
type ConfigStore ¶
type ConfigStore struct {
// contains filtered or unexported fields
}
ConfigStore persists per-app ops config, encrypting the shared secret.
func NewConfigStore ¶
func NewConfigStore(db *store.DB, cipher *secret.Cipher) *ConfigStore
NewConfigStore builds a store. cipher must be the master AES-256-GCM cipher.
func (*ConfigStore) DeleteApp ¶
func (s *ConfigStore) DeleteApp(project string) error
DeleteApp removes an app's ops config (incl. the encrypted shared secret) and its recorded health-score history. Used by the app-delete teardown.
func (*ConfigStore) EnabledProjects ¶
func (s *ConfigStore) EnabledProjects() ([]string, error)
EnabledProjects returns the projects with ops probing enabled.
func (*ConfigStore) Get ¶
func (s *ConfigStore) Get(project string) (Config, bool, error)
Get returns an app's ops config, decrypting the secret. ok=false if none.
type Descriptor ¶
type Descriptor struct {
OpsInterfaceVersion string `json:"opsInterfaceVersion"`
Capabilities []string `json:"capabilities"`
BasePath string `json:"basePath"`
}
Descriptor is the public GET /.well-known/ops document (plan §4.1).
type Discovery ¶
type Discovery struct {
Mode Mode
Version string
Capabilities []string
BasePath string
Note string
}
Discovery is the outcome of the discovery phase (plan §4.1).
type Doer ¶
type Doer interface {
Get(ctx context.Context, base, relPath, secretHeader string, sec secret.Redacted) (*opsclient.Response, error)
Post(ctx context.Context, base, relPath, secretHeader string, sec secret.Redacted, body []byte) (*opsclient.Response, error)
}
Doer is the minimal SSRF-safe client surface adapters use. *opsclient.Client satisfies it; tests inject a fake. (All host-pinning/rebind defense lives in the concrete client — this interface only decouples for testing.)
type Indicator ¶
type Indicator struct {
Name string
Status string // up | down | degraded | unknown
Message string
Source string // adapter name, e.g. "ops.v1"
}
Indicator is one normalized per-dependency health tile (plan §4.3).
type MetricGroup ¶
type MetricGroup struct {
Title string
Items []MetricItem
}
MetricGroup is a titled card of metric items — the open-ended "monitor" unit. The app names the groups it wants (Database, Cache, Routes, System, Memory, …); Mooring renders each as a panel, so the set is NOT limited to a fixed schema.
type MetricItem ¶
type MetricItem struct {
Label string
Value string
Unit string
Status string // "" | up | down | degraded | unknown
}
MetricItem is one labeled value within a metric group (e.g. "Hit rate" = "94.2" "%"). Status is optional and only used to color the row (up/down/degraded).
type Mode ¶
type Mode string
Mode distinguishes a RICH (contract-implementing) app from a BASIC one.
type Prober ¶
type Prober struct {
// contains filtered or unexported fields
}
Prober runs discovery + probe for one app per call (the monitor drives the cadence: sequential + jittered, plan §4). It also persists the snapshot ring and performs server-side-proxied queue actions.
func NewProber ¶
func NewProber(cs *ConfigStore, client Doer, db *store.DB, resolve ServiceResolver) *Prober
NewProber builds a Prober. client is the SSRF-safe outbound client; resolve rewrites a service-name base_url to the backing container's bridge IP (nil = literal-IP only).
func (*Prober) Probe ¶
Probe returns the canonical ops Result for a project. ok=false means ops is not enabled for this app (it stays BASIC from Docker-derived data).
func (*Prober) ProbeTarget ¶
func (p *Prober) ProbeTarget(ctx context.Context, project string, target Target, adapterName, mode string) *Result
ProbeTarget probes ONE ops Target directly (no DB-backed config, no snapshot ring), for per-service ops driven from the canonical mooring.yaml. mode is auto|rich|basic. Returns nil when mode is "basic" (ops disabled for the service).
type Queue ¶
type Queue struct {
Name string
IsPaused bool
Counts []QueueCount
}
Queue is a normalized queue row (plan §4.2).
type QueueCount ¶
QueueCount is one named counter within a queue.
type Result ¶
type Result struct {
Mode Mode
Version string
Capabilities []string
Indicators []Indicator
Queues []Queue
Metrics []MetricGroup
Snapshot []SnapshotPoint
AlertingCapable bool
Err string
}
Result is the canonical ops record attached to a service (plan §4.3: one record, distinguished by Mode + per-indicator Source).
func (Result) HealthScore ¶
HealthScore returns the fraction of indicators that are up (1.0 if none).
type ServiceResolver ¶
ServiceResolver maps (project, service) → a routable container bridge IP, via the read-only socket-proxy. ok=false when no running replica is found. It exists because the control plane is a host process that cannot resolve a compose service name (those live only on Docker's internal DNS) — so a base_url like http://api:3000 must be rewritten to the container's IP before the prober dials it. nil disables the rewrite (only literal-IP base_urls work then).
type SetInput ¶
type SetInput struct {
Enabled bool
BaseURL string
SecretHeader string
NewSecret *string
OpsMode string
BasePath string
Adapter string
}
SetInput is an operator's ops-config edit. NewSecret is tri-state: nil keeps the stored secret, "" clears it, any other value replaces it.
type SnapshotPoint ¶
SnapshotPoint is one health-score ring sample for the sparkline.
type Status ¶
Status is the cached discovery/probe state for an app (review #10: surfaces the disc_* columns the prober records so the operator can see last outcome).
type Target ¶
type Target struct {
BaseURL string
SecretHeader string
Secret secret.Redacted
BasePath string // operator-configured fallback prefix; descriptor may override
}
Target is everything an adapter needs to reach an app's ops endpoints. The host is pinned by BaseURL; the secret travels server-side only (plan §4.1).