contract

type CredentialDisposition uint8

type CredentialProbe func(r *http.Request) CredentialDisposition

type FrontendRouteClaims func(instanceID string, cfg yaml.Node) ([]RouteClaim, error)

type GeoIPObserver interface {
	Decision(coregeoip.Reason, bool)
}

type GeoIPResolverConfig struct {
	Source         config.ClientIPSource
	TrustedProxies []netip.Prefix
}

type GeoIPSecurityInput struct {
	Policy   *coregeoip.Policy
	Lookup   coregeoip.CountryLookup
	Resolver GeoIPResolverConfig
	Observer GeoIPObserver
}

type HTTPCoreInput struct {
	Executor *runtime.Executor
}

type HTTPFrontendInput struct {
	Executor             *runtime.Executor
	Registry             *pluginreg.Registry
	DefaultRouteSelector string
	RoutePrefixes        []string
	Plugins              []config.PluginConfig
	MaxRequestBodyBytes  int64
	DecodeAdmission      lipsdk.DecodeAdmission
	TrafficPorts         traffic.PortBundle
	PreRequestKeepalive  lipsdk.FrontendKeepaliveConfig
	// HTTPHeaders is the resolved inbound header-name set for this generation.
	HTTPHeaders lipsdk.HTTPHeaders
	// StreamKeepaliveInterval is the recovery SSE keepalive interval.
	StreamKeepaliveInterval time.Duration
	// GenerationContext is the runtime-owned generation lifecycle context. It
	// cancels when the generation begins shutdown (quiesce/drain) and is passed
	// to every mounted frontend through [lipsdk.FrontendMountOptions] so
	// long-lived transports (WebSocket sessions) close exactly once on retire.
	GenerationContext context.Context
	// ContinuationWiringFactory creates composition-root-owned continuation
	// state for each frontend mount generation.
	ContinuationWiringFactory lipsdk.ContinuationMountWiringFactory
	// FrontendRouteClaims optionally maps a frontend factory id to a provider
	// that computes the normalized owner-aware route claims for one frontend
	// instance. When set, [stdhttp.MountBundledFrontends] validates route
	// ownership (owner-aware claims + canonical path takeover) in a
	// generation-scoped RouteRegistry BEFORE any ServeMux handler is mounted; a
	// conflict fails the candidate atomically with both-owner diagnostics.
	// Frontends without a provider participate in no route-ownership
	// validation, so the seam stays fully generic plugin architecture.
	FrontendRouteClaims map[string]FrontendRouteClaims
	// LargePayload carries optional large-payload fast-path candidate configuration
	// for supported frontends.
	LargePayload LargePayloadInput
}

type HTTPModelInput struct {
	CatalogRuntime       *modelcatalog.CatalogRuntime
	ModelRegistryRuntime *modelregistry.Runtime
}

type HTTPOperationsInput struct {
	BillingReports          billing.ReportingStore
	BillingReportsPath      string
	BillingProvisioner      billing.AccountProvisioner
	BillingExposureRecovery billing.ExposureRecovery
	// BillingOperatorReports carries the optional 16.2A operator readers
	// for the protected reports mount. The zero value leaves every new
	// operator route reporting disabled; stock startup never opts into
	// the normalized statement import.
	BillingOperatorReports billingadmin.OperatorReports
	Metrics                *metrics.Bundle
	Store                  diag.AttemptLoader
	SecretGuardInventory   *diag.InventoryExtras
	ControlPlaneQueries    lipcp.Queries
	ReadinessReport        lipcp.ReadinessReportReader
	TokenAccountingAdmin   adminaccounting.Service
	RouteOverrideAdmin     http.Handler
	KeepwarmAdmin          adminkeepwarm.Options
	KeepwarmAdminEnabled   bool
	Registrations          []lipsdk.Registration
	TerminalDecisionPolicy TerminalDecisionPolicyInput
}

type HTTPSecurityInput struct {
	HTTPAuthProviders    []httpauth.Provider
	SecureSessionStore   ssessiondiag.Store
	UsageAuthority       cpadmin.AccountingAuthorityQueries
	ConcurrencyAuthority cpadmin.ConcurrencyAuthorityQueries
	GeoIP                GeoIPSecurityInput
	SelfDefense          SelfDefenseSecurityInput
}

