config

type AutocertConfig struct {
	// Enabled toggles the autocert auto-pilot. False (default)
	// means the bridge serves only the self-signed cert. True
	// (in public mode + with a configured Domain + Email) means
	// the bridge mints + serves an LE cert for Domain.
	Enabled bool `yaml:"enabled,omitempty"`

	// Domain is the publicly-routable hostname the operator's iOS
	// clients (and the operator's browser) dial. Required when
	// `deployment.mode: public` is set; ignored otherwise.
	//
	// Consumed by:
	//   - Admin Origin allowlist (PR 2)
	//   - autocert.Manager.HostPolicy (PR 3) — only Domain is
	//     accepted as a host for cert minting
	//   - tls.Manager SNI gate (PR 3) — only requests whose SNI
	//     matches Domain hit the autocert path
	Domain string `yaml:"domain,omitempty"`

	// Email is the operator's contact address registered with the
	// ACME directory. LE uses this to send expiry warnings and
	// service-disruption notices. Required when Enabled.
	Email string `yaml:"email,omitempty"`

	// CacheDir is the on-disk directory where autocert stores the
	// account key, issued certs, and pending challenge state.
	// Empty defaults to `<dataDir>/acme` at load time. Persistence
	// across restarts is load-bearing: wiping this dir between
	// restarts burns the LE duplicate-cert rate-limit budget
	// (5/week per registered domain).
	CacheDir string `yaml:"cacheDir,omitempty"`

	// UseStaging routes the ACME client at LE's staging directory
	// instead of production. Untrusted cert (browsers warn) but
	// no rate limits — useful during deployment-tuning when the
	// production rate limits would otherwise burn fast. Default
	// false (production).
	UseStaging bool `yaml:"useStaging,omitempty"`

	// External443Mapping documents that the operator runs an
	// external port-forward / load balancer that maps `WAN:443`
	// to the bridge's `listenAddress`. Required when `Enabled`
	// AND `listenAddress` doesn't already end in `:443` — without
	// it, LE's TLS-ALPN-01 challenge cannot reach the bridge.
	// True is the operator's promise that the mapping is in
	// place; Validate cannot probe the WAN side.
	External443Mapping bool `yaml:"external443Mapping,omitempty"`
}

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"`
	Scanner         ScannerConfig      `yaml:"scanner,omitempty"`
	Limits          LimitsConfig       `yaml:"limits,omitempty"`
	Integrity       IntegrityConfig    `yaml:"integrity,omitempty"`
	Deployment      DeploymentConfig   `yaml:"deployment,omitempty"`
	Autocert        AutocertConfig     `yaml:"autocert,omitempty"`
	MDNS            MDNSConfig         `yaml:"mdns,omitempty"`

	// DisableHTTP3 prevents the server from binding UDP ports and
	// advertising Alt-Svc headers for HTTP/3 upgrades. Defaults to false.
	DisableHTTP3 bool `yaml:"disableHttp3,omitempty"`
}

type DeploymentConfig struct {
	// Mode selects the posture: "loopback" (default) or "public".
	// Empty value falls back to "loopback" at load time.
	Mode string `yaml:"mode,omitempty"`

	// AdminTLSTerminatedByProxy lets operators run the bridge in
	// public mode behind a TLS-terminating reverse proxy (Caddy /
	// nginx) without having the bridge mint its own admin TLS cert.
	// When true: the admin listener serves plain HTTP on its bind
	// address (operator's responsibility to keep that bind on a
	// private interface or restrict it via firewall); session
	// cookies still carry Secure (so the operator's proxy MUST
	// front them with HTTPS — browsers refuse to send Secure
	// cookies over plain HTTP, surfacing a misconfigured setup as
	// a visible login failure rather than a silent leak). When
	// false (and Mode == public): the bridge wraps its admin
	// listener in tls.NewListener against the same Manager that
	// fronts the public API, so the admin console gets the LE
	// cert for the operator's domain SNI and a self-signed cert
	// for direct-IP / unknown SNI.
	AdminTLSTerminatedByProxy bool `yaml:"adminTLSTerminatedByProxy,omitempty"`
}

type DeploymentMode string

