config

package
v0.0.0-...-443440a Latest Latest
Warning

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

 Go to latest Published: Aug 16, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

Package config provides configuration types and validation for OSAPI.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Validate 

func Validate(
	c *Config,
) error

Validate validates a structs exposed fields.

Types

type APIServer 

type APIServer struct {
	// Port the server will bind to.
	Port int `mapstructure:"port"        validate:"min=1,max=65535"`
	// Security contains security-related configuration for the server, such as CORS and tokens.
	Security ServerSecurity `mapstructure:"security"                                     mask:"struct"`
	// JobTimeout is how long the controller waits for agent responses
	// before returning partial results. Uses Go duration format.
	// Defaults to 30s when empty.
	JobTimeout string `mapstructure:"job_timeout" validate:"omitempty,go_duration"`
}

APIServer holds the HTTP server config (port + security).

type AgentConditions 

type AgentConditions struct {
	MemoryPressureThreshold int     `mapstructure:"memory_pressure_threshold" validate:"min=1,max=100"`
	HighLoadMultiplier      float64 `mapstructure:"high_load_multiplier"      validate:"gt=0"`
	DiskPressureThreshold   int     `mapstructure:"disk_pressure_threshold"   validate:"min=1,max=100"`
}

AgentConditions holds threshold configuration for node conditions.

type AgentConfig 

type AgentConfig struct {
	// NATS connection settings for the agent.
	NATS NATSConnection `mapstructure:"nats"`
	// Consumer settings for the agent's JetStream consumer.
	Consumer AgentConsumer `mapstructure:"consumer,omitempty"`
	// Facts settings for the agent's facts collection.
	Facts AgentFacts `mapstructure:"facts,omitempty"`
	// QueueGroup for load balancing multiple agents.
	QueueGroup string `mapstructure:"queue_group"`
	// Hostname identifies this agent instance for routing.
	Hostname string `mapstructure:"hostname"`
	// MaxJobs maximum number of concurrent jobs to process.
	MaxJobs int `mapstructure:"max_jobs"                       validate:"min=1"`
	// Labels are key-value pairs for label-based routing (e.g., role: web, env: prod).
	// Maximum 5 labels per agent — each label creates multiple NATS consumers
	// for hierarchical prefix matching.
	Labels map[string]string `mapstructure:"labels"                         validate:"max=5"`
	// Conditions holds threshold settings for node condition evaluation.
	Conditions AgentConditions `mapstructure:"conditions,omitempty"`
	// ProcessConditions holds threshold settings for process-level condition evaluation.
	ProcessConditions ProcessConditions `mapstructure:"process_conditions,omitempty"`
	// PrivilegeEscalation configures least-privilege agent mode.
	PrivilegeEscalation PrivilegeEscalation `mapstructure:"privilege_escalation,omitempty"`
	// PKI holds PKI enrollment and signing settings.
	PKI     AgentPKI      `mapstructure:"pki,omitempty"`
	Metrics MetricsServer `mapstructure:"metrics"`
}

AgentConfig configuration settings.

type AgentConsumer 

type AgentConsumer struct {
	// Name is the durable consumer name.
	Name string `mapstructure:"name"`
	// MaxDeliver is the maximum number of redelivery attempts before sending to DLQ.
	MaxDeliver int `mapstructure:"max_deliver"`
	// AckWait is the time to wait for an ACK before redelivering.
	AckWait string `mapstructure:"ack_wait"        validate:"omitempty,go_duration"` // e.g. "30s", "1m"
	// MaxAckPending is the maximum outstanding unacknowledged messages.
	MaxAckPending int `mapstructure:"max_ack_pending"`
	// ReplayPolicy is "instant" or "original".
	ReplayPolicy string `mapstructure:"replay_policy"`
	// BackOff durations between redelivery attempts.
	BackOff []string `mapstructure:"back_off"` // e.g. ["30s", "2m", "5m"]
}

AgentConsumer configuration for the agent's JetStream consumer settings.

type AgentFacts 

type AgentFacts struct {
	// Interval is how often the agent collects and publishes facts.
	Interval string `mapstructure:"interval" validate:"omitempty,go_duration"` // e.g. "5m", "1h"
}

