database

type BaseDocument struct {
	ID string `json:"id,omitempty"`

	// https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/time-to-live
	TimeToLive int `json:"ttl,omitempty"`

	// System-defined properties generated by Cosmos DB
	CosmosResourceID  string      `json:"_rid,omitempty"`
	CosmosSelf        string      `json:"_self,omitempty"`
	CosmosETag        azcore.ETag `json:"_etag,omitempty"`
	CosmosAttachments string      `json:"_attachments,omitempty"`
	CosmosTimestamp   int         `json:"_ts,omitempty"`
}

type BillingDBClient interface {
	BillingDocs(subscriptionID string) BillingDocCRUD
	BillingGlobalListers() BillingGlobalListers
}

type BillingDocCRUD interface {
	// Create a new billing document
	Create(ctx context.Context, doc *BillingDocument) error

	// GetByID retrieves a billing document by its ID
	GetByID(ctx context.Context, billingDocID string) (*BillingDocument, error)

	// List returns an iterator for all billing documents in the given subscription partition.
	// This includes both active and deleted billing documents.
	List(ctx context.Context) (DBClientIterator[BillingDocument], error)

	// ListActive lists all active billing documents (without deletion time) for the subscription
	ListActive(ctx context.Context) ([]*BillingDocument, error)

	// ListActiveForCluster lists active billing documents for a specific cluster
	ListActiveForCluster(ctx context.Context, resourceID *azcorearm.ResourceID) ([]*BillingDocument, error)

	// PatchByID patches a billing document by its ID
	PatchByID(ctx context.Context, billingDocID string, ops BillingDocumentPatchOperations) error

	// PatchByClusterID patches all active billing documents for a cluster
	PatchByClusterID(ctx context.Context, resourceID *azcorearm.ResourceID, ops BillingDocumentPatchOperations) error
}

type BillingDocument struct {
	BaseDocument

	// The cluster creation time represents the time when the cluster was provisioned successfully
	CreationTime time.Time `json:"creationTime,omitempty"`
	// The cluster deletion time
	DeletionTime *time.Time `json:"deletionTime,omitempty"`

	// The location of the HCP cluster
	Location string `json:"location,omitempty"`
	// The tenant ID of the HCP cluster
	TenantID string `json:"tenantId,omitempty"`
	// The subscription ID of the HCP cluster (also the partition key)
	SubscriptionID string `json:"subscriptionId,omitempty"`
	// The HCP cluster ARM resource ID
	ResourceID *azcorearm.ResourceID `json:"resourceId,omitempty"`
	// The ARM resource ID of the managed resource group of the HCP cluster
	ManagedResourceGroup string `json:"managedResourceGroup,omitempty"`
}

type BillingDocumentList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	ResourceVersion string
	Items           []BillingDocument `json:"items"`
}

type BillingDocumentPatchOperations struct {
	azcosmos.PatchOperations
}

type BillingGlobalListers interface {
	BillingDocs() GlobalLister[BillingDocument]
}

type ClusterNestedResourceIDBuilder struct{}

type ControllerContainer interface {
	// TODO controllers are a concept that is at this scope and at lower scopes and sometimes you want to query all like it
	// TODO they look a lot like operations, though we can model them as a one-off to start.
	Controllers(hcpClusterID string) ResourceCRUD[api.Controller, *api.Controller]
}

type CosmosDBTransactionDetails struct {
	PartitionKey string                           `json:"partitionKey"`
	Steps        []CosmosDBTransactionStepDetails `json:"steps"`
}

type CosmosDBTransactionStep func(b *azcosmos.TransactionalBatch) (string, error)

type CosmosDBTransactionStepDetails struct {
	ActionType string      `json:"actionType"`
	CosmosID   string      `json:"cosmosID"`
	ResourceID string      `json:"resourceID"`
	GoType     string      `json:"goType"`
	Etag       azcore.ETag `json:"etag"`
}