type LargePayloadInput struct {
	// Enabled gates fast-path candidate evaluation. Default false.
	Enabled bool
	// ThresholdBytes is the decoded-size consideration gate. When <= 0,
	// largebody.DefaultThresholdBytes (1 MiB) is used.
	ThresholdBytes int64
	// WireEligibility optionally supplies the generation-frozen WireEligibilitySummary.
	WireEligibility largebody.WireEligibilitySummary
	// SpoolLedger optionally supplies the shared in-flight logical spool ledger.
	SpoolLedger *largebody.SpoolLedger
	// MemorySpoolBytes bounds retained bytes in Go heap per capture before spilling.
	MemorySpoolBytes int64
	// SpoolDir is the directory where temporary spill files are created.
	SpoolDir string
	// CopyBufferSize is the chunk size used for reading from the client body.
	CopyBufferSize int
	// MaxSemanticFactBytes bounds profile-derived metadata such as normalized part shapes.
	MaxSemanticFactBytes int64
	// Diagnostics optionally supplies a diagnostic observer.
	Diagnostics largebody.DiagnosticsObserver
}

type OwnedRoute struct {
	// Method is the HTTP method this route is registered for, or empty when the
	// registration carries no method and therefore answers every method.
	Method string
	// Path is the router's own pattern path, already normalized, and already
	// carrying the trailing separator when Subtree is true.
	Path string
	// Subtree reports whether this route owns its whole subtree. It is true only
	// when the router's pattern ends in a separator, which is exactly the
	// trailing-slash registration form.
	Subtree bool
}

type OwnedRouteCandidate struct {
	Method string
	Path   string
}

type RouteClaim struct {
	OwnerID string
	Method  string
	Path    string
	Kind    RouteKind
}

type RouteConflictError struct {
	Method        string
	Path          string
	ExistingOwner string
	NewOwner      string
	ExistingKind  RouteKind
	NewKind       RouteKind
}

type RouteDiagnostic struct {
	OwnerID   string `json:"owner_id"`
	Method    string `json:"method"`
	Path      string `json:"path"`
	Kind      string `json:"kind"`
	Transport string `json:"transport,omitempty"`
}

type RouteKind string

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

type SelfDefenseObserver interface {
	// Denial records one generic refusal for a finite reason.
	Denial(reason ingressdefense.Reason)
	// QuarantineTransition records one started or escalated quarantine for a
	// finite reason. entryCount is the bounded number of tracked source entries
	// after the transition.
	QuarantineTransition(reason ingressdefense.Reason, entryCount int)
}

type SelfDefenseSecurityInput struct {
	// Policy is the immutable, reloadable request policy of this generation.
	Policy *ingressdefense.Policy
	// State is the process-owned bounded adaptive state, borrowed for the
	// lifetime of this generation.
	State *ingressdefense.State
	// Resolver is the shared client-address trust configuration.
	Resolver GeoIPResolverConfig
	// ImpossiblePaths toggles the fixed impossible-path matcher. Disabling it
	// bypasses only the matcher and retains adaptive quarantine behavior.
	ImpossiblePaths bool
	// OwnedRouteCandidates are the method/path pairs this configuration could
	// publish: the operator-configured diagnostics, metrics and operator-mount
	// paths, plus every enabled frontend's claimed route paths.
	//
	// They are deliberately CANDIDATES, not an inventory. Reading a configured
	// value does not mean the router owns it: a diagnostics block with
	// enabled=false mounts nothing, and a path shape does not tell you whether the
	// registration was exact or a trailing-slash subtree. Composition therefore
	// resolves these against the real router, and the resolved owned routes are
	// what the gate receives.
	OwnedRouteCandidates []OwnedRouteCandidate
	// OwnedRoutes is the resolved inventory: what the router that was just built
	// actually owns, with the router's own match semantics. Composition fills it
	// after the last mount and before the stack; it is deliberately not derivable
	// from the candidates alone, because ownership and match semantics are
	// properties of the router.
	OwnedRoutes []OwnedRoute
	// Probe is the optional conservative credential-presence probe.
	Probe CredentialProbe
	// Observer is the optional bounded metrics seam.
	Observer SelfDefenseObserver
	// Now supplies the request-time instant passed to the adaptive state, so the
	// gate and its paired auth observer share one time base. A nil Now uses
	// time.Now; tests inject a fake clock.
	Now func() time.Time
}

type StandardHTTPInput struct {
	Core       HTTPCoreInput
	Security   HTTPSecurityInput
	Operations HTTPOperationsInput
	Models     HTTPModelInput
	Frontends  HTTPFrontendInput
}

type TerminalDecisionPolicyInput struct {
	Store                   *sessionpolicy.Store
	FeatureStatus           func(context.Context, string) (known, available bool, err error)
	ResolveClientScope      func(context.Context, *http.Request, string) (sessionpolicy.Key, sessionpolicy.Authority, error)
	AuthorizeOperatorTarget func(context.Context, *http.Request, string, string) (sessionpolicy.Key, sessionpolicy.Authority, error)
	GenerationDefault       func(string) bool
	MaxBodyBytes            int64
}

type TrafficSnapshot interface {
	RawCapture() traffic.RawCaptureSink
	TrafficObserver() traffic.Observer
	TrafficRedactors() []traffic.Redactor
}