interfaces

import "github.com/k-orc/openstack-resource-controller/internal/controllers/generic/interfaces"

type APIObjectAdapter[orcObjectPT any, resourceSpecT any, filterT any] interface {
    // NOTE: the objects we generate which implement this interface all also
    // implement client.Object. Despite this, they fail at runtime when passed
    // to the controller-runtime client. Therefore we deliberately don't declare
    // this interface here to prevent accidental usage.
    metav1.Object

    GetObject() orcObjectPT

    GetManagementPolicy() orcv1alpha1.ManagementPolicy
    GetManagedOptions() *orcv1alpha1.ManagedOptions

    GetStatusID() *string
    GetResourceSpec() *resourceSpecT
    GetImportID() *string
    GetImportFilter() *filterT
}

type BaseResourceActuator[
    orcObjectPT interface {
        *orcObjectT
        client.Object
        orcv1alpha1.ObjectWithConditions
    }, orcObjectT any,
    osResourceT any,
] interface {
    // GetResourceID returns a string identifier for the OpenStack resource
    // managed by this actuator, typically the object's uuid. This is the value
    // stored in status.id.
    GetResourceID(osResource *osResourceT) string

    // GetOSResourceByID fetches this actuator's OpenStack resource by id.
    GetOSResourceByID(ctx context.Context, id string) (*osResourceT, error)

    // ListOSResourcesForAdoption is used to prevent resource leaks in the event
    // that we create an OpenStack resource, but fail to write its ID to the
    // object's status. It returns a set of resources which match what the
    // actuator would have created for this object. Ideally it should attempt to
    // do this match as accurately as possible, remembering that OpenStack does
    // not prevent the creation of objects with duplicate names.
    //
    // It is called in the creation flow immediately before creating a resource,
    // and in the deletion flow when deleting an object which has a finalizer
    // but no status.id.
    //
    // It returns 2 values:
    // - an iterator over the matching OpenStack resources
    // - a boolean indicating whether adoption should be considered for this object
    //
    // For example, we must return false for an object with no resource spec.
    ListOSResourcesForAdoption(ctx context.Context, orcObject orcObjectPT) (iter.Seq2[*osResourceT, error], bool)
}

type Controller interface {
    SetupWithManager(context.Context, ctrl.Manager, controller.Options) error
    GetName() string
}

type CreateResourceActuator[
    orcObjectPT interface {
        *orcObjectT
        client.Object
        orcv1alpha1.ObjectWithConditions
    }, orcObjectT any,
    filterT any,
    osResourceT any,
] interface {

    // ListOSResourcesForImport returns all OpenStack resources matching the
    // given resource import filter.
    ListOSResourcesForImport(ctx context.Context, orcObject orcObjectPT, filter filterT) ([]progress.ProgressStatus, iter.Seq2[*osResourceT, error], error)

    // CreateResource creates an OpenStack resource for the current object. It
    // will return successfully at most once for a managed object, at the time
    // it is created. See `ResourceReconciler` for how to modify an existing
    // object.
    //
    // CreateResource MUST NOT perform any action which can fail after creating
    // the primary OpenStack resource. Once the OpenStack resource exists this
    // method will not be called again, so any failure after creation of the
    // OpenStack resource is not safe.
    //
    // If further initialisation of a resource is required after creation, for
    // example a Neutron object whose tags cannot be set during creation, this
    // must be done by a reconciler instead.
    //
    // CreateResource MAY also perform other actions prior to creating the
    // primary OpenStack resource, e.g. creating dependent ORC objects. These
    // must be created idempotently, and must be created BEFORE creating the
    // OpenStack resource.
    //
    // CreateResource does not need to check if the resource already exists, as
    // that is done before it is called.
    //
    // If CreateResource cannot create the resource it MUST return either one or
    // more ProgressStatuses, or an error. If returning ProgressStatuses, these
    // MUST be sufficient to ensure that the object will be reconciled again at
    // an appropriate time.
    CreateResource(ctx context.Context, orcObject orcObjectPT) ([]progress.ProgressStatus, *osResourceT, error)
    // contains filtered or unexported methods
}

type DeleteResourceActuator[
    orcObjectPT interface {
        *orcObjectT
        client.Object
        orcv1alpha1.ObjectWithConditions
    }, orcObjectT any,
    osResourceT any,
] interface {

    // DeleteResource deletes the OpenStack resource owned by the current
    // object.
    //
    // The delete flow does not succeed until an attempt to get the resource
    // returns no results, so DeleteResource does not need to verify that
    // deletion has completed.
    //
    // DeleteResource SHOULD NOT return an error if the resource no longer exists.
    //
    // DeleteResource MAY also perform other actions prior to deleting the
    // OpenStack resource, e.g. deleting dependent ORC objects. These actions
    // must be performed idempotently, and must be performed BEFORE deleting the
    // OpenStack resource.
    //
    // If DeleteResource cannot delete the resource it MUST return either one or
    // more ProgressStatuses, or an error. If returning ProgressStatuses, these
    // MUST be sufficient to ensure that the objet will be reconciled again at
    // an appropriate time.
    DeleteResource(ctx context.Context, orcObject orcObjectPT, osResource *osResourceT) ([]progress.ProgressStatus, error)
    // contains filtered or unexported methods
}

