runtime

type APIKeyPrefillDef struct {
	// Name is the header/query/cookie name.
	Name string `json:"name"`
	// In selects where the key travels: header | query | cookie.
	In string `json:"in" config:",default=header"`
	// Token is the pre-filled key value (use ${VAR} for secrets).
	Token string `json:"token" config:",optional"`
}

type AsyncCallbackConf struct {
	// URL is the webhook endpoint called on job completion (required).
	URL string `json:"url" config:",optional"`
	// Secret is the HMAC key for signing the callback payload.
	Secret string `json:"secret" config:",optional"`
	// Retry is the number of retry attempts if the callback fails.
	Retry int `json:"retry" config:",optional"`
	// RetryDelay is the delay between retry attempts.
	RetryDelay string `json:"retry_delay" config:",optional"`
}

type AsyncHandler func(body []byte, job *JobState) error

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

type AsyncReassignConf struct {
	// Enabled enables the background reaper goroutine.
	Enabled bool `json:"enabled" config:",optional"`
	// ProcessingTimeout is how long a job can stay in "processing" before being reaped.
	// Default: 5m
	ProcessingTimeout string `json:"processing_timeout" config:",optional"`
	// ReapInterval is how often the reaper checks for stale jobs.
	// Default: 30s
	ReapInterval string `json:"reap_interval" config:",optional"`
	// MaxRetries is the maximum number of times a job can be retried before moving to "failed".
	// Default: 3
	MaxRetries int `json:"max_retries" config:",optional"`
}

type AsyncStoreConf struct {
	// Driver selects the backend: "memory" (default), "postgres", "redis", "nats_kv".
	Driver string `json:"driver" config:",optional"`
	// DB references a database name for driver: postgres.
	DB string `json:"db" config:",optional"`
	// KV references a kv store name for driver: redis.
	KV string `json:"kv" config:",optional"`
	// Stream references a stream name for driver: nats_kv.
	Stream string `json:"stream" config:",optional"`
	// Bucket is the NATS KV bucket name (driver: nats_kv).
	Bucket string `json:"bucket" config:",optional"`
	// Table is the PostgreSQL table name (driver: postgres).
	Table string `json:"table" config:",optional"`

	// Reassign configures automatic recovery of stuck jobs (reaper).
	Reassign *AsyncReassignConf `json:"reassign" config:",optional"`
	// Callback configures a webhook to notify on job completion.
	Callback *AsyncCallbackConf `json:"callback" config:",optional"`
	// ResultTTL is how long completed/failed jobs are kept before cleanup.
	// Default: 0 (keep forever)
	ResultTTL string `json:"result_ttl" config:",optional"`
	// MaxConcurrent limits the number of jobs processed simultaneously.
	// Default: 0 (unlimited)
	MaxConcurrent int `json:"max_concurrent" config:",optional"`
}

type AuthConfig struct {
	// Enabled is a constant.
	Enabled bool `json:"enabled" config:",optional"`
	// Driver is a constant.
	Driver string `json:"driver" config:",default=none"` // none | manual | openfga-zitadel | ory
	// Secret is a constant.
	Secret string `json:"secret" config:",optional"`
	// PrevSecret is a constant.
	PrevSecret string `json:"prev_secret" config:",optional"`
	// Algorithm is a constant.
	Algorithm string `json:"algorithm" config:",default=HS256"`
	// JWKSURL enables RS256 validation against a remote JWKS endpoint
	// (e.g. an OAuth server's /.well-known/jwks.json) with kid-based rotation.
	JWKSURL string `json:"jwks_url" config:",optional"`
	// ContextKey is a constant.
	ContextKey string `json:"context_key" config:",default=claims"`
	// Issuer is a constant.
	Issuer string `json:"issuer" config:",optional"`
	// Audience is a constant.
	Audience string `json:"audience" config:",optional"`
	// Expiry is a constant.
	Expiry int `json:"expiry" config:",default=900"` // JWT TTL in seconds (default 15 min)
	// ZitadelURL is a constant.
	ZitadelURL string `json:"zitadel_url" config:",optional"`
	// OpenFGAURL is a constant.
	OpenFGAURL string `json:"openfga_url" config:",optional"`
	// OpenFGAStore is a constant.
	OpenFGAStore string `json:"openfga_store" config:",optional"`
	// KratosURL is a constant.
	KratosURL string `json:"kratos_url" config:",optional"`
	// KetoURL is a constant.
	KetoURL string `json:"keto_url" config:",optional"`
	// Refresh is a constant.
	Refresh *RefreshConfig `json:"refresh" config:",optional"`
	// Cookie is a constant.
	Cookie *AuthCookieConfig `json:"cookie" config:",optional"`
}

type AuthCookieConfig struct {
	// AccessTokenName is a constant.
	AccessTokenName string `json:"access_token_name" config:",default=token"`
	// RefreshTokenName is a constant.
	RefreshTokenName string `json:"refresh_token_name" config:",default=refresh_token"`
	// Domain is a constant.
	Domain string `json:"domain" config:",optional"`
	// Path is a constant.
	Path string `json:"path" config:",default=/"`
	// HTTPOnly is a constant.
	HTTPOnly bool `json:"http_only" config:",default=true"`
	// Secure is a constant.
	Secure bool `json:"secure" config:",default=true"`
	// SameSite is a constant.
	SameSite string `json:"same_site" config:",default=Strict"`
}

type AuthPrefillDef struct {
	// PreferredScheme names the security scheme selected by default.
	PreferredScheme string `json:"preferred_scheme" config:",optional"`
	// BearerToken prefills the HTTP bearer token.
	BearerToken string `json:"bearer_token" config:",optional"`
	// APIKey prefills an API key credential.
	APIKey *APIKeyPrefillDef `json:"api_key" config:",optional"`
}

type AutocertTLS struct {
	// Domains is a constant.
	Domains []string `json:"domains"`
	// Email is a constant.
	Email string `json:"email"`
	// CacheDir is a constant.
	CacheDir string `json:"cache_dir" config:",optional"`
}

type CORSConf struct {
	// Origins is a constant.
	Origins []string `json:"origins" config:",optional"`
	// Methods is a constant.
	Methods []string `json:"methods" config:",optional"`
	// Headers is a constant.
	Headers []string `json:"headers" config:",optional"`
	// Credentials is a constant.
	Credentials bool `json:"credentials" config:",optional"`
	// MaxAge is a constant.
	MaxAge int `json:"max_age" config:",default=300"`
	// ExposeHeaders is a constant.
	ExposeHeaders []string `json:"expose_headers" config:",optional"`
	// AllowPrivateNetwork is a constant.
	AllowPrivateNetwork bool `json:"allow_private_network" config:",optional"`
}

type CORSGroupConf struct {
	// Name is the unique group name referenced by entry[].cors or middleware cors:<name>.
	Name string `json:"name"`
	// Origins is a constant.
	Origins []string `json:"origins" config:",optional"`
	// Methods is a constant.
	Methods []string `json:"methods" config:",optional"`
	// Headers is a constant.
	Headers []string `json:"headers" config:",optional"`
	// Credentials is a constant.
	Credentials bool `json:"credentials" config:",optional"`
	// MaxAge is a constant.
	MaxAge int `json:"max_age" config:",default=300"`
	// ExposeHeaders is a constant.
	ExposeHeaders []string `json:"expose_headers" config:",optional"`
	// AllowPrivateNetwork is a constant.
	AllowPrivateNetwork bool `json:"allow_private_network" config:",optional"`
}

type CRUDFactory func() CRUDProvider

