bundleapply

type Bundle struct {
	// Objects in apply order: cluster-scoped prerequisites (Namespaces,
	// CRDs, RBAC) first, then namespaced workloads.
	Objects []*unstructured.Unstructured
}

type DeleteOptions struct {
	// Client is the Kubernetes surface to delete against (required).
	Client ResourceClient
	// Timeout bounds an optional wait for the deleted objects to actually
	// vanish (finalizers, garbage collection). Zero/negative skips the
	// wait entirely — the objects are deleted and the call returns
	// without confirming they are gone.
	Timeout time.Duration
	// PollInterval is how often the gone-check is re-run. Defaults to 2s.
	PollInterval time.Duration
	// Log receives progress lines. Defaults to no-op.
	Log Logf
}

type DeleteResult struct {
	// Deleted lists the objects (kind ns/name) this run removed — in
	// reverse apply order.
	Deleted []string
	// Failed lists objects that could NOT be deleted (with the reason).
	// A non-empty Failed always accompanies a non-nil error.
	Failed []string
	// Gone is the count confirmed absent after the wait (only meaningful
	// when Options.Timeout > 0).
	Gone int
}

type Logf func(format string, args ...any)

type ObjectStatus struct {
	Kind      string `json:"kind"`
	Namespace string `json:"namespace,omitempty"`
	Name      string `json:"name"`
	// Exists reports whether the object is present on the cluster at all.
	Exists bool `json:"exists"`
	// Ready reuses the exact rollout evaluation ApplyBundle's readiness
	// wait uses (evalReadiness) — a status Ready=true means the same
	// thing an apply's confirmed-ready count means.
	Ready bool `json:"ready"`
	// Reason is a short human string: why not-ready, why not-exists, or
	// the confirming detail when ready.
	Reason string `json:"reason,omitempty"`
	// Installer marks an object annotated outpost.dhnt.io/lifecycle=installer.
	// Its absence alone never decides installed-ness — the declared
	// outputs do (see the lifecycle contract in lifecycle.go).
	Installer bool `json:"installer,omitempty"`
	// DeclaredOutput marks a row synthesized from an installer's
	// outpost.dhnt.io/installs declaration rather than decoded from the
	// manifest — the durable post-install evidence being asserted.
	DeclaredOutput bool `json:"declared_output,omitempty"`
}

type Options struct {
	// Client is the Kubernetes surface to apply against (required).
	Client ResourceClient
	// Timeout bounds the readiness wait for the WHOLE bundle. Must be > 0
	// — a zero/negative timeout is rejected rather than treated as
	// "wait forever" (an unbounded wait can mask a stuck rollout).
	Timeout time.Duration
	// PollInterval is how often readiness is re-checked. Defaults to 2s
	// when unset.
	PollInterval time.Duration
	// CRDWaitTimeout bounds, per CRD, the wait for Established + the
	// served types appearing in discovery before dependent custom
	// resources are applied. Defaults to 60s when unset. Timing out is a
	// hard failure (ErrCRDNotReady), never "apply the CR and hope".
	CRDWaitTimeout time.Duration
	// AllowScaleToZero is the EXPLICIT opt-in that lets a workload with
	// zero desired replicas count as rolled out. Without it a
	// spec.replicas: 0 workload is a terminal failure — zero desired
	// satisfying "all replicas ready" is an absence-of-evidence green.
	AllowScaleToZero bool
	// DisableRollback keeps everything this run created in place on
	// failure, instead of the default best-effort cleanup. The result
	// still reports exactly what was created and left behind.
	DisableRollback bool
	// RollbackTimeout bounds the best-effort cleanup pass. Defaults to
	// 60s. The cleanup runs on a context detached from the caller's (a
	// cancelled apply must still get its bounded cleanup chance).
	RollbackTimeout time.Duration
	// Log receives progress lines. Defaults to no-op.
	Log Logf
}

type ResourceClient interface {
	// Apply performs an idempotent server-side apply of obj (create if
	// absent, reconcile if present) and returns the applied object.
	Apply(ctx context.Context, obj *unstructured.Unstructured) (*unstructured.Unstructured, error)
	// Get fetches the live object matching obj's GVK / namespace / name.
	// A missing object is reported as an error wrapping ErrNotFound so
	// the apply loop can tell "does not exist yet" (this run will create
	// it) from every other failure, which stays hard.
	Get(ctx context.Context, obj *unstructured.Unstructured) (*unstructured.Unstructured, error)
	// Delete removes the live object matching obj's GVK / namespace /
	// name. Deleting an object that is already gone is a success — the
	// rollback path must converge, not fight over who removed it.
	Delete(ctx context.Context, obj *unstructured.Unstructured) error
	// ServesGVK reports whether the apiserver's discovery currently
	// serves the given GroupVersionKind. Used to gate custom resources
	// behind their CRD actually being discoverable — an Established CRD
	// whose type has not reached the discovery cache still 404s.
	ServesGVK(ctx context.Context, gvk schema.GroupVersionKind) (bool, error)
}

type Result struct {
	Applied int
	Ready   int
	// Created lists the objects (kind ns/name) that did not exist before
	// this run applied them — the rollback set. Pre-existing objects this
	// run reconciled are never in here and are never deleted.
	Created []string
	// RolledBack lists the created objects the failure cleanup deleted.
	RolledBack []string
	// CleanupFailed lists created objects the cleanup could NOT delete
	// (with the reason) — these were left behind and the operator must
	// remove them by hand.
	CleanupFailed []string
}

type StatusOptions struct {
	// Client is the Kubernetes surface to read (required).
	Client ResourceClient
	// AllowScaleToZero mirrors Options.AllowScaleToZero: a workload with
	// spec.replicas: 0 reports Ready (scaled down on purpose) instead of
	// the terminal ErrZeroDesiredWorkload reason. Without it, a
	// zero-desired workload's Reason names the same terminal condition
	// ApplyBundle would have failed on — status never waits, it only
	// reports what a wait would have seen.
	AllowScaleToZero bool
}

type StatusResult struct {
	Objects []ObjectStatus
	// Installed is true only when every non-installer object exists on
	// the cluster AND every installer's declared durable outputs exist.
	// An installer's own absence never decides it (lifecycle contract).
	Installed bool
	// AllReady is true only when every asserted object — non-installer
	// bundle objects plus declared installer outputs — exists AND reports
	// Ready. A garbage-collected installer does not count against it; a
	// present-but-unready (e.g. failed) installer does.
	AllReady bool
}

type WaitOptions struct {
	Timeout          time.Duration
	PollInterval     time.Duration
	AllowScaleToZero bool
	Log              Logf
}