advanced

type ClusterAccessReconciler interface {
	// Register registers a cluster to be managed by the reconciler.
	// No-op if reg is nil.
	// Overwrites any previous registration with the same ID.
	Register(reg ClusterRegistration) ClusterAccessReconciler
	// Unregister unregisters a cluster from being managed by the reconciler.
	// No-op if no registration with the given ID exists.
	Unregister(id string) ClusterAccessReconciler
	// WithRetryInterval sets the retry interval.
	WithRetryInterval(interval time.Duration) ClusterAccessReconciler
	// WithManagedLabels allows to overwrite the managed-by and managed-purpose labels that are set on the created resources.
	// Note that the implementation might depend on these labels to identify the resources it created,
	// so changing them might lead to unexpected behavior. They also must be unique within the context of this reconciler.
	// Use with caution.
	WithManagedLabels(gen ManagedLabelGenerator) ClusterAccessReconciler

	// Access returns an internal Cluster object granting access to the cluster for the specified request with the specified id.
	// Will fail if the cluster is not registered or no AccessRequest is registered for the cluster, or if some other error occurs.
	Access(ctx context.Context, request reconcile.Request, id string, additionalData ...any) (*clusters.Cluster, error)
	// AccessRequest fetches the AccessRequest object for the cluster for the specified request with the specified id.
	// Will fail if the cluster is not registered or no AccessRequest is registered for the cluster, or if some other error occurs.
	// The same additionalData must be passed into all methods of this ClusterAccessReconciler for the same request and id.
	AccessRequest(ctx context.Context, request reconcile.Request, id string, additionalData ...any) (*clustersv1alpha1.AccessRequest, error)
	// ClusterRequest fetches the ClusterRequest object for the cluster for the specified request with the specified id.
	// Will fail if the cluster is not registered or no ClusterRequest is registered for the cluster, or if some other error occurs.
	// The same additionalData must be passed into all methods of this ClusterAccessReconciler for the same request and id.
	ClusterRequest(ctx context.Context, request reconcile.Request, id string, additionalData ...any) (*clustersv1alpha1.ClusterRequest, error)
	// Cluster fetches the external Cluster object for the cluster for the specified request with the specified id.
	// Will fail if the cluster is not registered or no Cluster can be determined, or if some other error occurs.
	// The same additionalData must be passed into all methods of this ClusterAccessReconciler for the same request and id.
	Cluster(ctx context.Context, request reconcile.Request, id string, additionalData ...any) (*clustersv1alpha1.Cluster, error)

	// Reconcile creates the ClusterRequests and/or AccessRequests for the registered clusters.
	// This function should be called during all reconciliations of the reconciled object.
	// ctx is the context for the reconciliation.
	// request is the object that is being reconciled
	// It returns a reconcile.Result and an error if the reconciliation failed.
	// The reconcile.Result may contain a RequeueAfter value to indicate that the reconciliation should be retried after a certain duration.
	// The duration is set by the WithRetryInterval method.
	// Any additional arguments provided are passed into all methods of the ClusterRegistration objects that are called.
	Reconcile(ctx context.Context, request reconcile.Request, additionalData ...any) (reconcile.Result, error)
	// ReconcileDelete deletes the ClusterRequests and/or AccessRequests for the registered clusters.
	// This function should be called during the deletion of the reconciled object.
	// ctx is the context for the reconciliation.
	// request is the object that is being reconciled
	// It returns a reconcile.Result and an error if the reconciliation failed.
	// The reconcile.Result may contain a RequeueAfter value to indicate that the reconciliation should be retried after a certain duration.
	// The duration is set by the WithRetryInterval method.
	// Any additional arguments provided are passed into all methods of the ClusterRegistration objects that are called.
	ReconcileDelete(ctx context.Context, request reconcile.Request, additionalData ...any) (reconcile.Result, error)

	// WithFakingCallback passes a callback function with a specific key.
	// The available keys depend on the implementation.
	// The key determines when the callback function is executed.
	// This feature is meant for unit testing, where usually no ClusterProvider, which could answer ClusterRequests and AccessRequests, is running.
	WithFakingCallback(key string, callback FakingCallback) ClusterAccessReconciler
}

type ClusterRegistration interface {
	// ID is the unique identifier for the cluster.
	ID() string
	// Suffix is the suffix to be used for the names of the created resources.
	// It must be unique within the context of the reconciler.
	// If empty, the ID will be used as suffix.
	Suffix() string
	// Scheme is the scheme for the Kubernetes client of the cluster.
	// If nil, the default scheme will be used.
	Scheme() *runtime.Scheme
	// AccessRequestAvailable returns true if an AccessRequest can be retrieved from this registration.
	AccessRequestAvailable() bool
	// ClusterRequestAvailable returns true if a ClusterRequest can be retrieved from this registration.
	ClusterRequestAvailable() bool
	// Parameterize turns this ClusterRegistration into a ParamterizedClusterRegistration.
	Parameterize(req reconcile.Request, additionalData ...any) ParameterizedClusterRegistration
}

