lipsdk

type AuthErrorRenderInput struct {
	FrontendID  string
	RequestPath string
	Decision    sdkauth.Decision
	// DefaultStatus is the status suggested by the adapter (e.g. 401, 403, 503) before rendering.
	DefaultStatus    int
	ChallengeHeaders http.Header
	// Policy and trace fields are optional; default renderers use them for safe messaging only.
	AccessMode    sdkauth.AccessMode
	HandlerKind   sdkauth.HandlerKind
	RequiredLevel sdkauth.RequiredLevel
	TraceID       string
	RemoteAddr    string
}

type AuthErrorRenderResult struct {
	Status      int
	Headers     http.Header
	ContentType string
	Body        []byte
}

type AuthErrorRenderer interface {
	RenderAuthError(ctx context.Context, in AuthErrorRenderInput) AuthErrorRenderResult
}

type BackendAccessScope string

type BackendBuild = any

type BackendCredentialMode string

type BackendExecutionClass string

type BackendExecutionProfile struct {
	Class BackendExecutionClass
}

type BackendFactory func(n yaml.Node) (BackendBuild, error)

type BackendSecurityProfile struct {
	CredentialMode BackendCredentialMode
	AccessScope    BackendAccessScope
}

type ConfigPayload struct {
	Node yaml.Node
}

type ContinuationMountWiring struct {
	Store    lipcont.Store
	Resolver lipcont.Resolver
	Close    func() error
}

type ContinuationMountWiringFactory func(frontendID, instanceID string, cfg yaml.Node) (ContinuationMountWiring, error)

type DecodeAdmission interface {
	TryAcquire(ctx context.Context, weight int64) (release func(), ok bool, err error)
}

type DisabledMandatoryPluginError struct {
	Kind PluginKind
	ID   string
}

type DuplicateRegistrationError struct {
	Kind PluginKind
	ID   string
}

type ExecutorView interface {
	// Execute requires a non-nil ctx (same as [context.Context] contract for all request paths).
	Execute(ctx context.Context, call *lipapi.Call) (lipapi.EventStream, error)
	// CancelALeg explicitly cancels a proxy-owned A-leg and its active B-legs.
	CancelALeg(ctx context.Context, req lipapi.ALegCancelRequest) error
	// WallClock returns the optional wall clock callback used for response metadata; nil means unset.
	WallClock() func() time.Time
}

type FrontendKeepaliveConfig struct {
	Enabled  bool
	Interval time.Duration
}

type FrontendMount func(mux *http.ServeMux, opts FrontendMountOptions) error

