config

type AppConfig struct {
	Name      string `config:"name"`
	Port      uint16 `config:"port"`
	BodyLimit string `config:"body_limit"`
	// TrustedProxies lists proxy IPs or CIDR ranges allowed to set
	// X-Forwarded-For. When empty, the client IP is the direct connection peer
	// and a forwarded header from an untrusted client is ignored.
	TrustedProxies []string `config:"trusted_proxies"`
}

type ApprovalConfig struct {
	// AutoMigrate runs the approval DDL migration on application start.
	AutoMigrate bool `config:"auto_migrate"`

	// TimeoutScanInterval is the polling cadence for the timeout scanner
	// that finds tasks past their deadline. Default: 1 minute.
	TimeoutScanInterval time.Duration `config:"timeout_scan_interval"`

	// PreWarningScanInterval is the polling cadence for the pre-warning
	// scanner that notifies before a task hits its deadline. Default: 5 minutes.
	PreWarningScanInterval time.Duration `config:"pre_warning_scan_interval"`

	// CleanupScanInterval is the cadence of the retention cleanup job
	// that prunes form snapshots, urge records, and CC records past
	// their retention window. Default: 24 hours.
	CleanupScanInterval time.Duration `config:"cleanup_scan_interval"`

	// DelegationMaxDepth caps how deep a delegation chain (A→B→C…) can
	// be resolved before short-circuiting. Default: 10.
	DelegationMaxDepth int `config:"delegation_max_depth"`

	// FormSnapshotRetention is the retention window for apv_form_snapshot
	// rows; older snapshots are deleted by the cleanup job. Default: 90 days.
	FormSnapshotRetention time.Duration `config:"form_snapshot_retention"`

	// UrgeRecordRetention is the retention window for apv_urge_record rows.
	// Default: 30 days.
	UrgeRecordRetention time.Duration `config:"urge_record_retention"`

	// CCRecordRetention is the retention window for apv_cc_record rows
	// (only records that have been read are pruned). Default: 90 days.
	CCRecordRetention time.Duration `config:"cc_record_retention"`
}

type Config interface {
	// Unmarshal decodes configuration at the given key into target.
	Unmarshal(key string, target any) error
}

type CorsConfig struct {
	Enabled      bool     `config:"enabled"`
	AllowOrigins []string `config:"allow_origins"`
}

type DBKind string

type DataSourceConfig struct {
	Kind           DBKind `config:"type"`
	Host           string `config:"host"`
	Port           uint16 `config:"port"`
	User           string `config:"user"`
	Password       string `config:"password"`
	Database       string `config:"database"`
	Schema         string `config:"schema"`
	Path           string `config:"path"`
	EnableSQLGuard bool   `config:"enable_sql_guard"`

	// SSLMode selects the TLS posture for network dialects (Postgres, MySQL).
	// It defaults to SSLModeDisable (plaintext) when omitted, so TLS is opt-in
	// and existing zero-config deployments are unaffected. SQLite ignores it.
	SSLMode SSLMode `config:"ssl_mode"`
	// SSLRootCert is an optional path to a PEM file holding the CA
	// certificate(s) used to verify the server in the verify-ca / verify-full
	// modes. When empty, the host's system certificate pool is used.
	SSLRootCert string `config:"ssl_root_cert"`
}

type DataSourcesConfig struct {
	Map map[string]DataSourceConfig
}

type EventConfig struct {
	// DefaultTransport is the route fallback when no rule matches.
	DefaultTransport string `config:"default_transport"`
	// AsyncQueueSize is the capacity of the async fan-in queue used
	// by WithAsync publishes.
	AsyncQueueSize int `config:"async_queue_size"`
	// AsyncWorkers is the number of goroutines draining the async
	// fan-in queue.
	AsyncWorkers int `config:"async_workers"`
	// PublishTimeout caps an individual transport.Publish call.
	PublishTimeout time.Duration `config:"publish_timeout"`

	Transports EventTransportsConfig `config:"transports"`
	Middleware EventMiddlewareConfig `config:"middleware"`
	Inbox      EventInboxConfig      `config:"inbox"`
	// Routing is matched top-to-bottom; the first rule whose Pattern
	// matches via path.Match wins. fan-out is expressed by listing
	// multiple transports in Transports.
	Routing []EventRoutingRule `config:"routing"`
}

