Configuration

The MusterBox config profile, validation, and defaults.

All integrations start from a configuration profile. The SDK validates the profile before any network traffic leaves the device — invalid config fails fast with InvalidConfig instead of half-working at runtime.

Config schema

Config schema version 1. The profile is a TOML file (or an equivalent programmatic object) with these sections and defaults:

Setting	Default	Notes
environment	sandbox	One of local, sandbox, staging, production
log.level	info	Logging verbosity
offline_buffering	true	Buffer events while offline and flush later
event_queue_capacity	1000	Max queued events before backpressure
shutdown_timeout_ms	5000	Grace period for the shutdown sequence
transport.request_timeout_ms	10000	Per-request timeout
transport.connect_timeout_ms	10000	Connection timeout
transport.max_retry_attempts	5	Retries for transient failures
transport.retry_base_delay_ms	500	Exponential backoff base
transport.retry_max_delay_ms	30000	Backoff ceiling
batch_size	25	Events per flush batch
flush_interval_ms	1000	Periodic flush cadence

# musterbox.toml
[base]
environment = "sandbox"

[logs]
level = "info"

[transport]
request_timeout_ms = 10000
max_retry_attempts = 5

Loading configuration

use musterbox_core::config::Config;

let config = Config::from_env()?;          // MYSTERY_VAR_* injection point
let config = Config::from_file("musterbox.toml")?;
let config = Config::from_content(toml_str)?;

The encoder is frame-based, UTF-8, and version-aware. Foreign or future-config version tags causes the loader to return a MismatchedVersion error instead of mis-reading fields.

Validation modes

MusterBoxSDK enforces different validation strictness depending on the lifecycle stage:

Mode	Purpose
MusterBoxConfig (default)	Load and validate everything, fail fast
UnvalidatedConfig	Raw, unvalidated descriptor (for tooling)
ValidatedConfig	What from_env/from_file produce after passing checks

Config secrets and credentials are never logged: diagnostics redact base_url, tokens, and key material.

Overriding the backend URL

For local development against a custom backend:

[base]
environment = "production"        # keep production env semantics
[transport]
base_url_override = "http://localhost:4100/api/v1"

An override that is neither http:// nor https:// is rejected by validation.

Precedence

1. Explicit base_url_override (when provided).

2. The environment’s default base URL:

   Environment	URL
   local	http://localhost:8081
   sandbox	https://sandbox-api.musterbox.dev
   staging	https://staging-api.musterbox.dev
   production	https://api.musterbox.com

3. The auth API base is always derived as control plane base + /api/v1.

Next: Initialization & lifecycle.