type DBClientIterator[T any] interface {
	Items(ctx context.Context) DBClientIteratorItem[T]
	GetContinuationToken() string
	GetError() error
}

type DBClientIteratorItem[T any] iter.Seq2[string, *T]

type DBClientListResourceDocsOptions struct {
	// ResourceType matches (case-insensitively) the Azure resource type. If unspecified,
	// ResourcesDBClient.ListResourceDocs will match resource documents for any resource type.
	ResourceType *azcorearm.ResourceType

	// PageSizeHint can limit the number of items returned at once. A negative value will cause
	// the returned iterator to yield all matching documents (same as leaving the option nil).
	// A positive value will cause the returned iterator to include a continuation token if
	// additional items are available.
	PageSizeHint *int32

	// ContinuationToken can be supplied when limiting the number of items returned at once
	// through PageSizeHint.
	ContinuationToken *string
}

type DBTransaction interface {
	// AddStep adds a transaction function to the list to perform
	AddStep(CosmosDBTransactionStepDetails, CosmosDBTransactionStep)

	// GetPartitionKey returns the transaction's partition key.
	GetPartitionKey() string

	// OnSuccess adds a function to call if the transaction executes successfully.
	OnSuccess(callback DBTransactionCallback)

	// Execute submits the prepared transaction.
	Execute(ctx context.Context, o *azcosmos.TransactionalBatchOptions) (DBTransactionResult, error)
}

type DBTransactionCallback func(DBTransactionResult)

type DBTransactionResult interface {
	// GetItem returns the internal API representation for the cosmosUID.
	// That is consistent with other returns from our database layer.
	// The Item is only available if the transaction was
	// executed with the EnableContentResponseOnWrite option set, or
	// the document was requested with DBTransaction.ReadDoc.
	GetItem(cosmosUID string) (any, error)
}

type Defaulter interface {
	EnsureDefaults()
}

type ExternalAuthsCRUD interface {
	ResourceCRUD[api.HCPOpenShiftClusterExternalAuth, *api.HCPOpenShiftClusterExternalAuth]
	ControllerContainer
}

type FleetDBClient interface {
	Stamps() StampsCRUD
	GlobalListers() FleetGlobalListers
}

type FleetGlobalListers interface {
	Stamps() GlobalLister[fleet.Stamp]
	ManagementClusters() GlobalLister[fleet.ManagementCluster]
}

type FleetPartitionKeyDeriver struct{}

type FleetResourceIDBuilder struct{}

type GenericDocument[InternalAPIType any] struct {
	TypedDocument `json:",inline"`

	Content InternalAPIType `json:"properties"`
}

type GlobalLister[T any] interface {
	List(ctx context.Context, options *DBClientListResourceDocsOptions) (DBClientIterator[T], error)
}

type HCPClusterCRUD interface {
	ResourceCRUD[api.HCPOpenShiftCluster, *api.HCPOpenShiftCluster]
	ControllerContainer
	ManagementClusterContentContainer

	ExternalAuth(hcpClusterID string) ExternalAuthsCRUD
	NodePools(hcpClusterID string) NodePoolsCRUD
}

type KubeApplierApplyDesireCRUD interface {
	ApplyDesiresForCluster(subscriptionID, resourceGroupName, clusterName string) (ResourceCRUD[kubeapplier.ApplyDesire, *kubeapplier.ApplyDesire], error)
	ApplyDesiresForNodePool(subscriptionID, resourceGroupName, clusterName, nodePoolName string) (ResourceCRUD[kubeapplier.ApplyDesire, *kubeapplier.ApplyDesire], error)
}