type EventInboxConfig struct {
	Retention       time.Duration `config:"retention"`
	ProcessingLease time.Duration `config:"processing_lease"`
	CleanupInterval time.Duration `config:"cleanup_interval"`
}

type EventMemoryTransportConfig struct {
	QueueSize      int           `config:"queue_size"`
	FullPolicy     string        `config:"full_policy"` // error | block | drop_oldest
	PublishTimeout time.Duration `config:"publish_timeout"`
}

type EventMiddlewareConfig struct {
	Logging bool `config:"logging"`
	Tracing bool `config:"tracing"`
	// TracingStrict, when true, switches the Tracing middleware to
	// strict mode: incoming TraceIDs from cross-process transports are
	// treated as untrusted and parked under IncomingTraceIDFromContext;
	// a fresh ID is generated for log correlation. Default (false) is
	// W3C / OpenTelemetry-compatible propagation suitable for intra-
	// cluster pub/sub. Toggle this on at the edge between trust zones.
	TracingStrict bool `config:"tracing_strict"`
	Metrics       bool `config:"metrics"`
	Recover       bool `config:"recover"`
	// Inbox controls whether the consume-side idempotency middleware
	// is enabled. It only activates on transports whose Capabilities
	// declare AtLeastOnce regardless of this flag.
	Inbox bool `config:"inbox"`
}

type EventOutboxTransportConfig struct {
	Enabled         bool          `config:"enabled"`
	RelayInterval   time.Duration `config:"relay_interval"`
	MaxRetries      int           `config:"max_retries"`
	BatchSize       int           `config:"batch_size"`
	LeaseMultiplier int           `config:"lease_multiplier"`
	MinLease        time.Duration `config:"min_lease"`
	SinkName        string        `config:"sink"`
	CleanupInterval time.Duration `config:"cleanup_interval"`
	CompletedTTL    time.Duration `config:"completed_ttl"`
}

type EventRedisStreamTransportConfig struct {
	Enabled           bool          `config:"enabled"`
	StreamPrefix      string        `config:"stream_prefix"`
	MaxLenApprox      int64         `config:"max_len_approx"`
	BlockTimeout      time.Duration `config:"block_timeout"`
	ClaimIdle         time.Duration `config:"claim_idle"`
	ClaimInterval     time.Duration `config:"claim_interval"`
	ClaimBatchSize    int64         `config:"claim_batch_size"`
	ReaperConcurrency int           `config:"reaper_concurrency"`
	// HandlerTimeout bounds each delivery so a hung handler cannot pin a worker.
	// Zero disables the deadline — but the deadline is also the ONLY thing that
	// frees a wedged reaper slot before shutdown: a reclaimed handler that blocks
	// forever holds its bounded slot until Stop, so with HandlerTimeout=0 a few
	// stuck reclaims can starve reaper failover for all other streams. Operators
	// who disable it should size ReaperConcurrency with that risk in mind.
	HandlerTimeout time.Duration `config:"handler_timeout"`
	SetupTimeout   time.Duration `config:"setup_timeout"`
	ConsumerID     string        `config:"consumer_id"`
	StartID        string        `config:"start_id"`
}

type EventRoutingRule struct {
	Pattern    string   `config:"pattern"`
	Transports []string `config:"transports"`
}

type EventTransportsConfig struct {
	Memory      EventMemoryTransportConfig      `config:"memory"`
	Outbox      EventOutboxTransportConfig      `config:"outbox"`
	RedisStream EventRedisStreamTransportConfig `config:"redis_stream"`
}

type FilesystemConfig struct {
	Root string `config:"root"`
}

type MCPConfig struct {
	Enabled bool `config:"enabled"`
	// RequireAuth gates the MCP HTTP endpoint behind bearer-token authentication.
	// It is a pointer so an unset value defaults to secure (auth required); set it
	// to false explicitly to allow anonymous access.
	RequireAuth *bool `config:"require_auth"`
}

type MinIOConfig struct {
	Endpoint  string `config:"endpoint"`
	AccessKey string `config:"access_key"`
	SecretKey string `config:"secret_key"`
	Bucket    string `config:"bucket"`
	Region    string `config:"region"`
	UseSSL    bool   `config:"use_ssl"`
}

