Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ Use golangci-lint v2 and a current govulncheck. All checks are blocking.
- **No `os/exec`** in non-test code, and no schema validator in the binary. The linter enforces both.
- **One HTTP client.** Every call to a backend goes through `internal/httpx`: GET only, no redirect, no proxy, a body cap, a deadline, two calls in flight per backend. The linter rejects `net/http` anywhere else in non-test code.
- **Severity comes from authorities.** Vigil combines verdicts and applies the stale and missing-authority caps. It does not compute severity from raw data.
- **Slugs only.** Use the public host slugs (`castle`, `tower`, `citadel`, `apiary`, `lathe`, `box`) in code, docs, fixtures and examples. No IP addresses, hostnames or secrets. Placeholders use reserved documentation values. Real addresses live in an untracked overlay.
- **Aliases only.** Fixtures, docs and examples use neutral host aliases (`core`, `spoke`, `depot`, `annex`, `lab`, `edge`) and `example.invalid`, never real machine names. No IP addresses, hostnames or secrets. Placeholders use reserved documentation values. An operator's real slugs and addresses live only in their untracked, off-repo overlay.
- **Schemas are the contract.** JSON Schemas under `schema/` are written by hand. A change that adds a field is additive within `v0`; anything that removes or renames one needs a new major.
- **Hermetic tests.** Table-driven, `httptest` for every backend, no live network, no wall clock (inject the clock).

Expand Down
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Facet is the chrome), and it never computes severity from raw data.
```
Simplex ──verdict document (file)──────▶ ──vigil.summary/v0 (pull, read token)──▶ Facet
Augur ──verdict document (file)──────▶ Vigil ◀──vigil.signal/v0 (POST, write token)─────
prom (lathe) · grafana (lathe) ──named──▶ Cubit / Scry ──▶ informational blocks
prom (lab) · grafana (lab) ──named──▶ Cubit / Scry ──▶ informational blocks
```

## Reading a summary (V2)
Expand Down Expand Up @@ -133,7 +133,8 @@ in the config is exit 5 for every command.
as `redacted`. A scrape URL, a last error or discovered labels never reach
the output.
- `prom query` runs exactly one named query from the config. The host slug is
the only template variable and `--host` must be a mapped or public slug.
the only template variable and `--host` must be a slug the overlay's
`hosts[]` defines.
The request asks for one series more than the cap, so more results fail
with `series_cap` instead of a truncated answer; any backend warning fails
with `query_warnings` instead of a partial answer. Every result carries the
Expand Down Expand Up @@ -166,7 +167,7 @@ in the config is exit 5 for every command.
environment reference, and an optional `vantage` label on the prom backend.
Backend addresses live in an overlay (`example.overlay.yaml` is the tracked
example; a real overlay is never committed); the overlay's `hosts[]` maps the
instance labels a backend reports onto public slugs. Both examples validate
instance labels a backend reports onto the slugs it prints. Both examples validate
against the JSON Schemas under `schema/`.

