api

Documentation

Overview

Package api implements the brain's HTTP surface and the client used by agents and controllers. stdlib only, hardened for unattended operation: header/read/write timeouts, bounded bodies, optional bearer auth, gzip ingest, Prometheus metrics, graceful shutdown.

Index

• type Brain
  • func NewBrain(cfg BrainConfig, catalog *pricing.Catalog, st *store.Store) (*Brain, error)
  • func (b *Brain) Clusters() []string
  • func (b *Brain) Handler() http.Handler
  • func (b *Brain) Ingest(snap *model.ClusterSnapshot) error
  • func (b *Brain) Plan(cluster string) (*plan.Plan, error)
  • func (b *Brain) Recommendations(cluster string) ([]recommend.Recommendation, error)
  • func (b *Brain) Serve(ctx context.Context, addr string) error
• type BrainConfig
• type Client
  • func NewClient(baseURL, token string) (*Client, error)
  • func (c *Client) GetPlan(ctx context.Context, cluster string) (*plan.Plan, error)
  • func (c *Client) GetRecommendations(ctx context.Context, cluster string) ([]recommend.Recommendation, error)
  • func (c *Client) Healthy(ctx context.Context) bool
  • func (c *Client) PushSnapshot(ctx context.Context, snap *model.ClusterSnapshot) error

Types

type Brain

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

Brain is the central optimizer: it ingests snapshots, learns, and serves recommendations, plans and cost reports per cluster.

func NewBrain

func NewBrain(cfg BrainConfig, catalog *pricing.Catalog, st *store.Store) (*Brain, error)

NewBrain builds a brain, restoring persisted learning when a store is given.

func (*Brain) Clusters

func (b *Brain) Clusters() []string

Clusters lists known cluster ids.

func (*Brain) Handler

func (b *Brain) Handler() http.Handler

Handler returns the brain's full HTTP handler.

func (*Brain) Ingest

func (b *Brain) Ingest(snap *model.ClusterSnapshot) error

Ingest processes one snapshot (also used directly by the embedded analyze path, bypassing HTTP).

func (*Brain) Plan

func (b *Brain) Plan(cluster string) (*plan.Plan, error)

Plan builds a fresh plan for a cluster and records it.

func (*Brain) Recommendations

func (b *Brain) Recommendations(cluster string) ([]recommend.Recommendation, error)

Recommendations computes current recommendations for a cluster.

func (*Brain) Serve

func (b *Brain) Serve(ctx context.Context, addr string) error

Serve runs the brain HTTP server until ctx is cancelled, then shuts down gracefully.

type BrainConfig

type BrainConfig struct {
	// Token, when set, is required as "Authorization: Bearer <token>" on all
	// /api/ routes. /healthz and /metrics stay open.
	Token string
	// MaxBodyBytes bounds snapshot uploads (after transport decompression we
	// additionally bound the decoded stream). Default 64 MiB.
	MaxBodyBytes int64
	// CheckpointEvery persists recommender state every N snapshots per
	// cluster. Default 10.
	CheckpointEvery int
	Recommend       recommend.Config
	Plan            plan.Config
	Logger          *slog.Logger
}

BrainConfig tunes the central decision service.

type Client

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

Client talks to a brain. Used by agents (push) and controllers (pull).

func NewClient

func NewClient(baseURL, token string) (*Client, error)

NewClient validates the base URL and returns a client with sane timeouts.

func (*Client) GetPlan

func (c *Client) GetPlan(ctx context.Context, cluster string) (*plan.Plan, error)

GetPlan fetches a freshly built plan for the cluster.

func (*Client) GetRecommendations

func (c *Client) GetRecommendations(ctx context.Context, cluster string) ([]recommend.Recommendation, error)

GetRecommendations fetches current recommendations for the cluster.

func (*Client) Healthy

func (c *Client) Healthy(ctx context.Context) bool

Healthy probes the brain's health endpoint.

func (*Client) PushSnapshot

func (c *Client) PushSnapshot(ctx context.Context, snap *model.ClusterSnapshot) error

PushSnapshot uploads a snapshot (gzip-compressed).