type CRUDOverrides struct {
	// List is a constant.
	List string `json:"list" config:",optional"`
	// Get is a constant.
	Get string `json:"get" config:",optional"`
	// Create is a constant.
	Create string `json:"create" config:",optional"`
	// Update is a constant.
	Update string `json:"update" config:",optional"`
	// Delete is a constant.
	Delete string `json:"delete" config:",optional"`
}

type CRUDProvider interface {
	List(ctx fiber.Ctx, params ListParams) error
	Get(ctx fiber.Ctx, id string) error
	Create(ctx fiber.Ctx, body []byte) error
	Update(ctx fiber.Ctx, id string, body []byte) error
	Delete(ctx fiber.Ctx, id string) error
}

type CSPConf struct {
	// Level is a constant.
	Level string `json:"level" config:",default=basic"`
	// DefaultSrc is a constant.
	DefaultSrc []string `json:"default_src" config:",optional"`
	// ScriptSrc is a constant.
	ScriptSrc []string `json:"script_src" config:",optional"`
	// StyleSrc is a constant.
	StyleSrc []string `json:"style_src" config:",optional"`
	// ImgSrc is a constant.
	ImgSrc []string `json:"img_src" config:",optional"`
	// ConnectSrc is a constant.
	ConnectSrc []string `json:"connect_src" config:",optional"`
	// FontSrc is a constant.
	FontSrc []string `json:"font_src" config:",optional"`
	// FrameSrc is a constant.
	FrameSrc []string `json:"frame_src" config:",optional"`
	// FrameAncestors is a constant.
	FrameAncestors []string `json:"frame_ancestors" config:",optional"`
	// ObjectSrc is a constant.
	ObjectSrc []string `json:"object_src" config:",optional"`
	// BaseURI is a constant.
	BaseURI []string `json:"base_uri" config:",optional"`
	// FormAction is a constant.
	FormAction []string `json:"form_action" config:",optional"`
	// UpgradeInsecureReq is a constant.
	UpgradeInsecureReq bool `json:"upgrade_insecure_requests" config:",optional"`
}

type CSPGroupConf struct {
	// Name is the unique group name referenced by entry[].csp or middleware csp:<name>.
	Name string `json:"name"`
	// CSPConfig is the per-route CSP policy (same shape as security_headers.csp_config).
	CSPConfig *CSPConf `json:"csp_config" config:",optional"`
}

type CSRFConf struct {
	// Enabled is a constant.
	Enabled bool `json:"enabled" config:",optional"`
	// CookieName is a constant.
	CookieName string `json:"cookie_name" config:",optional"`
	// HeaderName is a constant.
	HeaderName string `json:"header_name" config:",optional"`
	// SameSite is a constant.
	SameSite string `json:"same_site" config:",optional"`
	// Secure is a constant.
	Secure bool `json:"secure" config:",optional"`
	// ExcludePaths is a constant.
	ExcludePaths []string `json:"exclude_paths" config:",optional"`
	// JSONCheck is a constant.
	JSONCheck bool `json:"json_check" config:",optional"`
}

type CacheConfig struct {
	// L1 is a constant.
	L1 string `json:"l1" config:",default=ram"` // ram | none
	// L1TTL is a constant.
	L1TTL string `json:"l1_ttl" config:",default=5m"`
	// L1Size is a constant.
	L1Size int `json:"l1_size" config:",default=10000"`
	// L2 is a constant.
	L2 string `json:"l2" config:",optional"` // disk | none
	// L2Path is a constant.
	L2Path string `json:"l2_path" config:",optional"`
}

type ClientConnInterface = grpc.ClientConnInterface

type ContentSecurityDef struct {
	// Enabled is a constant.
	Enabled bool `json:"enabled" config:",optional"`
	// Strict is a constant.
	Strict bool `json:"strict" config:",optional"`
	// PublicKey is a constant.
	PublicKey string `json:"public_key"`
}

type Cookie struct {
	Name     string
	Value    string
	Path     string
	Domain   string
	MaxAge   int
	HTTPOnly bool
	Secure   bool
	SameSite string
}

type CookieConf struct {
	// SameSite is a constant.
	SameSite string `json:"same_site" config:",optional"` // Strict, Lax, None
	// Secure is a constant.
	Secure bool `json:"secure" config:",optional"`
}

type CorrelationConf struct {
	// Enabled enables the correlation ID middleware.
	Enabled bool `json:"enabled" config:",optional"`
	// RequestHeader is the header to read the correlation ID from.
	RequestHeader string `json:"request_header" config:",default=X-Correlation-ID"`
	// ResponseHeader is the header to set the correlation ID on.
	ResponseHeader string `json:"response_header" config:",default=X-Correlation-ID"`
	// SkipPaths are request paths that should not receive a correlation ID.
	SkipPaths []string `json:"skip_paths" config:",optional"`
}

type CronJob struct {
	// Name is a constant.
	Name string `json:"name"`
	// Schedule is a constant.
	Schedule string `json:"schedule"`
	// Mode is a constant.
	Mode string `json:"mode" config:",default=nats"` // nats, handler, internal
	// Publish is a constant.
	Publish *CronPublish `json:"publish" config:",optional"`
	// Handler is a constant.
	Handler string `json:"handler" config:",optional"`
}

type CronJobFunc func(ctx context.Context) error

type CronPublish struct {
	// Stream is a constant.
	Stream string `json:"stream"`
	// Subject is a constant.
	Subject string `json:"subject" config:",optional"`
}

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

type CryptionDef struct {
	// Enabled is a constant.
	Enabled bool `json:"enabled" config:",optional"`
	// Key is a constant.
	Key string `json:"key"`
}

type DBConfig struct {
	// Name is a constant.
	Name string `json:"name"`
	// Driver is a constant.
	Driver string `json:"driver" config:",default=postgres"`
	// URL is a constant.
	URL string `json:"url"`
	// AuthToken is the auth token for remote Turso/libSQL drivers
	// (turso-serverless, libsql, go-libsql sync). Supports ${VAR} from env.
	AuthToken string `json:"auth_token" config:",optional"`
	// ReadURL is the read replica connection URL for read/write splitting.
	ReadURL string `json:"read_url" config:",optional"`
	// Database is a constant.
	Database string `json:"database" config:",optional"`
	// Pool is a constant.
	Pool *PoolConf `json:"pool" config:",optional"`
	// Turso is a constant.
	Turso *TursoConf `json:"turso" config:",optional"`
	// SlowQuery is a constant.
	SlowQuery *SlowQueryConf `json:"slow_query" config:",optional"`
}

type DefaultExitHooks struct{}

type DefaultHooks[T any] struct{}

type DeployConfig struct {
	// Target is a constant.
	Target string `json:"target" config:",default=auto"`
}

type DocsHooks struct {
	// Mutators run in registration order on the generated spec.
	Mutators []SpecMutator
	// ScalarOptions are appended to the options built from the YAML config.
	ScalarOptions []scalargo.Option
}

type EncryptCookieDef struct {
	// Enabled is a constant.
	Enabled bool `json:"enabled" config:",optional"`
	// Key is a constant.
	Key string `json:"key"` // required when enabled
	// Except is a constant.
	Except []string `json:"except" config:",optional"` // cookie names to skip
}

