api

type Cond interface {
	// Match returns whether a record match the condition.
	Match(timer *TimerRecord) bool
}

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

type EventExtra struct {
	// EventManualRequestID is the related request id of the manual trigger.
	// If current event is not triggered manually, it is empty.
	EventManualRequestID string
	// EventWatermark is the watermark when event triggers.
	EventWatermark time.Time
}

type GetTimerOption func(*TimerCond)

type Hook interface {
	// Start starts the hook.
	Start()
	// Stop stops the hook. When it is called, this means the framework is shutting down.
	Stop()
	// OnPreSchedEvent will be called before triggering a new event. It's return value tells the next action of the triggering.
	// For example, if `TimerShedEvent.Delay` is a non-zero value, the event triggering will be postponed.
	// Notice that `event.Timer().EventID` will be empty because the current event is not actually triggered,
	// use `event.EventID()` to get the event id instead.
	OnPreSchedEvent(ctx context.Context, event TimerShedEvent) (PreSchedEventResult, error)
	// OnSchedEvent will be called when a new event is triggered.
	OnSchedEvent(ctx context.Context, event TimerShedEvent) error
}

type HookFactory func(hookClass string, cli TimerClient) Hook

type ManualRequest struct {
	// ManualRequestID is the id of manual request.
	ManualRequestID string
	// ManualRequestTime is the request time.
	ManualRequestTime time.Time
	// ManualTimeout is the timeout for the request, if the timer is not triggered after timeout, processed will be set to true
	// with empty event id.
	ManualTimeout time.Duration
	// ManualProcessed indicates the request is processed (triggered or timeout).
	ManualProcessed bool
	// ManualEventID means the triggered event id for the current request.
	ManualEventID string
}

type Operator struct {
	// Op indicates the operator type.
	Op OperatorTp
	// Not indicates whether to apply 'NOT' to the condition.
	Not bool
	// Children is the children of the operator.
	Children []Cond
}

type OperatorTp int8

type OptionalVal[T any] struct {
	// contains filtered or unexported fields
}

type PreSchedEventResult struct {
	// Delay indicates to delay the event after a while.
	// If `Delay` is 0, it means no delay, and then `OnSchedEvent` will be called.
	// Otherwise, after a while according to `Delay`, `OnPreSchedEvent` will be called again to
	// check whether to trigger the event.
	Delay time.Duration
	// EventData indicates the data should be passed to the event that should be triggered.
	// EventData can be used to store some pre-computed configurations of the next event.
	EventData []byte
}

type SchedEventPolicy interface {
	// NextEventTime returns the time to schedule the next timer event. If the second return value is true,
	// it means we have a next event schedule after `watermark`. Otherwise, it means there is no more event after `watermark`.
	NextEventTime(watermark time.Time) (time.Time, bool)
}

type SchedEventStatus string

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

type SchedPolicyType string

type TimerClient interface {
	// GetDefaultNamespace returns the default namespace of this client.
	GetDefaultNamespace() string
	// CreateTimer creates a new timer.
	CreateTimer(ctx context.Context, spec TimerSpec) (*TimerRecord, error)
	// GetTimerByID queries the timer by ID.
	GetTimerByID(ctx context.Context, timerID string) (*TimerRecord, error)
	// GetTimerByKey queries the timer by key.
	GetTimerByKey(ctx context.Context, key string) (*TimerRecord, error)
	// GetTimers queries timers by options.
	GetTimers(ctx context.Context, opts ...GetTimerOption) ([]*TimerRecord, error)
	// UpdateTimer updates a timer.
	UpdateTimer(ctx context.Context, timerID string, opts ...UpdateTimerOption) error
	// ManualTriggerEvent triggers event manually.
	ManualTriggerEvent(ctx context.Context, timerID string) (string, error)
	// CloseTimerEvent closes the triggering event of a timer.
	CloseTimerEvent(ctx context.Context, timerID string, eventID string, opts ...UpdateTimerOption) error
	// DeleteTimer deletes a timer.
	DeleteTimer(ctx context.Context, timerID string) (bool, error)
}

type TimerCond struct {
	// ID indicates to filter the timer record with ID.
	ID OptionalVal[string]
	// Namespace indicates to filter the timer by Namespace.
	Namespace OptionalVal[string]
	// Key indicates to filter the timer record with ID.
	// The filter behavior is defined by `KeyPrefix`.
	Key OptionalVal[string]
	// KeyPrefix indicates how to filter with timer's key if `Key` is set.
	// If `KeyPrefix is` true, it will check whether the timer's key is prefixed with `TimerCond.Key`.
	// Otherwise, it will check whether the timer's key equals `TimerCond.Key`.
	KeyPrefix bool
	// Tags indicates to filter the timer record with specified tags.
	Tags OptionalVal[[]string]
}

