visor

README

Vega Visor

A binaries runner for Core and Data Node that facilitates automatic protocol upgrades.

Features:

• Visor is connected to core nodes and listens for protocol upgrades.
• Visor allows you to run core and data node binaries based on custom configuration.
• When a protocol upgrade is ready to be used, Visor automatically stops currently running binaries and starts new ones with the selected version.
• Visor can be configured to automatically fetch binaries with the correct version during the upgrade.
• Visor is highly configurable and allows you to configure the number of restarts, restarts delays, specific upgrade configuration and much more.

Architecture

Visor stores all its required config files and state in a home folder. The basic folder structure can be generated by visor init cmd or manually.

Home folder structure:

HOME_FOLDER_PATH
├── config.toml
├── current
├── genesis
│   └── run-config.toml
└── vX.X.X
    └── run-config.toml

• config.toml - a Visor configuration file.
• run-config.toml - a Run configuration file.
• current - a symlink to the currently loaded configuration folder used to run the binaries. On Visor start up, when the current folder is missing, Visor will link to the genesis folder to use as current by default. During the upgrade, if not specified otherwise, Visor will try to link to a folder named after the version of the upgrade - for example vX.X.X. This symlink is automatically managed by Visor and it should not be tampered with manually.
• genesis - a default folder with Run configuration that Visor automatically links to current folder in case current folder does not exists.
• vX.X.X - any folder with a name of the upgrade version that stores Run configuration for the upgrade.

Upgrade flow

1. During the first start up of Visor (when Visor has never been used before) a user provides run-config.toml and stores it in genesis folder.
2. When Visor starts up, it automatically links the current folder to the genesis folder and starts the corresponding processes based on the provided run-config.toml.
3. Visor connects to the core node and communicates with it via RPC API.
4. When validators agree on executing a protocol upgrade to a certain version and the network has reached the proposed upgrade block height, the core node will notify Visor about the upgrade.

• When autoInstall is enabled by a validator, then Visor automatically fetches the binaries with the correct version and prepares the upgrade folder.
• When autoInstall is NOT enabled, then a validator has to manually download the right binaries with correspoding version and prepare the upgrade folder with run-config.toml in it before the upgrade block height.

1. When Visor is notified about the upgrade to a specific version, it links the upgrade folder assosiated with the upgrade (either by being called as version or being specifically mapped manually in Visor config). Then it executes the run config from the upgrade folder.

After that, the whole process is repeated from points 3-5 every time another upgrade takes place.

Setup

Visor stores all its required config files and state in a home folder. The basic folder structure can be generated by visor init cmd or manually. It is vital that all necessary files and folders are present in the home folder, therefore using the init command is recommended.

It is recommended that you run Visor itself with a service manager such as Systemd.

1. Create Visor home folder - visor init.
2. Configure Visor with config.
3. Configure first upgrade folder with run config.
4. Start Visor with a service manager - visor run --home home-path.

Configuration

Visor has 2 different types of configuration. The Visor configuration and Run configuration where the first one is used to configure Visor itself and the latter is used to specify the protocol upgrade.

Visor configuration

A configuration for Visor itself. This configuration is automatically reloaded by Visor so changes in the edited file will be automatically reflected by Visor.

Docs

Run configuration

A configuration for a specific upgrade. This configuration allows to specify binaries and their arguments to be be run in a specific upgrade.

Docs

Documentation

Index

• Variables
• func Init(log *logging.Logger, homeFolder string, withDataNode bool) error
• type Args
  • func (a Args) Exists(name string) bool
  • func (a *Args) ForceSet(name, value string) bool
  • func (a Args) GetFlagWithArg(name string) []string
  • func (a *Args) Set(name, value string) bool
• type BinariesRunner
  • func NewBinariesRunner(log *logging.Logger, binsFolder string, stopDelay, stopTimeout time.Duration, ...) *BinariesRunner
  • func (r *BinariesRunner) Kill() error
  • func (r *BinariesRunner) Run(ctx context.Context, runConf *config.RunConfig, isRestart bool) chan error
  • func (r *BinariesRunner) Stop() error
• type Visor
  • func NewVisor(ctx context.Context, log *logging.Logger, clientFactory client.Factory, ...) (*Visor, error)
  • func (v *Visor) Run(ctx context.Context) error

Variables

var ErrNoHistorySegmentFound = errors.New(noHistorySegmentFoundMsg)

Functions

func Init

func Init(log *logging.Logger, homeFolder string, withDataNode bool) error

Types

type Args

type Args []string

TODO make these functions more robust.

func (Args) Exists

func (a Args) Exists(name string) bool

func (*Args) ForceSet

func (a *Args) ForceSet(name, value string) bool

ForceSet sets a new argument even if the argument currently exists.

func (Args) GetFlagWithArg

func (a Args) GetFlagWithArg(name string) []string

GetFlagWithArg finds and returns a flag with it's argument. Returns nil if not found. Example: --home /path.

func (*Args) Set

func (a *Args) Set(name, value string) bool

Set sets a new argument. Ignores if argument exists.

type BinariesRunner

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

func NewBinariesRunner

func NewBinariesRunner(log *logging.Logger, binsFolder string, stopDelay, stopTimeout time.Duration, rInfo *types.ReleaseInfo) *BinariesRunner

func (*BinariesRunner) Kill

func (r *BinariesRunner) Kill() error

func (*BinariesRunner) Run

func (r *BinariesRunner) Run(ctx context.Context, runConf *config.RunConfig, isRestart bool) chan error

func (*BinariesRunner) Stop

func (r *BinariesRunner) Stop() error

type Visor

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

func NewVisor

func NewVisor(ctx context.Context, log *logging.Logger, clientFactory client.Factory, homePath string) (*Visor, error)

func (*Visor) Run

func (v *Visor) Run(ctx context.Context) error