types

type Admission func(ctx context.Context, in AdmissionInput) (AdmissionResult, error)

type AdmissionInput struct {
	Source            string
	Verb              string
	DryRun            bool
	Kind              string
	Namespace         string
	Name              string
	Tag               string
	Object            v1alpha1.Object
	Store             any
	PostUpsert        PostUpsert
	InitialFinalizers func(v1alpha1.Object) []string
}

type AdmissionResult struct {
	Status     string
	Tag        string
	Generation int64
}

type AppOptions struct {
	// OpenAPISchemaNamer overrides Huma's default schema naming function.
	// Use this when an application exposes same-named Go types from different
	// packages; Huma's default namer omits package paths and panics on those
	// collisions. Nil preserves Huma's default schema names.
	OpenAPISchemaNamer func(reflect.Type, string) string

	// DatabaseFactory is an optional function to create a database that
	// adds new functionality. The factory receives the base database and
	// can run additional migrations. If nil, uses the default PostgreSQL
	// database.
	DatabaseFactory DatabaseFactory

	// SkipMigrations skips the server's startup OSS migrator (the
	// v1alpha1 migration set inside internaldb.NewPostgreSQL) so the
	// server boots against a schema that was already migrated by
	// `arctl db migrate up` (typically from CI/CD ahead of the
	// rollout). DatabaseFactory-supplied migrators are NOT
	// automatically skipped — downstream factories that run their own
	// migrations should consult this same flag (e.g. via closure
	// capture from AppOptions construction) to honor the operator's
	// intent. Wins over the SKIP_MIGRATIONS env var when set true.
	SkipMigrations bool

	// RuntimeAdapters registers per-type PostUpsert/PostDelete
	// hooks for the KindRuntime resource handler, keyed by the
	// lowercase canonical Runtime.Spec.Type ("bedrockagentcore",
	// "geminiagentruntime", "kagent", ...). Used by downstream builds
	// to mirror Runtime apply/delete into a type-specific sidecar
	// table. Missing types = no sidecar reconciliation for that type
	// — the v1alpha1 Runtime row still persists.
	RuntimeAdapters map[string]RuntimeAdapter

	// DeploymentAdapters registers v1alpha1 DeploymentAdapter
	// implementations keyed by lowercase Runtime.Spec.Type ("local",
	// "kubernetes", ...). The Deployment controller and adjacent adapter
	// resolver look up by the type string; downstream builds inject
	// additional adapters here.
	DeploymentAdapters map[string]DeploymentAdapter

	// DeploymentDependencyKinds registers additional resource kinds whose
	// durable control-plane events may change a Deployment's desired inputs.
	// The Deployment controller requeues current Deployments for these events;
	// its apply fingerprint still suppresses unchanged adapter work.
	DeploymentDependencyKinds map[string]bool

	// Authorizers gates every read + write operation on the
	// generic v1alpha1 resource handler, keyed by canonical Kind name
	// (v1alpha1.KindAgent, v1alpha1.KindMCPServer, etc.). Downstream
	// builds wire their RBAC engine here so reader / publisher / admin
	// gates fire on the OSS-registered Agent / MCPServer / Skill /
	// Prompt / Runtime / Deployment endpoints. Missing keys behave
	// like "no per-kind gate" — the resource handler's default permits
	// the call, with API-level authn middleware still applying.
	Authorizers map[string]Authorizer

	// ListFilters injects per-kind ExtraWhere predicates into
	// list queries. Use this for row-level visibility (e.g. RBAC
	// filtering: a reader without a grant for a given resource never
	// sees the row in a list response). The (string, []any) tuple is
	// passed straight through to v1alpha1store.ListOpts.ExtraWhere /
	// ExtraArgs — see that docstring for placeholder rules.
	ListFilters map[string]ListFilter

	// PostUpserts run after the generic resource handler PUTs a
	// row, per kind. Downstream applications wire this for kinds that need
	// runtime side-effects on apply — Runtime apply mirroring spec
	// into a per-type sidecar table, for example. Missing keys =
	// no post-upsert hook for that kind.
	//
	// Hook errors fail the request with 500 (the row is already
	// persisted, so a hook failure indicates degraded state).
	PostUpserts map[string]PostUpsert

	// PostDeletes mirror PostUpserts on the delete path.
	PostDeletes map[string]PostDelete

	// Prepares run per-kind after validation and before Store.Upsert on
	// both the dedicated PUT route and the batch /v0/apply path. Keyed by
	// canonical Kind. Used to mutate the decoded object before persistence
	// (e.g. strip sensitive spec fields). Missing keys = no prepare
	// hook for that kind.
	Prepares map[string]Prepare

	// Admission optionally accepts a validated write before the row reaches
	// production storage. Nil preserves normal direct writes.
	// TODO(controller): temporary synchronous-handler bridge; remove with
	// reconciler admission/staging.
	Admission Admission

	// DeleteAdmission optionally accepts an authorized delete before the row is
	// removed from production storage. Nil preserves normal direct deletes.
	// TODO(controller): temporary synchronous-handler bridge; remove with
	// reconciler admission/staging.
	DeleteAdmission DeleteAdmission

	// ResolverWrapper decorates the shared ResourceRef resolver before route
	// registration. Nil preserves the default store-backed resolver.
	// TODO(controller): temporary bridge for pending staged refs in HTTP apply.
	ResolverWrapper func(v1alpha1.ResolverFunc) v1alpha1.ResolverFunc

	// V1Alpha1StoreTables registers additional v1alpha1 kinds with their
	// backing PostgreSQL tables. Downstream builds that add their own
	// Scheme kinds should populate this so the shared /v0/apply,
	// resolver, and generic route plumbing can see the same store map
	// as any ExtraRoutes they register.
	//
	// A bare "table" resolves in the OSS schema. To place a kind in
	// another schema, qualify the value as "schema.table"; the schema
	// segment must be a valid lowercase identifier (^[a-z_][a-z0-9_]*$)
	// or server startup panics.
	V1Alpha1StoreTables map[string]string

	// V1Alpha1MutableStoreKinds marks extra v1alpha1 kinds that use mutable
	// namespace/name object behavior instead of tagged artifact semantics.
	// Downstream control-plane/config kinds are v1alpha1-shaped but are not
	// content artifacts.
	V1Alpha1MutableStoreKinds map[string]bool

	// RegistryValidator overrides the per-package registry
	// validator (the dispatcher consulted on apply to confirm
	// each declared package — npm / pypi / oci — exists
	// and (for OCI) carries the
	// `LABEL io.modelcontextprotocol.server.name` ownership annotation
	// proving the publisher controls the OCI namespace).
	//
	// Default (nil) is registries.Dispatcher, which fans out to every
	// per-registry validator and matches the public-catalogue contract
	// the upstream modelcontextprotocol/registry project ships. That's
	// the right behavior for the OSS public catalogue but not for
	// private deployments where:
	//
	//   - images live in private ECR / GCR / ACR that anonymous fetch
	//     can't reach;
	//   - server names aren't claims against a public namespace, so the
	//     ownership-annotation requirement is moot;
	//   - synthetic test names mean no public image can satisfy the
	//     annotation match.
	//
	// Pass a custom RegistryValidatorFunc to filter out origin types
	// the build doesn't want enforced (e.g. wrap registries.Dispatcher
	// and short-circuit when origin.OCI != nil), or pass an explicit
	// no-op (`func(...) error { return nil }`) to disable per-package
	// registry validation entirely. Cross-kind ResourceRef checks still
	// run regardless.
	RegistryValidator v1alpha1.RegistryValidatorFunc

	// ExtraRoutes allows external integrations to register additional HTTP
	// routes using the same API instance and path prefix as OSS core
	// routes.
	ExtraRoutes func(api huma.API, pathPrefix string)

	// ExtraResourceRoutes is like ExtraRoutes, but runs after the v1alpha1
	// resource route context has been finalized.
	// TODO(controller): temporary bridge for downstream synchronous approval routes.
	ExtraResourceRoutes func(api huma.API, pathPrefix string, ctx ResourceRouteContext)

	// HTTPServerFactory is an optional function to create a server that
	// adds new API routes.
	HTTPServerFactory HTTPServerFactory

	// OnHTTPServerCreated is an optional callback that receives the
	// created server (potentially extended via HTTPServerFactory).
	OnHTTPServerCreated func(Server)

	// UIHandler is an optional HTTP handler for serving a custom UI at
	// the root path ("/"). If provided, this handler will be used instead
	// of the default redirect to docs. API routes will still take
	// precedence over the UI handler.
	UIHandler http.Handler

	// AuthnProvider is an optional authentication provider. Nil disables HTTP
	// authentication middleware, which is the permissive default.
	AuthnProvider auth.AuthnProvider

	// AuthzProvider is an optional authorization provider. Nil selects the
	// permissive default provider.
	AuthzProvider auth.AuthzProvider

	// MCPProtectedResourceMetadata, when non-nil, makes the MCP bridge serve
	// RFC 9728 protected-resource metadata at the well-known path. Nil disables
	// OAuth discovery. Authentication and authorization enforcement are
	// determined by the configured providers.
	MCPProtectedResourceMetadata *oauthex.ProtectedResourceMetadata

	// MCPResourceMetadataURL is the external URL of that metadata document,
	// emitted as the resource_metadata parameter of the bridge's 401
	// WWW-Authenticate challenge. Empty omits the hint.
	MCPResourceMetadataURL string

	// MCPAuthnProvider optionally overrides AuthnProvider for the MCP bridge
	// only, letting a build apply bridge-specific validation (e.g. audience
	// binding to the MCP resource). Nil falls back to AuthnProvider.
	MCPAuthnProvider auth.AuthnProvider

	// Auditor receives audit events from the v1alpha1 store layer
	// (e.g. ResourceTagCreated on Upsert creates). The default OSS
	// behavior is a no-op; downstream builds plug in a real audit sink.
	// If nil, NoopAuditor is used.
	Auditor Auditor

	// InitialFinalizers seeds finalizers atomically on create for kinds
	// whose external teardown must be protected from a concurrent delete.
	InitialFinalizers map[string]func(v1alpha1.Object) []string
}

