vango

type APIConfig struct {
	// MaxBodyBytes is the maximum number of bytes read from the HTTP request body
	// when an API handler declares a typed body parameter.
	//
	// Default: 1 MiB.
	MaxBodyBytes int64

	// RequireJSONContentType enforces that requests with a non-empty body specify a
	// JSON Content-Type (application/json or application/*+json) when an API handler
	// declares a structured (non-[]byte, non-string) body parameter.
	//
	// When false (default), missing Content-Type is accepted, but explicit non-JSON
	// Content-Type is rejected.
	RequireJSONContentType bool
}

type APIHandler = any

type Action[A any, R any] = corevango.Action[A, R]

type ActionHandler[A any, R any] = corevango.ActionHandler[A, R]

type ActionOption = corevango.ActionOption

type ActionRejection = corevango.ActionRejection

type ActionRejectionReason = corevango.ActionRejectionReason

type ActionState = corevango.ActionState

type AnimationEvent = corevango.AnimationEvent

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

type AssetManifest = assets.Manifest

type AssetResolver = assets.Resolver

type Attr = vdom.Attr

type AuthCheckConfig = server.AuthCheckConfig

type AuthExpiredAction = server.AuthExpiredAction

type AuthExpiredConfig = server.AuthExpiredConfig

type AuthExpiredReason = server.AuthExpiredReason

type AuthFailureMode = server.AuthFailureMode

type AuthResumePolicy = server.AuthResumePolicy

type CacheControlStrategy int

type Cleanup = corevango.Cleanup

type Component = vdom.Component

type Config struct {
	// Session configures session behavior including durability and limits.
	Session SessionConfig

	// Static configures static file serving.
	Static StaticConfig

	// API configures JSON API routes (app.API).
	API APIConfig

	// Security configures security features (CSRF, origin checking, cookies).
	Security SecurityConfig

	// GlobalSignalPubSub is the broadcast backend for global signals.
	// When nil, global signals update via eventual consistency only.
	GlobalSignalPubSub GlobalBroadcastBackend

	// GlobalSignalRefreshInterval controls how often global signals refresh
	// from persistence when no broadcast backend is configured.
	// nil means use the default (30 seconds).
	// 0 disables refresh entirely.
	GlobalSignalRefreshInterval *time.Duration

	// DevMode enables development mode which disables security checks.
	// SECURITY: NEVER use in production - this disables:
	//   - Origin checking (allows all origins)
	//   - CSRF validation
	//   - Secure cookie requirements
	DevMode bool

	// Logger is the structured logger for the application.
	// If nil, slog.Default() is used.
	Logger *slog.Logger

	// Observability configures optional logging for mutations.
	// All fields are opt-in and default to false.
	Observability ObservabilityConfig

	// Metrics configures the runtime metrics sink.
	// When nil, metrics emission defaults to the internal collector.
	Metrics MetricsSink

	// StrictConcurrency forces session-loop-only write enforcement (signals,
	// session keys) to panic even when pkg/vango.DevMode is false.
	//
	// Default: false (production-safe: drop + warn + metric).
	//
	// Useful for staging/canary environments to catch concurrency violations
	// before they reach production.
	StrictConcurrency bool

	// OnSessionStart is called when a new WebSocket session is established.
	// Use this to transfer data from the HTTP context (e.g., authenticated user)
	// to the Vango session before the handshake completes.
	//
	// Example:
	//   OnSessionStart: func(httpCtx context.Context, s *vango.Session) {
	//       if user := myauth.UserFromContext(httpCtx); user != nil {
	//           auth.Set(s, user)  // Use auth.Set to set presence flag
	//       }
	//   }
	OnSessionStart func(httpCtx context.Context, s *Session)

	// OnSessionResume is called when resuming an existing WebSocket session.
	// Use this to rehydrate session data from the HTTP context (e.g., re-validate auth).
	//
	// Unlike OnSessionStart, this is called when resuming after disconnect.
	// Return nil to allow the resume, or an error to reject it.
	//
	// Example:
	//   OnSessionResume: func(httpCtx context.Context, s *vango.Session) error {
	//       user, err := myauth.ValidateFromContext(httpCtx)
	//       if err != nil {
	//           return err  // Reject resume if previously authenticated
	//       }
	//       if user != nil {
	//           auth.Set(s, user)
	//       }
	//       return nil
	//   }
	OnSessionResume func(httpCtx context.Context, s *Session) error

	// SSR configures server-side rendering behavior.
	SSR SSRConfig
}

