config

package
v1.0.1 Latest Latest
Warning

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

Go to latest
Published: Aug 10, 2026 License: AGPL-3.0 Imports: 22 Imported by: 0

README

Configuration package

The configuration package owns source precedence, platform paths, decoding, and validation. Loading reads process state but does not change it.

Source precedence

Starport resolves each value in this order:

  1. A STARPORT_ process environment variable.
  2. The first environment file that defines the value.
  3. A built-in default.

The standard loader reads one platform file named config.env. It uses these locations:

Platform File
Linux and other Unix systems $XDG_CONFIG_HOME/starport/config.env, or $HOME/.config/starport/config.env when XDG_CONFIG_HOME is empty
macOS $HOME/Library/Application Support/starport/config.env
Windows %AppData%\starport\config.env

os.UserConfigDir supplies the platform root. Tests can inject a different root and environment map without changing global process state.

Managed paths

The platform configuration directory owns these defaults:

Concept Relative path
Environment file config.env
Badger data data/badger
Rate-limit rules rate_limits.yaml

Starport resolves a configured relative path from the platform configuration directory. An absolute path remains unchanged. This rule makes file behavior independent of the directory that starts the process.

Secure local defaults

The HTTP server listens on 127.0.0.1:8080. CORS and rate-limit hot reload are off until an operator enables them. A supplied credential master key must contain at least 32 bytes.

starport init --provider openai and starport init --provider ollama create the standard local file with mode 0600. Initialization creates the credential master key and the first named identity. It does not replace an existing file or identity store.

The container image explicitly listens on 0.0.0.0 because publishing a container port is an operator action. It also stores Badger data under /var/lib/starport/data/badger. Its writable configuration root is /var/lib/starport/config.

Environment variables

All external fields use the STARPORT_ prefix. For example:

STARPORT_SERVER_PORT=8080
STARPORT_STORAGE_MODE=badger
STARPORT_LOGGING_LEVEL=info

Use the configuration reference for the complete field list. Starmap acquisition credentials stay separate from Starport inference credentials.

Inspection

Use these commands to inspect the resolved configuration:

starport config paths
starport config show
starport config validate

config show uses the configuration schema to replace each secret and URL with <redacted>. Loader errors report only the failed loading stage. These commands never show configured values in an error and never change process or file state. With --json, validation writes valid: false and a safe loading stage before it returns a nonzero status.

starport doctor uses the same loader. Passive diagnosis does not open storage. starport doctor --probe opens configured storage through a write-blocking adapter and checks the stored catalog and identity state. If Badger needs writable recovery, the probe skips storage inspection and gives recovery instructions. It also skips this inspection on platforms where Badger does not support read-only mode.

Rate-limit reload

To enable rule reload, set both values:

STARPORT_RATE_LIMITING_ENABLE_HOT_RELOAD=true
STARPORT_RATE_LIMITING_CONFIG_PATH=/absolute/path/to/rate_limits.yaml

Starport requires the rules file after an operator enables reload. The hot reloader watches its directory and also checks the file at the configured interval.

Documentation

Overview

Package config provides configuration management for Starport. It supports loading configuration from environment variables and .env files, with comprehensive validation and hot reload capabilities for rate limiting rules.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func OperatorError added in v1.0.1

func OperatorError(err error) error

OperatorError returns an error that is safe to show without configured values. It preserves the original error for programmatic inspection.

func Redacted added in v1.0.1

func Redacted(cfg *Config) map[string]any

Redacted returns an inspectable configuration tree without secret values.

Types

type BadgerConfig

type BadgerConfig struct {
	Path           string        `env:"PATH,overwrite"`
	SyncWrites     bool          `env:"SYNC_WRITES,default=false"`
	Compression    string        `env:"COMPRESSION,default=snappy"`
	GCInterval     time.Duration `env:"GC_INTERVAL,default=5m"`
	GCDiscardRatio float64       `env:"GC_DISCARD_RATIO,default=0.5"`
}

BadgerConfig defines Badger DB settings

func (*BadgerConfig) Validate

func (c *BadgerConfig) Validate() error

Validate validates BadgerConfig

type CacheConfig

type CacheConfig struct {
	Enabled bool `env:"ENABLED,default=true"`
}

CacheConfig defines cache settings

type CatalogConfig

type CatalogConfig struct {
	WorkspacePath   string        `env:"WORKSPACE_PATH"`
	RefreshOnStart  bool          `env:"REFRESH_ON_START,default=false"`
	RefreshInterval time.Duration `env:"REFRESH_INTERVAL,default=0s"`
	RefreshTimeout  time.Duration `env:"REFRESH_TIMEOUT,default=2m"`
}

