Documentation
¶
Overview ¶
Package server owns the sqi-server component lifecycle: starting and stopping the store, message bus, scheduler, HTTP server, and mDNS responder in the correct dependency order.
The server owns these components, started and stopped in dependency order:
- store (SQLite)
- bus (NATS JetStream)
- scheduler
- httpServer (chi router) — REST + WebSocket + UI routes
- discovery (mDNS)
Index ¶
Constants ¶
const ShutdownTimeout = 30 * time.Second
ShutdownTimeout is the maximum time Server.Run waits for all components to stop cleanly before returning. Components that do not respect context cancellation within this window are abandoned.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// HTTPAddr is the TCP address the REST + WebSocket server listens on.
HTTPAddr string // default "0.0.0.0:8080"
// CORSOrigins is the list of origins that the CORS middleware permits.
// Use ["*"] to allow all origins (suitable for local / dev deployments).
// An empty slice is treated as ["*"]. Tighten this for production
// deployments once the web UI's origin is known.
CORSOrigins []string // default ["*"]
// EnablePprof registers the Go runtime profiling endpoints at
// /debug/pprof/ when true. Should never be enabled on servers accessible
// to untrusted networks. Default false.
EnablePprof bool
// NATSAddr is the TCP address the embedded NATS server listens on.
// It defaults to all interfaces so that workers discovering the server
// via mDNS can connect to NATS at the advertised LAN host. (No broker
// authentication yet; that arrives in phase 3.)
NATSAddr string // default "0.0.0.0:4222"
// NATSDataDir is the directory used by JetStream for file-backed stream
// storage. It is created at startup if it does not exist.
NATSDataDir string // default "data/nats"
// NATSMaxStoreMB is the maximum disk space JetStream may use, in
// megabytes. 0 means unlimited (not recommended for production).
NATSMaxStoreMB int // default 1024
// SQLitePath is the path to the SQLite database file used in simple mode.
// It is created at startup if it does not exist.
SQLitePath string // default "sqi.db"
// CheckpointInterval is how often the background WAL checkpointer runs.
// See internal/config.StoreConfig.CheckpointInterval for semantics.
CheckpointInterval time.Duration // default 5m
// Scheduler holds tuning parameters for the assignment loop, worker
// registry, and heartbeat sweep. Zero values use scheduler.DefaultConfig().
Scheduler scheduler.Config
// DiscoveryEnabled controls whether the mDNS responder advertises this
// server on the local network. Disable in environments that forbid
// multicast (most cloud VPCs). Default true.
DiscoveryEnabled bool
// DiscoveryInstanceName is the mDNS service instance name advertised on
// the network. Each server on the same subnet should use a distinct name.
// Default "sqi-server".
DiscoveryInstanceName string
// DisableRateLimit turns off per-IP API rate limiting. Only set this in
// tests and benchmarks; never in production.
DisableRateLimit bool
// EnforceOpenJDLimits controls whether quantitative OpenJD limit checks
// (name lengths, element counts, reserved-name rules) are enforced during
// job submission. Default true. Mirror of config.OpenJDConfig.EnforceLimits.
EnforceOpenJDLimits bool
// SeedDefaults, when true, creates a "default" farm and queue on first
// startup if the store has no farms yet. No-op once any farm exists.
// Default true.
SeedDefaults bool
}
Config holds runtime parameters for the server.
This struct is a stand-in used by the serve subcommand; the serve subcommand can also load a [config.Config] and derive a Config from it rather than using defaults.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns a Config with sensible development defaults. Production deployments override these via the config file or environment variables.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server coordinates the startup and shutdown of all sqi-server components. It is created by New and driven by [Run].
func New ¶
New creates a Server with the given configuration and logger.
diagBuf is the diagnostic-log ring buffer fed by the server's own logs (via the logger's server sink) and by worker diagnostics (via the scheduler). It must be created before the logger so startup logs are captured; pass nil to disable diagnostics.
func (*Server) Health ¶
Health returns the *health.Registry owned by this server. Components (store, bus) call Health().Register(...) during startup to participate in readiness gating via GET /readyz.
func (*Server) Metrics ¶
Metrics returns the *metrics.Metrics instance owned by this server. Other components (scheduler, bus, store) use it to record observations.
func (*Server) Run ¶
Run starts all server components and blocks until ctx is canceled (typically by a SIGINT or SIGTERM delivered via [signal.NotifyContext]). It then initiates a graceful shutdown and returns once all components have stopped or ShutdownTimeout is exceeded.
A nil return value means the server started and shut down without errors. Startup failures return immediately with a non-nil error.