type EntryDef struct {
	// Type is a constant.
	Type string `json:"type"` // crud, rest, webhook, websocket, sse, file
	// Method is a constant.
	Method string `json:"method" config:",optional"`
	// Path is a constant.
	Path string `json:"path" config:",optional"`
	// Handler is a constant.
	Handler string `json:"handler" config:",optional"`
	// Summary documents the operation in the OpenAPI spec (one line).
	Summary string `json:"summary" config:",optional"`
	// Description documents the operation in the OpenAPI spec (long form).
	Description string `json:"description" config:",optional"`
	// AuthModes is a constant.
	AuthModes []string `json:"auth_modes" config:",optional"` // ["jwt"], ["apikey"], ["jwt","apikey"]
	// JWTFrom is a constant.
	JWTFrom string `json:"jwt_from" config:",optional"` // per-entry: "header:Authorization", "cookie:token", "query:token"
	// Roles is a constant.
	Roles []string `json:"roles" config:",optional"`
	// Permissions is a constant.
	Permissions []string `json:"permissions" config:",optional"`
	// DB is a constant.
	DB string `json:"db" config:",optional"` // references database name
	// CORS references a named cors_groups[].name policy for this entry.
	// Empty means the server-level CORS (or none) applies.
	CORS string `json:"cors" config:",optional"`
	// CSP references a named csp_groups[].name policy for this entry.
	// Empty means the global security_headers CSP applies.
	CSP string `json:"csp" config:",optional"`
	// TenantScope is a constant.
	TenantScope string `json:"tenant_scope" config:",optional"` // JWT claim for tenant ID (e.g. "org_id")
	// TenantField is a constant.
	TenantField string `json:"tenant_field" config:",optional"` // DB column for tenant filter (e.g. "tenant_id")

	// ServiceName is the gRPC service name (required for type: grpc).
	ServiceName string `json:"service_name" config:",optional"`

	// CRUD
	Model string `json:"model" config:",optional"`
	// Table is a constant.
	Table string `json:"table" config:",optional"`
	// Resource is a constant.
	Resource string `json:"resource" config:",optional"`
	// Overrides is a constant.
	Overrides *CRUDOverrides `json:"overrides" config:",optional"`

	// Event stream selection
	EventStream string `json:"event_stream" config:",optional"`

	// Event publish targets
	EventPublish []EventPublishTarget `json:"event_publish" config:",optional"`

	// File
	AllowedTypes []string `json:"allowed_types" config:",optional"`
	// MaxSize is a constant.
	MaxSize string `json:"max_size" config:",optional"`
	// MaxFiles is a constant.
	MaxFiles int `json:"max_files" config:",optional"`
	// MagicBytes is a constant.
	MagicBytes bool `json:"magic_bytes" config:",optional"`
	// Storage is a constant.
	Storage *StorageDef `json:"storage" config:",optional"`

	// Security per-entry overrides
	CSRF *bool `json:"csrf" config:",optional"` // false = skip CSRF for this entry
	// RequiresMFA is a constant.
	RequiresMFA bool `json:"requires_mfa" config:",optional"` // true = MFA must be verified
	// RateLimit is a constant.
	RateLimit *RateLimitDef `json:"rate_limit" config:",optional"` // per-entry rate limit (pre-auth)
	// RateLimitPerUser is a constant.
	RateLimitPerUser *RateLimitDef `json:"rate_limit_per_user" config:",optional"` // per-entry per-user rate limit (post-auth)
	// RateLimitPerKey is a constant.
	RateLimitPerKey *RateLimitDef `json:"rate_limit_per_key" config:",optional"` // per-entry per-key rate limit (post-auth)
	// PerRoleLimits is a constant.
	PerRoleLimits map[string]*RateLimitDef `json:"rate_limit_per_role" config:",optional"` // per-role rate limits
	// Cache is a constant.
	Cache string `json:"cache" config:",optional"` // references kv[].name for CRUD cache

	// Validation
	ValidationModel string `json:"validate" config:",optional"` // validation model name

	// APIVersion sets the API version prefix for this entry (e.g. "v1", "v2").
	// If empty and the server api_prefix does not already contain a version,
	// defaults to "v1".
	APIVersion string `json:"api_version" config:",optional"`

	// APIStatus indicates the lifecycle status of this endpoint.
	// Values: current | deprecated | removed
	APIStatus string `json:"api_status" config:",optional"`
	// SunsetDate is the RFC3339 date when the endpoint will be removed.
	SunsetDate string `json:"sunset_date" config:",optional"`

	// Timeout per-entry (e.g. "30s")
	Timeout string `json:"timeout" config:",optional"`

	// Retry configures the retry behavior for idempotent methods (GET, HEAD, PUT, DELETE, OPTIONS).
	Retry *RetryConf `json:"retry" config:",optional"`
	// Fallback sets the fallback strategy when the circuit breaker is open.
	// Values: "degraded" | "stale" | "" (disabled)
	Fallback string `json:"fallback" config:",optional"`
	// Bulkhead defines named concurrency limits for external outbound calls.
	// Each key is a dependency name, value is max concurrent calls.
	Bulkhead map[string]int `json:"bulkhead" config:",optional"`

	// API Key prefix (only applies when auth_modes includes "apikey")
	APIPrefix string `json:"api_key_prefix" config:",optional"`

	// Pagination (CRUD only)
	PageSize int `json:"page_size" config:",optional"` // default 10, also min
	// MaxPageSize is a constant.
	MaxPageSize int `json:"max_page_size" config:",optional"` // default 100, also max
	// Pagination is a constant.
	Pagination string `json:"pagination" config:",optional"` // "offset" | "keyset"
	// Sortable is a constant.
	Sortable []string `json:"sortable" config:",optional"` // allowed sort columns

	// AsyncStore configures the job store backend for type: async entries.
	AsyncStore *AsyncStoreConf `json:"async_store" config:",optional"`
}

type EntryHandlers struct {
	Rest      map[string]func(fiber.Ctx) error
	WS        map[string]WSHandler
	SSE       map[string]SSEHandler
	CRUD      map[string]CRUDProvider
	Storage   map[string]server.StorageBackend
	Async     map[string]AsyncHandler
	Transform map[string]any
	Reapers   []*Reaper
}

type EntryHooks[T any] interface {
	BeforeCreate(ctx context.Context, req T) (T, error)
	AfterCreate(ctx context.Context, entity *T) error
	BeforeUpdate(ctx context.Context, id string, patch map[string]any) (map[string]any, error)
	AfterUpdate(ctx context.Context, entity *T) error
	BeforeDelete(ctx context.Context, id string) error
	AfterDelete(ctx context.Context, id string) error
	BeforeTransform(ctx context.Context, req T) (T, error)
	AfterTransform(ctx context.Context, result any) error
}

type EventPublishTarget struct {
	// Stream is a constant.
	Stream string `json:"stream"`
	// Subject is a constant.
	Subject string `json:"subject" config:",optional"`
	// EventStream is a constant.
	EventStream string `json:"event_stream" config:",optional"` // broker name; empty = all brokers
}

type EventStreamConnConf struct {
	// Name is a constant.
	Name string `json:"name"`
	// Driver is a constant.
	Driver string `json:"driver"` // nats, kafka
	// URL is a constant.
	URL string `json:"url" config:",optional"`
	// Brokers is a constant.
	Brokers []string `json:"brokers" config:",optional"`
	// ConsumerGroup is a constant.
	ConsumerGroup string `json:"consumer_group" config:",optional"`
	// MaxReconnects is a constant.
	MaxReconnects int `json:"max_reconnects" config:",optional"`
	// ReconnectWait is a constant.
	ReconnectWait string `json:"reconnect_wait" config:",optional"`
	// Timeout is a constant.
	Timeout string `json:"timeout" config:",optional"`
	// RetryOnFail is a constant.
	RetryOnFail bool `json:"retry_on_fail" config:",optional"`
	// Streams is a constant.
	Streams []StreamDef `json:"streams" config:",optional"`
}

