vukem

type APIMiddlewareOptions struct {
	// SecureHeaders adjusts the SecureHeaders config after Vukem's defaults
	// are set, e.g. to add CSPSources or a ReportURI. The result is
	// validated at boot.
	SecureHeaders func(cfg *middleware.SecureHeadersConfig)
	// I18n configures the locale resolver installed when WithTranslations
	// was given. Nil resolves from the query and Accept-Language only (API
	// clients send no cookies or sessions). Validated at boot; needs
	// WithTranslations.
	I18n *i18n.MiddlewareConfig
}

type App struct {
	// Config is the core configuration.
	Config Config
	// Source gives access to every configuration value (for module configs).
	Source *config.Source
	// Key is the decoded APP_KEY; derive purpose-specific keys from it
	// (DeriveKey returns an error instead of panicking when it is unset).
	// It is zero only outside production when APP_KEY is unset.
	Key config.Key
	// Crypt encrypts with a key derived from APP_KEY and still decrypts
	// values sealed with APP_PREVIOUS_KEYS. DB() hands it to orm.Encrypted.
	// It is nil when Key is zero; its methods then fail with crypt.ErrNoKey.
	Crypt *crypt.Encrypter
	// Log is the application logger.
	Log *slog.Logger
	// Kind is the runtime kind (web, console, test).
	Kind Kind
	// Router holds the HTTP routes; /up is registered by default.
	Router *router.Router
	// Views renders templates when WithViews was given (nil otherwise).
	Views *view.Engine
	// Vite renders asset tags when WithVite was given (nil otherwise).
	Vite *vite.Vite
	// Inertia is the Inertia adapter when WithInertia was given (nil
	// otherwise).
	Inertia *inertia.Inertia
	// I18n holds the translations when WithTranslations was given (nil
	// otherwise); DefaultMiddleware then resolves the request locale.
	I18n *i18n.Bundle

	// Telegram is the Telegram log handler; use it for Contact and Send.
	// It is never nil: without TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID it
	// is disabled (Configured reports false, Send drops, SendSync returns
	// telegram.ErrDisabled).
	Telegram *telegram.Handler

	// Events is the application event bus (WithListeners registers listeners).
	Events *events.Bus

	// Devtools is the development dashboard when WithDevtools or
	// DEVTOOLS=true enabled it (nil otherwise).
	Devtools *devtools.Devtools
	// contains filtered or unexported fields
}

type AppSeeder interface {
	SeedApp(ctx context.Context, app *App) error
}

type AppSeederFunc func(ctx context.Context, app *App) error

type Booter interface {
	Boot(ctx context.Context, app *App) error
}

type BuildFunc func(opts ...Option) (*App, error)

type CacheConfig struct {
	// Store is "memory" (default) or "database" (table CACHE_TABLE).
	Store  string `env:"CACHE_STORE"  default:"memory"`
	Prefix string `env:"CACHE_PREFIX" default:"vukem:"`
	Table  string `env:"CACHE_TABLE"  default:"cache"`
	// MaxEntries bounds the memory store.
	MaxEntries int `env:"CACHE_MAX_ENTRIES" default:"10000"`
}

type Command interface {
	// Name is "namespace:action", e.g. "reports:send".
	Name() string
	// Description is shown by "list".
	Description() string
	// Flags defines flags on fs; it may be a no-op.
	Flags(fs *flag.FlagSet)
	// Run executes the command with the remaining positional args.
	Run(ctx context.Context, app *App, args []string) error
}

type CommandFunc struct {
	CommandName string
	Desc        string
	DefineFlags func(fs *flag.FlagSet)
	Fn          func(ctx context.Context, app *App, args []string) error
}

