admin

Documentation

Overview

Package admin is cadish's opt-in observability / command-center surface: a separate HTTP server (its own listener, off by default, auth-gated) that serves a single-page dashboard from embedded assets plus a JSON API and an optional Prometheus endpoint.

It is strictly OFF the datapath:

• Its own net.Listener on a separate bind (never the proxy's listener).
• Started only when an `admin { … }` block is present; otherwise this package is never constructed and the request handler's metrics seam stays nil.
• Every endpoint requires a bearer token (crypto/subtle compare).
• It only READS already-cheap live state (atomic metrics counters, on-demand cache/lb snapshots) and re-runs `cadish check` for the config view; it never mutates proxy state and never blocks a request.

Index

• type CacheStats
• type IngressSource
• type IngressStats
• type LiveSource
• type Server
  • func New(ac *config.AdminConfig, m *metrics.Metrics, live LiveSource, ing IngressSource, ...) *Server
  • func (s *Server) Addr() string
  • func (s *Server) ListenAndServe() error
  • func (s *Server) Shutdown(ctx context.Context) error
• type SiteState

Types

type CacheStats

type CacheStats struct {
	RAMObjects        int   `json:"ram_objects"`
	DiskObjects       int   `json:"disk_objects"`
	RAMBytes          int64 `json:"ram_bytes"`
	DiskBytes         int64 `json:"disk_bytes"`
	RAMMaxBytes       int64 `json:"ram_max_bytes"`
	DiskMaxBytes      int64 `json:"disk_max_bytes"`
	DiskPersistErrors int64 `json:"disk_persist_errors"`
}

CacheStats mirrors cache.Stats for the JSON projection (no internal/cache import needed by consumers of the admin API).

type IngressSource

type IngressSource interface {
	IngressStats() (IngressStats, bool)
}

IngressSource is the OPTIONAL read seam for the Kubernetes Ingress controller's reconcile stats (mirrors LiveSource). The CLI's `cadish ingress` mode wires an adapter over the running *ingress.Controller; plain `cadish run` passes nil and the dashboard simply omits the "Kubernetes Ingress" panel (zero cost off that path). The bool reports whether stats are currently available (false ⇒ panel hidden).

type IngressStats

type IngressStats struct {
	WatchedIngresses int    `json:"watched_ingresses"`
	LastAppliedHash  string `json:"last_applied_hash"`
	Rejects          int    `json:"rejects"`
	LastError        string `json:"last_error"`
	IsLeader         bool   `json:"is_leader"`
}

IngressStats mirrors ingress.Stats's JSON shape. It is duplicated here (a small, stable record) so internal/admin needs no compile-time dependency on internal/ingress; the CLI adapts the controller's snapshot into this type.

type LiveSource

type LiveSource interface {
	LiveState() []SiteState
}

LiveSource is the read seam the admin server uses to render per-site live state (two-tier cache fill). *server.Handler satisfies it via LiveState; admin depends on this interface rather than importing internal/server, keeping the dependency direction one-way (server does not import admin).

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is the admin/dashboard HTTP server. Construct with New and run with ListenAndServe; stop with Shutdown.

func New

func New(ac *config.AdminConfig, m *metrics.Metrics, live LiveSource, ing IngressSource, pools []*lb.Upstream, cfgPath string) *Server

New builds the admin server.

• ac is the parsed `admin` block (its Listen + AuthToken + Metrics flag).
• m is the live metrics seam (the same *Metrics passed to server.Options).
• live reads per-site cache state (the running *server.Handler).
• ing reads the Kubernetes Ingress controller's reconcile stats; nil outside `cadish ingress` mode ⇒ the dashboard omits the Ingress panel.
• pools are the lb upstream pools for the health view (config.Pools()).
• cfgPath is the Cadishfile path, re-read for the config view (cadish check).

func (*Server) Addr

func (s *Server) Addr() string

Addr returns the actual bound address (useful when Listen used :0 in tests). Returns "" before ListenAndServe has bound.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe binds the admin listener and serves until Shutdown. A clean shutdown returns nil. The listener bind happens here (not in New) so a bad bind address surfaces as a start error.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully drains the admin server.

type SiteState

type SiteState struct {
	Name      string     `json:"name"`
	Addresses []string   `json:"addresses"`
	Cache     CacheStats `json:"cache"`
}

SiteState mirrors server.SiteState's JSON shape. It is duplicated here (a small, stable record) so internal/admin needs no compile-time dependency on internal/server; the CLI adapts the server's slice into this type.