checkpoint

Documentation

Overview

Package checkpoint provides methods for creating MKVS checkpoints.

Index

• Constants
• Variables
• type Checkpointer
  • func NewCheckpointer(ctx context.Context, ndb db.NodeDB, creator Creator, cfg CheckpointerConfig) (Checkpointer, error)
• type CheckpointerConfig
• type ChunkMetadata
• type ChunkProvider
• type CreateRestorer
  • func NewCreateRestorer(creator Creator, restorer Restorer) CreateRestorer
• type CreationParameters
• type Creator
  • func NewFileCreator(dataDir string, ndb db.NodeDB) (Creator, error)
• type GetCheckpointsRequest
• type Metadata
  • func (m *Metadata) EncodedHash() hash.Hash
  • func (m Metadata) GetChunkMetadata(idx uint64) (*ChunkMetadata, error)
• type Restorer
  • func NewRestorer(ndb db.NodeDB) (Restorer, error)

Constants

const CheckIntervalDisabled time.Duration = 1<<63 - 1

CheckIntervalDisabled is the checkpointing interval which basically disables periodic checkpoints (unless a checkpoint is forced).

Variables

var (
	// ErrCheckpointNotFound is the error when a checkpoint is not found.
	ErrCheckpointNotFound = errors.New(moduleName, 1, "checkpoint: not found")

	// ErrChunkNotFound is the error when a chunk is not found.
	ErrChunkNotFound = errors.New(moduleName, 2, "checkpoint: chunk not found")

	// ErrRestoreAlreadyInProgress is the error when a checkpoint restore is already in progress and
	// the caller wanted to start another restore.
	ErrRestoreAlreadyInProgress = errors.New(moduleName, 3, "checkpoint: restore already in progress")

	// ErrNoRestoreInProgress is the error when no checkpoint restore is currently in progress.
	ErrNoRestoreInProgress = errors.New(moduleName, 4, "checkpoint: no restore in progress")

	// ErrChunkAlreadyRestored is the error when a chunk has already been restored.
	ErrChunkAlreadyRestored = errors.New(moduleName, 5, "checkpoint: chunk already restored")

	// ErrChunkProofVerificationFailed is the error when a chunk fails proof verification.
	ErrChunkProofVerificationFailed = errors.New(moduleName, 6, "chunk: chunk proof verification failed")

	// ErrChunkCorrupted is the error when a chunk is corrupted.
	ErrChunkCorrupted = errors.New(moduleName, 7, "chunk: corrupted chunk")
)

Types

type Checkpointer

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

	// ForceCheckpoint makes the checkpointer create a checkpoint of the given version even if it is
	// outside the regular checkpoint schedule. In case the checkpoint at that version already
	// exists, this will be a no-op.
	//
	// The checkpoint will be created asynchronously.
	ForceCheckpoint(version uint64)

	// WatchCheckpoints returns a channel that produces a stream of checkpointed versions. The
	// versions are emitted before the checkpointing process starts.
	WatchCheckpoints() (<-chan uint64, pubsub.ClosableSubscription, error)

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

	// Pause pauses or unpauses the checkpointer. Pausing doesn't influence the checkpointing
	// intervals; after unpausing, a checkpoint won't be created immediately, but the checkpointer
	// will wait for the next regular event.
	Pause(pause bool)
}

Checkpointer is a checkpointer.

func NewCheckpointer

func NewCheckpointer(
	ctx context.Context,
	ndb db.NodeDB,
	creator Creator,
	cfg CheckpointerConfig,
) (Checkpointer, error)

NewCheckpointer creates a new checkpointer that can be notified of new finalized versions and will automatically generate the configured number of checkpoints.

type CheckpointerConfig

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) ([]node.Root, error)
}

CheckpointerConfig is a checkpointer configuration.

type ChunkMetadata

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

ChunkMetadata is chunk metadata.

type ChunkProvider

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
}

ChunkProvider is a chunk provider.

type CreateRestorer

type CreateRestorer interface {
	Creator
	Restorer
}

CreateRestorer is an interface that combines the checkpoint creator and restorer.

func NewCreateRestorer

func NewCreateRestorer(creator Creator, restorer Restorer) CreateRestorer

NewCreateRestorer combines a checkpoint creator and a restorer.

type CreationParameters

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
}

CreationParameters are the checkpoint creation parameters used by the checkpointer.

type Creator

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
}

Creator is a checkpoint creator.

func NewFileCreator

func NewFileCreator(dataDir string, ndb db.NodeDB) (Creator, error)

NewFileCreator creates a new checkpoint creator that writes created chunks into the filesystem.

type GetCheckpointsRequest

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"`
}

GetCheckpointsRequest is a GetCheckpoints request.

type Metadata

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

Metadata is checkpoint metadata.

func (*Metadata) EncodedHash

func (m *Metadata) EncodedHash() hash.Hash

EncodedHash returns the encoded cryptographic hash of the checkpoint metadata.

func (Metadata) GetChunkMetadata

func (m Metadata) GetChunkMetadata(idx uint64) (*ChunkMetadata, error)

GetChunkMetadata returns the chunk metadata for the corresponding chunk.

type Restorer

type Restorer interface {
	// StartRestore starts a checkpoint restoration process.
	//
	// Multipart management in the underlying database is the responsibility of the caller.
	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.
	//
	// Multipart management in the underlying database is the responsibility of the caller.
	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. At this point,
	// the restoration is also cleaned  up so that AbortRestore doesn't need to be called.
	//
	// Multipart management in the underlying database is the responsibility of the caller.
	RestoreChunk(ctx context.Context, index uint64, r io.Reader) (bool, error)
}

Restorer is a checkpoint restorer.

func NewRestorer

func NewRestorer(ndb db.NodeDB) (Restorer, error)

NewRestorer creates a new checkpoint restorer.