type Config struct {
	Name  string        `env:"APP_NAME"  default:"Vukem"`
	Env   config.Env    `env:"APP_ENV"   default:"development"`
	Debug bool          `env:"APP_DEBUG"`
	URL   string        `env:"APP_URL"   default:"http://localhost:3000"`
	Key   config.Secret `env:"APP_KEY"`
	// PreviousKeys are former APP_KEY values (comma-separated, same format)
	// that still open what they sealed or signed after a key rotation:
	// app.Crypt tokens (encrypted cookies and columns, queued mail), cookie
	// sessions, the maintenance bypass and, through DerivePreviousKeys,
	// signed URLs and social login state. New values always use APP_KEY.
	PreviousKeys    config.Secret `env:"APP_PREVIOUS_KEYS"`
	Host            string        `env:"HOST"              default:"localhost"`
	Port            int           `env:"PORT"              default:"3000"`
	ShutdownTimeout time.Duration `env:"SHUTDOWN_TIMEOUT"  default:"15s"`
	// H2C serves HTTP/2 without TLS (prior knowledge, for gRPC clients) in
	// production too, behind a proxy that speaks h2c. It is always on
	// outside production.
	H2C bool `env:"HTTP_H2C"`
	// MaxHeaderBytes caps the request line plus headers the HTTP server
	// reads (4096 to 1048576 bytes, Go's own default; outside is a boot
	// error). Larger requests get 431.
	MaxHeaderBytes int    `env:"HTTP_MAX_HEADER_BYTES" default:"65536"`
	LogLevel       string `env:"LOG_LEVEL"             default:"info"`
	LogFormat      string `env:"LOG_FORMAT"`
	// LogDedupWindow collapses repeated identical ERROR records of the
	// default logger into one summary per window (a Go duration; "0"
	// disables it). Empty means 1m in production and off elsewhere.
	LogDedupWindow string `env:"LOG_DEDUP_WINDOW"`
	// APIVersion is info.version of the OpenAPI document.
	APIVersion string `env:"API_VERSION" default:"1.0.0"`
	// OpenAPIPrefix keeps only routes under it in the document (e.g. /api).
	OpenAPIPrefix string `env:"OPENAPI_PREFIX"`
	// OpenAPIInProduction serves /openapi.json in production too.
	OpenAPIInProduction bool `env:"OPENAPI_IN_PRODUCTION"`
	// Devtools enables the /_vukem dashboard (refused in production).
	Devtools bool `env:"DEVTOOLS"`
	// DevtoolsInsecureAllowRemote serves the dashboard to non-loopback
	// clients (containers, remote VMs). Anyone who reaches the app then
	// sees its requests, queries, logs and mail.
	DevtoolsInsecureAllowRemote bool `env:"DEVTOOLS_INSECURE_ALLOW_REMOTE"`
	// TrustedProxies lists the proxies (comma-separated CIDRs or IPs) whose
	// X-Forwarded-For is honoured by c.IP(). Empty trusts nobody; an
	// invalid entry is a boot error.
	TrustedProxies string `env:"TRUSTED_PROXIES"`
	// TrustForwardedProto treats X-Forwarded-Proto: https from a trusted
	// proxy as HTTPS (HSTS). It requires TRUSTED_PROXIES.
	TrustForwardedProto bool `env:"TRUST_FORWARDED_PROTO"`
	// HSTSForce sends HSTS on every response in production, for TLS
	// proxies whose range cannot be put in TRUSTED_PROXIES. It requires an
	// https APP_URL in every environment but is applied only in production
	// (docs/security.md, A02).
	HSTSForce bool `env:"HSTS_FORCE"`
	// ClientIPHeader names a single-IP header set by the trusted proxy
	// (such as X-Real-IP) that c.IP() reads instead of X-Forwarded-For.
	// It requires TRUSTED_PROXIES.
	ClientIPHeader string `env:"CLIENT_IP_HEADER"`
	// RateLimitIPv6Prefix is the prefix length ratelimit.ByIP groups IPv6
	// clients by (1-128): one client usually owns a whole /64 and can
	// rotate addresses inside it. IPv4 keys stay per address.
	RateLimitIPv6Prefix int `env:"RATE_LIMIT_IPV6_PREFIX" default:"64"`
}

type DatabaseConfig struct {
	URL     string `env:"DATABASE_URL" default:"file:storage/database.sqlite"`
	MaxOpen int    `env:"DB_MAX_OPEN"  default:"10"`
	MaxIdle int    `env:"DB_MAX_IDLE"  default:"5"`
}

type FlagSeeder interface {
	SeedFlags(fs *flag.FlagSet)
}