AgentFacts configuration for the agent's facts collection settings.

type AgentPKI 

type AgentPKI struct {
	// Enabled activates PKI enrollment and job signature verification.
	Enabled bool `mapstructure:"enabled"`
	// KeyDir is the directory for agent keypair storage.
	KeyDir string `mapstructure:"key_dir"`
}

AgentPKI holds PKI configuration for the agent.

type CORS 

type CORS struct {
	// List of origins allowed to access the server (e.g., "foo").
	AllowOrigins []string `mapstructure:"allow_origins,omitempty"`
}

CORS represents the CORS (Cross-Origin Resource Sharing) settings.

type Client 

type Client struct {
	// URL the client will connect to
	URL string `mapstructure:"url"`
	// Security contains security-related configuration for the client, such as access tokens.
	Security ClientSecurity `mapstructure:"security" mask:"struct"`
}

Client configuration settings.

type ClientSecurity 

type ClientSecurity struct {
	// BearerToken is the JWT used for role-based access control.
	BearerToken string `mapstructure:"bearer_token" validate:"required"`
}

ClientSecurity represents security-related settings for the client.

type Config 

type Config struct {
	Controller Controller  `mapstructure:"controller"      mask:"struct"`
	Agent      AgentConfig `mapstructure:"agent,omitempty"`
	NATS       NATS        `mapstructure:"nats"`
	Telemetry  Telemetry   `mapstructure:"telemetry"`
	// Debug enable or disable debug option set from CLI.
	Debug bool `mapstructure:"debug"`
}

Config represents the root structure of the YAML configuration file. This struct is used to unmarshal configuration data from Viper.

type Controller 

type Controller struct {
	Client        Client              `mapstructure:"client"`
	API           APIServer           `mapstructure:"api"                     mask:"struct"`
	NATS          NATSConnection      `mapstructure:"nats"`
	Metrics       MetricsServer       `mapstructure:"metrics"`
	Notifications NotificationsConfig `mapstructure:"notifications,omitempty"`
	// UI holds settings for the embedded management UI.
	UI UIConfig `mapstructure:"ui,omitempty"`
	// PKI holds PKI enrollment and signing settings.
	PKI ControllerPKI `mapstructure:"pki,omitempty"`
}

Controller holds the control plane configuration.

type ControllerPKI 

type ControllerPKI struct {
	// Enabled activates PKI enrollment and job signing.
	Enabled bool `mapstructure:"enabled"`
	// KeyDir is the directory for controller keypair storage.
	KeyDir string `mapstructure:"key_dir"`
	// AutoAccept automatically accepts all agent enrollment requests.
	AutoAccept bool `mapstructure:"auto_accept"`
	// RotationGracePeriod is how long both old and new keys are accepted
	// during key rotation. Uses Go duration format.
	RotationGracePeriod string `mapstructure:"rotation_grace_period" validate:"omitempty,go_duration"`
}

ControllerPKI holds PKI configuration for the controller.

type CustomRole 

type CustomRole struct {
	// Permissions granted to this role.
	Permissions []string `mapstructure:"permissions"`
}

CustomRole defines a named set of permissions that can be assigned to tokens.

type KVBucketInfo 

type KVBucketInfo struct {
	// Name is a human-readable label for the bucket (e.g. "job-queue").
	Name string
	// Bucket is the bucket name from the config field.
	Bucket string
}

KVBucketInfo holds a KV bucket's human-readable name and its configured bucket name. It is returned by NATS.AllKVBuckets so callers can iterate all KV buckets without manually listing every sub-config field.

type MetricsServer 

type MetricsServer struct {
	// Enabled activates the metrics server.
	Enabled bool `mapstructure:"enabled"`
	// Host the metrics server binds to.
	Host string `mapstructure:"host"`
	// Port the metrics server listens on.
	Port int `mapstructure:"port"    validate:"omitempty,min=1,max=65535"`
}

MetricsServer configures the per-component metrics HTTP server.

type NATS 

