config

package
v0.1.2 Latest Latest
Warning

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

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

Documentation

Overview

Package config provides config loading, resolution, and validation for BubbleFish Nexus. All structs model the TOML files in ~/.bubblefish/Nexus/.

Config is loaded once at startup and treated as immutable. Hot-reload (Phase 0D) replaces the pointer atomically; in-flight requests always finish with the config they started with.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ConfigDir

func ConfigDir() (string, error)

ConfigDir returns the canonical configuration directory for BubbleFish Nexus. If the BUBBLEFISH_HOME environment variable is set and non-empty, its value is used (resolved to an absolute path). Otherwise falls back to ~/.bubblefish/Nexus. Returns an error if path resolution fails; callers must treat this as fatal.

func ResolveEnv

func ResolveEnv(ref string, logger *slog.Logger) (string, error)

ResolveEnv resolves a secret reference string to its plaintext value.

Supported prefixes:

  • "env:VAR_NAME" — reads the environment variable VAR_NAME.
  • "file:/path" — reads the file at /path, trims leading/trailing whitespace.
  • anything else — returned as-is (literal value).

The resolved path for "file:" references is logged at DEBUG level. The resolved VALUE is NEVER logged at any level.

Reference: Tech Spec Section 6.1.

func RunBuild

func RunBuild(configDir string, logger *slog.Logger) error

RunBuild implements the `bubblefish build` command.

