Documentation
¶
Overview ¶
Package api is Zoomies' HTTP surface: the REST API described by api/openapi.yaml, the Server-Sent Events streams the UI lives on, the Prometheus endpoint, the GitHub webhook receiver, and the embedded operator UI.
Everything here is transport. Decisions about the fleet belong to internal/controller, authorisation policy to internal/auth and SQL to internal/store; a handler in this package reads a request, asks one of those three, and renders the answer in the shape the OpenAPI document promises. Keeping it that thin is what makes the contract checkable: the surface can be walked route by route in a test, and nothing behind it has an opinion about HTTP.
Index ¶
Constants ¶
const SessionCookie = "zoomies_session"
SessionCookie is the name of the cookie a browser session lives in. It is exported because the OpenAPI document names it and the CLI's browser-login helper has to read it back.
Variables ¶
This section is empty.
Functions ¶
func ClientIP ¶
clientIP returns the address a request came from, resolved through the proxies the operator has said to trust.
Types ¶
type Options ¶
type Options struct {
// Controller is the running control plane. Required.
Controller *controller.Controller
// Logger is the process logger; nil uses slog's default.
Logger *slog.Logger
// StreamHeartbeat is how often a live stream sends a keep-alive and
// re-checks the credential it was opened with. Zero uses the shipped
// interval; a test sets it small so it does not have to wait one.
StreamHeartbeat time.Duration
}
Options are what the API needs to serve. Everything else it uses -- the store, the auth service, the event bus, the configuration -- it takes from the controller, so there is exactly one wiring of those and no way for the API to end up talking to a different database than the fleet does.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the HTTP surface. Build it with New and either hand Handler() to a listener of your own or let ListenAndServe run one.
func New ¶
New builds the server. It does no I/O beyond loading the encryption key and, when single sign-on is configured, discovering the identity provider.
func (*Server) Handler ¶
Handler returns the whole surface: API, webhook, metrics and UI. It is safe to serve from a listener of the caller's own, which is what the tests and the installer's health check do.
func (*Server) ListenAndServe ¶
ListenAndServe serves until ctx is cancelled, then shuts down gracefully.
It returns nil on a clean shutdown; anything else is a failure worth exiting on. The listener is opened before the readiness notification is sent, so a service manager that starts a dependent unit on READY=1 is not racing the bind.
Source Files
¶
- auth.go
- errors.go
- handlers_admin.go
- handlers_agents.go
- handlers_audit.go
- handlers_auth.go
- handlers_diagnostics.go
- handlers_hosts.go
- handlers_installations.go
- handlers_jobs.go
- handlers_meta.go
- handlers_migrations.go
- handlers_overview.go
- handlers_pools.go
- handlers_provisioning.go
- handlers_recovery.go
- handlers_runners.go
- handlers_usage.go
- openapi_spec.go
- params.go
- router.go
- server.go
- sse.go
- tailcat.go
- web.go