type NATS struct {
	Server     NATSServer     `mapstructure:"server,omitempty"`
	Stream     NATSStream     `mapstructure:"stream,omitempty"`
	KV         NATSKV         `mapstructure:"kv,omitempty"`
	DLQ        NATSDLQ        `mapstructure:"dlq,omitempty"`
	Audit      NATSAudit      `mapstructure:"audit,omitempty"`
	Registry   NATSRegistry   `mapstructure:"registry,omitempty"`
	Facts      NATSFacts      `mapstructure:"facts,omitempty"`
	State      NATSState      `mapstructure:"state,omitempty"`
	Objects    NATSObjects    `mapstructure:"objects,omitempty"`
	FileState  NATSFileState  `mapstructure:"file_state,omitempty"`
	Enrollment NATSEnrollment `mapstructure:"enrollment,omitempty"`
}

NATS configuration settings.

func (NATS) AllKVBuckets 

func (n NATS) AllKVBuckets() []KVBucketInfo

AllKVBuckets returns all KV bucket configurations declared in the NATS config. Each entry carries a human-readable name and the bucket name from config. Entries with an empty Bucket field are still included so that callers can filter by their own policy.

func (NATS) AllObjectStoreBuckets 

func (n NATS) AllObjectStoreBuckets() []ObjectStoreBucketInfo

AllObjectStoreBuckets returns all Object Store bucket configurations declared in the NATS config. Entries with an empty Bucket field are still included so that callers can filter by their own policy.

type NATSAudit 

type NATSAudit struct {
	// Stream is the JetStream stream name for audit log entries.
	Stream string `mapstructure:"stream"`
	// Subject is the base subject prefix for audit messages.
	Subject  string `mapstructure:"subject"`
	MaxAge   string `mapstructure:"max_age"   validate:"omitempty,go_duration"` // e.g. "720h" (30 days)
	MaxBytes int64  `mapstructure:"max_bytes"`
	Storage  string `mapstructure:"storage"` // "file" or "memory"
	Replicas int    `mapstructure:"replicas"`
}

NATSAudit configuration for the audit log stream.

type NATSAuth 

type NATSAuth struct {
	// Type is the auth method: "none", "user_pass", or "nkey".
	Type string `mapstructure:"type"`
	// Username for user_pass auth.
	Username string `mapstructure:"username"`
	// Password for user_pass auth.
	Password string `mapstructure:"password"  mask:"password"`
	// NKeyFile path to the NKey seed file for nkey auth.
	NKeyFile string `mapstructure:"nkey_file"`
}

NATSAuth holds client-side authentication settings for connecting to NATS.

type NATSConnection 

type NATSConnection struct {
	// Host the NATS server hostname.
	Host string `mapstructure:"host"`
	// Port the NATS server port.
	Port int `mapstructure:"port"           validate:"min=1,max=65535"`
	// ClientName the NATS client name for identification.
	ClientName string `mapstructure:"client_name"`
	// Namespace is a prefix for all NATS subjects used by this client.
	Namespace string `mapstructure:"namespace"`
	// Auth holds client-side authentication configuration.
	Auth NATSAuth `mapstructure:"auth,omitempty"`
}

NATSConnection is a reusable NATS connection configuration block.

type NATSDLQ 

type NATSDLQ struct {
	MaxAge   string `mapstructure:"max_age"  validate:"omitempty,go_duration"` // e.g. "7d", "24h"
	MaxMsgs  int64  `mapstructure:"max_msgs"`
	Storage  string `mapstructure:"storage"` // "file" or "memory"
	Replicas int    `mapstructure:"replicas"`
}

NATSDLQ configuration for Dead Letter Queue stream settings.

type NATSEnrollment 

type NATSEnrollment struct {
	// Bucket is the KV bucket name for pending enrollment entries.
	Bucket   string `mapstructure:"bucket"`
	Storage  string `mapstructure:"storage"` // "file" or "memory"
	Replicas int    `mapstructure:"replicas"`
}

NATSEnrollment configuration for the PKI enrollment KV bucket. No TTL — pending enrollment requests persist until accepted or rejected.

type NATSFacts 