type ExitHandler func(ctx context.Context, msg []byte) ([]byte, error)

type ExitHooks interface {
	OnMessage(ctx context.Context, msg []byte) ([]byte, error)
	OnSuccess(ctx context.Context)
	OnError(ctx context.Context, err error)
}

type ExitWorker struct {
	// Name is a constant.
	Name string `json:"name"`
	// Subscribe is a constant.
	Subscribe SubscribeDef `json:"subscribe"`
	// Handler is a constant.
	Handler string `json:"handler"`
	// MaxConcurrent is a constant.
	MaxConcurrent int `json:"max_concurrent" config:",default=1"`
	// DB is a constant.
	DB string `json:"db" config:",optional"`
	// Reply is a constant.
	Reply bool `json:"reply" config:",optional"`
	// ReplyTimeout is a constant.
	ReplyTimeout string `json:"reply_timeout" config:",default=30s"`
	// PullBatch is a constant.
	PullBatch int `json:"pull_batch" config:",optional"`
	// PullMaxWait is a constant.
	PullMaxWait string `json:"pull_max_wait" config:",optional"`
	// ConsumerMode is a constant.
	ConsumerMode string `json:"consumer_mode" config:",optional"` // push or pull
	// EventStream is a constant.
	EventStream string `json:"event_stream" config:",optional"` // broker name
	// TermOnFailure terminates (DLQ) instead of Nak when handler returns error.
	TermOnFailure bool `json:"term_on_failure" config:",optional"`
}

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

type FlashMessage struct {
	Key   string
	Value string
	Level uint8
}

type GCConfig struct {
	// GOGC sets the GC target percentage. Default 100. Higher = less GC, more memory.
	// Set to 200 for higher throughput at the cost of ~2x memory.
	GOGC int `json:"go_gc" config:",default=100"`
	// MemoryLimit sets GOMEMLIMIT. Can be a percentage of container memory (e.g. "80%")
	// or an absolute value (e.g. "2GiB", "512MiB"). Empty means no limit.
	MemoryLimit string `json:"memory_limit" config:",optional"`
}

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

type GrpcClientConf struct {
	// Name is a unique name for this client connection.
	Name string `json:"name"`
	// Target is the gRPC target address (e.g. "dns:///product-svc:8081").
	Target string `json:"target" config:",optional"`
	// Secure enables TLS transport credentials instead of insecure.
	Secure bool `json:"secure" config:",optional"`
	// Endpoints are direct gRPC endpoints (e.g. ["localhost:8081"]).
	Endpoints []string `json:"endpoints" config:",optional"`
	// Timeout is the default RPC timeout in milliseconds.
	Timeout int64 `json:"timeout" config:",default=2000"`
	// NonBlock enables non-blocking dial.
	NonBlock bool `json:"non_block" config:",default=true"`
}

type GrpcInterceptorsConfig struct {
	Trace      bool
	Breaker    bool
	Timeout    bool
	Shedding   bool
	Prometheus bool
}

type GrpcRegisterFn func(server *grpc.Server)

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

type GrpcServerConf struct {
	// ListenOn is the address to listen on (e.g. ":8081").
	ListenOn string `json:"listen_on" config:",optional"`
	// Timeout is the default RPC timeout in milliseconds.
	Timeout int64 `json:"timeout" config:",default=2000"`
	// CpuThreshold is the CPU load threshold for adaptive shedding (0-1000). 0 disables.
	CpuThreshold int64 `json:"cpu_threshold" config:",default=900"`
	// Health enables the gRPC health check service.
	Health bool `json:"health" config:",default=true"`
	// EtcdEndpoints are the etcd cluster hosts for service registration (micro mode).
	EtcdEndpoints []string `json:"etcd_endpoints" config:",optional"`
	// EtcdKey is the service key to register in etcd (e.g. "user-svc").
	EtcdKey string `json:"etcd_key" config:",optional"`
}

type HTTPClientDef struct {
	// Target is the language/platform key (e.g. "node", "php", "python").
	Target string `json:"target" config:",optional"`
	// Client is the client library key (e.g. "undici", "guzzle", "requests").
	Client string `json:"client" config:",optional"`
}

type JobState struct {
	ID                 string     `json:"id"`
	Status             JobStatus  `json:"status"`
	Result             any        `json:"result,omitempty"`
	Error              string     `json:"error,omitempty"`
	CreatedAt          time.Time  `json:"created_at"`
	UpdatedAt          time.Time  `json:"updated_at"`
	RetryCount         int        `json:"retry_count,omitempty"`
	MaxRetries         int        `json:"max_retries,omitempty"`
	ProcessingDeadline *time.Time `json:"processing_deadline,omitempty"`
	CallbackURL        string     `json:"callback_url,omitempty"`
}

type JobStatus string

type JobStore interface {
	Create(id string) *JobState
	Get(id string) (*JobState, bool)
	// Snapshot returns a defensive copy of a job state, safe to serialize
	// outside the store lock (HTTP handlers). Mutating it does not persist.
	Snapshot(id string) (*JobState, bool)
	Update(id string, status JobStatus, result any, errMsg string)
	Delete(id string)
	// List returns all jobs (best-effort, limited).
	List() ([]*JobState, error)
	// ReapStale resets jobs stuck in "processing" for longer than the deadline.
	// Returns the number of jobs reaped.
	ReapStale(ctx context.Context, timeout time.Duration, maxRetries int) (int, error)
	// Cleanup removes completed and failed jobs older than ttl.
	// Returns the number of jobs cleaned.
	Cleanup(ctx context.Context, ttl time.Duration) (int, error)
}

type KVConfig struct {
	// Name is a constant.
	Name string `json:"name"`
	// Driver is a constant.
	Driver string `json:"driver" config:",default=redis"`
	// URL is a constant.
	URL string `json:"url"`
	// PoolSize is the redis connection pool size. 0 uses the go-redis default (10 * GOMAXPROCS).
	PoolSize int `json:"pool_size" config:",optional"`
}

type KeysetResponse struct {
	Data       any    `json:"data"`
	NextCursor string `json:"nextCursor,omitempty"`
	PageSize   int    `json:"pageSize"`
}

type ListParams struct {
	Page       int
	Size       int
	Sort       string
	Filters    map[string]string
	Cursor     string   // keyset pagination cursor
	Pagination string   // "offset" | "keyset"
	Fields     []string // column subset for egress optimization (empty = all)
}

type ManualTLS struct {
	// CertFile is a constant.
	CertFile string `json:"cert_file"`
	// KeyFile is a constant.
	KeyFile string `json:"key_file"`
}

type Map = map[string]any

type OldInputData struct {
	Key   string
	Value string
}

