admin

Documentation

Overview

Package admin provides an optional HTTP management API for prox.

When configured, the admin server exposes endpoints for health checks, config reload, certificate status, and runtime inspection. It is designed to be zero-overhead when disabled — no goroutines, listeners, or allocations are created unless the admin block is present in config.

Index

• type BalancerEntry
• type CertEntry
• type Deps
• type HealthResponse
• type MatchInfo
• type PluginEntry
• type ReloadResult
• type RouteEntry
• type Server
  • func New(cfg *config.AdminConfig, deps Deps) *Server
  • func (s *Server) ListenAndServe() error
  • func (s *Server) Shutdown(ctx context.Context) error
• type ServiceEntry

Types

type BalancerEntry

type BalancerEntry struct {
	Service    string   `json:"service"`
	RouteIndex int      `json:"route_index"`
	Type       string   `json:"type"`
	Action     string   `json:"action"`
	Targets    []string `json:"targets"`
}

BalancerEntry is one item in the GET /api/balancers response.

type CertEntry

type CertEntry struct {
	Domain  string     `json:"domain"`
	Status  string     `json:"status"`
	Expires *time.Time `json:"expires,omitempty"`
	Issuer  string     `json:"issuer,omitempty"`
}

CertEntry is one item in the GET /api/certs response.

type Deps

type Deps struct {
	StartTime    time.Time
	Version      string
	GetConfig    func() *config.Config
	Reload       func() *ReloadResult
	RouteCount   func() int
	ServiceInfo  func() []ServiceEntry
	CertStatus   func() []CertEntry
	PluginInfo   func() []PluginEntry
	BalancerInfo func() []BalancerEntry
}

Deps provides the admin server with access to runtime state. All fields are callbacks to avoid tight coupling with other packages.

type HealthResponse

type HealthResponse struct {
	Status      string `json:"status"`
	Version     string `json:"version"`
	Uptime      string `json:"uptime"`
	Routes      int    `json:"routes"`
	Services    int    `json:"services"`
	ConfigValid bool   `json:"config_valid"`
}

HealthResponse is the JSON body for GET /api/health.

type MatchInfo

type MatchInfo struct {
	Domain  string   `json:"domain,omitempty"`
	Path    string   `json:"path,omitempty"`
	Methods []string `json:"methods,omitempty"`
}

MatchInfo describes a route's matching criteria.

type PluginEntry

type PluginEntry struct {
	Name string `json:"name"`
	Path string `json:"path"`
}

PluginEntry is one item in the GET /api/plugins response.

type ReloadResult

type ReloadResult struct {
	OK       bool   `json:"ok"`
	Routes   int    `json:"routes,omitempty"`
	Services int    `json:"services,omitempty"`
	Error    string `json:"error,omitempty"`
}

ReloadResult is the JSON body for POST /api/reload.

type RouteEntry

type RouteEntry struct {
	Service  string     `json:"service"`
	Index    int        `json:"index"`
	Match    *MatchInfo `json:"match,omitempty"`
	Action   string     `json:"action"`
	Balancer string     `json:"balancer,omitempty"`
	Plugins  []string   `json:"plugins,omitempty"`
}

RouteEntry is one item in the GET /api/routes response.

type Server

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

Server is the admin API HTTP server.

func New

func New(cfg *config.AdminConfig, deps Deps) *Server

New creates an admin server bound to the given address. The listen address may be a TCP address ("127.0.0.1:9090") or a Unix socket path prefixed with "unix://" ("unix:///var/run/prox.sock").

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe starts the admin API server. It blocks until the server is shut down or an error occurs.

func (*Server) Shutdown

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

Shutdown gracefully stops the admin server.

type ServiceEntry

type ServiceEntry struct {
	Name   string `json:"name"`
	Listen string `json:"listen"`
	TLS    bool   `json:"tls"`
	ACME   bool   `json:"acme"`
	Routes int    `json:"routes"`
}

ServiceEntry is one item in the GET /api/services response.