type CookieOption = server.CookieOption

type Ctx = server.Ctx

type DragEvent = corevango.DragEvent

type DropEvent = corevango.DropEvent

type EventRateLimitConfig = corevango.EventRateLimitConfig

type Form[T any] = form.Form[T]

type FormData = corevango.FormData

type GlobalBroadcastBackend = corevango.GlobalBroadcastBackend

type HTTPError = corevango.HTTPError

type Handler[T any] = corevango.Handler[T]

type HookEvent = corevango.HookEvent

type HookEventValidator = corevango.HookEventValidator

type InputEvent = corevango.InputEvent

type IslandMessage = corevango.IslandMessage

type IslandMessageValidator = corevango.IslandMessageValidator

type KeyboardEvent = corevango.KeyboardEvent

type LayoutHandler = func(Ctx, Slot) *VNode

type Memo[T any] = corevango.Memo[T]

type MetricsSink = corevango.MetricsSink

type ModifiedHandler = corevango.ModifiedHandler

type MouseEvent = corevango.MouseEvent

type NavigateEvent = corevango.NavigateEvent

type NavigateOption = server.NavigateOption

type NoProps = corevango.NoProps

type ObservabilityConfig = corevango.ObservabilityConfig

type PageHandler = any

type PagedResponse[T any] = corevango.PagedResponse[T]

type Props = vdom.Props

type PropsCell[P any] = corevango.PropsCell[P]

type RenderFn = corevango.RenderFn

type ResizeEvent = corevango.ResizeEvent

type Resource[T any] = corevango.Resource[T]

type ResourceOption = corevango.ResourceOption

type ResourceState = corevango.State

type Response[T any] = corevango.Response[T]

type RouteMiddleware = router.Middleware

type RouteMiddlewareFunc = router.MiddlewareFunc

type SSRConfig struct {
	// EnableResourcePreload controls whether Resources are executed during SSR renders.
	//
	// When enabled, Setup component one-shot renders will:
	//   - run setup-registered pending effects (on an SSR single-writer loop)
	//   - wait for Resources to reach Ready/Error (bounded by ResourceTimeout)
	//
	// This improves progressive enhancement: SSR output can include loaded data
	// even before a WebSocket session mounts.
	//
	// Default: true.
	EnableResourcePreload *bool

	// ResourceTimeout bounds SSR resource preloading time.
	// 0 disables waiting (resources may remain Pending/Loading in SSR output).
	//
	// Default: 300ms.
	ResourceTimeout *time.Duration
}

type ScrollEvent = corevango.ScrollEvent

