api

Documentation

Overview

Package api implements the HTTP REST API for the scheduler platform, exposing task management and scheduler control endpoints.

Index

• type DuckBrainConfigSnapshot
• type GatewayConfigSnapshot
• type ProjectFailureRate
• type ResolvedConfig
• type Server
  • func NewServer(db *sql.DB, loop *scheduler.Loop) *Server
  • func (s *Server) Handler() http.Handler
  • func (s *Server) SetBlocksStore(st *blocks.Store)
  • func (s *Server) SetDuckBrainHealth(fn func() map[string]interface{})
  • func (s *Server) SetFailureWindow(n int)
  • func (s *Server) SetResolvedConfig(cfg ResolvedConfig)

Types

type DuckBrainConfigSnapshot

type DuckBrainConfigSnapshot struct {
	Namespace string `json:"namespace"`
	URL       string `json:"url"`
}

DuckBrainConfigSnapshot is the duckbrain section of the resolved config exposed by GET /api/v1/config.

type GatewayConfigSnapshot

type GatewayConfigSnapshot struct {
	URL            string `json:"url"`
	Key            string `json:"key"` // masked (first 4 chars + "****"); empty when unset
	ForemanHome    string `json:"foreman_home"`
	NoExecFallback bool   `json:"no_exec_fallback"`
}

GatewayConfigSnapshot is the gateway section of the resolved config exposed by GET /api/v1/config. The key is masked at set time — the plaintext gateway key never reaches the wire.

type ProjectFailureRate

type ProjectFailureRate struct {
	Failed      int     `json:"failed"`
	Total       int     `json:"total"`
	FailureRate float64 `json:"failure_rate"`

	// AutoDisableArmed reports whether this project currently meets the
	// auto-disable condition (GAP-047): the feature is enabled
	// (threshold > 0), the sample size reaches minTicks, and the failure
	// rate is at or above the threshold. It mirrors the exact condition in
	// internal/scheduler/alert_escalation.go CheckFailureRateAutoDisable.
	AutoDisableArmed bool `json:"auto_disable_armed"`
}

ProjectFailureRate is the per-project failure-rate breakdown for a single project over a window of recent ticks. It appears in /api/v1/status under the "projects_failure_rates" key (SCHED-GAP-018).

type ResolvedConfig

type ResolvedConfig struct {
	DBPath                 string                  `json:"db_path"`
	Listen                 string                  `json:"listen"`
	MinInterval            string                  `json:"min_interval"`
	MaxInterval            string                  `json:"max_interval"`
	NumLevels              int                     `json:"num_levels"`
	WeightBudget           int                     `json:"weight_budget"`
	MaxConcurrent          int                     `json:"max_concurrent"`
	TickTimeout            string                  `json:"tick_timeout"`
	NamespaceMode          bool                    `json:"namespace_mode"`
	AutoDisableFailureRate float64                 `json:"auto_disable_failure_rate"`
	AutoDisableWindow      int                     `json:"auto_disable_window"`
	AutoDisableMinTicks    int                     `json:"auto_disable_min_ticks"`
	FailureWindow          int                     `json:"failure_window"`
	Gateway                GatewayConfigSnapshot   `json:"gateway"`
	DuckBrain              DuckBrainConfigSnapshot `json:"duckbrain"`
}

ResolvedConfig is a startup-time snapshot of the daemon's ACTIVE three-layer configuration (TOML file < env vars < CLI flags), captured in main.go after TOML/env resolution and exposed read-only via GET /api/v1/config for operator introspection (SCHED-GAP-034). Durations are rendered as Go duration strings (e.g. "30s", "2h").

type Server

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

Server is the HTTP API server for the fleet scheduler.

func NewServer

func NewServer(db *sql.DB, loop *scheduler.Loop) *Server

NewServer creates an API server.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler returns an http.Handler for all API routes.

func (*Server) SetBlocksStore

func (s *Server) SetBlocksStore(st *blocks.Store)

SetBlocksStore installs the JSONL-backed deploy groups/templates store served by the /api/v1/groups* and /api/v1/templates* endpoints (including the template deploy action). main.go resolves the store paths (--db dir by default, --groups-file/--templates-file or scheduler TOML overrides) and calls this before the HTTP server starts. A Server without a store answers 503 on those routes.

func (*Server) SetDuckBrainHealth

func (s *Server) SetDuckBrainHealth(fn func() map[string]interface{})

SetDuckBrainHealth registers a provider for DuckBrain sync health so the status endpoint can surface fallback state (reachable, spool depth, etc).

func (*Server) SetFailureWindow

func (s *Server) SetFailureWindow(n int)

SetFailureWindow sets the number of recent ticks per project used for the /api/v1/status per-project failure-rate breakdown (SCHED-GAP-018).

func (*Server) SetResolvedConfig

func (s *Server) SetResolvedConfig(cfg ResolvedConfig)

SetResolvedConfig stores the resolved-config snapshot served by GET /api/v1/config (SCHED-GAP-034). The gateway key is masked before storage so the plaintext key can never leak through the endpoint. It also (re)builds the urgency calculator for GET /api/v1/queue (GAP-054) from the resolved interval range; an absent or unparseable range leaves the calculator nil (listQueue falls back to priority-only scores).