`overall` is the worst severity among the readable verdicts in `verdicts[]`,
Expand Down
6 changes: 3 additions & 3 deletions cmd/vigil/fuzz_cli_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -40,16 +40,16 @@ var usageMessages = map[string]bool{
// overridden never reaches anything.
func FuzzCLIArgs(f *testing.F) {
for _, s := range []string{
"version", "prom targets", "prom query up_all", "prom query up_by_host --host castle",
"version", "prom targets", "prom query up_all", "prom query up_by_host --host core",
"sources --json", "grafana health --now 2026-11-14T09:00:00Z", "--help", "prom --help",
"sources http://leak.example.invalid/x", "prom query up{job=\"x\"}", "--config https://leak.example.invalid sources",
"--overlay //leak/x sources", "prom query rate(x[5m]) --host 192.0.2.7:9090", "--now yesterday sources",
"--nope", "-x", "", "prom", "grafana", "help", "completion bash", "sources --config", "--json=maybe sources",
"prom query a b", "version extra", "sources --host castle", "--now 2026-11-14T09:00:00Z --json prom targets",
"prom query a b", "version extra", "sources --host core", "--now 2026-11-14T09:00:00Z --json prom targets",
"prom query http://leak.example.invalid/x", "prom query up_all --host http://leak.example.invalid",
"prom query up(x)", "prom query up_all --host a{b}",
"prom query a --host \" --host ", "-hh \"", "\"000000 -h", "--overlay \" sources",
"prom query up_all --config ? --overlay #", "prom query up_all --host Castle", "prom query UP",
"prom query up_all --config ? --overlay #", "prom query up_all --host Core", "prom query UP",
} {
f.Add(s)
}
Expand Down
4 changes: 2 additions & 2 deletions cmd/vigil/wire_grafana_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ listen: 127.0.0.1:10082
backends:
- id: prom
kind: prom
vantage: lathe
vantage: lab
- id: grafana
kind: grafana
authorities:
Expand Down Expand Up @@ -263,7 +263,7 @@ func TestSourcesRowsAreData(t *testing.T) {
if r.LastOK != nil {
t.Errorf("%s: last_ok = %v, V1 keeps no state", tc.name, *r.LastOK)
}
if r.Kind == "prom" && r.Vantage != "lathe" {
if r.Kind == "prom" && r.Vantage != "lab" {
t.Errorf("%s: prom row vantage = %q", tc.name, r.Vantage)
}
}
Expand Down
17 changes: 9 additions & 8 deletions cmd/vigil/wire_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ listen: 127.0.0.1:10082
backends:
- id: prom
kind: prom
vantage: lathe
vantage: lab
authorities:
- id: simplex
path_ref: /var/lib/vigil/simplex.json
Expand All @@ -117,7 +117,8 @@ queries:
var backendSeq atomic.Int32

// writeDocs writes a config and an overlay that points at address, under a
// backend id no other test uses.
// backend id no other test uses. The overlay lists the host alias core in
// hosts[], because a --host slug is accepted only from the overlay.
func writeDocs(t *testing.T, cfgBody, address string) (cfg, ov string) {
t.Helper()
id := fmt.Sprintf("prom%d", backendSeq.Add(1))
Expand All @@ -128,7 +129,7 @@ func writeDocs(t *testing.T, cfgBody, address string) (cfg, ov string) {
if err := os.WriteFile(cfg, []byte(cfgBody), 0o600); err != nil {
t.Fatal(err)
}
overlay := fmt.Sprintf("apiVersion: vigil.overlay/v0\nbackends:\n - id: %s\n address: %s\n", id, address)
overlay := fmt.Sprintf("apiVersion: vigil.overlay/v0\nbackends:\n - id: %s\n address: %s\nhosts:\n - slug: core\n instances:\n - core.example.invalid:9100\n", id, address)
if err := os.WriteFile(ov, []byte(overlay), 0o600); err != nil {
t.Fatal(err)
}
Expand Down Expand Up @@ -164,7 +165,7 @@ func TestPromTargetsJSON(t *testing.T) {
t.Errorf("stdout leaks %q:\n%s", leak, out)
}
}
if !strings.Contains(out, `"vantage":"lathe"`) || !strings.Contains(out, `"backend":"prom`) {
if !strings.Contains(out, `"vantage":"lab"`) || !strings.Contains(out, `"backend":"prom`) {
t.Errorf("document lacks backend or vantage: %s", out)
}
// The same inputs print the same bytes.
Expand All @@ -183,7 +184,7 @@ func TestPromTargetsTable(t *testing.T) {
}
// The table is internal/render's, called as it is: header block, a blank
// line, then the rows.
for _, want := range []string{"BACKEND", "VANTAGE", "lathe", "GENERATED_AT 2026-11-14T09:00:00Z", "TARGET", "JOB", "HEALTH", "LAST_SCRAPE"} {
for _, want := range []string{"BACKEND", "VANTAGE", "lab", "GENERATED_AT 2026-11-14T09:00:00Z", "TARGET", "JOB", "HEALTH", "LAST_SCRAPE"} {
if !strings.Contains(out, want) {
t.Errorf("table lacks %q:\n%s", want, out)
}
Expand All @@ -200,7 +201,7 @@ func TestPromQueryJSON(t *testing.T) {
cfg, ov := writeDocs(t, wireConfig, srv.URL)
for _, args := range [][]string{
{"prom", "query", "up_all"},
{"prom", "query", "up_by_host", "--host", "castle"},
{"prom", "query", "up_by_host", "--host", "core"},
} {
full := append(append([]string{}, args...), "--json", "--config", cfg, "--overlay", ov, "--now", "2026-11-14T09:00:00Z")
code, out, errs := live(t, full...)
Expand Down Expand Up @@ -235,7 +236,7 @@ func TestPromQueryHostRules(t *testing.T) {
code string
}{
{[]string{"prom", "query", "up_by_host"}, "missing_host"},
{[]string{"prom", "query", "up_all", "--host", "castle"}, "unexpected_host"},
{[]string{"prom", "query", "up_all", "--host", "core"}, "unexpected_host"},
{[]string{"prom", "query", "up_by_host", "--host", "nosuchhost"}, "unknown_host"},
{[]string{"prom", "query", "no_such_query"}, "unknown_query"},
} {
Expand Down Expand Up @@ -316,7 +317,7 @@ func TestConfigErrorsDoNotEchoValues(t *testing.T) {
"locator-url": strings.Replace(wireConfig, "path_ref: /var/lib/vigil/simplex.json", "path_ref: https://"+marker+".example.invalid/x", 1),
"unknown-key": wireConfig + marker + ": 1\n",
"query-name-url": strings.Replace(wireConfig, "name: up_all", "name: http://"+marker+".example.invalid/x", 1),
"dup-backend": strings.Replace(wireConfig, "backends:\n - id: prom\n kind: prom\n vantage: lathe\n", "backends:\n - id: prom\n kind: prom\n - id: prom\n kind: prom\n", 1),
"dup-backend": strings.Replace(wireConfig, "backends:\n - id: prom\n kind: prom\n vantage: lab\n", "backends:\n - id: prom\n kind: prom\n - id: prom\n kind: prom\n", 1),
} {
cfg, ov := writeDocs(t, body, srv.URL)
code, out, errs := live(t, "prom", "targets", "--config", cfg, "--overlay", ov)
Expand Down
2 changes: 1 addition & 1 deletion docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ there is no free-form path over HTTP or on the CLI, and the host slug

| Flag | Meaning |
| --- | --- |
| `--host SLUG` | fills `{{.host}}`; must be a mapped or public slug |
| `--host SLUG` | fills `{{.host}}`; must be a slug the overlay's `hosts[]` defines |

Placeholder rules, both exit 3 with no backend call:

Expand Down
6 changes: 3 additions & 3 deletions docs/semantics.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ There is no `/v0/query`, no `/v0/queries`, and no route that takes a URL, a sele

- **The name is the only handle.** It must match the shape of a configured name (`^[a-z][a-z0-9_]{0,47}$`). A URL, a selector or an expression in its place is a usage error, exit 3, before any file is read. Test: `TestURLShapedArgumentsExitUsage`.
- **One placeholder, one literal.** The host slug is the only template variable, and the only substitution is the exact text `{{.host}}`. Vigil replaces that text and runs no template engine. Config validation refuses any other `{{` in an `expr`. Fixture: `testdata/config/invalid/expr-second-variable.yaml`.
- **`--host` is checked before it reaches an expression.** It must be a slug (`^[a-z][a-z0-9-]{0,31}$`) that is listed in the overlay's `hosts[]` or is one of the public slugs. Anything else is exit 3. An unchecked value would let a caller write PromQL through a label matcher.
- **`--host` is checked before it reaches an expression.** It must be a slug (`^[a-z][a-z0-9-]{0,31}$`) that is listed in the overlay's `hosts[]`. No slug is built in, so a slug the overlay does not list is exit 3, the same as any other unknown value. An unchecked value would let a caller write PromQL through a label matcher.
- **The expression and the flag must agree.** An `expr` that names `{{.host}}`, run without `--host`, is exit 3 with the code `missing_host`. `--host` given to an `expr` with no placeholder is exit 3 with the code `unexpected_host`. There is no fan-out in V1: one run asks about one host or about the whole expression, never about every host in turn.
- **Instant queries only.** The request carries `query`, `time` (the pinned clock when `--now` is set), `timeout` and `limit`.
- **Deadline.** 5s by default and 10s at most, set per query in config as `5s` to `10s`. It is sent as the API `timeout` parameter and enforced by a client deadline. A longer value is refused at load. Fixture: `testdata/config/invalid/timeout-too-long.yaml`.
Expand Down Expand Up @@ -115,7 +115,7 @@ A `vigil.signal/v0` is ephemeral and arrives only by authenticated POST.
- The Simplex writer publishes its document on every exit that carries a verdict or a blind vantage: 0, 1, 2 and 5. It never writes on 3 (configuration error) or 4 (I/O error); with no file there is nothing to read, so Vigil reports that authority `unavailable`. The vendored Simplex fixtures show it: `testdata/simplex/config-error` (exit 3) and `testdata/simplex/io-error` (exit 4) hold an `exit` file and no document; every other case holds both.
- The writer of record is `simplex serve --out PATH`, which rewrites the file every interval (default 30s, well inside Vigil's 120s `stale_after`). The fallback is a timer that runs `simplex check --json --out PATH`.
- Prometheus and Grafana are queried live and have no freshness bound; their state is `ok` or unreachable.
- Vigil queries the secondary Prometheus on lathe only. The primary's liveness reaches it through a named query on the peer series.
- Vigil queries the secondary Prometheus on the vantage host only. The primary's liveness reaches it through a named query on the peer series.

## 10. Versioning

Expand Down Expand Up @@ -229,7 +229,7 @@ Tests, by column: exit 0 is `TestPromTargetsJSON`, `TestPromQueryJSON`, `TestGra
`vigil.overlay/v0` is the only place an address exists. It is YAML, strict, and never committed (the scrub fails the tree if one is tracked). It has two keys beyond `apiVersion`:

- `backends[]`: `id` and `address`, keyed by the backend ids declared in config. An address is a scheme, a host, an optional port and optional path segments. Userinfo, a query, a fragment and any `.` or `..` segment are refused. Fixtures: `testdata/overlay/invalid/address-credentials.yaml`, `address-query.yaml` and `address-dot-segment.yaml`.
- `hosts[]` (optional): each `{slug, instances[]}` maps the `instance` labels a backend reports onto one public slug. An instance is a host or `host:port` as Prometheus reports it, and it is matched exactly. A host with no instances, or an instance that is a path, is refused. Fixtures: `testdata/overlay/valid/hosts.yaml`, `testdata/overlay/invalid/host-empty-instances.yaml` and `host-instance-path.yaml`.
- `hosts[]` (optional): each `{slug, instances[]}` maps the `instance` labels a backend reports onto one slug. An instance is a host or `host:port` as Prometheus reports it, and it is matched exactly. A host with no instances, or an instance that is a path, is refused. Fixtures: `testdata/overlay/valid/hosts.yaml`, `testdata/overlay/invalid/host-empty-instances.yaml` and `host-instance-path.yaml`.

Config adds one optional key to a backend, `vantage`: the slug of the place the backend is queried from. It is carried in every `prom` result and in the backend's `sources[]` row, so a reader can tell which side of the mesh answered. Fixtures: `testdata/config/valid/vantage.yaml`, `testdata/config/invalid/backend-vantage-not-a-slug.yaml`.

Expand Down
2 changes: 1 addition & 1 deletion example.config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ listen: "127.0.0.1:10082"
backends:
- id: prom
kind: prom
vantage: lathe
vantage: lab
- id: grafana
kind: grafana

Expand Down
8 changes: 4 additions & 4 deletions example.overlay.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@ backends:
# unmapped. An instance is a bare host or a host with a port, exactly as the
# backend reports it; brackets hold an IPv6 literal.
hosts:
- slug: castle
- slug: core
instances:
- "198.51.100.10:9100"
- castle.example.invalid
- slug: lathe
- core.example.invalid
- slug: lab
instances:
- "198.51.100.20:9100"
- lathe.example.invalid
- lab.example.invalid
30 changes: 15 additions & 15 deletions internal/config/config_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -345,35 +345,35 @@ backends:
- id: prom
address: http://prom.example.invalid:9090
hosts:
- slug: castle
instances: [castle.example.invalid:9100]
- slug: castle
instances: [castle.example.invalid:9101]
- slug: core
instances: [core.example.invalid:9100]
- slug: core
instances: [core.example.invalid:9101]
`, exitcode.Usage},
{"instance claimed twice", `apiVersion: vigil.overlay/v0
backends:
- id: prom
address: http://prom.example.invalid:9090
hosts:
- slug: castle
instances: [castle.example.invalid:9100]
- slug: tower
instances: [castle.example.invalid:9100]
- slug: core
instances: [core.example.invalid:9100]
- slug: spoke
instances: [core.example.invalid:9100]
`, exitcode.Usage},
{"no instances", `apiVersion: vigil.overlay/v0
backends:
- id: prom
address: http://prom.example.invalid:9090
hosts:
- slug: castle
- slug: core
instances: []
`, exitcode.Usage},
{"instance is a path", `apiVersion: vigil.overlay/v0
backends:
- id: prom
address: http://prom.example.invalid:9090
hosts:
- slug: castle
- slug: core
instances: ["/etc/passwd"]
`, exitcode.Usage},
}
Expand All @@ -398,7 +398,7 @@ func TestBind(t *testing.T) {
cfg, err := config.Load(writeFile(t, dir, "c.yaml", minimal+`backends:
- id: prom
kind: prom
vantage: lathe
vantage: lab
queries:
- name: q
backend: prom
Expand All @@ -407,7 +407,7 @@ queries:
if err != nil {
t.Fatalf("load config: %v", err)
}
if b, ok := cfg.Backend("prom"); !ok || b.Vantage != "lathe" {
if b, ok := cfg.Backend("prom"); !ok || b.Vantage != "lab" {
t.Fatalf("backend vantage = %+v", b)
}

Expand All @@ -416,16 +416,16 @@ backends:
- id: prom
address: http://prom.example.invalid:9090
hosts:
- slug: castle
instances: [castle.example.invalid:9100]
- slug: core
instances: [core.example.invalid:9100]
`))
if err != nil {
t.Fatalf("load overlay: %v", err)
}
if err := good.Bind(cfg); err != nil {
t.Fatalf("bind: %v", err)
}
if slug, ok := good.SlugFor("castle.example.invalid:9100"); !ok || slug != "castle" {
if slug, ok := good.SlugFor("core.example.invalid:9100"); !ok || slug != "core" {
t.Fatalf("slug = %q, %v", slug, ok)
}
if addr, ok := good.Address("prom"); !ok || addr != "http://prom.example.invalid:9090" {
Expand Down
13 changes: 3 additions & 10 deletions internal/promclient/promclient.go
Original file line number Diff line number Diff line change
Expand Up @@ -46,10 +46,6 @@ const (
redacted = "redacted"
)

// PublicSlugs are the six slugs the product publishes. A --host is accepted for
// one of these even when the overlay does not map it.
var PublicSlugs = []string{"castle", "tower", "citadel", "apiary", "lathe", "box"}

var (
slugPattern = regexp.MustCompile(`^[a-z][a-z0-9-]{0,31}$`)
jobPattern = regexp.MustCompile(`^[a-z][a-z0-9_-]{0,63}$`)
Expand Down Expand Up @@ -347,16 +343,13 @@ func healthWord(h string) string {
}
}

// knownHost accepts a slug the overlay maps or one of the public slugs.
// knownHost accepts only a slug the overlay maps. The product keeps no built-in
// list: an operator's overlay is the one place a host is named, so a slug that
// is valid in shape but absent from it is an unknown host, not a public one.
func knownHost(ov *config.Overlay, host string) bool {
if !slugPattern.MatchString(host) {
return false
}
for _, slug := range PublicSlugs {
if slug == host {
return true
}
}
for _, h := range ov.Hosts {
if h.Slug == host {
return true
Expand Down
Loading
Loading