type ClusterRegistrationBuilder interface {
	// WithTokenAccess enables an AccessRequest for token-based access to be created for the cluster.
	// Use this method, if the token configuration does not depend on the reconcile request, use WithTokenAccessGenerator otherwise.
	// Calling this method will override any previous calls to WithTokenAccess, WithTokenAccessGenerator, WithOIDCAccess, or WithOIDCAccessGenerator.
	// Passing in a nil cfg will disable AccessRequest creation, if it was token-based before, and have no effect if it was OIDC-based before.
	WithTokenAccess(cfg *clustersv1alpha1.TokenConfig) ClusterRegistrationBuilder
	// WithTokenAccessGenerator is like WithTokenAccess, but takes a function that generates the TokenConfig based on the reconcile request.
	// Calling this method will override any previous calls to WithTokenAccess, WithTokenAccessGenerator, WithOIDCAccess, or WithOIDCAccessGenerator.
	// Passing in a nil function will disable AccessRequest creation, if it was token-based before, and have no effect if it was OIDC-based before.
	WithTokenAccessGenerator(f func(req reconcile.Request, additionalData ...any) (*clustersv1alpha1.TokenConfig, error)) ClusterRegistrationBuilder
	// WithOIDCAccess enables an AccessRequest for OIDC-based access to be created for the cluster.
	// Use this method, if the OIDC configuration does not depend on the reconcile request, use WithOIDCAccessGenerator otherwise.
	// Calling this method will override any previous calls to WithTokenAccess, WithTokenAccessGenerator, WithOIDCAccess, or WithOIDCAccessGenerator.
	// Passing in a nil cfg will disable AccessRequest creation, if it was OIDC-based before, and have no effect if it was token-based before.
	WithOIDCAccess(cfg *clustersv1alpha1.OIDCConfig) ClusterRegistrationBuilder
	// WithOIDCAccessGenerator is like WithOIDCAccess, but takes a function that generates the OIDCConfig based on the reconcile request.
	// Calling this method will override any previous calls to WithTokenAccess, WithTokenAccessGenerator, WithOIDCAccess, or WithOIDCAccessGenerator.
	// Passing in a nil function will disable AccessRequest creation, if it was OIDC-based before, and have no effect if it was token-based before.
	WithOIDCAccessGenerator(f func(req reconcile.Request, additionalData ...any) (*clustersv1alpha1.OIDCConfig, error)) ClusterRegistrationBuilder
	// WithScheme sets the scheme for the Kubernetes client of the cluster.
	// If not set or set to nil, the default scheme will be used.
	WithScheme(scheme *runtime.Scheme) ClusterRegistrationBuilder
	// WithNamespaceGenerator sets the function that generates the namespace on the Platform cluster to use for the created requests.
	WithNamespaceGenerator(f func(req reconcile.Request, additionalData ...any) (string, error)) ClusterRegistrationBuilder
	// Build builds the ClusterRegistration object.
	Build() ClusterRegistration
}

type ClusterRequestSpecGenerator func(req reconcile.Request, additionalData ...any) (*clustersv1alpha1.ClusterRequestSpec, error)

type FakingCallback func(ctx context.Context, platformClusterClient client.Client, key string, req *reconcile.Request, cr *clustersv1alpha1.ClusterRequest, ar *clustersv1alpha1.AccessRequest, c *clustersv1alpha1.Cluster, access *clusters.Cluster) error

type ManagedLabelGenerator func(controllerName string, req reconcile.Request, reg ClusterRegistration) (string, string, map[string]string)

type ObjectReferenceGenerator func(req reconcile.Request, additionalData ...any) (*commonapi.ObjectReference, error)

type ParameterizedClusterRegistration interface {
	ClusterRegistration

	// AccessRequestTokenConfig is the token configuration for the AccessRequest to be created for the cluster.
	// Might be nil if no AccessRequest should be created or if OIDC access is used.
	// Only one of AccessRequestTokenConfig and AccessRequestOIDCConfig should be non-nil.
	AccessRequestTokenConfig() (*clustersv1alpha1.TokenConfig, error)
	// AccessRequestOIDCConfig is the OIDC configuration for the AccessRequest to be created for the cluster.
	// Might be nil if no AccessRequest should be created or if token-based access is used.
	// Only one of AccessRequestTokenConfig and AccessRequestOIDCConfig should be non-nil.
	AccessRequestOIDCConfig() (*clustersv1alpha1.OIDCConfig, error)
	// ClusterRequestSpec is the spec for the ClusterRequest to be created for the cluster.
	// It is nil if no ClusterRequest should be created.
	// Only one of ClusterRequestSpec, ClusterReference and ClusterRequestReference should be non-nil.
	ClusterRequestSpec() (*clustersv1alpha1.ClusterRequestSpec, error)
	// ClusterReference returns name and namespace of an existing Cluster resource.
	// It is nil if a new ClusterRequest should be created or if the Cluster is referenced by an existing ClusterRequest.
	// Only one of ClusterRequestSpec, ClusterReference and ClusterRequestReference should be non-nil.
	ClusterReference() (*commonapi.ObjectReference, error)
	// ClusterRequestReference returns name and namespace of the ClusterRequest resource.
	// It is nil if a new ClusterRequest should be created or if the Cluster is referenced directly.
	// Only one of ClusterRequestSpec, ClusterReference and ClusterRequestReference should be non-nil.
	ClusterRequestReference() (*commonapi.ObjectReference, error)
	// Namespace generates the namespace on the Platform cluster to use for the created requests.
	// The generated namespace is expected be unique within the context of the reconciler.
	Namespace() (string, error)
}