It loads the full configuration from configDir (daemon.toml + sources/*.toml + destinations/*.toml), validates every source's [source.policy] block against the known destination set, then writes compiled/policies.json to the compiled/ subdirectory of configDir.

Any SCHEMA_ERROR (empty resolved api_key, duplicate resolved keys, unknown destination reference) causes RunBuild to return immediately with a descriptive error. On success the compiled/ directory exists with 0700 permissions and policies.json has 0600.

Reference: Tech Spec Section 9.1, Phase 1 Behavioral Contract.

func ValidModes

func ValidModes() []string

ValidModes returns the set of recognised deployment mode names.

Types

type AuditConfig

type AuditConfig struct {
	Enabled              bool                  `toml:"enabled"`
	LogFile              string                `toml:"log_file"`
	MaxFileSizeMB        int                   `toml:"max_file_size_mb"`
	AdminRateLimitPerMin int                   `toml:"admin_rate_limit_per_minute"`
	DualWrite            *bool                 `toml:"dual_write"` // Default true; pointer to distinguish unset from false
	Integrity            AuditIntegrityConfig  `toml:"integrity"`
	Encryption           AuditEncryptionConfig `toml:"encryption"`
}

AuditConfig models [daemon.audit]. Reference: Tech Spec Addendum Section A4.1, Update U1.6.

func (*AuditConfig) AuditDualWriteEnabled

func (a *AuditConfig) AuditDualWriteEnabled() bool

AuditDualWriteEnabled returns the effective dual_write setting (default true).

type AuditEncryptionConfig

type AuditEncryptionConfig struct {
	Enabled bool   `toml:"enabled"`
	KeyFile string `toml:"key_file"` // Separate 32-byte AES-256 key for interaction log
}

AuditEncryptionConfig models [daemon.audit.encryption]. SEPARATE from [daemon.wal.encryption] — independent AES-256 key. Reference: Update U1.2.

type AuditIntegrityConfig

type AuditIntegrityConfig struct {
	Mode       string `toml:"mode"`         // "crc32" (default) or "mac"
	MacKeyFile string `toml:"mac_key_file"` // Separate 32-byte HMAC-SHA256 key for interaction log
}

AuditIntegrityConfig models [daemon.audit.integrity]. SEPARATE from [daemon.wal.integrity] — independent HMAC key. Reference: Update U1.1.

type CollectionDecayConfig

type CollectionDecayConfig struct {
	HalfLifeDays      float64 `toml:"half_life_days"`
	DecayMode         string  `toml:"decay_mode"`
	StepThresholdDays float64 `toml:"step_threshold_days"`
}

CollectionDecayConfig models [destination.decay.collections.<name>]. Per-collection overrides take highest precedence in the tiered decay system.

Reference: Tech Spec Section 3.6.

type Config

type Config struct {
	Daemon         DaemonConfig         `toml:"daemon"`
	Retrieval      RetrievalConfig      `toml:"retrieval"`
	Consistency    ConsistencyConfig    `toml:"consistency"`
	SecurityEvents SecurityEventsConfig `toml:"security_events"`

	// Sources and Destinations are populated by scanning the sources/ and
	// destinations/ sub-directories. Not decoded from daemon.toml itself.
	Sources      []*Source
	Destinations []*Destination

	// ResolvedSourceKeys maps source name → resolved API key bytes.
	// Pre-computed at startup; never mutated after Load returns.
	// NEVER log these values.
	ResolvedSourceKeys map[string][]byte

	// ResolvedAdminKey is the resolved admin_token bytes.
	// NEVER log this value.
	ResolvedAdminKey []byte

	// ResolvedMCPKey is the resolved MCP api_key bytes.
	// May be nil if MCP is disabled or api_key is empty.
	// NEVER log this value.
	ResolvedMCPKey []byte
}

Config is the fully loaded and resolved runtime configuration. After a successful Load, ResolvedSourceKeys and ResolvedAdminKey are populated and safe to use on the hot path without any os.Getenv calls.

func Load

func Load(configDir string, logger *slog.Logger) (*Config, error)

Load reads daemon.toml, sources/*.toml, and destinations/*.toml from configDir, validates and resolves all secret references, then returns the fully initialised Config.

Validation failures are returned as errors with the "SCHEMA_ERROR:" prefix so callers can format them consistently. Any SCHEMA_ERROR means the daemon must not start.

Reference: Tech Spec Section 9, Section 6.1.

func (*Config) DestinationByName

func (c *Config) DestinationByName(name string) *Destination

DestinationByName returns the Destination with the given name, or nil.

func (*Config) SourceByName

func (c *Config) SourceByName(name string) *Source

SourceByName returns the Source with the given name, or nil if not found.

type ConsistencyConfig

type ConsistencyConfig struct {
	Enabled         bool `toml:"enabled"`
	IntervalSeconds int  `toml:"interval_seconds"`
	SampleSize      int  `toml:"sample_size"`
}

ConsistencyConfig models the [consistency] section.

type DaemonConfig

type DaemonConfig struct {
	Port       int    `toml:"port"`
	Bind       string `toml:"bind"`
	AdminToken string `toml:"admin_token"` // env:/file:/literal reference
	LogLevel   string `toml:"log_level"`
	LogFormat  string `toml:"log_format"`
	Mode       string `toml:"mode"` // safe, balanced, or fast
	QueueSize  int    `toml:"queue_size"`

	Shutdown          ShutdownConfig                `toml:"shutdown"`
	WAL               WALDaemonConfig               `toml:"wal"`
	RateLimit         GlobalRateLimitConfig         `toml:"rate_limit"`
	Embedding         EmbeddingConfig               `toml:"embedding"`
	MCP               MCPConfig                     `toml:"mcp"`
	Web               WebConfig                     `toml:"web"`
	TLS               TLSConfig                     `toml:"tls"`
	TrustedProxies    TrustedProxiesConfig          `toml:"trusted_proxies"`
	Signing           SigningConfig                 `toml:"signing"`
	JWT               JWTConfig                     `toml:"jwt"`
	Events            EventsConfig                  `toml:"events"`
	Audit             AuditConfig                   `toml:"audit"`
	RetrievalFirewall DaemonRetrievalFirewallConfig `toml:"retrieval_firewall"`
	OAuth             OAuthDaemonConfig             `toml:"oauth"`
}

DaemonConfig models the [daemon] section of daemon.toml.

type DaemonRetrievalFirewallConfig

type DaemonRetrievalFirewallConfig struct {
	Enabled     bool     `toml:"enabled"`
	TierOrder   []string `toml:"tier_order"`
	DefaultTier string   `toml:"default_tier"`
}

DaemonRetrievalFirewallConfig models [daemon.retrieval_firewall]. Reference: Tech Spec Addendum Section A4.1.

type Destination

type Destination struct {
	Name   string
	Type   string
	DBPath string
	DSN    string
	URL    string
	APIKey string
	Decay  DestinationDecayConfig
}

Destination is the fully decoded, validated destination configuration.

type DestinationDecayConfig

type DestinationDecayConfig struct {
	HalfLifeDays      float64                          `toml:"half_life_days"`
	DecayMode         string                           `toml:"decay_mode"`
	StepThresholdDays float64                          `toml:"step_threshold_days"`
	Collections       map[string]CollectionDecayConfig `toml:"collections"`
}

DestinationDecayConfig models [destination.decay].

type EmbeddingConfig

type EmbeddingConfig struct {
	Enabled        bool   `toml:"enabled"`
	Provider       string `toml:"provider"`
	URL            string `toml:"url"`     // env:/file:/literal reference
	APIKey         string `toml:"api_key"` // env:/file:/literal reference
	Model          string `toml:"model"`
	Dimensions     int    `toml:"dimensions"`
	TimeoutSeconds int    `toml:"timeout_seconds"`
}

EmbeddingConfig models [daemon.embedding].

type EventSink

type EventSink struct {
	Name           string `toml:"name"`
	URL            string `toml:"url"`
	TimeoutSeconds int    `toml:"timeout_seconds"`
	MaxRetries     int    `toml:"max_retries"`
	Content        string `toml:"content"` // "summary" or "full"
}

EventSink models [[daemon.events.sinks]].

type EventsConfig

type EventsConfig struct {
	Enabled             bool        `toml:"enabled"`
	MaxInFlight         int         `toml:"max_inflight"`
	RetryBackoffSeconds []int       `toml:"retry_backoff_seconds"`
	Sinks               []EventSink `toml:"sinks"`
}

EventsConfig models [daemon.events].

type FieldVisibilityConfig

type FieldVisibilityConfig struct {
	IncludeFields []string `toml:"include_fields"`
	StripMetadata bool     `toml:"strip_metadata"`
}

FieldVisibilityConfig models [source.policy.field_visibility].

type GlobalRateLimitConfig

type GlobalRateLimitConfig struct {
	GlobalRequestsPerMinute int `toml:"global_requests_per_minute"`
}

GlobalRateLimitConfig models [daemon.rate_limit].

type IdempotencyConfig

type IdempotencyConfig struct {
	Enabled            bool `toml:"enabled"`
	DedupWindowSeconds int  `toml:"dedup_window_seconds"`
}

IdempotencyConfig models [source.idempotency].

type JWTConfig

type JWTConfig struct {
	Enabled       bool   `toml:"enabled"`
	JWKSUrl       string `toml:"jwks_url"`
	ClaimToSource string `toml:"claim_to_source"`
	Audience      string `toml:"audience"`
}

JWTConfig models [daemon.jwt].

type MCPConfig

type MCPConfig struct {
	Enabled    bool   `toml:"enabled"`
	Port       int    `toml:"port"`
	Bind       string `toml:"bind"`
	SourceName string `toml:"source_name"`
	APIKey     string `toml:"api_key"` // env:/file:/literal reference
}

MCPConfig models [daemon.mcp].

type OAuthClientConfig

type OAuthClientConfig struct {
	ClientID        string   `toml:"client_id"`
	ClientName      string   `toml:"client_name"`
	RedirectURIs    []string `toml:"redirect_uris"`
	OAuthSourceName string   `toml:"oauth_source_name"`
	AllowedScopes   []string `toml:"allowed_scopes"`
}

OAuthClientConfig models [[daemon.oauth.clients]].

type OAuthDaemonConfig

type OAuthDaemonConfig struct {
	Enabled            bool                `toml:"enabled"`
	IssuerURL          string              `toml:"issuer_url"`
	PrivateKeyFile     string              `toml:"private_key_file"`
	AccessTokenTTLSecs int                 `toml:"access_token_ttl_seconds"`
	AuthCodeTTLSecs    int                 `toml:"auth_code_ttl_seconds"`
	Clients            []OAuthClientConfig `toml:"clients"`
}

OAuthDaemonConfig models [daemon.oauth]. Reference: Post-Build Add-On Update Technical Specification Section 6.1.

type PayloadLimitsConfig

type PayloadLimitsConfig struct {
	MaxBytes int64 `toml:"max_bytes"`
}

PayloadLimitsConfig models [source.payload_limits].

type PolicyCacheConfig

type PolicyCacheConfig struct {
	ReadFromCache               bool    `toml:"read_from_cache"`
	WriteToCache                bool    `toml:"write_to_cache"`
	MaxTTLSeconds               int     `toml:"max_ttl_seconds"`
	SemanticSimilarityThreshold float64 `toml:"semantic_similarity_threshold"`
}

PolicyCacheConfig models [source.policy.cache].

type PolicyDecayConfig

type PolicyDecayConfig struct {
	HalfLifeDays      float64 `toml:"half_life_days"`
	DecayMode         string  `toml:"decay_mode"`
	StepThresholdDays float64 `toml:"step_threshold_days"`
}

PolicyDecayConfig models [source.policy.decay] (per-source override).

type RetrievalConfig

type RetrievalConfig struct {
	TimeDecay        bool    `toml:"time_decay"`
	HalfLifeDays     float64 `toml:"half_life_days"`
	DecayMode        string  `toml:"decay_mode"` // "exponential" or "step"
	OverSampleFactor int     `toml:"over_sample_factor"`
	DefaultProfile   string  `toml:"default_profile"` // fast, balanced, deep
}

RetrievalConfig models the top-level [retrieval] section.

type SecurityEventsConfig

type SecurityEventsConfig struct {
	Enabled bool   `toml:"enabled"`
	LogFile string `toml:"log_file"`
}

SecurityEventsConfig models the [security_events] section.

type ShutdownConfig

type ShutdownConfig struct {
	DrainTimeoutSeconds int `toml:"drain_timeout_seconds"`
}

ShutdownConfig models [daemon.shutdown].

type SigningConfig

type SigningConfig struct {
	Enabled bool   `toml:"enabled"`
	KeyFile string `toml:"key_file"` // env:/file:/literal reference
}

SigningConfig models [daemon.signing].

type Source

type Source struct {
	Name             string
	APIKey           string // raw (unresolved) reference — NEVER log resolved value
	Namespace        string
	CanRead          bool
	CanWrite         bool
	TargetDest       string
	DefaultActorType string
	DefaultActorID   string
	DefaultProfile   string
	RateLimit        SourceRateLimitConfig
	PayloadLimits    PayloadLimitsConfig
	Mapping          map[string]string   // output field → gjson dot-path
	Transform        map[string][]string // output field → transform pipeline
	Idempotency      IdempotencyConfig
	Policy           SourcePolicyConfig
}

Source is the fully decoded, validated source configuration. Field names mirror sourceBody but are exported and used throughout the daemon.

type SourcePolicyConfig

type SourcePolicyConfig struct {
	AllowedDestinations   []string                      `toml:"allowed_destinations"`
	AllowedOperations     []string                      `toml:"allowed_operations"`
	AllowedRetrievalModes []string                      `toml:"allowed_retrieval_modes"`
	AllowedProfiles       []string                      `toml:"allowed_profiles"`
	MaxResults            int                           `toml:"max_results"`
	MaxResponseBytes      int                           `toml:"max_response_bytes"`
	FieldVisibility       FieldVisibilityConfig         `toml:"field_visibility"`
	Cache                 PolicyCacheConfig             `toml:"cache"`
	Decay                 PolicyDecayConfig             `toml:"decay"`
	RetrievalFirewall     SourceRetrievalFirewallConfig `toml:"retrieval_firewall"`
}

SourcePolicyConfig models [source.policy].

type SourceRateLimitConfig

type SourceRateLimitConfig struct {
	RequestsPerMinute int `toml:"requests_per_minute"`
}

SourceRateLimitConfig models [source.rate_limit].

type SourceRetrievalFirewallConfig

type SourceRetrievalFirewallConfig struct {
	BlockedLabels             []string `toml:"blocked_labels"`
	MaxClassificationTier     string   `toml:"max_classification_tier"`
	RequiredLabels            []string `toml:"required_labels"`
	DefaultClassificationTier string   `toml:"default_classification_tier"`
	VisibleNamespaces         []string `toml:"visible_namespaces"`
	CrossNamespaceRead        bool     `toml:"cross_namespace_read"`

	// Precomputed sets built at config-load time to avoid per-request
	// allocation in the PostFilter hot path. Rebuilt on every config load
	// (including hot-reload), so they are always fresh.
	BlockedLabelsSet     map[string]struct{} `toml:"-"`
	RequiredLabelsSet    map[string]struct{} `toml:"-"`
	VisibleNamespacesSet map[string]struct{} `toml:"-"`
}

SourceRetrievalFirewallConfig models [source.policy.retrieval_firewall]. Reference: Tech Spec Addendum Section A4.2.

type TLSConfig

type TLSConfig struct {
	Enabled      bool   `toml:"enabled"`
	CertFile     string `toml:"cert_file"` // env:/file:/literal reference
	KeyFile      string `toml:"key_file"`  // env:/file:/literal reference
	MinVersion   string `toml:"min_version"`
	MaxVersion   string `toml:"max_version"`
	ClientCAFile string `toml:"client_ca_file"`
	ClientAuth   string `toml:"client_auth"`
}

TLSConfig models [daemon.tls].

type TrustedProxiesConfig

type TrustedProxiesConfig struct {
	CIDRs            []string `toml:"cidrs"`
	ForwardedHeaders []string `toml:"forwarded_headers"`
}

TrustedProxiesConfig models [daemon.trusted_proxies].

type WALDaemonConfig

type WALDaemonConfig struct {
	Path             string              `toml:"path"`
	MaxSegmentSizeMB int64               `toml:"max_segment_size_mb"`
	Integrity        WALIntegrityConfig  `toml:"integrity"`
	Encryption       WALEncryptionConfig `toml:"encryption"`
	Watchdog         WALWatchdogConfig   `toml:"watchdog"`
}

WALDaemonConfig models [daemon.wal].

type WALEncryptionConfig

type WALEncryptionConfig struct {
	Enabled bool   `toml:"enabled"`
	KeyFile string `toml:"key_file"` // env:/file:/literal reference
}

WALEncryptionConfig models [daemon.wal.encryption].

type WALIntegrityConfig

type WALIntegrityConfig struct {
	Mode       string `toml:"mode"`         // "crc32" or "mac"
	MacKeyFile string `toml:"mac_key_file"` // env:/file:/literal reference
}

WALIntegrityConfig models [daemon.wal.integrity].

type WALWatchdogConfig

type WALWatchdogConfig struct {
	IntervalSeconds    int   `toml:"interval_seconds"`
	MinDiskBytes       int64 `toml:"min_disk_bytes"`
	MaxAppendLatencyMS int   `toml:"max_append_latency_ms"`
}

WALWatchdogConfig models [daemon.wal.watchdog].

type WebConfig

type WebConfig struct {
	Port        int  `toml:"port"`
	RequireAuth bool `toml:"require_auth"`
}

WebConfig models [daemon.web].

Jump to

Keyboard shortcuts

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