Documentation
¶
Overview ¶
Package api wires together the sqi-server HTTP surface: the chi router, standard middleware stack, and all route groups.
Router layout ¶
GET /healthz — liveness probe GET /readyz — readiness probe GET /metrics — Prometheus scrape endpoint GET /debug/pprof/* — Go runtime profiling (gated by config) /api/v1/* — REST API GET /api/v1/ws — WebSocket upgrade GET /api/v1/openapi.yaml — OpenAPI 3.1 spec /* — embedded SPA + static assets
Middleware stack (outermost → innermost) ¶
- chi Recoverer — catches panics, returns 500, logs stack trace
- go-chi/cors — CORS preflight + headers (origins from Config)
- chi RequestID — sets X-Request-ID; chi's version generates a UUID when the header is absent
- chi Compress — gzip response bodies for clients that accept it
- middleware.RequestLogger — structured slog request logging
- middleware.RequestMetrics — Prometheus HTTP metrics
/api/v1 sub-router middleware ¶
- middleware.APIVersion("1") — sets X-API-Version: 1 on every API response. To mark individual endpoints as deprecated, wrap their handler with middleware.Deprecated.
Note: the structured-logging and metrics middleware are mounted here instead of the now-removed obsServer so every HTTP and WebSocket request continues to be logged and counted.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewRouter ¶
func NewRouter(cfg Config, deps Deps, logger *slog.Logger, m *metrics.Metrics, hr *health.Registry) chi.Router
NewRouter builds and returns the chi router that serves the full sqi-server HTTP surface. The returned router is ready to be handed to http.Server.
Route groups for the REST API (/api/v1/*) and WebSocket (/api/v1/ws) are populated incrementally as each task is completed. Pass a Deps value with all application-layer dependencies for the currently implemented handlers.
Types ¶
type Config ¶
type Config struct {
// CORSOrigins is the list of origins the CORS middleware allows.
// Use ["*"] to permit all origins (suitable for local/dev deployments).
// Defaults to ["*"] when empty.
CORSOrigins []string
// EnablePprof registers Go runtime profiling endpoints at /debug/pprof/
// when true. Must never be enabled on servers exposed to untrusted networks.
EnablePprof bool
// DisableRateLimit turns off per-IP rate limiting when true.
// Use in tests and benchmarks where the loopback address would cause all
// concurrent requests to share one bucket and trigger 429s.
DisableRateLimit bool
// WorkerOfflineThreshold is the heartbeat-timeout window used to decide
// whether a disabled worker is dead (and thus removable). It mirrors the
// scheduler's WorkerTimeout. Zero is treated as "no grace" (a disabled
// worker with any past heartbeat is considered dead).
WorkerOfflineThreshold time.Duration
}
Config holds HTTP-layer configuration for NewRouter.
type Deps ¶
type Deps struct {
// Store provides access to all persistent state (jobs, tasks, workers, …).
Store store.Store
// Submitter handles the full OpenJD parse → validate → persist pipeline
// used by POST /api/v1/jobs.
Submitter *openjd.Submitter
// Scheduler is the running scheduler instance. It is called by
// DELETE /api/v1/jobs/{id} to propagate cancellation to workers
// and by future task/retry endpoints.
Scheduler *scheduler.Scheduler
// Hub is the WebSocket fan-out hub used by the /api/v1/ws handler.
// May be nil in tests that do not exercise WebSocket push;
// the handler degrades gracefully by accepting subscriptions without
// delivering any pushes.
Hub *ws.Hub
// DiagReader exposes the in-memory diagnostic log buffer to
// GET /api/v1/diagnostics/logs. It is nil-tolerant: when nil (diagnostics
// disabled) the endpoint responds with 503.
DiagReader DiagReader
// Products is the product catalog (built-ins + stored), used by the
// /api/v1/products endpoints. Required for product routes.
Products *product.Catalog
// PresetLib is the community preset library client used by the
// /api/v1/presets endpoints. Nil-tolerant: when nil or unconfigured the
// endpoints respond 503.
PresetLib PresetLibrary
// Version is the server build metadata reported by GET /api/v1/version.
// The zero value is acceptable (fields default to empty strings).
Version version.Info
}
Deps holds the application-layer dependencies injected into the REST handlers. All fields are required; a nil field will cause a panic when the corresponding endpoint is first called.
type DiagReader ¶
DiagReader is the read-only view of the diagnostic log buffer the handler depends on. *diag.Buffer satisfies it. When diagnostics are disabled the server injects a nil reader, in which case the endpoint returns 503.
type PresetLibrary ¶ added in v0.2.0
type PresetLibrary interface {
Configured() bool
FetchIndex(ctx context.Context, forceRefresh bool) ([]presetlib.IndexEntry, error)
FetchDefinition(ctx context.Context, entry presetlib.IndexEntry) (store.Product, error)
}
PresetLibrary is the subset of *presetlib.Service the preset handlers use. Nil (or an unconfigured library) makes every preset endpoint respond 503.
Source Files