config

package
v0.0.57 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: AGPL-3.0 Imports: 8 Imported by: 0

README

config

Stores and provides access to the API configuration for the rest of the server. Configuration is loaded by the CLI layer (via viper) and passed in through a setter; this package does not read files directly. The config describes the full competition setup: number of teams, whether the competition starts paused rather than scoring immediately on the very first boot against an empty database, which seeds both the scoring pause and the check pause to the same value, boxes with host address templates, services on each box with their check assignments and optional userlist references, credential userlists with optional domain and NetBIOS settings, the HTTP listener address and port, and an optional sinks section that configures data backends.

Two sinks are currently supported. The PostgreSQL sink enables persistent score storage and all database-backed routes. The OpenTelemetry sink ships each score result as an OTLP log record to a configurable HTTP endpoint; it supports HTTP Basic auth (either as a username/password pair or a pre-encoded credential string), a vendor-specific stream routing header, and tunable batching parameters with sensible defaults. Both sinks are optional and independently enabled by the presence of their respective configuration blocks.

The sinks type exposes helper methods consumed at router setup time. These allow individual routes to be conditionally swapped at startup: routes that require a database can be replaced with a 501 Not Implemented handler, and database-specific middleware can be turned into a no-op, all without any per-request branching.

The package follows the same middleware pattern used by the database connection layer. A Gin middleware stores the config object in each request's context at startup, and a pair of context-based accessors allow handlers to retrieve it — one that panics on error and one that returns an error explicitly. The setter that stores the config guards against being called more than once by panicking on a second invocation. The default config YAML is embedded in the binary at build time and exposed so the CLI layer can write it to disk. Validation logic is currently stubbed out.

Environment variables can override any config field using the prefix QU_ followed by the field path with dots and hyphens replaced by underscores (e.g. QU_SINKS_POSTGRES_PASSWORD, QU_SINKS_OTEL_BASIC_AUTH).

Documentation

Overview

Package config handles the delivery of the config to the rest of the API. Config is loaded by the CLI layer (cmd/) via viper and passed in via SetConfig.

Index

Constants

View Source
const CfgKey string = "cfg-object"

CfgKey is the key used to store the config object in the request context.

View Source
const (
	// DefaultConfigFile is the default (relative) path for the config file.
	DefaultConfigFile = "config.yaml"
)
View Source
const MaxStringLength int = 16

stored in two places: here and in the db schema

Variables

View Source
var (
	// DefaultConfigBytes contains the YAML bytes of the default config file.
	//go:embed default-config.yaml
	DefaultConfigBytes []byte

	// TeamRange is a helper-slice used to loop over every team.
	TeamRange []types.TeamNum
)

exported

Functions

func ConfigMiddleware

func ConfigMiddleware() gin.HandlerFunc

Middleware stores the config connection object in the gin context. This can be retrieved as necessary in routes.

func SetConfig

func SetConfig(newCfg *APIConfigSpec)

SetConfig stores the config in the global state. Must be called before Get() or TeamRange. Panics if called more than once.

Types

type APIConfigSpec

type APIConfigSpec struct {
	NumTeams    types.TeamNum    `yaml:"num_teams"    mapstructure:"num_teams"     json:"num_teams"     example:"5"`
	StartPaused types.PauseState `yaml:"start_paused" mapstructure:"start_paused"  json:"start_paused"  example:"false"`
	Sinks       Sinks            `yaml:"sinks"        mapstructure:"sinks"         json:"sinks"`
	Boxes       []BoxSpec        `yaml:"boxes"        mapstructure:"boxes"         json:"boxes"`
	UserLists   []UserListSpec   `yaml:"user_lists"   mapstructure:"user_lists"    json:"user_lists"`
	HTTP        HTTPSpec         `yaml:"http"         mapstructure:"http"          json:"http"`
}

APIConfigSpec defines the entire API configuration file.

func Get

func Get(c *gin.Context) *APIConfigSpec

Get returns the config object stored in the request context. Panics on error.

func GetE

func GetE(c *gin.Context) (*APIConfigSpec, error)

GetE returns the config object stored in the request context.

func (*APIConfigSpec) Validate

func (cfg *APIConfigSpec) Validate() error

Validate validates the API configuration.

type BoxSpec

type BoxSpec struct {
	Name     types.BoxName       `yaml:"name"     mapstructure:"name"     json:"name"     example:"scrapyard"`
	Host     string              `yaml:"host"     mapstructure:"host"     json:"host"     example:"127.0.0.{}"`
	Services []types.ServiceSpec `yaml:"services" mapstructure:"services" json:"services"`
}