type ApplyDependencySnapshot struct {
	Kind         string `json:"kind"`
	Namespace    string `json:"namespace,omitempty"`
	Name         string `json:"name"`
	Tag          string `json:"tag,omitempty"`
	UID          string `json:"uid,omitempty"`
	Generation   int64  `json:"generation,omitempty"`
	MaterialHash string `json:"materialHash,omitempty"`
}

type ApplyFingerprintOptions struct {
	AdapterType  string
	Dependencies []v1alpha1.Object
	Extra        any
}

type ApplyFingerprintResult struct {
	Fingerprint  string
	Dependencies []ApplyDependencySnapshot
}

type ApplyInput struct {
	// Deployment is the resource being applied.
	Deployment *v1alpha1.Deployment

	// Target is the resolved TargetRef — either *v1alpha1.Agent or
	// *v1alpha1.MCPServer. Adapters type-switch on it.
	Target v1alpha1.Object

	// Runtime is the resolved RuntimeRef.
	Runtime *v1alpha1.Runtime

	// Resolver is passed so adapters can check nested ref existence
	// mid-Apply (blank-namespace refs inherit from the referencing
	// object — same rules as v1alpha1.Object ResolveRefs).
	Resolver v1alpha1.ResolverFunc

	// Getter fetches the typed Object for a ResourceRef. Adapters use
	// this when they need the target's Spec (not just an existence
	// check) — for example, resolving a Deployment's effective ModelRef or
	// walking AgentSpec.MCPServers to build agentgateway upstream config.
	Getter v1alpha1.GetterFunc
}

type ApplyResult struct {
	// Conditions to merge into Deployment.Status via
	// Store.PatchStatus. Canonical types:
	//   - "Progressing" — workload is being created/updated
	//   - "Ready"       — workload is running + serving
	//   - "RuntimeConfigured" — Runtime.Config parsed and connectable
	//   - "Degraded"    — transient failure, will retry
	Conditions []v1alpha1.Condition

	// RuntimeMetadata carries adapter-internal state to persist
	// into Deployment.Metadata.Annotations (keyed under
	// runtimes.agentregistry.solo.io/<type>/*). Callers marshal
	// to string values since Annotations is map[string]string.
	RuntimeMetadata map[string]string

	// Details is a map of top-level keys to JSON-encoded values to merge into
	// Deployment.Status.Details via Status.SetDetailsKeyJSON. Each adapter owns its
	// own top-level key; other keys in Status.Details are preserved across
	// the patch. A nil value at a key removes that key.
	//
	// Use Details for structured state that Conditions cannot express cleanly;
	// stable, typed status should still be modeled as Conditions.
	Details map[string]json.RawMessage
}

type Auditor interface {
	// ResourceTagCreated is invoked when Store.Upsert creates a new tag row
	// for a content-registry kind. Mutable-object kinds do not produce this
	// event.
	ResourceTagCreated(ctx context.Context, kind, namespace, name, tag string)
}

type AuthorizeInput struct {
	// Verb is one of "get", "list", "apply", "delete".
	Verb string
	// Kind is the canonical Kind name (v1alpha1.KindAgent, etc.).
	Kind string
	// Namespace is the URL-scoped namespace; "" for cross-namespace list.
	Namespace string
	// Name is the resource name; "" for list verbs.
	Name string
	// Tag is the resource tag for content kinds; "" for list/get-latest.
	Tag string
}

type Authorizer func(ctx context.Context, in AuthorizeInput) error

type CLITokenProvider interface {
	// Token returns a token for API calls.
	Token(ctx context.Context) (token string, err error)
}

type CLITokenProviderFactory func(root *cobra.Command) (CLITokenProvider, error)

type DatabaseFactory func(ctx context.Context, databaseURL string, baseStore database.Store, authz auth.Authorizer) (database.Store, error)

type DeleteAdmission func(ctx context.Context, in DeleteAdmissionInput) (DeleteAdmissionResult, error)

type DeleteAdmissionInput struct {
	Source     string
	Verb       string
	DryRun     bool
	Kind       string
	Namespace  string
	Name       string
	Tag        string
	Object     v1alpha1.Object
	Store      any
	PostDelete PostDelete
}

type DeleteAdmissionResult struct {
	Status string
	Tag    string
}

type DeploymentAdapter interface {
	// Type returns the canonical CamelCase discriminator string
	// ("Local", "Kubernetes", "BedrockAgentCore", ...). Runtime.Validate
	// canonicalizes Spec.Type at admission, so the reconciler's adapter
	// lookup compares Type() against Spec.Type with exact-match equality.
	Type() string

	// SupportedTargetKinds lists the v1alpha1 Kinds this adapter can
	// deploy. Typically []string{KindAgent, KindMCPServer}. Used by
	// the reconciler to early-reject a Deployment whose TargetRef
	// points at a kind the adapter doesn't handle.
	SupportedTargetKinds() []string

	// Apply ensures the Deployment's runtime matches its desired
	// state. DesiredState == "deployed" or "" (default) ⇒ run.
	// DesiredState == "undeployed" ⇒ reconciler routes to Remove
	// directly; adapters can assume Apply is only called with a
	// run-intent.
	//
	// Idempotent. Safe to call repeatedly with the same input.
	// Returns the initial conditions to persist (typically
	// Progressing=True). The adapter's async watch loop later refines
	// the conditions via PatchStatus.
	Apply(ctx context.Context, in ApplyInput) (*ApplyResult, error)

	// Remove tears down runtime resources. Called when:
	//   - Deployment.Metadata.DeletionTimestamp != nil (soft-delete)
	//   - Deployment.Spec.DesiredState == "undeployed"
	// Idempotent: safe to call when nothing exists. Row lifetime is
	// owned by the soft-delete + GC path; the adapter only handles
	// external-state teardown.
	Remove(ctx context.Context, in RemoveInput) (*RemoveResult, error)

	// Logs streams runtime logs from the deployed workload. The
	// returned channel closes when streaming ends; caller cancels via
	// ctx.
	Logs(ctx context.Context, in LogsInput) (<-chan LogLine, error)
}

type DeploymentDesiredFingerprinter interface {
	DesiredFingerprint(ctx context.Context, in ApplyInput) (string, error)
}

type DeploymentDiscoverySource interface {
	Discover(ctx context.Context, in DiscoverInput) ([]DiscoveryResult, error)
}

type DiscoverInput struct {
	Runtime *v1alpha1.Runtime
}

type DiscoveryResult struct {
	// TargetKind is the v1alpha1 Kind this workload looks like —
	// Agent or MCPServer. Empty if the adapter can't infer.
	TargetKind string
	// Namespace, Name, Tag identify the workload in the
	// registry's naming scheme. Blank fields mean "unmanaged" —
	// workload exists on the runtime but has no corresponding
	// Deployment row.
	Namespace string
	Name      string
	Tag       string
	// RuntimeMetadata mirrors what Apply writes so the caller can
	// correlate this discovery with an existing Deployment's
	// annotations.
	RuntimeMetadata map[string]string
}

type EmptyResponse struct {
	Message string `json:"message" doc:"Success message" example:"Operation completed successfully"`
}

type HTTPServerFactory func(base Server, store database.Store) Server

type ListFilter func(ctx context.Context, in AuthorizeInput) (extraWhere string, extraArgs []any, err error)

type LogLine struct {
	Timestamp time.Time
	Stream    string // "stdout" | "stderr" | runtime-specific
	Line      string
}

type LogsInput struct {
	Deployment *v1alpha1.Deployment
	// Follow ⇒ stream indefinitely until ctx is cancelled. !Follow ⇒
	// return the available backlog and close.
	Follow bool
	// TailLines bounds the initial backlog; 0 means unbounded.
	TailLines int
}

type PostDelete func(ctx context.Context, obj v1alpha1.Object) error

type PostUpsert func(ctx context.Context, obj v1alpha1.Object) error

type Prepare func(ctx context.Context, obj v1alpha1.Object) error

type RemoveInput struct {
	Deployment *v1alpha1.Deployment
	Runtime    *v1alpha1.Runtime
}

type RemoveResult struct {
	// Conditions to merge into Deployment.Status (typically
	// Progressing with Reason="Terminating", then Ready=False with
	// Reason="Removed" on completion).
	Conditions []v1alpha1.Condition
}

type ResourceRouteContext struct {
	Stores            map[string]any
	Resolver          v1alpha1.ResolverFunc
	RegistryValidator v1alpha1.RegistryValidatorFunc
	Apply             func(ctx context.Context, obj v1alpha1.Object, dryRun bool) v0.ApplyResult
	Delete            func(ctx context.Context, obj v1alpha1.Object, dryRun bool) v0.ApplyResult
}

type Response[T any] struct {
	Body T
}

type RuntimeAdapter interface {
	// Type returns the canonical CamelCase discriminator string
	// ("Local", "Kubernetes", "BedrockAgentCore", "GeminiAgentRuntime",
	// ...). Runtime.Validate canonicalizes Spec.Type at admission so
	// dispatch can compare with exact-match equality.
	Type() string

	// ApplyRuntime runs after the v1alpha1 store has persisted a
	// Runtime on PUT or batch apply. Must be idempotent — re-apply
	// with rotated config must converge sidecar state, not error.
	ApplyRuntime(ctx context.Context, runtime *v1alpha1.Runtime) error

	// RemoveRuntime runs after the v1alpha1 store has soft-deleted a
	// Runtime. runtimeID is the metadata.name (the v1alpha1 row's
	// stable identity). Must tolerate missing sidecar rows for
	// idempotency.
	RemoveRuntime(ctx context.Context, runtimeID string) error
}

type Server interface {
	// HumaAPI returns the Huma API instance, allowing registration of new
	// routes that will appear in the OpenAPI documentation.
	HumaAPI() huma.API

	// Mux returns the HTTP ServeMux, allowing registration of custom HTTP
	// handlers.
	Mux() *http.ServeMux

	// Start begins listening for incoming HTTP requests.
	Start() error

	// Shutdown gracefully shuts down the server.
	Shutdown(ctx context.Context) error
}