type KubeApplierDBClient interface {
	// ApplyDesiresForCluster returns a CRUD scoped to a cluster parent.
	ApplyDesiresForCluster(subscriptionID, resourceGroupName, clusterName string) (ResourceCRUD[kubeapplier.ApplyDesire, *kubeapplier.ApplyDesire], error)
	// ApplyDesiresForNodePool returns a CRUD scoped to a nodepool parent.
	ApplyDesiresForNodePool(subscriptionID, resourceGroupName, clusterName, nodePoolName string) (ResourceCRUD[kubeapplier.ApplyDesire, *kubeapplier.ApplyDesire], error)
	// ReadDesiresForCluster returns a CRUD scoped to a cluster parent.
	ReadDesiresForCluster(subscriptionID, resourceGroupName, clusterName string) (ResourceCRUD[kubeapplier.ReadDesire, *kubeapplier.ReadDesire], error)
	// ReadDesiresForNodePool returns a CRUD scoped to a nodepool parent.
	ReadDesiresForNodePool(subscriptionID, resourceGroupName, clusterName, nodePoolName string) (ResourceCRUD[kubeapplier.ReadDesire, *kubeapplier.ReadDesire], error)

	// Listers lists every *Desire of each kind in this container — i.e. across the
	// one management cluster's worth of data. Replaces the old GlobalListers /
	// PartitionListers split, which existed only because all management clusters
	// previously shared one container.
	Listers() KubeApplierListers

	// UntypedCRUD walks this container by resourceID prefix, returning
	// TypedDocument rows for cross-cutting cleanup. Deletion goes through
	// DeleteByCosmosID using the partitionKey from the listed row.
	UntypedCRUD(parentResourceID azcorearm.ResourceID) (UntypedResourceCRUD, error)
}

type KubeApplierDBClients interface {
	// For returns the client for the given management cluster, constructing it
	// on demand. It walks the configured ManagementClusterLister to find the
	// management cluster whose ResourceID matches; the container name comes
	// from the management cluster's Status.KubeApplierCosmosContainerName.
	// Returns nil if no management cluster matches, if the lister errors, or
	// if the matched management cluster has no container name configured.
	For(ctx context.Context, managementClusterResourceID *azcorearm.ResourceID) KubeApplierDBClient
}

type KubeApplierListers interface {
	ApplyDesires() GlobalLister[kubeapplier.ApplyDesire]
	ReadDesires() GlobalLister[kubeapplier.ReadDesire]
}

type KubeApplierPartitionKeyDeriver struct {
	ManagementClusterResourceID *azcorearm.ResourceID
}

type KubeApplierReadDesireCRUD interface {
	ReadDesiresForCluster(subscriptionID, resourceGroupName, clusterName string) (ResourceCRUD[kubeapplier.ReadDesire, *kubeapplier.ReadDesire], error)
	ReadDesiresForNodePool(subscriptionID, resourceGroupName, clusterName, nodePoolName string) (ResourceCRUD[kubeapplier.ReadDesire, *kubeapplier.ReadDesire], error)
}

type LockClient struct {
	// contains filtered or unexported fields
}

type LockClientInterface interface {
	GetDefaultTimeToLive() time.Duration
	SetRetryAfterHeader(header http.Header)
	AcquireLock(ctx context.Context, id string, timeout *time.Duration) (*azcosmos.ItemResponse, error)
	TryAcquireLock(ctx context.Context, id string) (*azcosmos.ItemResponse, error)
	HoldLock(ctx context.Context, item *azcosmos.ItemResponse) (context.Context, StopHoldLock)
	RenewLock(ctx context.Context, item *azcosmos.ItemResponse) (*azcosmos.ItemResponse, error)
	ReleaseLock(ctx context.Context, item *azcosmos.ItemResponse) error
}

type LocksDBClient interface {
	LockClient() LockClientInterface
}

type ManagementClusterContentContainer interface {
	ManagementClusterContents(resourceName string) ResourceCRUD[api.ManagementClusterContent, *api.ManagementClusterContent]
}

type ManagementClusterLister interface {
	List(ctx context.Context) ([]*fleet.ManagementCluster, error)
}

