config

type BackupConfig struct {
	// IntervalHours is the cadence for automatic snapshots.
	// nil/omitted → DefaultBackupIntervalHours.
	// 0 → disabled.
	// >0 → cadence in hours (negative values rejected at Validate).
	IntervalHours *int `yaml:"intervalHours,omitempty"`

	// Keep is the maximum number of snapshots to retain after a
	// rotation. Older snapshots beyond this count are deleted on
	// each periodic snapshot. Zero or negative disables pruning;
	// the operator manages backup-disk usage by hand in that case.
	// Defaults to DefaultBackupKeep when the entire backup section
	// is omitted; an operator who wants no pruning sets `keep: -1`
	// (a negative value won't trip Validate).
	Keep int `yaml:"keep,omitempty"`
}

type Config struct {
	LibraryRoots    []string `yaml:"libraryRoots"`
	ListenAddress   string   `yaml:"listenAddress"`
	AdminAddress    string   `yaml:"adminAddress,omitempty"`
	DataDir         string   `yaml:"dataDir"`
	TLSCertPath     string   `yaml:"tlsCertPath,omitempty"`
	TLSKeyPath      string   `yaml:"tlsKeyPath,omitempty"`
	ScanIntervalSec int      `yaml:"scanIntervalSec"`
	LibraryName     string   `yaml:"libraryName"`
	// CustomEndpoints lets operators advertise URLs that aren't
	// discoverable from the host's interface table — e.g. a reverse
	// proxy, a port-forwarded WAN URL, or a non-default Tailscale
	// MagicDNS that the auto-detector didn't pick up. Each entry is
	// a complete URL ("https://my-bridge.example.com:7788") and is
	// surfaced to iOS via /v1/health and the admin endpoints panel.
	//
	// Validation: each entry must parse as an absolute URL with
	// scheme="https" — entries failing validation are dropped at
	// load with a `.warn` log and don't fail the whole config.
	//
	// Operators add entries via the admin console's Settings page;
	// hand-edits to bridge.yaml work too. Used as input to the cert
	// SAN gather (PR feat/tls-broader-sans) so that adding a new
	// custom DNS hostname here, then rotating the cert, makes that
	// URL TLS-handshake-compatible from iOS.
	CustomEndpoints []string           `yaml:"customEndpoints,omitempty"`
	Update          UpdateConfig       `yaml:"update,omitempty"`
	Backup          BackupConfig       `yaml:"backup,omitempty"`
	LibraryWatch    LibraryWatchConfig `yaml:"libraryWatch,omitempty"`
	Upscale         UpscaleConfig      `yaml:"upscale,omitempty"`
	Tailscale       TailscaleConfig    `yaml:"tailscale,omitempty"`
}

type LibraryWatchConfig struct {
	// Enabled is the master toggle. Default false.
	Enabled bool `yaml:"enabled,omitempty"`
	// DebounceSeconds is the per-directory event coalesce window.
	// 10 seconds is the documented default — long enough that a
	// large-folder copy doesn't trigger a scan-per-file storm,
	// short enough that the perceived "instant" feel survives.
	// Zero or omitted → DefaultLibraryWatchDebounceSeconds.
	DebounceSeconds int `yaml:"debounceSeconds,omitempty"`
}

type TailscaleConfig struct {
	// Mode selects the integration: "cli" (default), "tsnet", or
	// "disabled". Empty value falls back to "cli" at load time.
	Mode string `yaml:"mode,omitempty"`

	// AuthKey is the Tailscale auth key used by tsnet on first run.
	//
	// Precedence (matches Tailscale's standard idiom):
	//   1. TS_AUTHKEY environment variable (preferred — keeps
	//      secrets out of yaml on disk)
	//   2. This field (fallback for ops who can't set env vars)
	//   3. Empty → triggers interactive OAuth (`bridge tsnet auth`
	//      prints an AuthURL the operator visits in a browser)
	//
	// Unused once tsnet has persisted state.
	AuthKey string `yaml:"authKey,omitempty"`

	// Hostname is the magic-DNS hostname tsnet will register with.
	// Empty falls back to the bridge's deviceName / library name.
	Hostname string `yaml:"hostname,omitempty"`
}

type TailscaleMode string

type UpdateConfig struct {
	// AutoInstall enables the poll-loop's automatic install attempt.
	// Off by default — the operator must opt in. Even when on, the
	// stream-active gate refuses if any /v1/download is in flight,
	// and quiet-hours (when set) restrict to the configured window.
	AutoInstall bool `yaml:"autoInstall,omitempty"`

	// QuietHours restricts auto-install to a daily window in
	// "HH:MM-HH:MM" form using the server's local time. Empty means
	// "any time". The window may wrap midnight (e.g.
	// "23:00-06:00") — see config_test.go for the wrap-around test
	// matrix. Any-clock format that fails to parse rejects at
	// Validate time so a bad config doesn't silently disable the
	// auto-installer.
	QuietHours string `yaml:"quietHours,omitempty"`

	// CheckIntervalHours overrides the default poll cadence (6 h).
	// Operator-tunable for installations on metered or rate-limited
	// uplinks. Values below 1h are clamped at runtime by the updater.
	// Zero = use the package default.
	CheckIntervalHours int `yaml:"checkIntervalHours,omitempty"`
}

type UpscaleConfig struct {
	// Enabled is the master toggle. Default false.
	Enabled bool `yaml:"enabled,omitempty"`

	// Workers is the size of the long-lived transcode worker pool
	// instantiated by `bridge serve` when Enabled. Zero (the default)
	// resolves to min(NumCPU-1, 4) at startup. Operators with beefy
	// hosts can raise; small-box deployments (Pi) should leave at
	// the default to avoid starving downloads / pairing requests.
	Workers int `yaml:"workers,omitempty"`

	// QueueCap is the hard cap on the worker pool's pending-job
	// channel. POST /v1/upscale enqueues are non-blocking and drop
	// to a 503 `queue_full` response when the channel can't accept
	// more — protects against a user spamming "Generate" on their
	// 50k-track library exhausting memory or wedging the HTTP path.
	// Zero (the default) resolves to DefaultUpscaleQueueCap.
	QueueCap int `yaml:"queueCap,omitempty"`

	// TargetRate selects the resampler output rate. "auto" (the
	// default) picks 176400 Hz for 44.1-family sources and 192000
	// Hz for 48-family sources. Explicit numeric values override
	// the auto pick (e.g. "352800" for DSD-friendly DACs that
	// prefer the next octave up). Sources at or above the chosen
	// rate are skipped — never downsample.
	TargetRate string `yaml:"targetRate,omitempty"`

	// TargetBits is the output bit depth. 24 (the default) is the
	// sweet spot for FLAC: lower ceiling than 32-bit float but
	// 96 dB above the audible noise floor and well below any
	// realistic dither quantisation noise. 32-bit-int output is
	// supported for completeness but rarely a sonic improvement.
	TargetBits int `yaml:"targetBits,omitempty"`
}