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 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 ClusterInternalState struct {
	InternalAPI api.HCPOpenShiftCluster `json:"internalAPI"`
}

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]
}

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 DBClient interface {
	// GetLockClient returns a LockClient, or nil if the DBClient does not support a LockClient.
	GetLockClient() LockClientInterface

	// 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() SubscriptionCRUD

	// BillingDocs retrieves a CRUD interface for managing billing documents within a subscription.
	BillingDocs(subscriptionID string) BillingDocCRUD

	ServiceProviderClusters(subscriptionID, resourceGroupName, clusterName string) ServiceProviderClusterCRUD

	// GlobalListers returns interfaces for listing all resources of a particular
	// type across all partitions, intended for feeding SharedInformers.
	GlobalListers() GlobalListers

	ServiceProviderNodePools(subscriptionID, resourceGroupName, clusterName, nodePoolName string) ServiceProviderNodePoolCRUD
}

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

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

type DBClientListActiveOperationDocsOptions 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 DBClientListResourceDocsOptions struct {
	// ResourceType matches (case-insensitively) the Azure resource type. If unspecified,
	// DBClient.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 ExternalAuth struct {
	TypedDocument `json:",inline"`

	ExternalAuthProperties `json:"properties"`
}

type ExternalAuthInternalState struct {
	InternalAPI api.HCPOpenShiftClusterExternalAuth `json:"internalAPI"`
}

type ExternalAuthProperties struct {
	// when we switch to inlining the internalObj, this will be in the right spot.  We add it now so that we can switch our
	// queries to select on cosmosMetata.ResourceID instead of resourceId
	CosmosMetadata api.CosmosMetadata `json:"cosmosMetadata"`

	// IntermediateResourceDoc exists so that we can stop inlining the resource document so that we can directly
	// embed the InternalAPIType which has colliding serialization fields.
	IntermediateResourceDoc *ResourceDocument `json:"intermediateResourceDoc"`

	// TODO we may need look-aside data that we want to store in the same place.  Build the nesting to allow it
	InternalState ExternalAuthInternalState `json:"internalState"`
}

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

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 GlobalListers 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]
	BillingDocs() GlobalLister[BillingDocument]
}

type HCPCluster struct {
	TypedDocument `json:",inline"`

	HCPClusterProperties `json:"properties"`
}

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

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

type HCPClusterProperties struct {
	// when we switch to inlining the internalObj, this will be in the right spot.  We add it now so that we can switch our
	// queries to select on cosmosMetata.ResourceID instead of resourceId
	CosmosMetadata api.CosmosMetadata `json:"cosmosMetadata"`

	// IntermediateResourceDoc exists so that we can stop inlining the resource document so that we can directly
	// embed the InternalAPIType which has colliding serialization fields.
	IntermediateResourceDoc *ResourceDocument `json:"intermediateResourceDoc"`

	// TODO we may need look-aside data that we want to store in the same place.  Build the nesting to allow it
	InternalState ClusterInternalState `json:"internalState"`
}

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 ManagementClusterContentCRUD interface {
	ResourceCRUD[api.ManagementClusterContent]
}

type ManagementClusterContentContainer interface {
	ManagementClusterContents(resourceName string) ManagementClusterContentCRUD
}

type NodePool struct {
	TypedDocument `json:",inline"`

	NodePoolProperties `json:"properties"`
}

type NodePoolInternalState struct {
	InternalAPI api.HCPOpenShiftClusterNodePool `json:"internalAPI"`
}

type NodePoolProperties struct {
	// when we switch to inlining the internalObj, this will be in the right spot.  We add it now so that we can switch our
	// queries to select on cosmosMetata.ResourceID instead of resourceId
	CosmosMetadata api.CosmosMetadata `json:"cosmosMetadata"`

	// IntermediateResourceDoc exists so that we can stop inlining the resource document so that we can directly
	// embed the InternalAPIType which has colliding serialization fields.
	IntermediateResourceDoc *ResourceDocument `json:"intermediateResourceDoc"`

	// TODO we may need look-aside data that we want to store in the same place.  Build the nesting to allow it
	InternalState NodePoolInternalState `json:"internalState"`
}

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

type OperationCRUD interface {
	ResourceCRUD[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 *DBClientListActiveOperationDocsOptions) DBClientIterator[api.Operation]
}

type OperationRequest = api.OperationRequest

type ResourceCRUD[InternalAPIType any] 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 ResourceDocument struct {
	ResourceID        *azcorearm.ResourceID       `json:"resourceId,omitempty"`
	InternalID        ocm.InternalID              `json:"internalId,omitempty"`
	ActiveOperationID string                      `json:"activeOperationId,omitempty"`
	ProvisioningState arm.ProvisioningState       `json:"provisioningState,omitempty"`
	Identity          *arm.ManagedServiceIdentity `json:"identity,omitempty"`
	SystemData        *arm.SystemData             `json:"systemData,omitempty"`
	Tags              map[string]string           `json:"tags,omitempty"`

	InternalState map[string]any `json:"internalState,omitempty"`
}

type ResourceDocumentStateFilter interface {
	// RemoveUnknownFields checks the customerDesiredState and serviceProviderState and removes unknown fields.
	// The simplest implementation is "remove everything" and the next simplest is round-tripping through JSON.
	RemoveUnknownFields(*ResourceDocument) error
}

type ServiceProviderClusterCRUD interface {
	ResourceCRUD[api.ServiceProviderCluster]
}

type ServiceProviderNodePoolCRUD interface {
	ResourceCRUD[api.ServiceProviderNodePool]
}

type StopHoldLock func() *azcosmos.ItemResponse

type SubscriptionCRUD interface {
	ResourceCRUD[arm.Subscription]
}

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

type TypedDocumentAccessor interface {
	GetTypedDocument() *TypedDocument
}

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)
}