type TimerRecord struct {
	TimerSpec
	// ID is the id of timer, it is unique and auto assigned by the store when created.
	ID string
	// ManualRequest is the request to trigger timer event manually.
	ManualRequest
	// EventStatus indicates the current schedule status of the timer's event.
	EventStatus SchedEventStatus
	// EventID indicates the id of current triggered event.
	// If the `EventStatus` is `IDLE`, this value should be empty.
	EventID string
	// EventData indicates the data of current triggered event.
	// If the `EventStatus` is `IDLE`, this value should be empty.
	EventData []byte
	// EventStart indicates the start time of current triggered event.
	// If the `EventStatus` is `IDLE`, `EventStart.IsZero()` should returns true.
	EventStart time.Time
	// EventExtra stores some extra attributes for event
	EventExtra
	// SummaryData is a binary which is used to store some summary information of the timer.
	// User can update it when closing a timer's event to update the summary.
	SummaryData []byte
	// CreateTime is the creation time of the timer.
	CreateTime time.Time
	// Version is the version of the record, when the record updated, version will be increased.
	Version uint64
	// Location is used to get the alias of TiDB timezone.
	Location *time.Location
}

type TimerShedEvent interface {
	// EventID returns the event ID the current event.
	EventID() string
	// Timer returns the timer record object of the current event.
	Timer() *TimerRecord
}

type TimerSpec struct {
	// Namespace is the namespace of the timer.
	Namespace string
	// Key is the key of the timer. Key is unique in each namespace.
	Key string
	// Tags is used to tag a timer.
	Tags []string
	// Data is a binary which is defined by user.
	Data []byte
	// TimeZone is the time zone name of the timer to evaluate the schedule policy.
	// If TimeZone is empty, it means to use the tidb cluster's time zone.
	TimeZone string
	// SchedPolicyType is the type of the event schedule policy.
	SchedPolicyType SchedPolicyType
	// SchedPolicyExpr is the expression of event schedule policy with the type specified by SchedPolicyType.
	SchedPolicyExpr string
	// HookClass is the class of the hook.
	HookClass string
	// Watermark indicates the progress the timer's event schedule.
	Watermark time.Time
	// Enable indicated whether the timer is enabled.
	// If it is false, the new timer event will not be scheduled even it is up to time.
	Enable bool
}

type TimerStore struct {
	TimerStoreCore
}

type TimerStoreCore interface {
	// Create creates a new record. If `record.ID` is empty, an id will be assigned automatically.
	// The first return value is the final id of the timer.
	Create(ctx context.Context, record *TimerRecord) (string, error)
	// List lists the timers that match the condition.
	List(ctx context.Context, cond Cond) ([]*TimerRecord, error)
	// Update updates a timer.
	Update(ctx context.Context, timerID string, update *TimerUpdate) error
	// Delete deletes a timer.
	Delete(ctx context.Context, timerID string) (bool, error)
	// WatchSupported indicates whether watch supported for this store.
	WatchSupported() bool
	// Watch watches all changes of the store. A chan will be returned to receive `WatchTimerResponse`
	// The returned chan be closed when the context in the argument is done.
	Watch(ctx context.Context) WatchTimerChan
	// Close closes the store
	Close()
}

type TimerUpdate struct {
	// Tags indicates to set all tags for a timer.
	Tags OptionalVal[[]string]
	// Enable indicates to set the timer's `Enable` field.
	Enable OptionalVal[bool]
	// TimeZone indicates to set the timer's `TimeZone` field.
	TimeZone OptionalVal[string]
	// SchedPolicyType indicates to set the timer's `SchedPolicyType` field.
	SchedPolicyType OptionalVal[SchedPolicyType]
	// SchedPolicyExpr indicates to set the timer's `SchedPolicyExpr` field.
	SchedPolicyExpr OptionalVal[string]
	// ManualRequest indicates to set the timer's manual request.
	ManualRequest OptionalVal[ManualRequest]
	// EventStatus indicates the event status.
	EventStatus OptionalVal[SchedEventStatus]
	// EventID indicates to set the timer event id.
	EventID OptionalVal[string]
	// EventData indicates to set the timer event data.
	EventData OptionalVal[[]byte]
	// EventStart indicates the start time of event.
	EventStart OptionalVal[time.Time]
	// EventExtra indicates to set the `EventExtra` field.
	EventExtra OptionalVal[EventExtra]
	// Watermark indicates to set the timer's `Watermark` field.
	Watermark OptionalVal[time.Time]
	// SummaryData indicates to set the timer's `Summary` field.
	SummaryData OptionalVal[[]byte]
	// CheckVersion indicates to check the timer's version when updated.
	CheckVersion OptionalVal[uint64]
	// CheckEventID indicates to check the timer's eventID.
	CheckEventID OptionalVal[string]
}

type TimerWatchEventNotifier interface {
	// Watch watches all changes of the store. A chan will be returned to receive `WatchTimerResponse`
	// The returned chan be closed when the context in the argument is done.
	Watch(ctx context.Context) WatchTimerChan
	// Notify sends the event to watchers.
	Notify(tp WatchTimerEventType, timerID string)
	// Close closes the notifier.
	Close()
}

type UpdateTimerOption func(*TimerUpdate)

type WatchTimerChan <-chan WatchTimerResponse

type WatchTimerEvent struct {
	// Tp indicates the event type.
	Tp WatchTimerEventType
	// TimerID indicates the timer id for the event.
	TimerID string
}

type WatchTimerEventType int8

type WatchTimerResponse struct {
	// Events contains all events in the response.
	Events []*WatchTimerEvent
}