type MonitorConfig struct {
	SampleInterval time.Duration `config:"sample_interval"` // Interval between samples (default: 10s)
	SampleDuration time.Duration `config:"sample_duration"` // Sampling window duration (default: 2s)
	// ExcludedMounts lists additional mount-point substrings to exclude from disk
	// statistics, on top of the built-in OS pseudo-filesystem prefixes. Use this for
	// host- or vendor-specific volumes (e.g. developer-tool or virtualization mounts)
	// that should not count toward disk totals.
	ExcludedMounts []string `config:"excluded_mounts"`
}

type RedisConfig struct {
	// Enabled gates the Redis client construction. When false (default) the
	// framework provides a nil *redis.Client into the fx graph and skips the
	// connection PING during start-up; downstream modules that ask for the
	// client via `optional:"true"` therefore stay dormant. Set this to true
	// only when the application actually depends on Redis (cache, redis_stream
	// transport, nonce store, etc.).
	Enabled  bool   `config:"enabled"`
	Host     string `config:"host"`
	Port     uint16 `config:"port"`
	User     string `config:"user"`
	Password string `config:"password"`
	Database uint8  `config:"database"` // Database number (0-15)
	Network  string `config:"network"`  // "tcp" or "unix" (default: "tcp")
}

type SSLMode string

type SecurityConfig struct {
	// Secret is the hex-encoded key used to sign and verify JWT tokens.
	// Leave empty in development to have the framework generate an ephemeral
	// key at startup; set a stable per-deployment value in production.
	Secret           string        `config:"secret"`
	TokenExpires     time.Duration `config:"token_expires"`
	RefreshNotBefore time.Duration `config:"refresh_not_before"`
	LoginRateLimit   int           `config:"login_rate_limit"`
	RefreshRateLimit int           `config:"refresh_rate_limit"`
}

type StorageConfig struct {
	Provider    StorageProvider  `config:"provider"`
	AutoMigrate bool             `config:"auto_migrate"`
	MinIO       MinIOConfig      `config:"minio"`
	Filesystem  FilesystemConfig `config:"filesystem"`

	// MaxUploadSize is the hard upper bound (in bytes) on a single object
	// uploaded through the storage RPC, regardless of declared mode.
	// Default: 1 GiB.
	MaxUploadSize int64 `config:"max_upload_size"`

	// ClaimTTL is how long an upload claim stays valid before being swept.
	// Default: 24h.
	ClaimTTL time.Duration `config:"claim_ttl"`

	// MaxPendingClaims caps the number of in-flight (status='pending')
	// upload claims a single principal may hold simultaneously. Prevents
	// a single user from exhausting backend resources by opening
	// thousands of multipart sessions. Enforcement is best-effort: the
	// init-upload check is a count-then-insert, so a concurrent burst from
	// one principal may briefly overshoot the cap by the number of
	// in-flight requests before settling. This is a DoS-hygiene limit, not
	// a hard security boundary. Default: 100.
	MaxPendingClaims int `config:"max_pending_claims"`

	// AllowPublicUploads controls whether clients may set public=true on
	// init_upload. When false (default), all uploads land under priv/
	// regardless of the client's request. Set to true only when the
	// business explicitly needs user-initiated public uploads.
	AllowPublicUploads bool `config:"allow_public_uploads"`

	// SweepInterval is how often the claim sweeper polls for expired
	// upload claims. Default: 5m.
	SweepInterval time.Duration `config:"sweep_interval"`
	// SweepBatchSize bounds how many expired claims one sweep tick processes.
	// Default: 200.
	SweepBatchSize int `config:"sweep_batch_size"`

	// DeleteWorkerInterval is how often the delete worker polls for due
	// pending-delete rows. Default: 5m.
	DeleteWorkerInterval time.Duration `config:"delete_worker_interval"`
	// DeleteBatchSize bounds how many rows the delete worker leases per tick.
	// Default: 100.
	DeleteBatchSize int `config:"delete_batch_size"`
	// DeleteConcurrency caps the number of in-flight object deletions
	// per worker tick. Default: 8.
	DeleteConcurrency int `config:"delete_concurrency"`
	// DeleteMaxAttempts is the retry budget after which a pending-delete
	// row is parked as dead-letter. Default: 12.
	DeleteMaxAttempts int `config:"delete_max_attempts"`
	// DeleteLeaseWindow is the visibility timeout applied when leasing
	// rows. Should comfortably exceed expected per-item processing time.
	// Default: 5m.
	DeleteLeaseWindow time.Duration `config:"delete_lease_window"`
}

type StorageProvider string