api

Documentation

Overview

Package api defines the interface exporting the upgrade infrastructure's functionality.

Index

• Constants
• Variables
• type Backend
• type Descriptor
  • func (d *Descriptor) EnsureCompatible() error
  • func (d *Descriptor) Equals(other *Descriptor) bool
  • func (d Descriptor) PrettyPrint(ctx context.Context, prefix string, w io.Writer)
  • func (d Descriptor) PrettyType() (interface{}, error)
  • func (d Descriptor) ValidateBasic() error
• type HandlerName
  • func (h HandlerName) ValidateBasic() error
• type PendingUpgrade
  • func (pu PendingUpgrade) HasAnyStages() bool
  • func (pu PendingUpgrade) HasStage(stage UpgradeStage) bool
  • func (pu PendingUpgrade) IsCompleted() bool
  • func (pu *PendingUpgrade) PushStage(stage UpgradeStage)
• type UpgradeStage

Constants

const (
	// ModuleName is the upgrade module name.
	ModuleName = "upgrade"

	// LogEventIncompatibleBinary is a log event value that signals the currently running version
	// of the binary is incompatible with the upgrade.
	LogEventIncompatibleBinary = "upgrade/incompatible-binary"
	// LogEventStartupUpgrade is a log event value that signals the startup upgrade handler was
	// called.
	LogEventStartupUpgrade = "upgrade/startup-upgrade"
	// LogEventConsensusUpgrade is a log event value that signals the consensus upgrade handler was
	// called.
	LogEventConsensusUpgrade = "upgrade/consensus-upgrade"
)

const (
	// UpgradeStageStartup is the startup upgrade stage, executed at the beginning of node startup.
	UpgradeStageStartup UpgradeStage = 1

	// UpgradeStageConsensus is the upgrade stage carried out during consensus events.
	UpgradeStageConsensus UpgradeStage = 2

	// InvalidUpgradeHeight means the upgrade epoch hasn't been reached yet.
	InvalidUpgradeHeight = int64(0)

	// LatestDescriptorVersion is the latest upgrade descriptor version that should be used for
	// descriptors.
	LatestDescriptorVersion = 1

	// MinDescriptorVersion is the minimum descriptor version that is allowed.
	MinDescriptorVersion = 1
	// MaxDescriptorVersion is the maximum descriptor version that is allowed.
	MaxDescriptorVersion = LatestDescriptorVersion

	// LatestPendingUpgradeVersion is the latest pending upgrade struct version.
	LatestPendingUpgradeVersion = 1

	// MinUpgradeHandlerLength is the minimum length of upgrade handler's name.
	MinUpgradeHandlerLength = 3
	// MaxUpgradeHandlerLength is the maximum length of upgrade handler's name.
	MaxUpgradeHandlerLength = 32

	// MinUpgradeEpoch is the minimum upgrade epoch.
	MinUpgradeEpoch = beacon.EpochTime(1)
	// MaxUpgradeEpoch is the maximum upgrade epoch.
	MaxUpgradeEpoch = beacon.EpochInvalid - 1
)

Variables

var (
	// ErrStopForUpgrade is the error returned by the consensus upgrade function when it detects that
	// the consensus layer has reached the scheduled shutdown epoch and should be interrupted.
	ErrStopForUpgrade = errors.New(ModuleName, 1, "upgrade: reached upgrade epoch")

	// ErrAlreadyPending is the error returned from SubmitDescriptor when the specific upgrade is already pending.
	ErrAlreadyPending = errors.New(ModuleName, 5, "upgrade: submitted upgrade is already pending, can not resubmit descriptor")

	// ErrUpgradeInProgress is the error returned from CancelUpgrade when the upgrade being cancelled is already in progress.
	ErrUpgradeInProgress = errors.New(ModuleName, 6, "upgrade: can not cancel upgrade in progress")

	// ErrUpgradeNotFound is the error returned when the upgrade in question cannot be found.
	ErrUpgradeNotFound = errors.New(ModuleName, 7, "upgrade: not found")

	// ErrBadDescriptor is the error returned when the provided descriptor is bad.
	ErrBadDescriptor = errors.New(ModuleName, 8, "upgrade: bad descriptor")
)

Types

type Backend

