common

type Column struct {
	// Immutable, columns cannot be renamed.
	Name string `json:"name"`
	// Immutable, columns cannot have their types changed.
	Type string `json:"type"`
	// Deleted columns are kept as placeholders in Table.Columns.
	// read only: true
	Deleted bool `json:"deleted,omitempty"`
	// We store the default value as string here since it's from user input.
	// Nil means the default value is NULL. Actual default value of column data type
	// should be stored in memstore.
	DefaultValue *string `json:"defaultValue,omitempty"`

	// Whether to compare characters case insensitively for enum columns. It only matters
	// for ingestion client as it's the place to concert enum strings to enum values.
	CaseInsensitive bool `json:"caseInsensitive,omitempty"`

	// Whether disable enum cases auto expansion.
	DisableAutoExpand bool `json:"disableAutoExpand,omitempty"`

	// Mutable column configs.
	Config ColumnConfig `json:"config,omitempty"`

	// HLLEnabled determines whether a column is enabled for hll cardinality estimation
	// HLLConfig is immutable
	HLLConfig HLLConfig `json:"hllConfig,omitempty"`
}

type ColumnConfig struct {
	// ColumnEvictionConfig : For column level in-memory eviction, it’s the best
	// effort TTL for in-memory data.
	// Column level eviction has nothing to do with data availability, but based
	// on how much data we pre-loaded, the major impact will be there for query
	// performance. Here we bring in two priorities configs: Preloading days and
	// Priority.
	//   - Preloading days is defined at each column level to indicate how many
	//     recent days data we want to preload to host memory. This is best effort
	//     operation.
	//   - Priority is defined at each column level to indicate the priority of
	//     each column. When data eviction happens, we will rely on column priority
	//     to decide which column will be evicted first.
	//     High number implies high priority.
	PreloadingDays int   `json:"preloadingDays,omitempty"`
	Priority       int64 `json:"priority,omitempty"`
}

type HLLConfig struct {
	IsHLLColumn bool `json:"isHLLColumn,omitempty"`
}

type MetaStore interface {
	GetEnumDict(table, column string) ([]string, error)

	// Sets the watcher for the specified enum column.
	// Should only be called once for each enum column.
	// Returns a events channel that emits enum cases starting from startCase,
	// and a done channel for consumer to ack once the event is processed.
	WatchEnumDictEvents(table, column string, startCase int) (events <-chan string, done chan<- struct{}, err error)

	// Returns the latest archiving/live cutoff for the specified shard.
	GetArchivingCutoff(table string, shard int) (uint32, error)

	// PurgeArchiveBatches deletes the metadata related to the archive batch
	PurgeArchiveBatches(table string, shard, batchIDStart, batchIDEnd int) error
	// Returns the version to use for the specified archive batch and size of the batch with the
	// specified archiving/live cutoff.
	GetArchiveBatchVersion(table string, shard, batchID int, cutoff uint32) (uint32, uint32, int, error)
	// Returns the latest snapshot version for the specified shard.
	// the return value is: redoLogFile, offset, lastReadBatchID, lastReadBatchOffset
	GetSnapshotProgress(table string, shard int) (int64, uint32, int32, uint32, error)

	// Set the watcher for table shard ownership change events.
	// Should only be called once.
	// Returns an event channel that emits desired ownership states,
	// and a done channel for consumer to ack once the event is processed.
	WatchShardOwnershipEvents() (events <-chan ShardOwnership, done chan<- struct{}, err error)

	// A subset of newly added columns can be appended to the end of
	// ArchivingSortColumns by adding their index in columns to archivingSortColumns
	// Update column config.
	// Returns the assigned case IDs for each case string.
	ExtendEnumDict(table, column string, enumCases []string) ([]int, error)

	// List available archive batches
	GetArchiveBatches(table string, shard int, start, end int32) ([]int, error)

	// Adds a version and size for the specified archive batch.
	AddArchiveBatchVersion(table string, shard, batchID int, version uint32, seqNum uint32, batchSize int) error

	// WriteArchiveBatchVersion
	OverwriteArchiveBatchVersion(table string, shard, batchID int, version uint32, seqNum uint32, batchSize int) error

	// Updates the archiving/live cutoff time for the specified shard. This is used
	// by the archiving job after each successful run.
	UpdateArchivingCutoff(table string, shard int, cutoff uint32) error

	// Updates the latest snapshot version for the specified shard.
	UpdateSnapshotProgress(table string, shard int, redoLogFile int64, upsertBatchOffset uint32, lastReadBatchID int32, lastReadBatchOffset uint32) error

	// Updates the latest redolog/offset that have been backfilled for the specified shard.
	UpdateBackfillProgress(table string, shard int, redoLogFile int64, offset uint32) error

	// Retrieve the latest redolog/offset that have been backfilled for the specified shard.
	GetBackfillProgressInfo(table string, shard int) (int64, uint32, error)

	// Update ingestion commit offset, used for kafka like streaming ingestion
	UpdateRedoLogCommitOffset(table string, shard int, offset int64) error

	// Get ingestion commit offset, used for kafka like streaming ingestion
	GetRedoLogCommitOffset(table string, shard int) (int64, error)

	// Update ingestion checkpoint offset, used for kafka like streaming ingestion
	UpdateRedoLogCheckpointOffset(table string, shard int, offset int64) error

	// Get ingestion checkpoint offset, used for kafka like streaming ingestion
	GetRedoLogCheckpointOffset(table string, shard int) (int64, error)

	TableSchemaWatchable
	TableSchemaMutator
}