type ManagementClustersCRUD interface {
	ValidatingResourceCRUD[fleet.ManagementCluster, *fleet.ManagementCluster]
	Controllers() ResourceCRUD[api.Controller, *api.Controller]
}

type NodePoolsCRUD interface {
	ResourceCRUD[api.HCPOpenShiftClusterNodePool, *api.HCPOpenShiftClusterNodePool]
	ControllerContainer
	ManagementClusterContentContainer
}

type OperationCRUD interface {
	ResourceCRUD[api.Operation, *api.Operation]

	// ListActiveOperations returns an iterator that searches for asynchronous operation documents
	// with a non-terminal status in the "Resources" container under the given partition key. The
	// options argument can further limit the search to documents that match the provided values.
	//
	// Note that ListActiveOperations does not perform the search, but merely prepares an iterator
	// to do so. Hence the lack of a Context argument. The search is performed by calling Items() on
	// the iterator in a ranged for loop.
	ListActiveOperations(options *ResourcesDBClientListActiveOperationDocsOptions) DBClientIterator[api.Operation]
}

type OperationRequest = api.OperationRequest

type PartitionKeyDeriver interface {
	PartitionKey(parentResourceID *azcorearm.ResourceID, resourceName string) (string, error)
	PartitionKeyFromObject(obj any) (string, error)
}

type ResourceCRUD[InternalAPIType any, InternalAPITypePointer arm.CosmosMetadataAccessorPtr[InternalAPIType]] interface {
	GetByID(ctx context.Context, cosmosID string) (*InternalAPIType, error)
	Get(ctx context.Context, resourceID string) (*InternalAPIType, error)
	List(ctx context.Context, opts *DBClientListResourceDocsOptions) (DBClientIterator[InternalAPIType], error)
	Create(ctx context.Context, newObj *InternalAPIType, options *azcosmos.ItemOptions) (*InternalAPIType, error)
	Replace(ctx context.Context, newObj *InternalAPIType, options *azcosmos.ItemOptions) (*InternalAPIType, error)
	Delete(ctx context.Context, resourceID string) error

	AddCreateToTransaction(ctx context.Context, transaction DBTransaction, newObj *InternalAPIType, opts *azcosmos.TransactionalBatchItemOptions) (string, error)
	AddReplaceToTransaction(ctx context.Context, transaction DBTransaction, newObj *InternalAPIType, opts *azcosmos.TransactionalBatchItemOptions) (string, error)
}

type ResourceIDBuilder interface {
	BuildResourceID(parentResourceID *azcorearm.ResourceID, resourceType azcorearm.ResourceType, resourceName string) (*azcorearm.ResourceID, error)
}

type ResourcesDBClient interface {
	// NewTransaction initiates a new transactional batch for the given partition key.
	NewTransaction(pk string) DBTransaction

	// UntypedCRUD provides access documents in the subscription
	UntypedCRUD(parentResourceID azcorearm.ResourceID) (UntypedResourceCRUD, error)

	// HCPClusters retrieves a CRUD interface for managing HCPCluster resources and their nested resources.
	HCPClusters(subscriptionID, resourceGroupName string) HCPClusterCRUD

	// Operations retrieves a CRUD interface for managing operations.  Remember that operations are not directly accessible
	// to end users via ARM.  They must also survive the thing they are deleting, so they live under a subscription directly.
	Operations(subscriptionID string) OperationCRUD

	Subscriptions() ResourceCRUD[arm.Subscription, *arm.Subscription]

	ServiceProviderClusters(subscriptionID, resourceGroupName, clusterName string) ResourceCRUD[api.ServiceProviderCluster, *api.ServiceProviderCluster]

	// ResourcesGlobalListers returns interfaces for listing ARM resource documents across all partitions
	// (Resources container only), intended for feeding SharedInformers.
	ResourcesGlobalListers() ResourcesGlobalListers

	ServiceProviderNodePools(subscriptionID, resourceGroupName, clusterName, nodePoolName string) ResourceCRUD[api.ServiceProviderNodePool, *api.ServiceProviderNodePool]
}

