checkpoint

type Checkpointer interface {
	// NotifyNewVersion notifies the checkpointer that a new version has been finalized.
	NotifyNewVersion(version uint64)

	// Flush makes the checkpointer immediately process any notifications.
	Flush()
}

type CheckpointerConfig struct {
	// Name identifying this checkpointer in logs.
	Name string

	// Namespace is the storage namespace this checkpointer is for.
	Namespace common.Namespace

	// CheckInterval is the interval on which to check if any checkpointing is needed.
	CheckInterval time.Duration

	// RootsPerVersion is the number of roots per version.
	RootsPerVersion int

	// Parameters are the checkpoint creation parameters.
	Parameters *CreationParameters
	// GetParameters can be used instead of specifying Parameters to dynamically fetch the current
	// checkpoint parameters. In this case Parameters must be set to nil.
	GetParameters func(context.Context) (*CreationParameters, error)

	// GetRoots can be used to override which finalized roots should be checkpointed. If this is not
	// specified, all finalized roots will be checkpointed.
	//
	// This must return exactly RootsPerVersion roots.
	GetRoots func(context.Context, uint64) ([]hash.Hash, error)
}

type ChunkMetadata struct {
	Version uint16    `json:"version"`
	Root    node.Root `json:"root"`
	Index   uint64    `json:"index"`
	Digest  hash.Hash `json:"digest"`
}

type ChunkProvider interface {
	// GetCheckpoints returns a list of checkpoint metadata for all known checkpoints.
	GetCheckpoints(ctx context.Context, request *GetCheckpointsRequest) ([]*Metadata, error)

	// GetCheckpointChunk fetches a specific chunk from an existing chekpoint.
	GetCheckpointChunk(ctx context.Context, chunk *ChunkMetadata, w io.Writer) error
}

type CreateRestorer interface {
	Creator
	Restorer
}

type CreationParameters struct {
	// Interval is the expected runtime state checkpoint interval (in rounds).
	Interval uint64

	// NumKept is the expected minimum number of checkpoints to keep.
	NumKept uint64

	// ChunkSize is the chunk size parameter for checkpoint creation.
	ChunkSize uint64

	// InitialVersion is the initial version.
	InitialVersion uint64
}

type Creator interface {
	ChunkProvider

	// CreateCheckpoint creates a new checkpoint at the given root.
	CreateCheckpoint(ctx context.Context, root node.Root, chunkSize uint64) (*Metadata, error)

	// GetCheckpoint retrieves checkpoint metadata for a specific checkpoint.
	GetCheckpoint(ctx context.Context, version uint16, root node.Root) (*Metadata, error)

	// DeleteCheckpoint deletes a specific checkpoint.
	DeleteCheckpoint(ctx context.Context, version uint16, root node.Root) error
}

type GetCheckpointsRequest struct {
	Version   uint16           `json:"version"`
	Namespace common.Namespace `json:"namespace"`

	// RootVersion specifies an optional root version to limit the request to. If specified, only
	// checkpoints for roots with the specific version will be considered.
	RootVersion *uint64 `json:"root_version,omitempty"`
}

type Metadata struct {
	Version uint16      `json:"version"`
	Root    node.Root   `json:"root"`
	Chunks  []hash.Hash `json:"chunks"`
}

type Restorer interface {
	// StartRestore starts a checkpoint restoration process.
	StartRestore(ctx context.Context, checkpoint *Metadata) error

	// AbortRestore aborts a checkpoint restore in progress.
	//
	// It is not an error to call this method when no checkpoint restore is in progress.
	AbortRestore(ctx context.Context) error

	// GetCurrentCheckpoint returns the checkpoint that is being restored. If no restoration is in
	// progress, this method may return nil.
	GetCurrentCheckpoint() *Metadata

	// RestoreChunk restores the given chunk into the underlying node database.
	//
	// This method requires that a restoration is in progress.
	//
	// Returns true when the checkpoint has been fully restored.
	RestoreChunk(ctx context.Context, index uint64, r io.Reader) (bool, error)
}