CatalogConfig defines Starmap acquisition and tenant workspace settings. Acquisition credentials remain in Starmap's provider environment contract.

func (*CatalogConfig) Validate

func (c *CatalogConfig) Validate() error

Validate validates Starmap catalog acquisition settings.

type ChatUIConfig

type ChatUIConfig struct {
	Enabled bool   `env:"ENABLED,default=false"`
	Title   string `env:"TITLE,default=Starport Chat"`
	Theme   string `env:"THEME,default=light"`
}

ChatUIConfig defines settings for the embedded chat UI

func (*ChatUIConfig) Validate

func (c *ChatUIConfig) Validate() error

Validate validates ChatUIConfig

type Config

type Config struct {
	Server       ServerConfig       `env:",prefix=SERVER_"`
	Storage      StorageConfig      `env:",prefix=STORAGE_"`
	Catalog      CatalogConfig      `env:",prefix=CATALOG_"`
	Providers    ProvidersConfig    `env:",prefix=PROVIDERS_"`
	RateLimiting RateLimitingConfig `env:",prefix=RATE_LIMITING_"`
	Security     SecurityConfig     `env:",prefix=SECURITY_"`
	Logging      LoggingConfig      `env:",prefix=LOGGING_"`
	Cache        CacheConfig        `env:",prefix=CACHE_"`
	ChatUI       ChatUIConfig       `env:",prefix=CHATUI_"`
}

Config represents the complete application configuration

func LoadWithDefaults

func LoadWithDefaults(ctx context.Context) (*Config, error)

LoadWithDefaults loads configuration from the standard sources.

func MustLoad

func MustLoad(ctx context.Context) *Config

MustLoad loads configuration and panics if loading fails.

func (*Config) Validate

func (c *Config) Validate() error

Validate performs validation on the configuration

type HotReloader

type HotReloader struct {
	// contains filtered or unexported fields
}

HotReloader manages hot-reloading of configuration files

func NewHotReloader

func NewHotReloader(configPath string, checkInterval time.Duration) (*HotReloader, error)

NewHotReloader creates a new hot reloader

func (*HotReloader) GetRateLimitRules

func (h *HotReloader) GetRateLimitRules() *RateLimitRules

GetRateLimitRules returns the current rate limit rules

func (*HotReloader) GetRuleForKey

func (h *HotReloader) GetRuleForKey(keyID string) (*RateLimitRule, bool)

GetRuleForKey returns the rate limit rule for a specific API key

func (*HotReloader) GetRuleForModel

func (h *HotReloader) GetRuleForModel(model string) (*RateLimitRule, bool)

GetRuleForModel returns the rate limit rule for a specific model

func (*HotReloader) OnUpdate

func (h *HotReloader) OnUpdate(callback func(*RateLimitRules))

OnUpdate registers a callback to be called when configuration is updated

func (*HotReloader) Start

func (h *HotReloader) Start(ctx context.Context) error

Start begins the hot reload monitoring

func (*HotReloader) Stop

func (h *HotReloader) Stop()

Stop stops the hot reloader

type Loader

type Loader struct {
	// contains filtered or unexported fields
}

Loader reads configuration without changing process state.

func NewLoader

func NewLoader() *Loader

NewLoader creates a loader for the process environment and platform paths.

func (*Loader) Load

func (l *Loader) Load(ctx context.Context) (*Config, error)

Load resolves configuration sources, applies defaults, and validates the result.

func (*Loader) WithEnvFiles

func (l *Loader) WithEnvFiles(files ...string) *Loader

WithEnvFiles sets environment files in descending precedence order. An empty list disables file loading.

func (*Loader) WithEnvironment added in v1.0.1

func (l *Loader) WithEnvironment(values map[string]string) *Loader

WithEnvironment replaces the process environment source.

func (*Loader) WithPaths added in v1.0.1

func (l *Loader) WithPaths(paths Paths) *Loader

WithPaths replaces platform path resolution.

func (*Loader) WithPrefix

func (l *Loader) WithPrefix(prefix string) *Loader

WithPrefix sets the environment variable prefix.

type LoggingConfig

type LoggingConfig struct {
	Level      string `env:"LEVEL,default=info"`
	Format     string `env:"FORMAT,default=json"`
	Output     string `env:"OUTPUT,default=stdout"`
	FilePath   string `env:"FILE_PATH"`
	MaxSize    int    `env:"MAX_SIZE,default=100"`
	MaxBackups int    `env:"MAX_BACKUPS,default=3"`
	MaxAge     int    `env:"MAX_AGE,default=7"`
	Compress   bool   `env:"COMPRESS,default=true"`
}