type NATSFacts struct {
	// Bucket is the KV bucket name for agent facts entries.
	Bucket   string `mapstructure:"bucket"`
	TTL      string `mapstructure:"ttl"      validate:"omitempty,go_duration"` // e.g. "1h"
	Storage  string `mapstructure:"storage"`                                   // "file" or "memory"
	Replicas int    `mapstructure:"replicas"`
}

NATSFacts configuration for the agent facts KV bucket.

type NATSFileState 

type NATSFileState struct {
	// Bucket is the KV bucket name for file deployment SHA tracking.
	Bucket   string `mapstructure:"bucket"`
	Storage  string `mapstructure:"storage"` // "file" or "memory"
	Replicas int    `mapstructure:"replicas"`
}

NATSFileState configuration for the file deployment state KV bucket. No TTL — deployed file state persists until explicitly removed.

type NATSKV 

type NATSKV struct {
	// Bucket is the KV bucket name for job definitions and status events.
	Bucket string `mapstructure:"bucket"          validate:"required"`
	// ResponseBucket is the KV bucket name for agent result storage.
	ResponseBucket string `mapstructure:"response_bucket" validate:"required"`
	TTL            string `mapstructure:"ttl"` // e.g. "1h", "30m"
	MaxBytes       int64  `mapstructure:"max_bytes"`
	Storage        string `mapstructure:"storage"` // "file" or "memory"
	Replicas       int    `mapstructure:"replicas"`
}

NATSKV configuration for KeyValue bucket settings.

type NATSObjects 

type NATSObjects struct {
	// Bucket is the Object Store bucket name for file content.
	Bucket   string `mapstructure:"bucket"`
	MaxBytes int64  `mapstructure:"max_bytes"`
	Storage  string `mapstructure:"storage"` // "file" or "memory"
	Replicas int    `mapstructure:"replicas"`
}

NATSObjects configuration for the NATS Object Store bucket.

type NATSRegistry 

type NATSRegistry struct {
	// Bucket is the KV bucket name for agent registration entries.
	Bucket   string `mapstructure:"bucket"   validate:"required"`
	TTL      string `mapstructure:"ttl"      validate:"omitempty,go_duration"` // e.g. "30s"
	Storage  string `mapstructure:"storage"`                                   // "file" or "memory"
	Replicas int    `mapstructure:"replicas"`
}

NATSRegistry configuration for the agent registry KV bucket.

type NATSServer 

type NATSServer struct {
	// Host the server will bind to.
	Host string `mapstructure:"host"`
	// Port the server will bind to.
	Port int `mapstructure:"port"`
	// StoreDir the directory for JetStream file storage.
	StoreDir string `mapstructure:"store_dir"`
	// Namespace is a prefix for all NATS subjects and infrastructure names.
	Namespace string `mapstructure:"namespace"`
	// Auth holds server-side authentication configuration.
	Auth    NATSServerAuth `mapstructure:"auth,omitempty"`
	Metrics MetricsServer  `mapstructure:"metrics"`
}

NATSServer configuration settings for the embedded NATS server.

type NATSServerAuth 

type NATSServerAuth struct {
	// Type is the auth method: "none", "user_pass", or "nkey".
	Type string `mapstructure:"type"`
	// Users allowed to connect (for user_pass auth).
	Users []NATSServerUser `mapstructure:"users"`
	// NKeys is a list of allowed public NKeys (for nkey auth).
	NKeys []string `mapstructure:"nkeys"`
}

NATSServerAuth holds server-side authentication settings for the embedded NATS server.

type NATSServerUser 

type NATSServerUser struct {
	// Username for the user.
	Username string `mapstructure:"username"`
	// Password for the user.
	Password string `mapstructure:"password" mask:"password"`
}

NATSServerUser represents an allowed username/password pair for the NATS server.

type NATSState 

type NATSState struct {
	// Bucket is the KV bucket name for persistent agent state.
	Bucket   string `mapstructure:"bucket"`
	Storage  string `mapstructure:"storage"` // "file" or "memory"
	Replicas int    `mapstructure:"replicas"`
}

NATSState configuration for the agent state KV bucket (drain flags, timeline events).

type NATSStream 