type SecurityConfig struct {
	// CSRFSecret is the secret key for CSRF token generation.
	// If nil and CSRF is enabled in non-DevMode, a random secret is generated
	// at startup (tokens won't survive server restarts).
	// To disable CSRF protection entirely, set CSRFEnabled = false explicitly.
	// For production, prefer a stable 32+ byte secret generated with crypto/rand and stored securely.
	CSRFSecret []byte

	// CSRFEnabled enables CSRF protection for state-changing HTTP endpoints.
	// Default: true.
	CSRFEnabled bool

	// AllowedOrigins lists allowed WebSocket origins (scheme + host + optional port).
	// Entries must not include path, query, or fragment.
	// If empty and AllowSameOrigin is true, only same-origin requests are allowed.
	// Example: []string{"https://myapp.com", "https://www.myapp.com"}
	AllowedOrigins []string

	// CustomOriginCheck allows a custom WebSocket origin validation function.
	// Requires AllowCustomOriginPolicy to be true in production.
	CustomOriginCheck func(r *http.Request) bool

	// AllowedRedirectHosts lists hostnames (and optional ports) allowed for external redirects.
	// When empty, external redirects are rejected.
	// Example: []string{"accounts.google.com", "auth.mycompany.com", "auth.mycompany.com:8443"}
	AllowedRedirectHosts []string

	// AllowedHosts lists hostnames (and optional ports) that are valid for this server.
	// Used by WebSocketURL() to prevent Host header poisoning attacks.
	// If empty in production (non-DevMode), WebSocketURL() returns empty (fail secure).
	// Example: []string{"myapp.com", "www.myapp.com"}
	AllowedHosts []string

	// CanonicalHost is the preferred hostname for URL generation.
	// When set, WebSocketURL() returns this host instead of the request host.
	// Useful for normalizing "www" vs non-"www" variants.
	CanonicalHost string

	// AllowSameOrigin enables automatic same-origin validation.
	// When true and AllowedOrigins is empty, validates that Origin header
	// matches the request Host header.
	// Default: true.
	AllowSameOrigin bool

	// AllowCustomOriginPolicy permits CustomOriginCheck without AllowedOrigins or AllowSameOrigin.
	// SECURITY: avoid this in production unless you fully understand your policy.
	AllowCustomOriginPolicy bool

	// TrustedProxies lists reverse proxy IPs trusted for X-Forwarded-* headers.
	// When set, forwarded proto headers are honored for secure cookie decisions.
	// Default: nil (do not trust forwarded headers).
	TrustedProxies []string

	// CookieSecure sets the Secure flag on cookies set by the server.
	// Should be true when using HTTPS.
	// Default: true.
	CookieSecure bool

	// CookieHttpOnly sets the HttpOnly flag on cookies set by the server.
	// Prevents JavaScript access to cookies that should not be read by JS.
	// Default: true (except for CSRF cookies which need JS access).
	CookieHttpOnly bool

	// CookieSameSite sets the SameSite attribute for cookies set by the server.
	// Lax is safe for most use cases and allows OAuth redirect flows.
	// Default: http.SameSiteLaxMode.
	CookieSameSite http.SameSite

	// CookieDomain sets the Domain attribute for cookies.
	// Empty string uses the current domain (most secure).
	// Default: "".
	CookieDomain string

	// SecurityHeaders configures default HTTP security headers.
	SecurityHeaders SecurityHeadersConfig

	// URLPolicy controls scheme allowlists for URL-bearing attributes rendered by the server.
	// If nil, defaults are used (href: http/https/mailto/tel/sms; resource/action: http/https).
	// AllowSrcdoc and AllowUnsafeRawHTML are false by default and must be explicitly enabled.
	URLPolicy *URLPolicyConfig
}

type SecurityHeadersConfig struct {
	Enabled bool

	// CSP controls Content-Security-Policy headers.
	CSPEnabled    bool
	CSPReportOnly bool
	CSP           string
	CSPOptions    *server.CSPOptions

	// HSTS controls Strict-Transport-Security headers.
	HSTSMaxAge            time.Duration
	HSTSIncludeSubdomains bool
	HSTSPreload           bool

	// FrameOptions controls the X-Frame-Options header ("DENY" or "SAMEORIGIN").
	FrameOptions string

	// ContentTypeNosniff controls the X-Content-Type-Options header.
	ContentTypeNosniff bool

	// ReferrerPolicy controls the Referrer-Policy header.
	ReferrerPolicy string

	// PermissionsPolicy controls the Permissions-Policy header.
	PermissionsPolicy string
}

type Session = server.Session