LoggingConfig defines logging settings

func (*LoggingConfig) Validate

func (c *LoggingConfig) Validate() error

Validate validates LoggingConfig

type Paths added in v1.0.1

type Paths struct {
	ConfigDir      string `json:"config_dir"`
	ConfigFile     string `json:"config_file"`
	DataDir        string `json:"data_dir"`
	BadgerDir      string `json:"badger_dir"`
	RateLimitsFile string `json:"rate_limits_file"`
}

Paths contains the platform-owned files and directories that Starport uses.

func PathsForConfigDir added in v1.0.1

func PathsForConfigDir(configDir string) Paths

PathsForConfigDir derives all managed paths from one configuration directory.

func PlatformPaths added in v1.0.1

func PlatformPaths() (Paths, error)

PlatformPaths resolves the current user's Starport paths.

type ProviderConfig

type ProviderConfig struct {
	BaseURL        string            `env:"BASE_URL" redact:"url"`
	APIKey         string            `env:"API_KEY" secret:"true"`
	AuthMode       providerauth.Mode `env:"AUTH_MODE"`
	Timeout        time.Duration     `env:"TIMEOUT,default=30s"`
	MaxConnections int               `env:"MAX_CONNECTIONS,default=100"`
	Enabled        bool              `env:"ENABLED"` // Used for optional providers like Ollama
	ProjectID      string            `env:"PROJECT_ID"`
	Location       string            `env:"LOCATION"`
}

ProviderConfig defines settings for a single LLM provider

func (*ProviderConfig) Validate

func (c *ProviderConfig) Validate() error

Validate validates ProviderConfig

type ProviderEntry

type ProviderEntry struct {
	ProviderID catalogs.ProviderID
	Config     ProviderConfig
}

ProviderEntry binds external operator configuration to one exact Starmap provider ID.

type ProvidersConfig

type ProvidersConfig struct {
	OpenAI         ProviderConfig `env:",prefix=OPENAI_"`
	Anthropic      ProviderConfig `env:",prefix=ANTHROPIC_"`
	GoogleAIStudio ProviderConfig `env:",prefix=GOOGLE_AI_STUDIO_"`
	GoogleVertexAI ProviderConfig `env:",prefix=GOOGLE_VERTEX_"`
	Groq           ProviderConfig `env:",prefix=GROQ_"`
	Mistral        ProviderConfig `env:",prefix=MISTRAL_"`
	Azure          ProviderConfig `env:",prefix=AZURE_OPENAI_"`
	Ollama         ProviderConfig `env:",prefix=OLLAMA_"`
}

ProvidersConfig defines LLM provider settings

func (ProvidersConfig) Entries

func (c ProvidersConfig) Entries() []ProviderEntry

Entries returns all supported external configuration slots. Adapter semantics and provider membership remain outside the configuration package.

func (*ProvidersConfig) Validate

func (c *ProvidersConfig) Validate() error

Validate validates each active provider configuration.

type RateLimitRule

type RateLimitRule struct {
	Name              string  `yaml:"name"`
	RequestsPerMinute int     `yaml:"requests_per_minute"`
	RequestsPerHour   int     `yaml:"requests_per_hour"`
	TokensPerMinute   int     `yaml:"tokens_per_minute"`
	TokensPerHour     int     `yaml:"tokens_per_hour"`
	BurstMultiplier   float64 `yaml:"burst_multiplier"`
}

RateLimitRule represents a rate limit configuration that can be hot-reloaded

type RateLimitRules

type RateLimitRules struct {
	Version string                   `yaml:"version"`
	Rules   map[string]RateLimitRule `yaml:"rules"`
	Models  map[string]RateLimitRule `yaml:"models"`
}

RateLimitRules represents the hot-reloadable rate limit configuration

type RateLimitingConfig

type RateLimitingConfig struct {
	// Global limits
	GlobalRequestsPerSecond int     `env:"GLOBAL_REQUESTS_PER_SECOND,default=10000"`
	GlobalBurstMultiplier   float64 `env:"GLOBAL_BURST_MULTIPLIER,default=2.0"`

	// Default key limits
	DefaultRequestsPerMinute int `env:"DEFAULT_REQUESTS_PER_MINUTE,default=60"`
	DefaultRequestsPerHour   int `env:"DEFAULT_REQUESTS_PER_HOUR,default=1000"`
	DefaultTokensPerMinute   int `env:"DEFAULT_TOKENS_PER_MINUTE,default=100000"`
	DefaultTokensPerHour     int `env:"DEFAULT_TOKENS_PER_HOUR,default=1000000"`
	DefaultBurst             int `env:"DEFAULT_BURST,default=10"`

	// Rate limit window
	WindowSize      time.Duration `env:"WINDOW_SIZE,default=1m"`
	SyncInterval    time.Duration `env:"SYNC_INTERVAL,default=5s"`
	CleanupInterval time.Duration `env:"CLEANUP_INTERVAL,default=10m"`

	// Hot reload settings
	EnableHotReload     bool          `env:"ENABLE_HOT_RELOAD,default=false"`
	ConfigPath          string        `env:"CONFIG_PATH,overwrite"`
	ReloadCheckInterval time.Duration `env:"RELOAD_CHECK_INTERVAL,default=10s"`
}