type HTTPServer struct {
	Server *http.Server
	// ShutdownTimeout bounds the graceful drain of in-flight requests.
	ShutdownTimeout time.Duration
	// Listener, when set, is used instead of listening on Server.Addr.
	Listener net.Listener
	// Ready, when set, receives the bound address once listening.
	Ready chan<- string
}

type HealthCheck func(ctx context.Context) error

type Instrumentation struct {
	// Queries is notified of every statement run through DB() and its
	// transactions, after devtools and WithQueryObservers.
	Queries database.QueryObserver
	// Jobs is notified of every job step of Queue(), next to devtools.
	Jobs queue.Observer
	// Mail wraps the transport of Mailer(). Wrappers apply in registration
	// order around the devtools-wrapped transport, so the last one
	// registered is the outermost.
	Mail func(mail.Transport) mail.Transport
}

type Kind string

type KindFilter interface {
	Kinds() []Kind
}

type MailConfig struct {
	// Mailer is "smtp", "resend", "mailtrap", "log" or "array" (tests). Production
	// must choose explicitly; elsewhere it defaults to "log".
	Mailer string `env:"MAIL_MAILER"`
	From   string `env:"MAIL_FROM"   default:"Vukem <hello@example.com>"`

	SMTPHost     string        `env:"SMTP_HOST"     default:"localhost"`
	SMTPPort     int           `env:"SMTP_PORT"     default:"587"`
	SMTPUsername string        `env:"SMTP_USERNAME"`
	SMTPPassword config.Secret `env:"SMTP_PASSWORD"`
	// SMTPInsecure allows servers without STARTTLS (local catchers only).
	SMTPInsecure bool `env:"SMTP_INSECURE"`

	ResendAPIKey config.Secret `env:"RESEND_API_KEY"`

	MailtrapAPIToken config.Secret `env:"MAILTRAP_API_TOKEN"`
	// MailtrapInboxID > 0 sends to that Email Sandbox inbox instead of delivering.
	MailtrapInboxID int64 `env:"MAILTRAP_INBOX_ID"`
}

type MiddlewareOptions struct {
	// SecureHeaders adjusts the SecureHeaders config after Vukem's defaults
	// (the Vite dev server) are set, e.g. to add CSPSources or a ReportURI.
	// The result is validated at boot.
	SecureHeaders func(cfg *middleware.SecureHeadersConfig)
	// Stateless installs no session middleware (cookieless apps). CSRF
	// protection stays on as Origin/Sec-Fetch-Site checks only: there is no
	// session token, so csrfToken and csrfField render empty, and session
	// features (Flash, session auth) fail with an error.
	Stateless bool
	// SessionBypass lists ServeMux patterns served without sessions. As in
	// ServeMux, a pattern ending in "/" ("/webhooks/") covers its whole
	// subtree; "POST /hooks/{id}" matches one method and path. It cannot be
	// combined with Stateless.
	SessionBypass []string
	// CSRFBypass lists ServeMux patterns (same matching as SessionBypass)
	// exempt from CSRF checks, e.g. signed webhooks. Each bypass is logged
	// at boot.
	CSRFBypass []string
	// CSRFTokenFallback also requires the session's CSRF token (the
	// csrfField template function, or the X-CSRF-Token header) on unsafe
	// requests that carry the session cookie but neither Sec-Fetch-Site nor
	// Origin, i.e. browsers too old for CrossOriginProtection (see
	// csrf.Config.TokenFallback). It needs sessions: combined with
	// Stateless it is a boot error.
	CSRFTokenFallback bool
	// I18n configures the locale resolver installed when WithTranslations
	// was given (nil: i18n.MiddlewareConfig defaults), e.g. its sources and
	// their order, or the selectable locales. It is validated at boot and
	// needs WithTranslations.
	I18n *i18n.MiddlewareConfig
}

type OpenAPIOptions struct {
	// PathPrefix keeps only routes under it, e.g. "/api/v1" (default
	// Config.OpenAPIPrefix, OPENAPI_PREFIX).
	PathPrefix string
	// InProduction serves this document in production too. Set it for a
	// public API; OPENAPI_IN_PRODUCTION=true does the same for every
	// document and API reference page.
	InProduction bool
}

type Option func(*options) error

type Provider interface {
	Register(app *App) error
}

type ProviderFunc func(app *App) error