type IntegrityConfig struct {
	// VariantSweepIntervalSec controls how often the
	// integrity.VariantWatcher walks `track_variants` and
	// stat()s each sidecar to detect external deletions.
	// Default 3600 s (1 h). Explicit zero disables the
	// watcher entirely — operators on minimal deploys who
	// run `bridge upscale --gc` manually opt out via this
	// knob.
	//
	// Pointer-typed so applyDefaults can distinguish
	// "missing field, use default" from "explicit zero,
	// disable". Same pattern LimitsConfig.RequestsPerMinute
	// uses for the same reason. Always read via
	// Config.VariantSweepInterval() below — never
	// dereference directly.
	//
	// Pair with the reactive serve-side cleanup in
	// internal/api.serveVariant: that path closes the
	// active-playback case the moment a client requests a
	// missing sidecar. The watcher catches the
	// not-currently-playing case at most VariantSweepInterval
	// later. Both publish the same `upscale.deleted` SSE
	// event so iOS reconciliation is uniform.
	VariantSweepIntervalSec *int `yaml:"variantSweepIntervalSec,omitempty"`

	// OrphanSidecarSweepIntervalSec controls how often the
	// integrity.OrphanSidecarSweeper walks `<variantsDir>/transcoded/`
	// for sidecar files that have no matching `track_variants` row
	// and unlinks them. The forward-sweep half of what the operator-
	// triggered `bridge upscale --gc` does today; the existing
	// VariantWatcher above handles the reverse half (DB rows whose
	// sidecar file no longer exists).
	//
	// **Default zero (disabled)** — opt-in feature. Operators on
	// minimal deploys or low-disk-pressure libraries can keep running
	// `--gc` manually; operators on libraries that churn variants
	// (frequent rip / re-tag passes that delete + re-add tracks under
	// the SAME relative path but produce different `track_variants.id`
	// rows) opt in via a non-zero value here.
	//
	// **Chunked + low-priority**: each tick processes at most
	// `gcChunkSize` filesystem entries (100, defined in the integrity
	// package). The operator-triggered `--gc` keeps its existing
	// unbounded-sweep semantics; this knob exists for the
	// hands-off-operator profile where chunking + cadence-spacing
	// matters.
	//
	// **Snapshot semantics**: each tick takes a `BEGIN DEFERRED`
	// snapshot of `track_variants.sidecar_path` BEFORE the
	// filesystem walk so a concurrent `UpsertVariant` writer can't
	// produce a false-positive orphan (the new sidecar lands on disk
	// before its row commits to the snapshot; pre-snapshot the
	// reverse race would have the sweeper unlink the file before the
	// row caught up).
	//
	// Pointer-typed to distinguish "missing field → use default
	// (disabled)" from "explicit zero → also disabled" — kept
	// symmetric with VariantSweepIntervalSec above even though they
	// resolve to the same behaviour here, so a future migration that
	// flips the default doesn't silently change operator-zeroed
	// configs.
	//
	// Always read via Config.OrphanSidecarSweepInterval() below.
	OrphanSidecarSweepIntervalSec *int `yaml:"orphanSidecarSweepIntervalSec,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 LimitsConfig struct {
	Manifest ManifestLimitsConfig `yaml:"manifest,omitempty"`
}

type MDNSConfig struct {
	Enabled *bool `yaml:"enabled,omitempty"`
}

type ManifestLimitsConfig struct {
	RequestsPerMinute *int `yaml:"requestsPerMinute,omitempty"`
	Burst             *int `yaml:"burst,omitempty"`
}

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

type ScannerConfig struct {
	DeleteAfterMissingScans int `yaml:"deleteAfterMissingScans,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"`

	// OptimizeEnabled gates the CarPlay-optimize feature
	// (`optimized-*` variant class — downsample to 16-bit /
	// 44.1k or 48k for fast cellular CarPlay playback).
	// Pointer-bool so the default is true when the field is
	// absent (`nil` → enabled); operators on storage-constrained
	// hosts can opt out via `optimizeEnabled: false`. Ignored
	// when `Enabled` is false (the master toggle covers both).
	OptimizeEnabled *bool `yaml:"optimizeEnabled,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"`

	// VariantsDir lets operators relocate upscaled FLAC sidecars off
	// the bridge's data partition onto any writable mount they have
	// space on — external drive, secondary disk, dedicated NAS subdir.
	// Empty (the default) falls through to `<dataDir>/transcoded/`
	// (preserved historical layout — no existing install breaks).
	//
	// MUST be an absolute path. MUST NOT resolve under any library
	// root (catastrophic — variants tangled with source files would
	// confuse the scanner AND collide with the read-only library
	// invariant from PR #75). Validation in `Config.Validate` enforces
	// both constraints; the directory itself is created on first
	// upscale via `os.MkdirAll`.
	//
	// On-disk layout under VariantsDir is source-path-mirrored
	// (`<artist>/<album>/<basename>.<variantID>.flac` style) so
	// operators with write access to their library can `mv` the
	// variants dir contents into the library and slot variants next
	// to source files. The DB lookup remains the only path-resolution
	// mechanism — moves do NOT change the wire shape; iOS doesn't
	// care.
	VariantsDir string `yaml:"variantsDir,omitempty"`
}