RateLimitingConfig defines rate limiting settings

func (*RateLimitingConfig) Validate

func (c *RateLimitingConfig) Validate() error

Validate validates RateLimitingConfig

type SecurityConfig

type SecurityConfig struct {
	MasterKey          string `env:"MASTER_KEY" secret:"true"`
	TLSCertPath        string `env:"TLS_CERT_PATH"`
	TLSKeyPath         string `env:"TLS_KEY_PATH"`
	EnableTLS          bool   `env:"ENABLE_TLS,default=false"`
	AllowedOrigins     string `env:"ALLOWED_ORIGINS"`
	EnableCORS         bool   `env:"ENABLE_CORS,default=false"`
	JWTSecret          string `env:"JWT_SECRET" secret:"true"`
	APIKeyHeader       string `env:"API_KEY_HEADER,default=Authorization"`
	EnableRateLimiting bool   `env:"ENABLE_RATE_LIMITING,default=true"`
}

SecurityConfig defines security settings

func (*SecurityConfig) Validate

func (c *SecurityConfig) Validate() error

Validate validates SecurityConfig

type ServerConfig

type ServerConfig struct {
	Port              int           `env:"PORT,default=8080"`
	Host              string        `env:"HOST,default=127.0.0.1"`
	ReadTimeout       time.Duration `env:"READ_TIMEOUT,default=30s"`
	WriteTimeout      time.Duration `env:"WRITE_TIMEOUT,default=30s"`
	IdleTimeout       time.Duration `env:"IDLE_TIMEOUT,default=120s"`
	RequestTimeout    time.Duration `env:"REQUEST_TIMEOUT,default=60s"`
	MaxRequestSize    int64         `env:"MAX_REQUEST_SIZE,default=10485760"`
	MaxHeaderBytes    int           `env:"MAX_HEADER_BYTES,default=1048576"`
	ShutdownTimeout   time.Duration `env:"SHUTDOWN_TIMEOUT,default=30s"`
	EnableProfiling   bool          `env:"ENABLE_PROFILING,default=false"`
	EnableHealthCheck bool          `env:"ENABLE_HEALTH_CHECK,default=true"`
}

ServerConfig defines HTTP server settings

func (*ServerConfig) Validate

func (c *ServerConfig) Validate() error

Validate validates ServerConfig

type StorageConfig

type StorageConfig struct {
	Mode   string       `env:"MODE,default=badger"`
	Badger BadgerConfig `env:",prefix=BADGER_"`
	Valkey ValkeyConfig `env:",prefix=VALKEY_"`
}

StorageConfig defines storage backend settings

func (StorageConfig) RuntimeStorage added in v1.0.1

func (c StorageConfig) RuntimeStorage() storage.Config

RuntimeStorage projects external storage settings into the storage adapter contract.

func (*StorageConfig) Validate

func (c *StorageConfig) Validate() error

Validate validates StorageConfig

type ValkeyConfig

type ValkeyConfig struct {
	URL            string        `env:"URL,default=valkey://localhost:6379" redact:"url"`
	MaxConnections int           `env:"MAX_CONNECTIONS,default=50"`
	MinIdleConns   int           `env:"MIN_IDLE_CONNS,default=10"`
	DialTimeout    time.Duration `env:"DIAL_TIMEOUT,default=5s"`
	ReadTimeout    time.Duration `env:"READ_TIMEOUT,default=3s"`
	WriteTimeout   time.Duration `env:"WRITE_TIMEOUT,default=3s"`
	IdleTimeout    time.Duration `env:"IDLE_TIMEOUT,default=5m"`
	ClusterMode    bool          `env:"CLUSTER_MODE,default=false"`
	Password       string        `env:"PASSWORD" secret:"true"`
}

ValkeyConfig defines Valkey/Redis settings

func (*ValkeyConfig) Validate

func (c *ValkeyConfig) Validate() error

Validate validates ValkeyConfig

Jump to

Keyboard shortcuts

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