type ShardOwnership struct {
	TableName string
	Shard     int
	ShouldOwn bool
}

type Table struct {
	// Name of the table, immutable.
	Name string `json:"name"`
	// Index to Columns also serves as column IDs.
	Columns []Column `json:"columns"`
	// IDs of primary key columns. This field is immutable.
	PrimaryKeyColumns []int `json:"primaryKeyColumns"`
	// Whether this is a fact table.
	IsFactTable bool `json:"isFactTable"`

	// table configurations
	Config TableConfig `json:"config"`

	// Fact table only.
	// IDs of columns to sort based upon.
	ArchivingSortColumns []int `json:"archivingSortColumns,omitempty"`

	// Incarnation gets incremented every time an table name is reused
	// only used for controller managed schema in cluster setting
	Incarnation int `json:"incarnation"`
	// Version gets incremented every time when schema is updated
	// only used for controller managed schema in cluster setting
	Version int `json:"version"`
}

type TableConfig struct {

	// Initial setting of number of buckets for primary key
	// if equals to 0, default will be used
	InitialPrimaryKeyNumBuckets int `json:"initPrimaryKeyNumBuckets,omitempty"`

	// Size of each live batch, should be sufficiently large.
	BatchSize int `json:"batchSize,omitempty" validate:"min=1"`

	// Specifies how often to create a new redo log file.
	RedoLogRotationInterval int `json:"redoLogRotationInterval,omitempty" validate:"min=1"`

	// Specifies the size limit of a single redo log file.
	MaxRedoLogFileSize int `json:"maxRedoLogFileSize,omitempty" validate:"min=1"`

	// Number of minutes after event time before a record can be archived.
	ArchivingDelayMinutes uint32 `json:"archivingDelayMinutes,omitempty" validate:"min=1"`
	// Specifies how often archiving runs.
	ArchivingIntervalMinutes uint32 `json:"archivingIntervalMinutes,omitempty" validate:"min=1"`

	// Specifies how often backfill runs.
	BackfillIntervalMinutes uint32 `json:"backfillIntervalMinutes,omitempty" validate:"min=1"`

	// Upper limit of current backfill buffer size + backfilling buffer size.
	BackfillMaxBufferSize int64 `json:"backfillMaxBufferSize,omitempty" validate:"min=1"`

	// Backfill buffer size in bytes that will trigger a backfill job.
	BackfillThresholdInBytes int64 `json:"backfillThresholdInBytes,omitempty" validate:"min=1"`

	// Size of each live batch used by backfill job.
	BackfillStoreBatchSize int `json:"backfillStoreBatchSize,omitempty" validate:"min=1"`

	// Records with timestamp older than now - RecordRetentionInDays will be skipped
	// during ingestion and backfill. 0 means unlimited days.
	RecordRetentionInDays int `json:"recordRetentionInDays,omitempty" validate:"min=0"`

	// Number of mutations to accumulate before creating a new snapshot.
	SnapshotThreshold int `json:"snapshotThreshold,omitempty" validate:"min=1"`

	// Specifies how often snapshot runs.
	SnapshotIntervalMinutes int `json:"snapshotIntervalMinutes,omitempty" validate:"min=1"`

	AllowMissingEventTime bool `json:"allowMissingEventTime,omitempty"`
}

type TableSchemaMutator interface {
	TableSchemaReader
	CreateTable(table *Table) error
	DeleteTable(name string) error
	UpdateTableConfig(table string, config TableConfig) error
	UpdateTable(table Table) error

	// A subset of newly added columns can be appended to the end of
	// ArchivingSortColumns by adding their index in columns to archivingSortColumns
	AddColumn(table string, column Column, appendToArchivingSortOrder bool) error
	// Update column config.
	UpdateColumn(table string, column string, config ColumnConfig) error
	DeleteColumn(table string, column string) error
}

type TableSchemaReader interface {
	ListTables() ([]string, error)
	GetTable(name string) (*Table, error)
}

type TableSchemaWatchable interface {
	// Sets the watcher for table list change (table deletion) events.
	// Should only be called once.
	// Returns a events channel that emits the entire table list on each table deletion event,
	// and a done channel for consumer to ack once the event is processed.
	WatchTableListEvents() (events <-chan []string, done chan<- struct{}, err error)
	// Sets the watcher for table modification/addition events.
	// Should only be called once.
	// Returns a events channel that emits the table schema on each change event for given table,
	// and a done channel for consumer to ack once the event is processed.
	WatchTableSchemaEvents() (events <-chan *Table, done chan<- struct{}, err error)
}