type SessionConfig struct {
	// ResumeWindow is how long a disconnected session remains resumable.
	// Within this window, a reconnecting client restores full session state.
	// After this window, the session is permanently expired.
	// nil means use the default (5 minutes).
	// 0 disables resumption entirely (None tier).
	ResumeWindow *time.Duration

	// Store is the persistence backend for sessions.
	// If nil, sessions are only stored in memory (lost on server restart).
	// Use vango.NewMemoryStore(), vango.NewRedisStore(), or vango.NewSQLStore().
	Store SessionStore

	// MaxDetachedSessions is the maximum number of disconnected sessions
	// to keep in memory. When exceeded, least recently used sessions are evicted.
	// Default: 10000.
	MaxDetachedSessions int

	// MaxSessionsPerIP is the maximum concurrent sessions from a single IP.
	// Helps prevent DoS attacks. 0 means no limit.
	// Default: 100.
	MaxSessionsPerIP int

	// MaxHandshakePathBytes limits the size of the `?path=` query parameter
	// used during WebSocket handshake (decoded bytes, includes query string).
	// 0 means no limit (not recommended).
	// Default: 8KB.
	MaxHandshakePathBytes int

	// EvictionPolicy determines how detached sessions are evicted when limits are exceeded.
	// Default: EvictionLRU.
	EvictionPolicy SessionEvictionPolicy

	// EvictOnIPLimit controls whether hitting MaxSessionsPerIP evicts the oldest
	// detached session for that IP instead of rejecting the new session.
	// Default: true when MaxSessionsPerIP > 0.
	EvictOnIPLimit bool

	// StormBudget configures rate limits for async primitives to prevent
	// amplification bugs (e.g., effect triggers resource refetch triggers effect).
	StormBudget *StormBudgetConfig

	// AuthCheck configures authentication freshness checks for the session.
	// When nil, no passive or active auth checks are performed.
	AuthCheck *AuthCheckConfig

	// AuthResumePolicy controls how authenticated session resumes are validated.
	//
	// Default: AuthResumePolicyStrict (requires authFunc or OnSessionResume for
	// authenticated sessions to resume).
	//
	// Set to AuthResumePolicyTrustSessionID only if you understand the security
	// implications. See server.AuthResumePolicy documentation for details.
	AuthResumePolicy AuthResumePolicy

	// AllowTrustSessionIDInProduction acknowledges the security tradeoff of
	// AuthResumePolicyTrustSessionID in non-DevMode.
	//
	// When false (default), non-Dev configs that set TrustSessionID are rejected.
	// TrustSessionID also requires ResumeWindow <= 30s in non-DevMode.
	AllowTrustSessionIDInProduction bool

	// StateBudget configures limits on persisted state size.
	// If nil, default limits are used.
	StateBudget *StateBudgetConfig

	// PersistenceSecret signs persisted blobs.
	// This includes session persistence and global-signal blobs when
	// global persistence/pubsub paths are enabled.
	// Must be 32+ bytes of cryptographically random data.
	PersistenceSecret []byte

	// PersistenceSecretPrevious allows secret rotation.
	// If set, blobs signed with this secret are accepted on resume.
	PersistenceSecretPrevious []byte

	// MaxBlobAge sets the maximum age for persisted session resume blobs.
	// Blobs older than this are rejected during resume, triggering a fresh session.
	// This applies to session resume only (not global signals).
	// It helps prevent replay attacks with stale session data.
	// 0 means no limit (default).
	MaxBlobAge time.Duration

	// HookEventValidator validates client hook event payloads.
	// Return an error to reject the event.
	// In production, startup warnings are emitted when this is unset.
	HookEventValidator HookEventValidator

	// DOMEventRateLimit applies per-session rate limiting to standard DOM events
	// (click/input/scroll/etc., including navigation).
	// RatePerSecond <= 0 disables rate limiting.
	DOMEventRateLimit *EventRateLimitConfig

	// HookEventRateLimit applies per-session rate limiting to hook events.
	// RatePerSecond <= 0 disables rate limiting.
	HookEventRateLimit *EventRateLimitConfig

	// HookEventMaxPayloadBytes limits JSON size of hook event payloads.
	// 0 means no limit.
	HookEventMaxPayloadBytes int

	// IslandMessageValidator validates island message payloads.
	// Return an error to reject the message.
	// In production, startup warnings are emitted when this is unset.
	IslandMessageValidator IslandMessageValidator

	// IslandEventRateLimit applies per-session rate limiting to island messages.
	// RatePerSecond <= 0 disables rate limiting.
	IslandEventRateLimit *EventRateLimitConfig

	// IslandEventMaxPayloadBytes limits JSON size of island message payloads.
	// 0 means no limit.
	IslandEventMaxPayloadBytes int

	// WasmMessageValidator validates WASM message payloads.
	// Return an error to reject the message.
	// In production, startup warnings are emitted when this is unset.
	WasmMessageValidator WasmMessageValidator

	// WasmEventRateLimit applies per-session rate limiting to WASM messages.
	// RatePerSecond <= 0 disables rate limiting.
	WasmEventRateLimit *EventRateLimitConfig

	// WasmEventMaxPayloadBytes limits JSON size of WASM message payloads.
	// 0 means no limit.
	WasmEventMaxPayloadBytes int

	// AllowRawHTMLInEventPayloads permits raw HTML or executable strings in
	// hook/island/WASM payloads. Default: false.
	// NOTE: Vango's unsafe-payload check is a heuristic substring filter,
	// not a sanitizer. Always validate and/or sanitize untrusted payloads.
	AllowRawHTMLInEventPayloads bool
}

