index

type AssetRecordVisitor func(recordID string, r *AssetState) error

type AssetState struct {
	ImpressionID     string `json:"impression"`
	AssetID          string `json:"asset"`
	ContentType      string `json:"contentType"`
	RevisionNumber   int64  `json:"revisionNumber,omitempty"`
	WasRevisionOf    string `json:"wasRevisionOf,omitempty"`
	SpecializationOf string `json:"specializationOf,omitempty"`
}

type Client interface {
	io.Closer

	// Bind links all underlying index states to a specific genesis block hash. If any of the stores
	// were already linked to a different hash, the call would fail.
	Bind(ctx context.Context, gbHash string) error

	// RootIndex returns a root index for the given account and requested access level.
	// If the index is not found, it will return ErrIndexNotFound.
	RootIndex(ctx context.Context, userID string, lvl model.AccessLevel) (RootIndex, error)

	// Index returns an index with the given id for the given account.
	// If the index is not found, it will return ErrIndexNotFound.
	Index(ctx context.Context, userID string, id string) (Index, error)
	// ListIndexes return a list of index definitions for all the indexes that are available
	// through this index client. We return a list of Properties to avoid construction of
	// all index instances that may be an expensive operation.
	ListIndexes(ctx context.Context, userID string) ([]*Properties, error)
	// DeleteIndex deletes the index from all the underlying index stores.
	DeleteIndex(ctx context.Context, userID, id string) error

	// IndexStore returns the index store with the given name.
	// If the store is not found, it will return ErrIndexStoreNotFound
	IndexStore(ctx context.Context, storeName string) (Store, error)
	// IndexStores return a list of index store definitions for all the stores that are available
	// through this index client. We return a list of StoreProperties to avoid construction of
	// all store instances that may be an expensive operation.
	IndexStores(ctx context.Context) []*StoreProperties
	// AddIndexStore instantiates and adds a new index store based on the provided configuration.
	AddIndexStore(ctx context.Context, cfg *StoreConfig, resolver cmdbase.ParameterResolver) error
}

type EncryptionMode string

type Index interface {
	io.Closer

	ID() string
	Properties() *Properties

	IsLocked() bool
	Unlock(key []byte) error
	Lock()

	IsWritable() bool
	Writer() (Writer, error)
}

type LockerState struct {
	ID         string `json:"id"`
	IndexID    string `json:"indexID"`
	AccountID  string `json:"accountID"`
	FirstBlock uint64 `json:"firstBlock,omitempty"`
	TopBlock   uint64 `json:"topBlock,omitempty"`
}

type Option func(opts *Options) error

type Options struct {
	ClientKey  []byte `json:"key,omitempty"`
	Parameters any    `json:"parameters,omitempty"`
}

type Properties struct {
	IndexType   string            `json:"type"`
	Asset       string            `json:"asset,omitempty"`
	AccessLevel model.AccessLevel `json:"accessLevel"`
	Algorithm   string            `json:"algo"`
	Params      any               `json:"params"`
}

type RecordState struct {
	ID            string             `json:"id"`
	Operation     model.OpType       `json:"op"`
	Status        model.RecordStatus `json:"status"`
	LockerID      string             `json:"locker"`
	ParticipantID string             `json:"participant"`
	BlockNumber   uint64             `json:"blockNumber"`
	Index         uint32             `json:"index"`
	ImpressionID  string             `json:"impression,omitempty"`
	ContentType   string             `json:"contentType,omitempty"`
}

type RecordVisitor func(r *RecordState) error

type RootIndex interface {
	Index

	GetRecord(ctx context.Context, recordID string) (*RecordState, error)
	TraverseRecords(ctx context.Context, lockerFilter, participantFilter string, vFunc RecordVisitor, maxRecords uint64) error
	TraverseVariants(ctx context.Context, lockerFilter, participantFilter string, vFunc VariantVisitor, includeHistory bool, maxVariants uint64) error
	TraverseAssetRecords(ctx context.Context, assetID string, vFunc AssetRecordVisitor, maxRecords uint64) error
	GetRecordsByImpressionID(ctx context.Context, impID string, lockerFilter map[string]bool) ([]string, error)
	GetVariant(ctx context.Context, variantID string, includeHistory bool) (*VariantRecordState, []*VariantRecordState, error)
}

type RootIndexParameters struct {
	ClientKey []byte `json:"key,omitempty"`
}

type Store interface {
	io.Closer

	ID() string
	Name() string
	Properties() *StoreProperties

	CreateIndex(ctx context.Context, userID string, indexType string, accessLevel model.AccessLevel, opts ...Option) (Index, error)
	RootIndex(ctx context.Context, userID string, lvl model.AccessLevel) (RootIndex, error)
	Index(ctx context.Context, userID string, id string) (Index, error)
	ListIndexes(ctx context.Context, userID string) ([]*Properties, error)
	DeleteIndex(ctx context.Context, userID, id string) error

	// Bind links the index store to a particular ledger instance by storing genesis block ID in the store.
	// If the store is already bound to a ledger, if will check the provided hash and return an error
	// if there is a mismatch. This is useful to catch conditions when the index store was used
	// in the context of a different ledger (i.e. in the development environment.
	Bind(ctx context.Context, gbHash string) error

	GenesisBlockHash(ctx context.Context) string
}

type StoreConfig struct {
	ID             string         `koanf:"id" json:"id"`
	Name           string         `koanf:"name" json:"name"`
	Type           string         `koanf:"type" json:"type"`
	EncryptionMode EncryptionMode `koanf:"encryptionMode" json:"encryptionMode"`
	Rebind         bool           `koanf:"rebind" json:"rebind"`
	Params         map[string]any `koanf:"params" json:"params,omitempty"`
}

type StoreConstructor func(cfg *StoreConfig, resolver cmdbase.ParameterResolver) (Store, error)

type StoreProperties struct {
	ID             string         `json:"id"`
	Name           string         `json:"name"`
	Type           string         `json:"type"`
	EncryptionMode EncryptionMode `json:"encryptionMode"`
}

type VariantRecordState struct {
	ID             string             `json:"id"`
	Operation      model.OpType       `json:"op"`
	Status         model.RecordStatus `json:"status"`
	LockerID       string             `json:"locker"`
	ParticipantID  string             `json:"participant"`
	BlockNumber    uint64             `json:"block"`
	Index          uint32             `json:"index"`
	AssetID        string             `json:"asset"`
	ImpressionID   string             `json:"imp"`
	RevisionNumber int64              `json:"rev"`
	CreatedAt      *time.Time         `json:"at"`
	ContentType    string             `json:"ctype"`
}

type VariantVisitor func(variantID string, master *VariantRecordState, history []*VariantRecordState) error

type Writer interface {
	io.Closer

	ID() string

	LockerStates(ctx context.Context) ([]LockerState, error)
	AddLockerState(ctx context.Context, accountID, lockerID string, firstBlock uint64) error
	AddLease(ctx context.Context, ds model.DataSet, effectiveBlockNumber uint64) error
	AddLeaseRevocation(ctx context.Context, ds model.DataSet) error
	UpdateTopBlock(ctx context.Context, blockNumber uint64) error
}