Documentation
¶
Overview ¶
Package apiserver implements a standalone REST API server that exposes all cloop functionality over HTTP with an OpenAPI 3.0 spec at /openapi.json. It is designed for CI/CD integration, external dashboards, and scripting.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func APIRoutes ¶ added in v0.0.2
APIRoutes describes this surface for the documentation generator in tests/docs, which renders docs/reference/http-api.md from it and from pkg/ui.APIRoutes.
Builds a zero Server: the handlers are method values, well-formed without server state, and nothing else about a route depends on a running daemon.
Types ¶
type Server ¶
type Server struct {
WorkDir string
Port int
Token string // optional bearer token; empty = no auth
// RPS and Burst control the per-IP token-bucket rate limiter.
// Zero values use defaultRPS / defaultBurst.
RPS float64
Burst int
// MaxRequestBodyBytes caps any incoming POST/PUT/PATCH request body
// the server will accept. Zero substitutes maxJSONBodyBytes (10 MiB).
// Oversize requests are rejected with HTTP 413. Set via
// config.UIConfig.MaxRequestBodyBytes when wired through cmd/serve.go.
// Task 20102.
MaxRequestBodyBytes int64
// TLSCertFile / TLSKeyFile enable native HTTPS. Both must be set or
// neither; Run refuses to start on a half-configuration rather than
// silently serving the bearer token over plaintext. TLSMinVersion is
// "1.2" (default) or "1.3". Set from --tls-cert / --tls-key, or from
// ui.tls.* in .cloop/config.yaml.
TLSCertFile string
TLSKeyFile string
TLSMinVersion string
// ReadyCheck overrides the readiness check used by /readyz. nil means
// use defaultReadyCheck (stat state.db, open it, run SELECT 1 bounded
// by ctx). Tests override this field to simulate degraded states like
// "closed db handle" or "state store not initialized".
ReadyCheck func(ctx context.Context) error
// Log is the structured logger used for lifecycle / error messages
// emitted by the API server itself (startup, shutdown, panics in
// background goroutines). Nil means the package picks a sensible
// default at first-use (text output to stdout, project bound).
Log logger.Logger
// contains filtered or unexported fields
}
Server is the cloop REST API HTTP server.
func (*Server) Run ¶
Run is the lifecycle entrypoint without signal handling: it blocks until ctx is cancelled or the underlying http.Server fails. On ctx cancellation it triggers a bounded graceful shutdown (10s) and returns nil.
func (*Server) Shutdown ¶
Shutdown initiates a graceful shutdown of a server started via Run. Safe to call from any goroutine; if the server has not started or has already been shut down it is a no-op. ctx bounds how long Shutdown will wait for in-flight requests to drain.
func (*Server) Start ¶
Start begins listening on the configured port. It installs SIGINT/SIGTERM handlers so the daemon shuts down gracefully when supervised by systemd or interrupted from a TTY: in-flight requests drain (bounded to 10s) before Start returns nil. Production callers use this; tests should call Run with their own context for fine-grained lifecycle control.
Source Files