type OpenAPIConf struct {
	// Enabled is a constant.
	Enabled bool `json:"enabled" config:",optional"`
	// Version is a constant.
	Version string `json:"version" config:",default=1.0.0"`
	// SpecPath is a constant.
	SpecPath string `json:"spec_path" config:",default=/openapi.json"`
	// DocsPath is a constant.
	DocsPath string `json:"docs_path" config:",default=/docs"`
	// Theme is a constant.
	Theme string `json:"theme" config:",default=moon"`
	// DarkMode is a constant.
	DarkMode bool `json:"dark_mode" config:",default=true"`
	// SpecCacheTTL sets Cache-Control max-age for /openapi.json
	SpecCacheTTL string `json:"spec_cache_ttl" config:",default=1h"`
	// FaviconURL sets a custom favicon for the docs page. It accepts:
	//   "" (empty)      → inline SVG magnifying glass
	//   "path/to/x.svg" → file on disk (relative to working dir, read once)
	//   "https://..."   → remote URL, downloaded server-side with TTL cache
	FaviconURL string `json:"favicon_url" config:",optional"`
	// FaviconRefresh is the cache TTL for remote favicons (e.g. "24h").
	// Defaults to 24h. Only used when favicon_url is an http(s) URL.
	FaviconRefresh string `json:"favicon_refresh" config:",default=24h"`
	// Title overrides the docs page title (defaults to the service name).
	Title string `json:"title" config:",optional"`
	// Description sets info.description in the generated spec and the docs page.
	Description string `json:"description" config:",optional"`
	// Layout selects the Scalar layout: "modern" or "classic" (default modern).
	Layout string `json:"layout" config:",optional"`
	// ForceDarkMode locks the docs UI to dark mode regardless of system theme.
	ForceDarkMode bool `json:"force_dark_mode" config:",optional"`
	// HideDarkModeToggle removes the light/dark switch from the docs UI.
	HideDarkModeToggle bool `json:"hide_dark_mode_toggle" config:",optional"`
	// CustomCSS injects brand CSS (e.g. --scalar-* variables) into the docs page.
	CustomCSS string `json:"custom_css" config:",optional"`
	// CustomHeadJS injects a script into the docs page <head>.
	CustomHeadJS string `json:"custom_head_js" config:",optional"`
	// CustomBodyJS injects a script right before the docs page </body>.
	CustomBodyJS string `json:"custom_body_js" config:",optional"`
	// HideDownload removes the "Download OpenAPI spec" button.
	HideDownload bool `json:"hide_download" config:",optional"`
	// HideModels hides the schema/model section from the docs UI.
	HideModels bool `json:"hide_models" config:",optional"`
	// HideSearch disables the docs search bar.
	HideSearch bool `json:"hide_search" config:",optional"`
	// Sidebar toggles the navigation sidebar (default true).
	Sidebar *bool `json:"sidebar" config:",optional"`
	// ShowToolbar controls the developer toolbar: always | localhost | never.
	ShowToolbar string `json:"show_toolbar" config:",optional"`
	// SearchHotKey sets the search keyboard shortcut key (default "k").
	SearchHotKey string `json:"search_hot_key" config:",optional"`
	// Editable lets users edit the spec live in the docs UI.
	Editable bool `json:"editable" config:",optional"`
	// TagsSorter sorts tag groups: alpha (empty preserves spec order).
	TagsSorter string `json:"tags_sorter" config:",optional"`
	// OperationsSorter sorts operations: alpha | method.
	OperationsSorter string `json:"operations_sorter" config:",optional"`
	// OperationTitleSource picks operation titles: summary | path.
	OperationTitleSource string `json:"operation_title_source" config:",optional"`
	// OrderSchemaPropertiesBy orders schema properties: alpha | preserve.
	OrderSchemaPropertiesBy string `json:"order_schema_properties_by" config:",optional"`
	// PersistAuth keeps Try-It credentials across page reloads.
	PersistAuth bool `json:"persist_auth" config:",optional"`
	// DefaultHTTPClient pins the Try-It client: {target, client}.
	DefaultHTTPClient *HTTPClientDef `json:"default_http_client" config:",optional"`
	// HiddenClients hides Try-It client entries (e.g. [postman]).
	HiddenClients []string `json:"hidden_clients" config:",optional"`
	// CDN overrides the Scalar asset CDN (default jsdelivr).
	CDN string `json:"cdn" config:",optional"`
	// Proxy routes Try-It requests through a CORS proxy.
	Proxy string `json:"proxy" config:",optional"`
	// BaseServerURL pins the server URL used by Try-It requests.
	BaseServerURL string `json:"base_server_url" config:",optional"`
	// ServersOverride replaces the spec servers list in the docs UI.
	ServersOverride []ServerOverrideDef `json:"servers_override" config:",optional"`
	// Sources renders multiple OpenAPI documents as docs tabs.
	Sources []SourceDef `json:"sources" config:",optional"`
	// Auth prefills the Try-It authentication panel.
	Auth *AuthPrefillDef `json:"auth" config:",optional"`
	// CSPConnect adds extra connect-src hosts so Try It can reach the APIs.
	CSPConnect []string `json:"csp_connect" config:",optional"`
}

type OutboxRecord struct {
	ID        int64  `db:"id,primary,auto"`
	Subject   string `db:"subject,required"`
	Payload   string `db:"payload,required"`
	Status    string `db:"status,required,default='pending'"`
	CreatedAt string `db:"created_at,default=now()"`
}

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

type PGPool = pgxpool.Pool

type PaginatedResponse struct {
	Data  any   `json:"data"`
	Total int64 `json:"total"`
	Page  int   `json:"page"`
	Size  int   `json:"size"`
}

type PoolConf struct {
	// MaxConns is a constant.
	MaxConns int32 `json:"max_conns" config:",default=10"`
	// MinConns is a constant.
	MinConns int32 `json:"min_conns" config:",default=2"`
	// MaxConnLifetime is a constant.
	MaxConnLifetime string `json:"max_conn_lifetime" config:",optional"`
	// MaxConnIdleTime is a constant.
	MaxConnIdleTime string `json:"max_conn_idle_time" config:",optional"`
	// HealthCheckPeriod is a constant.
	HealthCheckPeriod string `json:"health_check_period" config:",optional"`
	// ReservedConns is a constant.
	ReservedConns int32 `json:"reserved_conns" config:",default=10"`
	// StatementTimeout sets statement_timeout per connection.
	StatementTimeout string `json:"statement_timeout" config:",optional"`
}

type PoolConfig struct {
	// MaxIdleConns is a constant.
	MaxIdleConns int `json:"max_idle_conns" config:",default=200"`
	// MaxIdlePerHost is a constant.
	MaxIdlePerHost int `json:"max_idle_conns_per_host" config:",default=100"`
	// MaxConnsPerHost is a constant.
	MaxConnsPerHost int `json:"max_conns_per_host" config:",default=250"`
	// IdleTimeout is a constant.
	IdleTimeout string `json:"idle_timeout" config:",default=90s"`
}

type PoolHealth struct {
	Name           string  `json:"name"`
	Driver         string  `json:"driver"`
	TotalConns     int     `json:"total_connections"`
	IdleConns      int     `json:"idle_connections"`
	InUseConns     int     `json:"in_use_connections"`
	MaxConns       int     `json:"max_connections"`
	UtilizationPct float64 `json:"utilization_pct"`
	WaitCount      int64   `json:"wait_count"`
	WaitDuration   string  `json:"wait_duration"`
	Status         string  `json:"status"`
}

type PrometheusConfig struct {
	// Enabled enables the prometheus metrics agent and infra/metric counters.
	Enabled bool `json:"enabled"`
	// Host is the prometheus agent listen address.
	Host string `json:"host" config:",default=0.0.0.0"`
	// Port is the prometheus agent listen port.
	Port int `json:"port" config:",default=9101"`
	// Path is the prometheus metrics endpoint path.
	Path string `json:"path" config:",default=/metrics"`
}

