webapi

package
v1.1.3 Latest Latest
Warning

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

Go to latest
Published: Aug 13, 2026 License: GPL-2.0, GPL-3.0 Imports: 9 Imported by: 0

Documentation

Overview

Package webapi assembles knell's HTTP surface: the beat ingestion endpoint, the health endpoint, and Prometheus metrics, wrapped in the standard middleware stack.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func HostPolicyOptions added in v1.1.0

func HostPolicyOptions() []webhttp.HostAllowlistOption

HostPolicyOptions is the ALLOWED_HOSTS policy SHAPE knell ships: loopback-exempt, with the ALLOWED_HOSTS-naming 403 envelope. It lives here rather than beside the parsing because both halves of it are this package's: the envelope is an HTTP response body, and its code is the same metrics.RefusalHostNotAllowed countHostRefusals increments above, so the refusal's shape and its accounting cannot drift apart in different packages. The composition root hands it to config.Load, the mediation main already performs for notify.MaxNodeNameBytes.

WithLoopbackExempt keeps an in-container `curl http://127.0.0.1:9190/healthz` working under any allowlist: it admits a request only when BOTH the socket peer and the Host are loopback, so a rebinding request, which carries the attacker's hostname in Host, never qualifies.

func New

func New(b Beater, deps Deps) http.Handler

New assembles the routed and middleware-wrapped root handler. deps.BeatToken is the required credential gating the beat endpoint.

The beat endpoint keeps NO lifecycle state of its own. Whether a ping is still accepted is one question with one owner: watch.Watcher decides it under the mutex that guards the beat mutation, and this package asks (b.Beat) and reports what it answers — 503 with the shutting_down code for BeatClosed. A second view of the same question here could only ever approximate the watcher's, because no check made before Beat is atomic with the recording (this goroutine can be descheduled between the two), so it would add a source of drift and nothing else. The composition root closes admission at the start of the drain (webhttp's pre-drain hook), which is what keeps the window in which a ping is answered 503 narrow.

Only the beat endpoint refuses. /healthz and /metrics keep serving through the whole drain: the orchestrator has to see the liveness marker flip, and a last scrape of the freshness exposition during the drain is useful. That is a statement about the DRAIN only — an active ALLOWED_HOSTS allowlist refuses a foreign Host on all three routes at every point in the lifecycle, drain included (see Deps.Hosts).

Types

type Beater

type Beater interface {
	// Beat records id when admission is open and reports which of the three
	// outcomes it was: watch.BeatUnknown for an unknown id, watch.BeatClosed
	// once the watcher has closed admission for shutdown (nothing recorded in
	// either case), watch.BeatRecorded otherwise.
	Beat(id string) watch.BeatOutcome
}

Beater records pings. Implemented by watch.Watcher.

type Deps added in v1.1.0

type Deps struct {
	// Healthz answers liveness.
	Healthz http.Handler
	// Hosts is the exact-match Host allowlist (ALLOWED_HOSTS). A nil or
	// inactive policy accepts every Host, which is the documented default;
	// an active one is what breaks DNS rebinding, since a rebinding request
	// carries the ATTACKER's hostname in Host and nothing else on /healthz or
	// /metrics looks at that: BeatToken gates the BEAT route only, so without
	// an allowlist a rebinding page still reads the exposition that
	// enumerates every beat and its freshness.
	//
	// Because that is the exposure, the gate wraps the WHOLE mux rather than
	// the beat route: an ACTIVE allowlist refuses a foreign Host on /healthz
	// and /metrics too, not just /beat/{id}. That is deliberate — exempting the
	// probe routes would leave the exposition readable by the request this
	// exists to stop — but it means every hostname or IP a probe or a scraper
	// reaches knell by has to be listed, or those routes 403 for the operator's
	// own monitoring. The README's ALLOWED_HOSTS row says so for operators;
	// this says so for the next reader of New.
	Hosts *webhttp.HostPolicy
	// BeatToken is the REQUIRED bearer credential for POST /beat/{id} and the
	// endpoint's only gate (internal/config refuses to start without it). An
	// empty value is a wiring bug rather than a mode: the gate then fails
	// CLOSED and every ping is refused.
	BeatToken string
	// TrustedProxies is the reverse-proxy CIDR set client_ip is resolved
	// against (TRUSTED_PROXIES). Empty means no X-Forwarded-For is honored,
	// which is the spoof-proof default and correct for a directly published
	// port; behind the TLS proxy the README requires, an empty set makes every
	// access line name the proxy instead of the sender.
	//
	// Last because a slice's length and capacity words are not pointers, which
	// keeps the struct's pointer-scanned prefix at 48 bytes (govet
	// fieldalignment); it is the widest non-pointer tail of the four fields.
	TrustedProxies []*net.IPNet
}

Deps carries what the composition root supplies and webapi cannot reach on its own: the liveness handler (built over main's health.Marker), the Host allowlist, the beat credential, and the trusted-proxy set client_ip is resolved against. They are named rather than positional because the four are otherwise indistinguishable at a call site. The Prometheus exposition is deliberately absent: webapi already imports internal/metrics for the route-metric hook, so it serves metrics.Handler() itself rather than having the same dependency injected a second way.

Jump to

Keyboard shortcuts

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