type QueueConfig struct {
	// Connection is "sync" (default: jobs run during Dispatch), "memory"
	// (in process, run by a worker inside serve) or "database".
	Connection string `env:"QUEUE_CONNECTION" default:"sync"`
	// Queues lists the queues workers poll, in priority order.
	Queues string `env:"QUEUE_NAMES" default:"default"`
	// Concurrency is the number of parallel workers.
	Concurrency int `env:"QUEUE_CONCURRENCY" default:"4"`
	// Table and FailedTable are the database driver's tables.
	Table       string `env:"QUEUE_TABLE"        default:"jobs"`
	FailedTable string `env:"QUEUE_FAILED_TABLE" default:"failed_jobs"`
	// InServe runs a queue worker inside serve for the database driver
	// and custom drivers (Redis). Set it to false when dedicated
	// queue:work processes run the jobs instead; leaving it on next to
	// them is safe (reservations are atomic), it only adds workers. The
	// memory queue is always worked inside serve: no other process sees
	// its jobs.
	InServe bool `env:"QUEUE_IN_SERVE" default:"true"`
	// AllowLegacyMail sends clear-text mail jobs queued before v0.24.0
	// (an upgrade window: drain the queue before upgrading, or set it
	// until the old jobs are gone). Off, they fail.
	AllowLegacyMail bool `env:"QUEUE_ALLOW_LEGACY_MAIL"`
}

type RateLimitConfig struct {
	// Store is "memory" (default: GCRA per process) or "cache" (fixed
	// windows counted in App.Cache, which must be shared by every server:
	// CACHE_STORE=database or a Redis store set with WithCacheStore).
	Store string `env:"RATE_LIMIT_STORE" default:"memory"`
}

type Runner interface {
	Run(ctx context.Context) error
}

type RunnerFunc func(ctx context.Context) error

type ScheduleConfig struct {
	// Timezone of the expressions (IANA name, default UTC).
	Timezone string `env:"SCHEDULE_TIMEZONE" default:"UTC"`
	// InServe runs the scheduler inside serve. Set it to false when a
	// dedicated schedule:work process (or a cron calling schedule:run)
	// runs the schedule instead.
	InServe bool `env:"SCHEDULE_IN_SERVE" default:"true"`
}

type Seeder interface {
	Seed(ctx context.Context, db *database.DB) error
}

type SeederFunc func(ctx context.Context, db *database.DB) error

type SessionConfig struct {
	// Driver is "cookie" (encrypted cookie, default) or "memory"; the
	// database driver is installed by the database provider.
	Driver      string        `env:"SESSION_DRIVER"       default:"cookie"`
	Lifetime    time.Duration `env:"SESSION_LIFETIME"     default:"24h"`
	IdleTimeout time.Duration `env:"SESSION_IDLE_TIMEOUT" default:"2h"`
	CookieName  string        `env:"SESSION_COOKIE"       default:"vukem_session"`
	// Secure defaults to true in production or when APP_URL is https.
	Secure string `env:"SESSION_SECURE" default:"auto"`
	// RecordClient keeps the user agent and client network with each
	// logged-in server-side session (session.Config.RecordClient).
	RecordClient bool `env:"SESSION_RECORD_CLIENT" default:"false"`
}

type Shutdowner interface {
	Shutdown(ctx context.Context, app *App) error
}

type TelegramConfig struct {
	BotToken config.Secret `env:"TELEGRAM_BOT_TOKEN"`
	ChatID   string        `env:"TELEGRAM_CHAT_ID"`
	// MinLevel is debug, info, warn or error (default error).
	MinLevel string `env:"TELEGRAM_MIN_LEVEL" default:"error"`
	ThreadID int    `env:"TELEGRAM_THREAD_ID"`
	// Log forwards log records at MinLevel and above to the chat (default
	// true); false keeps app.Telegram for explicit Send and Contact only.
	Log bool `env:"TELEGRAM_LOG" default:"true"`
	// RateLimit caps forwarded log records per minute (0: no cap).
	RateLimit int `env:"TELEGRAM_RATE_LIMIT"`
	// APIURL is the Bot API base URL, for a self-hosted Bot API server or
	// a fake in tests. It must be https outside development and test.
	APIURL string `env:"TELEGRAM_API_URL" default:"https://api.telegram.org"`
}