BoxSpec contains the config specification of one box. It is the parent to a list of services. The Name is enforced to be unique, but multiple boxes can have identical services or hosts.

type HTTPSpec

type HTTPSpec struct {
	Host string `yaml:"host" mapstructure:"host" json:"host" example:"127.0.0.1"`
	Port int    `yaml:"port" mapstructure:"port" json:"port" example:"8888"`
}

HTTPSpec defines the settings applied to the API's listener.

type OTelBatching

type OTelBatching struct {
	BatchSize      int `yaml:"batch_size"      mapstructure:"batch_size"      json:"batch_size"      example:"20"`
	ExportInterval int `yaml:"export_interval" mapstructure:"export_interval" json:"export_interval" example:"5"`
	MaxQueueSize   int `yaml:"max_queue_size"  mapstructure:"max_queue_size"  json:"max_queue_size"  example:"200"`
}

OTelBatching controls how log records are batched before export. Zero values use defaults (BatchSize: 20, ExportInterval: 5s, MaxQueueSize: 200).

type OTelConfig

type OTelConfig struct {
	Endpoint  string `yaml:"endpoint"    mapstructure:"endpoint"    json:"endpoint"    example:"http://localhost:4318"`
	Username  string `yaml:"username"    mapstructure:"username"    json:"username"    example:"admin"`
	Password  string `yaml:"password"    mapstructure:"password"    json:"password"    example:"secret"`
	BasicAuth string `yaml:"basic_auth"  mapstructure:"basic_auth"  json:"basic_auth"  example:"dXNlcjpwYXNz"`

	// OpenObserve specific header
	StreamName string `yaml:"stream_name" mapstructure:"stream_name" json:"stream_name" example:"quincy"`

	// Batching settings
	Batching OTelBatching `yaml:"batching"    mapstructure:"batching"    json:"batching"`
}

type PGConfig

type PGConfig struct {
	Host     string `yaml:"host"     mapstructure:"host"     json:"host"     example:"localhost"`
	Port     uint16 `yaml:"port"     mapstructure:"port"     json:"port"     example:"5432"`
	Username string `yaml:"username" mapstructure:"username" json:"username" example:"postgres"`
	Password string `yaml:"password" mapstructure:"password" json:"password" example:"postgres"`
	Database string `yaml:"database" mapstructure:"database" json:"database" example:"quincy"`
	SSLMode  string `yaml:"ssl_mode" mapstructure:"ssl_mode" json:"ssl_mode" example:"prefer"`
	MaxConns int32  `yaml:"max_conns" mapstructure:"max_conns" json:"max_conns" example:"10"`
}

type Sinks

type Sinks struct {
	PGConfig   PGConfig   `yaml:"postgres" mapstructure:"postgres" json:"postgres"`
	OTelConfig OTelConfig `yaml:"otel"     mapstructure:"otel"     json:"otel"`
}

func (*Sinks) DBEnabled

func (s *Sinks) DBEnabled() bool

func (*Sinks) DBOr501

func (s *Sinks) DBOr501(endpoint gin.HandlerFunc) gin.HandlerFunc

DBOr501 returns the original endpoint if the db is configured. Otherwise it returns a simple 501 not implemented. This is used to make endpoints that require the db sink to be enabled.

func (*Sinks) DBOrNOP

func (s *Sinks) DBOrNOP(endpoint gin.HandlerFunc) gin.HandlerFunc

DBOrNOP returns the original endpoint if the db is configured. Otherwise it is a no-op. This is used to make middlewares that require the db sink to be enabled.

func (*Sinks) OTelEnabled

func (s *Sinks) OTelEnabled() bool

type UserListSpec

type UserListSpec struct {
	Name        types.UserListName `yaml:"name"    mapstructure:"name"    json:"name"               example:"local users"`
	DomainName  string             `yaml:"domain"  mapstructure:"domain"  json:"domain,omitempty"   example:"quin.cy"`
	NetBIOSName string             `yaml:"netbios" mapstructure:"netbios" json:"netbios,omitempty"  example:"QUIN"`
	Users       []UserSpec         `yaml:"users"   mapstructure:"users"   json:"users"`
}

UserListSpec contains the definition of a userlist. Userlists have a unique name. Optionally, they can have a Domain or NetBIOS name. These apply to every user in the list.

type UserSpec

type UserSpec struct {
	Username string `yaml:"username" mapstructure:"username" json:"username" example:"geraldo"`
	Password string `yaml:"password" mapstructure:"password" json:"password" example:"BuyMyNFT1!"`
}

UserSpec is the config specification of a single user.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL