kubernetesx

type APIResource struct {
	Group      string   `json:"group"`
	Version    string   `json:"version"`
	Kind       string   `json:"kind"`
	Namespaced bool     `json:"namespaced"`
	Verbs      []string `json:"verbs"`
}

type AccessReview struct {
	CanView   bool `json:"can_view"`
	CanCreate bool `json:"can_create"`
	CanUpdate bool `json:"can_update"`
	CanDelete bool `json:"can_delete"`
	// ReadOnly is true when CanCreate/CanUpdate/CanDelete are all false but
	// CanView is true. Hub labels such clusters as read-only.
	ReadOnly bool `json:"read_only"`
}

type AddToScheme = func(*runtime.Scheme) error

type ApplyOptions struct {
	// FieldManager is the SSA field owner. Each AISphere resource class
	// (namespace, sandbox, workload, network) should use its own manager so
	// that the API server tracks field ownership per concern.
	FieldManager string

	// ForceOwnership, when true, re-acquires fields owned by other managers
	// during apply. Use only for fields AISphere exclusively owns; never
	// set it to silently overwrite a collaborator (HPA, operator, …).
	ForceOwnership bool

	// DryRun, when true, validates the apply without persisting. The API
	// server still reports conflicts.
	DryRun bool
}

type Capabilities struct {
	ServerVersion VersionInfo   `json:"server_version"`
	APIs          []APIResource `json:"apis"`
}

type Client interface {
	Get(ctx context.Context, key ctrlclient.ObjectKey, obj ctrlclient.Object, opts ...ctrlclient.GetOption) error
	List(ctx context.Context, list ctrlclient.ObjectList, opts ...ctrlclient.ListOption) error
	Create(ctx context.Context, obj ctrlclient.Object, opts ...ctrlclient.CreateOption) error
	Update(ctx context.Context, obj ctrlclient.Object, opts ...ctrlclient.UpdateOption) error
	Patch(ctx context.Context, obj ctrlclient.Object, patch ctrlclient.Patch, opts ...ctrlclient.PatchOption) error
	Delete(ctx context.Context, obj ctrlclient.Object, opts ...ctrlclient.DeleteOption) error

	// Apply runs SSA on a typed object. Field ownership conflicts surface as
	// KUBERNETES_FIELD_CONFLICT via NormalizeError; they are never silently
	// overwritten.
	Apply(ctx context.Context, obj ctrlclient.Object, opts ApplyOptions) error

	// ApplyUnstructured runs SSA on an *unstructured.Unstructured, used for
	// third-party CRDs that have no generated Go type.
	ApplyUnstructured(ctx context.Context, obj ctrlclient.Object, opts ApplyOptions) error

	ServerVersion(ctx context.Context) (VersionInfo, error)
	Discover(ctx context.Context) (Capabilities, error)
	Probe(ctx context.Context, req ProbeRequest) (ProbeResult, error)

	Scheme() *runtime.Scheme
	RESTConfig() *rest.Config
	Dynamic() dynamic.Interface
	Discovery() discovery.DiscoveryInterface
}

type Config struct {
	// Host is the API server URL, e.g. "https://10.0.0.1:6443".
	// Required when Kubeconfig is empty and the process is not in-cluster.
	Host string `json:"host"`

	// ServerName overrides the TLS hostname used to verify the API server
	// certificate. Use it when Host is an IP address but the server
	// certificate is signed for a DNS name (e.g. Hub reaches a remote
	// cluster via a public IP while the cluster cert SAN only lists the
	// in-cluster domain). Setting ServerName preserves CA verification —
	// it does NOT disable TLS. Empty means the hostname is derived from
	// Host. Ignored when Kubeconfig is supplied unless the caller also
	// sets it explicitly after MergeCredential.
	ServerName string `json:"server_name"`

	// Kubeconfig is the raw kubeconfig YAML. When non-empty it takes priority
	// over Host for constructing *rest.Config. The selected context is
	// controlled by Context.
	Kubeconfig []byte `json:"kubeconfig,omitempty"`

	// Context selects the kubeconfig context to use. Empty means the
	// current-context of the kubeconfig.
	Context string `json:"context"`

	// Token is the bearer token used when authenticating with a
	// CredentialKindServiceAccount credential. Populated by MergeCredential;
	// ignored when Kubeconfig is non-empty. Like Kubeconfig, this field
	// carries secret material and must not be logged.
	Token string `json:"token,omitempty"`

	// CACert is the PEM-encoded CA certificate used to verify the API server
	// TLS certificate when authenticating with a service-account credential.
	// Populated by MergeCredential; ignored when Kubeconfig is non-empty.
	CACert []byte `json:"ca_cert,omitempty"`

	// QPS is the API server request rate limit. Zero leaves the client-go
	// default (5). Hub typically sets 50–100.
	QPS float32 `json:"qps"`

	// Burst is the burst budget above QPS. Zero leaves the client-go
	// default (10).
	Burst int `json:"burst"`

	// Timeout is the per-request timeout applied to the REST client. Zero
	// means no explicit timeout (rely on context deadline).
	Timeout time.Duration `json:"timeout_ns"`

	// UserAgent is sent as the User-Agent header. Empty defaults to
	// "aisphere-kubernetesx".
	UserAgent string `json:"user_agent"`

	// FieldManager is the default SSA field manager used by Apply when
	// ApplyOptions.FieldManager is empty. Defaults to "aisphere-hub".
	FieldManager string `json:"field_manager"`

	// InsecureSkipVerify disables TLS certificate verification. This is
	// dangerous and intended only for local dev clusters. Production must
	// leave it false.
	InsecureSkipVerify bool `json:"insecure_skip_verify"`

	// Logger is the component logger. If nil, kubernetesx uses
	// logx.DefaultLogger().
	Logger logx.Logger `json:"-" yaml:"-"`

	// Metrics is the optional metrics manager for kubernetesx operations.
	// A nil Manager is a valid no-op.
	Metrics metricsx.Manager `json:"-" yaml:"-"`

	// MetricsEnabled controls whether kubernetesx operations record metrics.
	MetricsEnabled bool `json:"metrics_enabled" yaml:"metrics_enabled"`
}

type Credential struct {
	// Kind selects the authentication strategy. Required.
	Kind CredentialKind `json:"kind"`

	// Kubeconfig is the raw kubeconfig YAML. Required when Kind ==
	// KUBECONFIG. Ignored otherwise.
	Kubeconfig []byte `json:"kubeconfig,omitempty"`

	// Context selects the kubeconfig context. Optional; empty means the
	// kubeconfig current-context.
	Context string `json:"context"`

	// Host is the API server URL. Required when Kind == SERVICE_ACCOUNT.
	Host string `json:"host"`

	// Token is the bearer token. Required when Kind == SERVICE_ACCOUNT.
	Token string `json:"token"`

	// CACert is the PEM-encoded CA certificate that signs the API server
	// cert. Optional; when empty the system roots are used (or
	// InsecureSkipVerify from Config).
	CACert []byte `json:"ca_cert"`
}

type CredentialKind string

type Option func(*options)

type ProbeRequest struct {
	// SkipAccessReview, when true, skips the create/update/delete
	// SelfSubjectAccessReview calls. Use this for cheap reachability checks
	// where the access matrix is already known.
	SkipAccessReview bool

	// Namespace is the namespace used as the subject of the access review.
	// Empty means a cluster-scoped review (namespace create/delete are
	// cluster-scoped; update is reviewed against this namespace when set).
	Namespace string
}

type ProbeResult struct {
	Reachable       bool          `json:"reachable"`
	ServerVersion   VersionInfo   `json:"server_version"`
	ClusterUID      string        `json:"cluster_uid"`
	APIs            []APIResource `json:"apis"`
	NamespaceAccess AccessReview  `json:"namespace_access"`
	Latency         time.Duration `json:"latency_ns"`
	Warnings        []string      `json:"warnings"`
}

type VersionInfo struct {
	Major      string `json:"major"`
	Minor      string `json:"minor"`
	GitVersion string `json:"git_version"`
	Platform   string `json:"platform"`
}