type NATSStream struct {
	// Name is the JetStream stream name.
	Name string `mapstructure:"name"     validate:"required"`
	// Subjects is the subject filter for the stream.
	Subjects string `mapstructure:"subjects" validate:"required"`
	MaxAge   string `mapstructure:"max_age"  validate:"omitempty,go_duration"` // e.g. "24h", "1h30m"
	MaxMsgs  int64  `mapstructure:"max_msgs"`
	Storage  string `mapstructure:"storage"` // "file" or "memory"
	Replicas int    `mapstructure:"replicas"`
	Discard  string `mapstructure:"discard"` // "old" or "new"
}

NATSStream configuration for JetStream stream settings.

type NotificationsConfig 

type NotificationsConfig struct {
	// Enabled activates the condition watcher and notifier.
	Enabled bool `mapstructure:"enabled"`
	// Notifier selects the notification backend: "log" (default).
	Notifier string `mapstructure:"notifier"`
	// RenotifyInterval is how often to re-fire active conditions.
	// Uses Go duration format (e.g., "1m", "5m", "1h"). Zero disables.
	RenotifyInterval string `mapstructure:"renotify_interval" validate:"omitempty,go_duration"`
}

NotificationsConfig holds settings for the pluggable condition notification system. When Enabled is true, a Watcher monitors the registry KV bucket and dispatches ConditionEvents via the configured Notifier.

type ObjectStoreBucketInfo 

type ObjectStoreBucketInfo struct {
	// Name is a human-readable label for the bucket (e.g. "file-objects").
	Name string
	// Bucket is the bucket name from the config field.
	Bucket string
}

ObjectStoreBucketInfo holds an Object Store bucket's human-readable name and its configured bucket name. It is returned by NATS.AllObjectStoreBuckets so callers can iterate all Object Store buckets without manually listing every sub-config field.

type PrivilegeEscalation 

type PrivilegeEscalation struct {
	// Enabled activates least-privilege mode: sudo for write commands
	// and capability verification at startup.
	Enabled bool `mapstructure:"enabled"`
}

PrivilegeEscalation configuration for least-privilege agent mode. When enabled, write commands use sudo and Linux capabilities are verified at startup.

type ProcessConditions 

type ProcessConditions struct {
	// MemoryPressureBytes is the RSS threshold in bytes (0 = disabled).
	MemoryPressureBytes int64 `mapstructure:"memory_pressure_bytes"`
	// HighCPUPercent is the CPU usage threshold as a percentage (0 = disabled).
	HighCPUPercent float64 `mapstructure:"high_cpu_percent"`
}

ProcessConditions holds threshold configuration for process-level conditions.

type ServerSecurity 

type ServerSecurity struct {
	// CORS Cross-Origin Resource Sharing (CORS) settings for the server.
	CORS CORS `mapstructure:"cors"`
	// SigningKey is the key used for signing or validating tokens.
	SigningKey string `mapstructure:"signing_key" validate:"required" mask:"password"`
	// Roles defines custom roles with fine-grained permissions.
	Roles map[string]CustomRole `mapstructure:"roles"`
}

ServerSecurity represents security-related settings for the server.

type Telemetry 

type Telemetry struct {
	Tracing TracingConfig `mapstructure:"tracing,omitempty"`
}

Telemetry configuration settings.

type TracingConfig 

type TracingConfig struct {
	// Enabled enables or disables tracing.
	Enabled bool `mapstructure:"enabled"`
	// Exporter selects the trace exporter: "stdout" or "otlp".
	Exporter string `mapstructure:"exporter"`
	// OTLPEndpoint is the gRPC endpoint for the OTLP exporter (e.g., "localhost:4317").
	OTLPEndpoint string `mapstructure:"otlp_endpoint"`
}

TracingConfig configuration settings for distributed tracing.

type UIConfig 

type UIConfig struct {
	// Enabled controls whether the embedded UI is served. Defaults to true.
	Enabled *bool `mapstructure:"enabled"`
}

UIConfig holds settings for the embedded management UI.

func (UIConfig) UIEnabled 

func (c UIConfig) UIEnabled() bool

UIEnabled returns whether the embedded UI is enabled, defaulting to true when the Enabled field is not set in config. The pointer semantics let us distinguish "not set" (default to true) from an explicit false.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.