type ORCApplyConfig[objectApplyPT any, statusApplyPT ORCStatusApplyConfig[statusApplyPT]] interface {
    WithUID(types.UID) objectApplyPT
    WithStatus(statusApplyPT) objectApplyPT
}

type ORCStatusApplyConfig[statusApplyPT any] interface {
    WithConditions(...*applyconfigv1.ConditionApplyConfiguration) statusApplyPT
    WithID(id string) statusApplyPT
}

type ReconcileResourceActuator[orcObjectPT, osResourceT any] interface {
    // GetResourceReconcilers returns zero or more ResourceReconcilers to be executed during the current reconcile.
    //
    // All ResourceReconcilers returned will be executed in the order returned.
    // They will all be passed the orcObject and osResource passed to
    // GetResourceReconcilers. Note therefore that any state changes performed
    // by earlier ResourceReconcilers may not be reflected in the objects passed
    // to later ones.
    //
    // Failure of a ResourceReconciler does not prevent execution of later
    // ResourceReconcilers. All ResourceReconcilers will be executed, and their
    // ProgressStatuses and errors aggregated.
    //
    // NOTE: Contrary to the typical Go idiom, GetResourceReconcilers may return
    // both valid results, and an error. In this case, all returned
    // ResourceReconcilers will still be executed. The error returned by
    // GetResourceReconcilers itself will be aggregated with those returned by
    // the ResourceReconcilers. An example situation in which
    // GetResourceReconcilers itself might fail is if it fetched a list of
    // objects and returned a separate ResourceReconciler for each of them.
    GetResourceReconcilers(ctx context.Context, orcObject orcObjectPT, osResource *osResourceT, controller ResourceController) ([]ResourceReconciler[orcObjectPT, osResourceT], error)
}

type ResourceController interface {
    GetName() string

    GetK8sClient() client.Client
    GetScopeFactory() scope.Factory
}

type ResourceHelperFactory[
    orcObjectPT interface {
        *orcObjectT
        client.Object
        orcv1alpha1.ObjectWithConditions
    }, orcObjectT any,
    resourceSpecT any, filterT any,
    osResourceT any,
] interface {
    // NewAPIObjectAdapter returns an APIObjectAdapter wrapping orcObject
    NewAPIObjectAdapter(orcObject orcObjectPT) APIObjectAdapter[orcObjectPT, resourceSpecT, filterT]

    // NewCreateActuator returns a CreateResourceActuator for the given
    // orcObject. If it is not able to return an actuator, it MUST return either
    // one or more ProgressStatuses, or an error. If returning ProgressStatuses,
    // these MUST ensure that the object will be reconciled again at an
    // appropriate time.
    NewCreateActuator(ctx context.Context, orcObject orcObjectPT, controller ResourceController) ([]progress.ProgressStatus, CreateResourceActuator[orcObjectPT, orcObjectT, filterT, osResourceT], error)

    // NewDeleteActuator returns a DeleteResourceActuator for the given
    // orcObject. If it is not able to return an actuator, it MUST return either
    // one or more ProgressStatuses, or an error. If returning ProgressStatuses,
    // these MUST ensure that the object will be reconciled again at an
    // appropriate time.
    //
    // Consider carefully whether a DeleteResourceActuator needs all the same
    // initialisation dependencies as a CreateResourceActuator. Consider that we
    // may want to delete a resource that is partially or not initialised, or
    // whose creation dependencies may no longer be in a healthy state.
    NewDeleteActuator(ctx context.Context, orcObject orcObjectPT, controller ResourceController) ([]progress.ProgressStatus, DeleteResourceActuator[orcObjectPT, orcObjectT, osResourceT], error)
}

type ResourceReconciler[orcObjectPT, osResourceT any] func(ctx context.Context, orcObject orcObjectPT, osResource *osResourceT) ([]progress.ProgressStatus, error)

type ResourceStatusWriter[objectPT orcv1alpha1.ObjectWithConditions, osResourcePT any, objectApplyPT ORCApplyConfig[objectApplyPT, statusApplyPT], statusApplyPT ORCStatusApplyConfig[statusApplyPT]] interface {
    // GetApplyConfig returns an ORCApplyConfig for this object for use in an
    // SSA transaction, initialised with a name and a namespace.
    GetApplyConfig(name, namespace string) objectApplyPT

    // ResourceAvailableStatus returns what the status of the Available
    // condition should be set to based on the observed state of the given
    // orcObject and osResource.
    ResourceAvailableStatus(orcObject objectPT, osResource osResourcePT) metav1.ConditionStatus

    // ApplyResourceStatus writes status.resource to the given status apply
    // configuration based on the given osResource
    ApplyResourceStatus(log logr.Logger, osResource osResourcePT, statusApply statusApplyPT)
}