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 ¶
- func ConfigDir() (string, error)
- func ResolveEnv(ref string, logger *slog.Logger) (string, error)
- func RunBuild(configDir string, logger *slog.Logger) error
- func ValidModes() []string
- type AuditConfig
- type AuditEncryptionConfig
- type AuditIntegrityConfig
- type CollectionDecayConfig
- type Config
- type ConsistencyConfig
- type DaemonConfig
- type DaemonRetrievalFirewallConfig
- type Destination
- type DestinationDecayConfig
- type EmbeddingConfig
- type EventSink
- type EventsConfig
- type FieldVisibilityConfig
- type GlobalRateLimitConfig
- type IdempotencyConfig
- type JWTConfig
- type MCPConfig
- type OAuthClientConfig
- type OAuthDaemonConfig
- type PayloadLimitsConfig
- type PolicyCacheConfig
- type PolicyDecayConfig
- type RetrievalConfig
- type SecurityEventsConfig
- type ShutdownConfig
- type SigningConfig
- type Source
- type SourcePolicyConfig
- type SourceRateLimitConfig
- type SourceRetrievalFirewallConfig
- type TLSConfig
- type TrustedProxiesConfig
- type WALDaemonConfig
- type WALEncryptionConfig
- type WALIntegrityConfig
- type WALWatchdogConfig
- type WebConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConfigDir ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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].