type FrontendMountOptions struct {
	// PluginCfg is the opaque plugin-local YAML subtree for this frontend instance.
	PluginCfg yaml.Node
	// Exec is the runtime execution surface the mounted handler uses to submit canonical calls.
	// Real frontend mounts require a non-nil Exec.
	Exec ExecutorView
	// DefaultRoute is the selector used when the frontend protocol omits a route/header override.
	DefaultRoute string
	// RoutePrefixes are backend route-selector prefixes accepted from protocol model fields.
	RoutePrefixes []string
	// MaxRequestBodyBytes caps inbound HTTP request size. Zero means the frontend should use its
	// own default limit.
	MaxRequestBodyBytes int64
	// DecodeAdmission optionally bounds concurrent decode work and weighted in-flight decode bytes.
	// Nil means unlimited for custom/minimal mounts.
	DecodeAdmission DecodeAdmission
	// Authorizer optionally performs frontend-local authentication for direct mounts.
	// Standard HTTP composition authenticates in the outer transport middleware; a
	// custom/direct mount should provide this seam when it is externally reachable.
	Authorizer interface {
		Authenticate(context.Context, sdkauth.InboundCallMeta) (sdkauth.Decision, error)
	}
	// AllowUnauthenticated explicitly opts a direct mount into anonymous access.
	// It defaults to false; standard composition satisfies the default through its
	// outer transport-auth context.
	AllowUnauthenticated bool
	// TrafficPorts optionally emits client→proxy raw bytes after body read (design §10).
	TrafficPorts traffic.PortBundle
	// PreRequestKeepalive optionally emits standards-compliant HTTP informational keepalives
	// while streaming requests wait for pre-request admission to complete. It must not commit
	// final response status or body bytes.
	PreRequestKeepalive FrontendKeepaliveConfig
	// AuthErrorRenderer is an optional per-frontend hook for safe HTTP error bodies on transport
	// authentication failure (R4). When nil, the standard distribution uses the default safe JSON
	// renderer. For the standard binary, prefer [pluginreg.Registry.RegisterAuthErrorRenderer] keyed
	// by auth wire frontend id (see stdhttp/auth DefaultFrontendIDFromRequest); [runtimebundle.BuildOptions.AuthErrorRenderersByFrontend]
	// overrides registry entries per key. This field remains for custom mounts outside pluginreg.
	AuthErrorRenderer AuthErrorRenderer
	// GenerationContext is the runtime-owned lifecycle context of the generation this
	// frontend is mounted into. It cancels when the generation begins shutdown (quiesce
	// during a reload, or full server shutdown) and stays alive for the generation's
	// entire service life. Frontends that own long-lived transport state (WebSocket
	// sessions) must observe it and close their owned resources exactly once so retired
	// generations drain without leaks and new sessions never bind to a closing generation.
	// A nil value means the mount is not generation-bound (tests, custom minimal mounts).
	GenerationContext context.Context // ContinuationStore and ContinuationResolver are optional composition-root
	// injections for frontends that expose proxy-owned response continuation.
	// Minimal/direct mounts may omit them; the frontend then uses its bounded
	// protocol-neutral fallback store.
	ContinuationStore    lipcont.Store
	ContinuationResolver lipcont.Resolver
	// ContinuationWiring is an already-created lifecycle-owned resource. It takes
	// precedence over the factory when both are provided.
	ContinuationWiring *ContinuationMountWiring
	// ContinuationWiringFactory creates lifecycle-owned resources. The standard
	// composition requires GenerationContext when this factory returns Close.
	ContinuationWiringFactory ContinuationMountWiringFactory
	// FrontendInstanceID is the immutable configured instance identity passed to
	// ContinuationWiringFactory. Empty falls back to the factory ID.
	FrontendInstanceID string
	// HTTPHeaders is the resolved inbound header-name set (defaults plus aliases).
	// Zero value uses [DefaultHTTPHeaders].
	HTTPHeaders HTTPHeaders
	// StreamKeepaliveInterval is the recovery SSE keepalive interval. Zero uses
	// the stream package default (12s).
	StreamKeepaliveInterval time.Duration
	// LargePayload carries optional large-payload fast-path candidate configuration
	// for supported frontends.
	LargePayload any
}

type HTTPHeaders struct {
	APIKey            []string
	Route             []string
	SessionID         []string
	ResumeToken       []string
	ALegID            []string
	SessionHint       []string
	Trace             []string
	DiagnosticsSecret []string
}

type MissingRequirementError struct {
	Kind PluginKind
	ID   string
}

type PluginKind string

type Registration struct {
	// ID is the runtime instance identifier (routing / duplicate detection within PluginKind).
	ID string
	// FactoryKind selects the bundled registry factory (e.g. openai-responses). When empty,
	// ID is used as the factory key for backward compatibility.
	FactoryKind string
	Kind        PluginKind
	Config      ConfigPayload
	Enabled     bool
}

type Requirement struct {
	Kind PluginKind
	// ID is the mandatory instance id for frontends and features (matches Registration.ID).
	// For backends, ID is the required registry factory key unless RegistryFactoryID is set.
	ID string
	// RegistryFactoryID selects the bundled factory when it differs from ID.
	// Empty means the factory key equals ID for ValidateBundledFactories and backend mandatory checks.
	RegistryFactoryID string
}

type RouteObserver interface {
	ObserveRouteDecision(ctx context.Context, traceID, decision, detail string)
}