type RateLimitConf struct {
	// Enabled is a constant.
	Enabled bool `json:"enabled" config:",optional"`
	// KV is a constant.
	KV string `json:"kv" config:",optional"` // references kv[].name
	// Algorithm is a constant.
	Algorithm string `json:"algorithm" config:",default=sliding_window"`
	// TTL is a constant.
	TTL string `json:"ttl" config:",optional"`
	// Global is a constant.
	Global *RateLimitDef `json:"global" config:",optional"`
	// PerIP is a constant.
	PerIP *RateLimitDef `json:"per_ip" config:",optional"`
	// PerUser is a constant.
	PerUser *RateLimitDef `json:"per_user" config:",optional"`
	// PerKey is a constant.
	PerKey *RateLimitDef `json:"per_key" config:",optional"`
	// SkipFailedRequests is a constant.
	SkipFailedRequests bool `json:"skip_failed_requests" config:",optional"`
	// SkipSuccessfulRequests is a constant.
	SkipSuccessfulRequests bool `json:"skip_successful_requests" config:",optional"`
}

type RateLimitDef struct {
	// RequestsPerSecond is a constant.
	RequestsPerSecond int `json:"requests_per_second"`
	// Burst is a constant.
	Burst int `json:"burst"`
	// TTL is a constant.
	TTL string `json:"ttl" config:",optional"`
}

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

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

type RedirectConfig struct {
	// Params are the route parameters (e.g. {"id": "123"} for /user/:id).
	Params Map
	// Queries are query string parameters merged into the redirect URL.
	Queries map[string]string
}

type RedirectDef struct {
	// From is the source path to match. Supports:
	//   Exact:      "/old"
	//   Wildcard:   "/old/*" (catch-all, forwarded to target)
	//   Param:      "/user/:id" (param forwarded to target)
	From string `json:"from"`
	// To is the target URL or path. Supports param references:
	//   "/new"              (static target)
	//   "/new/*"            (wildcard forwarded from From)
	//   "/profile/:id"      (param forwarded from From)
	//   "https://ext.com/x" (external URL)
	To string `json:"to"`
	// Status is the HTTP status code (default 302).
	Status int `json:"status" config:",default=302"`
	// Methods limits which HTTP methods trigger the redirect (default: ["GET"]).
	Methods []string `json:"methods" config:",optional"`
	// PreserveQuery keeps the original query string when redirecting (default: true).
	PreserveQuery *bool `json:"preserve_query" config:",optional"`
}

type RedisConfig = redis.RedisConf

type RefreshConfig struct {
	// Enabled is a constant.
	Enabled bool `json:"enabled" config:",default=false"`
	// TTL is a constant.
	TTL int `json:"ttl" config:",default=604800"` // 7 days in seconds
	// Endpoint is a constant.
	Endpoint string `json:"endpoint" config:",default=/auth/refresh"`
	// Secret is a constant.
	Secret string `json:"secret" config:",optional"` // separate from auth.secret
	// ZitadelTokenURL is a constant.
	ZitadelTokenURL string `json:"zitadel_token_url" config:",optional"`
	// ZitadelClientID is a constant.
	ZitadelClientID string `json:"zitadel_client_id" config:",optional"`
	// KratosRefreshURL is a constant.
	KratosRefreshURL string `json:"kratos_refresh_url" config:",optional"`
}

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

type RetryConf struct {
	// MaxRetries is the maximum number of retry attempts (default 3).
	MaxRetries int `json:"max_retries" config:",default=3"`
	// InitialInterval is the initial backoff duration (default 500ms).
	InitialInterval string `json:"initial_interval" config:",default=500ms"`
	// MaxBackoff is the maximum backoff duration (default 10s).
	MaxBackoff string `json:"max_backoff" config:",default=10s"`
	// Multiplier is the exponential backoff multiplier (default 2.0).
	Multiplier float64 `json:"multiplier" config:",default=2.0"`
}

type RouteMW struct {
	// Path is a constant.
	Path string `json:"path"`
	// Apply is a constant.
	Apply []string `json:"apply"`
}

type SLOConfig struct {
	// Name identifies this SLO.
	Name string
	// Target is the availability target (e.g. 99.9 for 99.9%).
	Target float64
	// Window is the measurement window (e.g. 30d).
	Window time.Duration
}

type SSEHandler func(ctx context.Context, send func(data string)) error

type SSRFConf struct {
	// Enabled is a constant.
	Enabled bool `json:"enabled" config:",optional"`
	// BlockPrivate is a constant.
	BlockPrivate bool `json:"block_private" config:",optional"`
	// BlockLoopback is a constant.
	BlockLoopback bool `json:"block_loopback" config:",optional"`
	// BlockMetadata is a constant.
	BlockMetadata bool `json:"block_metadata" config:",optional"`
	// AllowedHosts is a constant.
	AllowedHosts []string `json:"allowed_hosts" config:",optional"`
}

type SecurityDef struct {
	// ContentSecurity is a constant.
	ContentSecurity *ContentSecurityDef `json:"content_security" config:",optional"`
	// Cryption is a constant.
	Cryption *CryptionDef `json:"cryption" config:",optional"`
	// EncryptCookie is a constant.
	EncryptCookie *EncryptCookieDef `json:"encrypt_cookie" config:",optional"`
}

type SecurityHeadersConf struct {
	// FrameOptions is a constant.
	FrameOptions string `json:"frame_options" config:",optional"`
	// ReferrerPolicy is a constant.
	ReferrerPolicy string `json:"referrer_policy" config:",optional"`
	// PermissionsPolicy is a constant.
	PermissionsPolicy string `json:"permissions_policy" config:",optional"`
	// HSTS is a constant.
	HSTS bool `json:"hsts" config:",optional"`
	// HSTSMaxAge is a constant.
	HSTSMaxAge int `json:"hsts_max_age" config:",optional"`
	// HSTSIncludeSubs is a constant.
	HSTSIncludeSubs bool `json:"hsts_include_subdomains" config:",optional"`
	// CSP is a constant.
	CSP string `json:"csp" config:",optional"`
	// CSPConfig is a constant.
	CSPConfig *CSPConf `json:"csp_config" config:",optional"` // programmatic CSP builder
	// COOP is a constant.
	COOP string `json:"coop" config:",optional"`
	// COEP is a constant.
	COEP string `json:"coep" config:",optional"`
	// CORP is a constant.
	CORP string `json:"corp" config:",optional"`
	// CacheControl is a constant.
	CacheControl string `json:"cache_control" config:",optional"`
	// CSPReportPath is a constant.
	CSPReportPath string `json:"csp_report_path" config:",optional"`
}

type SeedFunc func(context.Context, *Service) error