type ResourcesDBClientListActiveOperationDocsOptions struct {
	// Request matches the type of asynchronous operation requested
	Request *OperationRequest
	// ExternalID matches (case-insensitively) the Azure resource ID of the cluster or node pool
	ExternalID *azcorearm.ResourceID
	// IncludeNestedResources includes nested resources under ExternalID
	IncludeNestedResources bool
}

type ResourcesGlobalListers interface {
	Subscriptions() GlobalLister[arm.Subscription]
	Clusters() GlobalLister[api.HCPOpenShiftCluster]
	NodePools() GlobalLister[api.HCPOpenShiftClusterNodePool]
	ExternalAuths() GlobalLister[api.HCPOpenShiftClusterExternalAuth]
	ServiceProviderClusters() GlobalLister[api.ServiceProviderCluster]
	ServiceProviderNodePools() GlobalLister[api.ServiceProviderNodePool]
	Controllers() GlobalLister[api.Controller]
	// ManagementClusterContents lists ManagementClusterContent documents across
	// partitions for every Cosmos resource type where managementClusterContents
	// is nested as a direct child resource. Those types are registered on the lister implementation.
	ManagementClusterContents() GlobalLister[api.ManagementClusterContent]
	Operations() GlobalLister[api.Operation]
	ActiveOperations() GlobalLister[api.Operation]
}

type StampsCRUD interface {
	ValidatingResourceCRUD[fleet.Stamp, *fleet.Stamp]
	ManagementClusters(stampIdentifier string) ManagementClustersCRUD
}

type StopHoldLock func() *azcosmos.ItemResponse

type SubscriptionPartitionKeyDeriver struct{}

type TypedDocument struct {
	BaseDocument
	PartitionKey string                `json:"partitionKey"`
	ResourceID   *azcorearm.ResourceID `json:"resourceID"`
	ResourceType string                `json:"resourceType"`
	Properties   json.RawMessage       `json:"properties"`
}

type UntypedResourceCRUD interface {
	Get(ctx context.Context, resourceID *azcorearm.ResourceID) (*TypedDocument, error)
	// List returns back only direct descendents from the parent.
	List(ctx context.Context, opts *DBClientListResourceDocsOptions) (DBClientIterator[TypedDocument], error)
	// ListRecursive returns back every descendent from the parent.  For instance, if you ListRecursive on a cluster,
	// you will get the controllers for the cluster, the nodepools, the controllers for each nodepool, the external auths,
	// the controllers for the external auths, etc.
	ListRecursive(ctx context.Context, opts *DBClientListResourceDocsOptions) (DBClientIterator[TypedDocument], error)
	Delete(ctx context.Context, resourceID *azcorearm.ResourceID) error
	DeleteByCosmosID(ctx context.Context, partitionKey, cosmosID string) error

	Child(resourceType azcorearm.ResourceType, resourceName string) (UntypedResourceCRUD, error)
}

type ValidatingResourceCRUD[InternalAPIType any, InternalAPITypePointer arm.CosmosMetadataAccessorPtr[InternalAPIType]] interface {
	GetByID(ctx context.Context, cosmosID string) (*InternalAPIType, error)
	Get(ctx context.Context, resourceID string) (*InternalAPIType, error)
	List(ctx context.Context, opts *DBClientListResourceDocsOptions) (DBClientIterator[InternalAPIType], error)
	Create(ctx context.Context, newObj *InternalAPIType, options *azcosmos.ItemOptions) (*InternalAPIType, error)
	Replace(ctx context.Context, newObj *InternalAPIType, oldObj *InternalAPIType, options *azcosmos.ItemOptions) (*InternalAPIType, error)
	Delete(ctx context.Context, resourceID string) error
}