type SessionEvictionPolicy = server.SessionEvictionPolicy

type SessionKey[T any] = corevango.SessionKey[T]

type SessionKeyOption[T any] = corevango.SessionKeyOption[T]

type SessionStore = session.SessionStore

type SetupCtx[P any] = corevango.SetupCtx[P]

type Signal[T any] = corevango.Signal[T]

type Slot = corevango.Slot

type StateBudgetConfig = corevango.StateBudgetConfig

type StaticConfig struct {
	// Dir is the directory containing static files (e.g., "public").
	// Files in this directory are served at the URL prefix.
	Dir string

	// Prefix is the URL path prefix for static files (e.g., "/").
	// A file at public/styles.css with Prefix="/" is served at /styles.css.
	// Default: "/".
	Prefix string

	// CacheControl determines caching behavior for static files.
	// Default: CacheControlNone (no caching headers).
	CacheControl CacheControlStrategy

	// Compression enables gzip/brotli compression for static files.
	// Default: false.
	Compression bool

	// Headers are custom headers to add to all static file responses.
	Headers map[string]string
}

type StormBudgetConfig = server.StormBudgetConfig

type Touch = corevango.Touch

type TouchEvent = corevango.TouchEvent

type TransitionEvent = corevango.TransitionEvent

type URLEncoding = urlparam.Encoding

type URLParamOption = urlparam.URLParamOption

type URLPolicyConfig struct {
	// AllowedHrefSchemes controls href/xlink:href schemes.
	// Empty or nil uses the defaults.
	AllowedHrefSchemes []string

	// AllowedResourceSchemes controls src/poster/srcset schemes.
	// Empty or nil uses the defaults.
	AllowedResourceSchemes []string

	// AllowedActionSchemes controls action/formaction schemes.
	// Empty or nil uses the resource schemes.
	AllowedActionSchemes []string

	// AllowSrcdoc enables server-side rendering of srcdoc attributes.
	// Client-side still requires allowSrcdoc to be enabled.
	AllowSrcdoc bool

	// AllowUnsafeRawHTML disables framework raw-HTML sanitization for
	// DangerouslySetInnerHTML/Raw and ResyncFull application on the client.
	// Default: false (sanitize raw HTML).
	//
	// SECURITY: Enabling this allows raw HTML to bypass framework sanitization.
	// Use only for fully trusted internal HTML with a strong CSP.
	AllowUnsafeRawHTML bool
}

type VKind = vdom.VKind

type VNode = vdom.VNode

type ValidationError = form.ValidationError

type Validator = form.Validator

type ValidatorFunc = form.ValidatorFunc

type WasmMessage = corevango.WasmMessage

type WasmMessageValidator = corevango.WasmMessageValidator

type WheelEvent = corevango.WheelEvent