type ServerConf struct {
	// Mode sets the server operating mode: "monolith" (default) or "micro".
	// In monolith mode, gRPC is disabled and all communication is direct.
	// In micro mode, gRPC server and clients are enabled for inter-service calls.
	Mode string `json:"mode" config:",default=monolith"`
	// Host is a constant.
	Host string `json:"host" config:",default=0.0.0.0"`
	// Prefork is a constant.
	Prefork bool `json:"prefork" config:",optional"`
	// BodyLimit is a constant.
	BodyLimit int `json:"body_limit" config:",default=4194304"`
	// Timeout is a constant.
	Timeout string `json:"timeout" config:",default=30s"`
	// ReadTimeout is a constant.
	ReadTimeout string `json:"read_timeout" config:",default=15s"`
	// WriteTimeout is a constant.
	WriteTimeout string `json:"write_timeout" config:",default=30s"`
	// IdleTimeout is a constant.
	IdleTimeout string `json:"idle_timeout" config:",default=120s"`
	// Compression is a constant.
	Compression bool `json:"compression" config:",optional"`
	// StreamRequestBody is a constant.
	StreamRequestBody bool `json:"stream_request_body" config:",optional"`
	// ReduceMemoryUsage is a constant.
	ReduceMemoryUsage bool `json:"reduce_memory_usage" config:",optional"`
	// MaxConns is a constant.
	MaxConns int `json:"max_conns" config:",default=1000"`
	// MaxBytes is a constant.
	MaxBytes int `json:"max_bytes" config:",default=4194304"`
	// MetricsPath is a constant.
	MetricsPath string `json:"metrics_path" config:",default=/metrics"`
	// HealthPath is the legacy healthcheck endpoint (always 200 when enabled).
	HealthPath string `json:"health_path" config:",default=/healthz"`
	// HealthEnabled enables the legacy /healthz endpoint.
	HealthEnabled bool `json:"health_enabled" config:",default=true"`
	// StartupPath is the startup probe endpoint. It verifies the app has
	// successfully started.
	StartupPath string `json:"startup_path" config:",default=/startupz"`
	// StartupEnabled enables the startup probe endpoint.
	StartupEnabled bool `json:"startup_enabled" config:",default=true"`
	// ReadinessPath is the readiness probe endpoint. It reports whether the
	// server finished starting and its dependencies are reachable.
	ReadinessPath string `json:"readiness_path" config:",default=/readyz"`
	// ReadinessEnabled enables the readiness probe endpoint.
	ReadinessEnabled bool `json:"readiness_enabled" config:",default=true"`
	// LivenessPath is the liveness probe endpoint. It reports whether the
	// process is running.
	LivenessPath string `json:"liveness_path" config:",default=/livez"`
	// LivenessEnabled enables the liveness probe endpoint.
	LivenessEnabled bool `json:"liveness_enabled" config:",default=true"`
	// ShutdownTimeout is a constant.
	ShutdownTimeout string `json:"shutdown_timeout" config:",default=10s"`
	// RecoverStack is a constant.
	RecoverStack bool `json:"recover_stack" config:",default=true"`
	// APIPrefix is a constant.
	APIPrefix string `json:"api_prefix" config:",default=/api"`
	// CORS is a constant.
	CORS *CORSConf `json:"cors" config:",optional"`
	// CORSGroups is a list of named CORS policies that routes can reference.
	CORSGroups []CORSGroupConf `json:"cors_groups" config:",optional"`
	// Middleware is a constant.
	Middleware []RouteMW `json:"middleware" config:",optional"`
	// Static is a constant.
	Static []StaticDef `json:"static" config:",optional"`
	// Redirects defines declarative HTTP redirects (no Go code needed).
	Redirects []RedirectDef `json:"redirects" config:",optional"`
	// OpenAPI is a constant.
	OpenAPI *OpenAPIConf `json:"openapi" config:",optional"`
	// SecurityHeaders is a constant.
	SecurityHeaders *SecurityHeadersConf `json:"security_headers" config:",optional"`
	// CSPGroups is a list of named per-route CSP policies, like CORSGroups.
	CSPGroups []CSPGroupConf `json:"csp_groups" config:",optional"`
	// CSRF is a constant.
	CSRF *CSRFConf `json:"csrf" config:",optional"`
	// RateLimit is a constant.
	RateLimit *RateLimitConf `json:"rate_limit" config:",optional"`
	// TLS is a constant.
	TLS *TLSConf `json:"tls" config:",optional"`
	// SSRF is a constant.
	SSRF *SSRFConf `json:"ssrf" config:",optional"`
	// Cookies is a constant.
	Cookies *CookieConf `json:"cookies" config:",optional"`
	// Security is a constant.
	Security *SecurityDef `json:"security" config:",optional"`
	// SlowQueryThreshold is a constant.
	SlowQueryThreshold string `json:"slow_query_threshold" config:",default=100ms"`
	// GC configures Go runtime garbage collection.
	GC *GCConfig `json:"gc" config:",optional"`
	// Logger is a constant.
	Logger bool `json:"logger" config:",default=true"`
	// LoadShedding is a constant.
	LoadShedding bool `json:"load_shedding" config:",default=true"`
	// Breaker is a constant.
	Breaker bool `json:"breaker" config:",default=true"`
	// Telemetry is a constant.
	Telemetry *TelemetryConf `json:"telemetry" config:",optional"`
	// Correlation enables the X-Correlation-ID tracking middleware.
	Correlation *CorrelationConf `json:"correlation" config:",optional"`
	// LogSkipPaths is a constant.
	LogSkipPaths []string `json:"log_skip_paths" config:",optional"`
	// LogSampleRate is a constant.
	LogSampleRate float64 `json:"log_sample_rate" config:",default=0"`
	// GrpcServer configures the gRPC server.
	GrpcServer *GrpcServerConf `json:"grpc_server" config:",optional"`
	// GrpcClients defines gRPC client connections to other services.
	GrpcClients []GrpcClientConf `json:"grpc_clients" config:",optional"`
}

type ServerOverrideDef struct {
	// URL is the server base URL.
	URL string `json:"url"`
	// Description documents when this server applies (e.g. "production").
	Description string `json:"description" config:",optional"`
}

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

type ServiceConfig struct {
	// Name is a constant.
	Name string `json:"name"`
	// Port is a constant.
	Port int `json:"port" config:",default=8080"`
	// Deploy is a constant.
	Deploy *DeployConfig `json:"deploy" config:",optional"`
	// Server is a constant.
	Server ServerConf `json:"server" config:",optional"`
	// Databases is a constant.
	Databases []DBConfig `json:"databases" config:",optional"`
	// KV is a constant.
	KV []KVConfig `json:"kv" config:",optional"`
	// Stream is a constant.
	Stream []StreamConfig `json:"stream" config:",optional"`
	// Entry is a constant.
	Entry []EntryDef `json:"entry" config:",optional"`
	// Exit is a constant.
	Exit []ExitWorker `json:"exit" config:",optional"`
	// Cron is a constant.
	Cron []CronJob `json:"cron" config:",optional"`
	// Auth is a constant.
	Auth *AuthConfig `json:"auth" config:",optional"`
	// Log is a constant.
	Log *logx.LogConf `json:"log" config:",optional"`
	// Prometheus enables prometheus metrics via infra/metric.
	Prometheus *PrometheusConfig `json:"prometheus" config:",optional"`
}

type SlowQueryConf struct {
	// Enabled enables slow query logging for this database.
	Enabled bool `json:"enabled" config:",optional"`
	// Threshold is the duration after which a query is considered slow (e.g. "200ms", "1s").
	Threshold string `json:"threshold" config:",default=100ms"`
}

type SourceDef struct {
	// Title shown on the docs tab.
	Title string `json:"title"`
	// Slug is the URL fragment used to route to this document.
	Slug string `json:"slug" config:",optional"`
	// URL points at an OpenAPI spec (e.g. http://ms-email:3107/openapi.json).
	URL string `json:"url" config:",optional"`
	// Default marks the tab displayed first.
	Default bool `json:"default" config:",optional"`
}

type SpecMutator func(spec *openapi3.T) error

type SpoolDef struct {
	// Mode is a constant.
	Mode string `json:"mode" config:",default=auto,options=auto|memory|disk"`
	// MemoryLimit is a constant.
	MemoryLimit string `json:"memory_limit" config:",default=4MB"`
	// Dir is a constant.
	Dir string `json:"dir" config:",optional"`
	// PartSize is a constant.
	PartSize string `json:"multipart_part_size" config:",default=16MB"`
	// Concurrency is a constant.
	Concurrency int `json:"multipart_concurrency" config:",default=4"`
	// Async is a constant.
	Async bool `json:"async" config:",optional"`
}