type Backend interface {
	// SubmitDescriptor submits the serialized descriptor to the upgrade manager
	// which then schedules and manages the upgrade.
	SubmitDescriptor(context.Context, *Descriptor) error

	// PendingUpgrades returns pending upgrades.
	PendingUpgrades(context.Context) ([]*PendingUpgrade, error)

	// HasPendingUpgradeAt returns whether there is a pending upgrade at a specified height.
	HasPendingUpgradeAt(context.Context, int64) (bool, error)

	// CancelUpgrade cancels a specific pending upgrade, unless it is already in progress.
	CancelUpgrade(context.Context, *Descriptor) error

	// GetUpgrade returns the pending upgrade (if any) that has the given descriptor.
	//
	// In case no such upgrade exists, this returns ErrUpgradeNotFound.
	GetUpgrade(context.Context, *Descriptor) (*PendingUpgrade, error)

	// StartupUpgrade performs the startup portion of the upgrade.
	// It is idempotent with respect to the current upgrade descriptor.
	StartupUpgrade() error

	// ConsensusUpgrade performs the consensus portion of the upgrade. Note that this will be called
	// multiple times (in BeginBlock and EndBlock) where the context in the first argument can be
	// used to determine which part it is.
	//
	// It is idempotent with respect to the current upgrade descriptor.
	ConsensusUpgrade(interface{}, beacon.EpochTime, int64) error

	// Close cleans up any upgrader state and database handles.
	Close()
}

Backend defines the interface for upgrade managers.

type Descriptor

type Descriptor struct {
	cbor.Versioned

	// Handler is the name of the upgrade handler.
	Handler HandlerName `json:"handler"`
	// Target is upgrade's target version.
	Target version.ProtocolVersions `json:"target"`
	// Epoch is the epoch at which the upgrade should happen.
	Epoch beacon.EpochTime `json:"epoch"`
}

Descriptor describes an upgrade.

func (*Descriptor) EnsureCompatible

func (d *Descriptor) EnsureCompatible() error

EnsureCompatible checks if currently running binary is compatible with the upgrade descriptor.

func (*Descriptor) Equals

func (d *Descriptor) Equals(other *Descriptor) bool

Equals compares descriptors for equality.

func (Descriptor) PrettyPrint

func (d Descriptor) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of Descriptor to the given writer.

func (Descriptor) PrettyType

func (d Descriptor) PrettyType() (interface{}, error)

PrettyType returns a representation of Descriptor that can be used for pretty printing.

func (Descriptor) ValidateBasic

func (d Descriptor) ValidateBasic() error

ValidateBasic does basic validation checks of the upgrade descriptor.

type HandlerName

type HandlerName string

HandlerName is the name of the upgrade descriptor handler.

func (HandlerName) ValidateBasic

func (h HandlerName) ValidateBasic() error

ValidateBasic does basic validation checks of the upgrade descriptor handler name.

type PendingUpgrade

type PendingUpgrade struct {
	cbor.Versioned

	// Descriptor is the upgrade descriptor describing the upgrade.
	Descriptor *Descriptor `json:"descriptor"`

	// UpgradeHeight is the height at which the upgrade epoch was reached
	// (or InvalidUpgradeHeight if it hasn't been reached yet).
	UpgradeHeight int64 `json:"upgrade_height"`

	// LastCompletedStage is the last upgrade stage that was successfully completed.
	LastCompletedStage UpgradeStage `json:"last_completed_stage"`
}

PendingUpgrade describes a currently pending upgrade and includes the submitted upgrade descriptor.

func (PendingUpgrade) HasAnyStages

func (pu PendingUpgrade) HasAnyStages() bool

HasAnyStages checks if any stages were completed at all.

func (PendingUpgrade) HasStage

func (pu PendingUpgrade) HasStage(stage UpgradeStage) bool

HasStage checks if a given stage has been completed or not.

func (PendingUpgrade) IsCompleted

func (pu PendingUpgrade) IsCompleted() bool

IsCompleted checks if all upgrade stages were already completed.

func (*PendingUpgrade) PushStage

func (pu *PendingUpgrade) PushStage(stage UpgradeStage)

PushStage marks the given stage as completed.

type UpgradeStage

type UpgradeStage uint64

UpgradeStage is used in the upgrade descriptor to store completed stages.