config

type APIConfig struct {
	Prefix string
	// DocsEnabled serves the FastAPI-style UI at /docs.
	// Default() (development) leaves this true. Changing Environment on a
	// Default() value does not flip it — use DefaultFor(env) or set this
	// field. LoadFromEnv uses DefaultDocsEnabled when GOMBIT_DOCS_ENABLED
	// is unset.
	DocsEnabled bool
}

type AuthConfig struct {
	// JWTSecret is the HMAC key for access tokens and, in cookie mode, the
	// CSRF double-submit token signature. It is never a VITE_* value.
	// Empty disables framework-owned auth routes outside production.
	JWTSecret string
	// AccessTokenTTL is the signed access-token lifetime.
	AccessTokenTTL time.Duration
	// RefreshTokenTTL is the refresh-token lifetime.
	RefreshTokenTTL time.Duration
	// BcryptCost is the bcrypt cost for password hashes. Zero means
	// bcrypt.DefaultCost. Tests may set a lower cost.
	BcryptCost int
	// Mode selects the mounted auth surface. Empty behaves as AuthModeJWT.
	Mode AuthMode
	// CookieSecure sets the Secure attribute on cookie-mode session and CSRF
	// cookies. Production requires true (Appendix C); development may set
	// false only for plain-HTTP localhost testing.
	CookieSecure bool
	// CookieSameSite sets the SameSite attribute on cookie-mode session and
	// CSRF cookies. Empty behaves as CookieSameSiteLax.
	CookieSameSite CookieSameSite
}

type AuthMode string

type CacheConfig struct {
	Driver    CacheDriver
	Namespace string
	Redis     RedisConfig
}

type CacheDriver string

type Config struct {
	AppName     string
	Environment Environment
	HTTP        HTTPConfig
	API         APIConfig
	Database    DatabaseConfig
	Cache       CacheConfig
	Jobs        JobsConfig
	Storage     StorageConfig
	Logging     LoggingConfig
	Auth        AuthConfig
	Security    SecurityConfig
}

type CookieSameSite string

type DatabaseConfig struct {
	Driver DatabaseDriver
	// Required declares whether the application needs a database to function —
	// the signal a deployment host uses to decide whether to provision one
	// (surfaced in the HOST-1 application contract). Defaults to true because a
	// Gombit app is database-backed by default; set it false for an app that
	// runs without one. It does not itself force a database at startup.
	Required        bool
	DSN             string
	MaxOpenConns    int
	MaxIdleConns    int
	ConnMaxLifetime time.Duration
}

type DatabaseDriver string

type EnvLookup func(key string) (value string, ok bool)

type Environment string

type FieldError struct {
	Field   string
	Env     string
	Value   string
	Message string
}

type FieldErrors []FieldError

type HTTPConfig struct {
	Addr           string
	TrustedProxies []string
	// RequestTimeout is the per-handler deadline propagated into the request
	// context (and thus into DB/cache calls that honor it). It is opt-in: the
	// default is 0, which imposes no deadline (issue #270 / PERF-12). The
	// deadline is applied inside the request_context middleware, which always
	// runs; when this is 0 only the deadline setup is skipped, and that skip is
	// a true no-op (no timer, no extra context) so it costs nothing on the
	// request path. The http.Server read/write/idle timeouts remain the
	// connection-level safety net regardless. Scaffolded apps set
	// GOMBIT_HTTP_REQUEST_TIMEOUT explicitly so new projects keep a per-handler
	// deadline. A negative value is rejected by Validate.
	RequestTimeout time.Duration
}

type JobsConfig struct {
	Driver JobsDriver
	// Queue is the default queue name.
	Queue string
	// Namespace prefixes every Redis key, so apps and environments sharing a
	// Redis server do not share queues.
	Namespace string
}

type JobsDriver string

type LocalStorageConfig struct {
	// Root is the directory objects are stored under; a relative path is
	// resolved against the working directory when the app starts. It is
	// created on the first write.
	Root string
	// URL is where the application serves stored objects' URLs, for the
	// local and memory drivers: a path ("/_storage", the default) or an
	// absolute URL ending in one. Empty: those drivers have no URLs.
	URL string
}

type LogLevel string

type LogSink string

type LoggingConfig struct {
	Level LogLevel
	Sink  LogSink
}

type RedisConfig struct {
	Addr         string
	Username     string
	Password     string
	DB           int
	DialTimeout  time.Duration
	ReadTimeout  time.Duration
	WriteTimeout time.Duration
	TLS          bool
	TLSInsecure  bool
}

type S3StorageConfig struct {
	// Endpoint is the service's base URL ("https://<account>.r2.cloudflarestorage.com",
	// "http://127.0.0.1:9000" for a local MinIO). Empty means AWS S3.
	Endpoint string
	// Region signs requests. Default us-east-1.
	Region string
	// Bucket holds the objects. Required.
	Bucket string
	// Prefix, when set, is put before every key ("myapp/"), so several apps
	// or environments can share a bucket.
	Prefix string
	// AccessKeyID and SecretAccessKey are static credentials. Leave both
	// empty to use the AWS default credential chain (environment, shared
	// config, an IAM role on EC2/ECS/Fargate).
	AccessKeyID     string
	SecretAccessKey string
	// ForcePathStyle addresses the bucket in the path
	// (endpoint/bucket/key) rather than the host (bucket.endpoint/key), as
	// MinIO and many S3-compatible services need.
	ForcePathStyle bool
	// PublicURL is the base URL public objects are read from, standing for
	// the bucket's root (a CDN, a custom domain, or the bucket's address).
	// Empty: public objects have no URL (signed URLs still work).
	PublicURL string
}

type SecurityConfig struct {
	// SanitizeInput installs the request-input HTML sanitizer (issue #271 /
	// PERF-13). It is off by default: the framework does not rewrite request
	// input. XSS is an output-encoding concern — the generated React frontend
	// escapes text (JSX), the framework admin SPA renders values as React text
	// (not HTML), a JSON API response is not an HTML sink, and the response CSP
	// is a backstop — and stripping markup on ingress corrupts faithful values
	// (a comment of `x < y`, a stored `<b>bold</b>`) as well as costing
	// allocations on every write request.
	// Enable it (GOMBIT_SECURITY_SANITIZE_INPUT=true) to restore the legacy
	// behavior: JSON string values and query values are stripped to plain text
	// before handlers run, with WithRawBodyPaths still exempting webhook paths.
	// For field-level stripping without turning the whole pipeline back on,
	// call framework.SanitizeHTML from a handler instead.
	SanitizeInput bool
}

type StorageConfig struct {
	Driver StorageDriver
	// PublicPrefix makes the objects whose keys start with it public: they
	// have permanent URLs (storage.PublicURL). Empty makes none public.
	// Default "public/".
	PublicPrefix string
	// URLSecret signs the local and memory drivers' URLs (HMAC-SHA256), at
	// least 32 bytes. Empty derives one from Auth.JWTSecret; with neither,
	// those drivers have no URLs.
	URLSecret string
	Local     LocalStorageConfig
	S3        S3StorageConfig
}

type StorageDriver string