type StaticDef struct {
	// Prefix is the URL prefix for serving files (e.g. "/assets").
	Prefix string `json:"prefix"`
	// Dir is the directory path on disk (e.g. "./public").
	// Required when FS is not set.
	Dir string `json:"dir" config:",optional"`
	// FS selects the filesystem source: "" or "disk" uses Dir on disk;
	// "embed" uses an fs.FS registered via WithFS(name).
	FS string `json:"fs" config:",optional"`
	// FSName references the fs.FS registered via Service.WithFS(name, fsys).
	// Required when fs: "embed".
	FSName string `json:"fs_name" config:",optional"`
	// Compress enables gzip/brotli/zstd compression for served files.
	Compress bool `json:"compress" config:",optional"`
	// ByteRange enables byte range requests (useful for video/audio).
	ByteRange bool `json:"byte_range" config:",optional"`
	// Browse enables directory listing when a directory is requested.
	Browse bool `json:"browse" config:",optional"`
	// Download sets Content-Disposition: attachment for direct downloads.
	Download bool `json:"download" config:",optional"`
	// MaxAge sets Cache-Control max-age in seconds. 0 means no cache header.
	MaxAge int `json:"max_age" config:",default=0"`
	// IndexNames overrides the default index file names (default: ["index.html"]).
	IndexNames []string `json:"index_names" config:",optional"`
	// SPA enables Single-Page Application mode: when a file is not found,
	// the handler serves the first index file instead of returning 404.
	SPA bool `json:"spa" config:",optional"`
	// Methods limits which HTTP methods serve files (default: ["GET", "HEAD"]).
	Methods []string `json:"methods" config:",optional"`
}

type StaticOption func(*StaticDef)

type StorageDef struct {
	// Mode is a constant.
	Mode string `json:"mode"` // s3, local
	// Bucket is a constant.
	Bucket string `json:"bucket" config:",optional"`
	// Path is a constant.
	Path string `json:"path" config:",optional"`
	// Region is a constant.
	Region string `json:"region" config:",optional"`
	// Endpoint is a constant.
	Endpoint string `json:"endpoint" config:",optional"`
	// AccessKey is a constant.
	AccessKey string `json:"access_key" config:",optional"`
	// SecretKey is a constant.
	SecretKey string `json:"secret_key" config:",optional"`
	// Presign is a constant.
	Presign bool `json:"presign" config:",optional"`
	// PresignTTL is a constant.
	PresignTTL string `json:"presign_ttl" config:",default=5m"`
	// Pool is a constant.
	Pool *PoolConfig `json:"pool" config:",optional"`
	// Spool is a constant.
	Spool *SpoolDef `json:"spool" config:",optional"`
	// Cache is a constant.
	Cache *CacheConfig `json:"cache" config:",optional"`
}

type StreamConfig struct {
	// Name is a constant.
	Name string `json:"name"`
	// Driver is a constant.
	Driver string `json:"driver" config:",default=nats"`
	// URL is a constant.
	URL string `json:"url" config:",optional"`
	// Brokers is a constant.
	Brokers []string `json:"brokers" config:",optional"`
	// ConsumerGroup is a constant.
	ConsumerGroup string `json:"consumer_group" config:",optional"`
	// MaxReconnects is a constant.
	MaxReconnects int `json:"max_reconnects" config:",optional"`
	// ReconnectWait is a constant.
	ReconnectWait string `json:"reconnect_wait" config:",optional"`
	// Timeout is a constant.
	Timeout string `json:"timeout" config:",optional"`
	// RetryOnFail is a constant.
	RetryOnFail bool `json:"retry_on_fail" config:",optional"`
	// User authenticates to the NATS server. Password may be set directly or
	// referenced from the environment with ${VAR} (the config expands it).
	User string `json:"user" config:",optional"`
	// Password authenticates to the NATS server.
	Password string `json:"password" config:",optional"`
	// CAFile verifies the server certificate (leave empty for system roots).
	CAFile string `json:"ca_file" config:",optional"`
	// CertFile/KeyFile are the client certificate pair for mTLS servers.
	CertFile string `json:"cert_file" config:",optional"`
	KeyFile  string `json:"key_file" config:",optional"`
	// Streams is a constant.
	Streams []StreamDef `json:"streams" config:",optional"`
}

type StreamDef struct {
	// Name is a constant.
	Name string `json:"name"`
	// MaxAge is a constant.
	MaxAge string `json:"max_age" config:",optional"`
	// MaxBytes is a constant.
	MaxBytes int64 `json:"max_bytes" config:",optional"`
	// Storage is a constant.
	Storage string `json:"storage" config:",default=file"`
	// Compression is a constant.
	Compression string `json:"compression" config:",default=s2"`
}

type SubscribeDef struct {
	// Stream is a constant.
	Stream string `json:"stream"`
	// Subject is a constant.
	Subject string `json:"subject" config:",optional"`
	// Durable is a constant.
	Durable string `json:"durable" config:",optional"`
}

type TLSConf struct {
	// Enabled is a constant.
	Enabled bool `json:"enabled"`
	// Manual is a constant.
	Manual *ManualTLS `json:"manual" config:",optional"`
	// Autocert is a constant.
	Autocert *AutocertTLS `json:"autocert" config:",optional"`
	// MinVersion is a constant.
	MinVersion string `json:"min_version" config:",optional"`
	// MaxVersion is a constant.
	MaxVersion string `json:"max_version" config:",optional"`
	// CurvePrefs is a constant.
	CurvePrefs []string `json:"curve_preferences" config:",optional"`
	// CipherSuites is a constant.
	CipherSuites []string `json:"cipher_suites" config:",optional"`
	// RedirectHTTP is a constant.
	RedirectHTTP bool `json:"redirect_http" config:",optional"`
	// RedirectPort is a constant.
	RedirectPort int `json:"redirect_port" config:",optional"`
}

type TelemetryConf struct {
	Enabled bool   `json:"enabled" config:",optional"`
	Name    string `json:"name" config:",optional"`
	// Endpoint is the OTLP receiver address (e.g. "localhost:4317").
	Endpoint string  `json:"endpoint" config:",optional"`
	Sampler  float64 `json:"sampler" config:",default=1.0"`
	// Batcher is the exporter type: otlpgrpc | otlphttp | zipkin | file.
	Batcher string `json:"batcher" config:",default=otlpgrpc"`
	// OtlpHeaders are additional headers sent with OTLP export requests.
	OtlpHeaders map[string]string `json:"otlp_headers" config:",optional"`
	// OtlpHttpPath is the URL path for OTLP HTTP transport (e.g. "/v1/traces").
	OtlpHttpPath string `json:"otlp_http_path" config:",optional"`
	// OtlpHttpSecure enables TLS for OTLP HTTP transport.
	OtlpHttpSecure bool `json:"otlp_http_secure" config:",optional"`
	// TraceResponseHeader sets a response header exposing the trace ID (e.g. "X-Trace-Id").
	TraceResponseHeader string `json:"trace_response_header" config:",optional"`
	// SkipPaths are request paths that should not be traced.
	SkipPaths []string `json:"skip_paths" config:",optional"`
}

type TursoConf struct {
	// Mode is a constant.
	Mode string `json:"mode" config:",default=local"` // local | remote
	// BusyTimeout is a constant.
	BusyTimeout int `json:"busy_timeout" config:",default=30000"` // ms, 0 = no wait
}

type WSHandler func(ctx context.Context, conn *websocket.Conn) error