server

README

Server

The server package is responsible for providing the mechanisms necessary to start an ABCI Tendermint application and provides the CLI framework (based on cobra) necessary to fully bootstrap an application. The package exposes two core functions: StartCmd and ExportCmd which creates commands to start the application and export state respectively.

Preliminary

The root command of an application typically is constructed with:

• command to start an application binary
• three meta commands: query, tx, and a few auxiliary commands such as genesis. utilities.

It is vital that the root command of an application uses PersistentPreRun() cobra command property for executing the command, so all child commands have access to the server and client contexts. These contexts are set as their default values initially and maybe modified, scoped to the command, in their respective PersistentPreRun() functions. Note that the client.Context is typically pre-populated with "default" values that may be useful for all commands to inherit and override if necessary.

Example:

var (
	initClientCtx  = client.Context{...}

	rootCmd = &cobra.Command{
		Use:   "simd",
		Short: "simulation app",
		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
			if err := client.SetCmdClientContextHandler(initClientCtx, cmd); err != nil {
				return err
			}

			return server.InterceptConfigsPreRunHandler(cmd)
		},
	}
    // add root sub-commands ...
)

The SetCmdClientContextHandler call reads persistent flags via ReadPersistentCommandFlags which creates a client.Context and sets that on the root command's Context.

The InterceptConfigsPreRunHandler call creates a viper literal, default server.Context, and a logger and sets that on the root command's Context. The server.Context will be modified and saved to disk via the internal interceptConfigs call, which either reads or creates a Tendermint configuration based on the home path provided. In addition, interceptConfigs also reads and loads the application configuration, app.toml, and binds that to the server.Context viper literal. This is vital so the application can get access to not only the CLI flags, but also to the application configuration values provided by this file.

StartCmd

The StartCmd accepts an AppCreator function which returns an Application. The AppCreator is responsible for constructing the application based on the options provided to it via AppOptions. The AppOptions interface type defines a single method, Get() interface{}, and is implemented as a viper literal that exists in the server.Context. All the possible options an application may use and provide to the construction process are defined by the StartCmd and by the application's config file, app.toml.

The application can either be started in-process or as an external process. The former creates a Tendermint service and the latter creates a Tendermint Node.

Under the hood, StartCmd will call GetServerContextFromCmd, which provides the command access to a server.Context. This context provides access to the viper literal, the Tendermint config and logger. This allows flags to be bound the viper literal and passed to the application construction.

Example:

func newApp(logger log.Logger, db dbm.DB, traceStore io.Writer, appOpts server.AppOptions) server.Application {
	var cache sdk.MultiStorePersistentCache

	if cast.ToBool(appOpts.Get(server.FlagInterBlockCache)) {
		cache = store.NewCommitKVStoreCacheManager()
	}

	skipUpgradeHeights := make(map[int64]bool)
	for _, h := range cast.ToIntSlice(appOpts.Get(server.FlagUnsafeSkipUpgrades)) {
		skipUpgradeHeights[int64(h)] = true
	}

	pruningOpts, err := server.GetPruningOptionsFromFlags(appOpts)
	if err != nil {
		panic(err)
	}

	return simapp.NewSimApp(
		logger, db, traceStore, true, skipUpgradeHeights,
		cast.ToString(appOpts.Get(flags.FlagHome)),
		cast.ToUint(appOpts.Get(server.FlagInvCheckPeriod)),
        simapp.EmptyAppOptions{},
		nil,
		baseapp.SetPruning(pruningOpts),
		baseapp.SetMinGasPrices(cast.ToString(appOpts.Get(server.FlagMinGasPrices))),
		baseapp.SetHaltHeight(cast.ToUint64(appOpts.Get(server.FlagHaltHeight))),
		baseapp.SetHaltTime(cast.ToUint64(appOpts.Get(server.FlagHaltTime))),
		baseapp.SetInterBlockCache(cache),
		baseapp.SetTrace(cast.ToBool(appOpts.Get(server.FlagTrace))),
	)
}

Note, some of the options provided are exposed via CLI flags in the start command and some are also allowed to be set in the application's app.toml. It is recommend to use the cast package for type safety guarantees and due to the limitations of CLI flag types.

Documentation

Overview

The commands from the SDK are defined with `cobra` and configured with the `viper` package.

This takes place in the `InterceptConfigsPreRunHandler` function. Since the `viper` package is used for configuration the precedence is dictated by that package. That is

1. Command line switches 2. Environment variables 3. Files from configuration values 4. Default values

The global configuration instance exposed by the `viper` package is not used by Cosmos SDK in this function. A new instance of `viper.Viper` is created and the following is performed. The environmental variable prefix is set to the current program name. Environmental variables consider the underscore to be equivalent to the `.` or `-` character. This means that an configuration value called `rpc.laddr` would be read from an environmental variable called `MYTOOL_RPC_LADDR` if the current program name is `mytool`.

Running the `InterceptConfigsPreRunHandler` also reads `app.toml` and `config.toml` from the home directory under the `config` directory. If `config.toml` or `app.toml` do not exist then those files are created and populated with default values. `InterceptConfigsPreRunHandler` takes two parameters to set/update a custom template to create custom `app.toml`. If these parameters are empty, the server then creates a default template provided by the SDK.

Index

• Constants
• func AddCommands(rootCmd *cobra.Command, defaultNodeHome string, appCreator types.AppCreator, ...)
• func ExportCmd(appExporter types.AppExporter, defaultNodeHome string) *cobra.Command
• func ExternalIP() (string, error)
• func FreeTCPAddr() (addr, port string, err error)
• func GenerateCoinKey(algo keyring.SignatureAlgo) (sdk.AccAddress, string, error)
• func GenerateSaveCoinKey(keybase keyring.Keyring, keyName string, overwrite bool, ...) (sdk.AccAddress, string, error)
• func GetPruningOptionsFromFlags(appOpts types.AppOptions) (storetypes.PruningOptions, error)
• func InterceptConfigsPreRunHandler(cmd *cobra.Command, customAppConfigTemplate string, ...) error
• func ListenForQuitSignals(g *errgroup.Group, block bool, cancelFn context.CancelFunc, ...)
• func NewRollbackCmd(appCreator types.AppCreator, defaultNodeHome string) *cobra.Command
• func SetCmdServerContext(cmd *cobra.Command, serverCtx *Context) error
• func SetupTraceWriter(logger tmlog.Logger, traceWriterFile string) (traceWriter io.WriteCloser, cleanup func(), err error)
• func ShowAddressCmd() *cobra.Command
• func ShowNodeIDCmd() *cobra.Command
• func ShowValidatorCmd() *cobra.Command
• func StartCmd(appCreator types.AppCreator, defaultNodeHome string) *cobra.Command
• func TrapSignal(cleanupFunc func())
• func VersionCmd() *cobra.Command
• type Context
  • func GetServerContextFromCmd(cmd *cobra.Command) *Context
  • func NewContext(v *viper.Viper, config *tmcfg.Config, logger tmlog.Logger) *Context
  • func NewDefaultContext() *Context
• type ErrorCode
  • func (e ErrorCode) Error() string

Constants

const (
	FlagHeight           = "height"
	FlagForZeroHeight    = "for-zero-height"
	FlagJailAllowedAddrs = "jail-allowed-addrs"
)

const (
	FlagMinGasPrices        = "minimum-gas-prices"
	FlagHaltHeight          = "halt-height"
	FlagHaltTime            = "halt-time"
	FlagInterBlockCache     = "inter-block-cache"
	FlagInterBlockCacheSize = "inter-block-cache-size"
	FlagUnsafeSkipUpgrades  = "unsafe-skip-upgrades"
	FlagTrace               = "trace"
	FlagInvCheckPeriod      = "inv-check-period"
	FlagPrometheus          = "prometheus"
	FlagChanCheckTxSize     = "chan-check-tx-size"

	FlagPruning           = "pruning"
	FlagPruningKeepRecent = "pruning-keep-recent"
	FlagPruningKeepEvery  = "pruning-keep-every"
	FlagPruningInterval   = "pruning-interval"
	FlagIndexEvents       = "index-events"
	FlagMinRetainBlocks   = "min-retain-blocks"
	FlagIAVLCacheSize     = "iavl-cache-size"
	FlagIAVLFastNode      = "iavl-disable-fastnode"

	// state sync-related flags
	FlagStateSyncSnapshotInterval   = "state-sync.snapshot-interval"
	FlagStateSyncSnapshotKeepRecent = "state-sync.snapshot-keep-recent"
)

Ostracon full-node start flags

const ServerContextKey = sdk.ContextKey("server.context")

ServerContextKey defines the context key used to retrieve a server.Context from a command's Context.

Functions

func AddCommands

func AddCommands(rootCmd *cobra.Command, defaultNodeHome string, appCreator types.AppCreator, appExport types.AppExporter, addStartFlags types.ModuleInitFlags)

add server commands

func ExportCmd

func ExportCmd(appExporter types.AppExporter, defaultNodeHome string) *cobra.Command

ExportCmd dumps app state to JSON.

func ExternalIP

func ExternalIP() (string, error)

https://stackoverflow.com/questions/23558425/how-do-i-get-the-local-ip-address-in-go TODO there must be a better way to get external IP

func FreeTCPAddr

func FreeTCPAddr() (addr, port string, err error)

Get a free address for a test ostracon server protocol is either tcp, http, etc

func GenerateCoinKey

func GenerateCoinKey(algo keyring.SignatureAlgo) (sdk.AccAddress, string, error)

Deprecated: GenerateCoinKey generates a new key mnemonic along with its addrress. Please use testutils.GenerateCoinKey instead.

func GenerateSaveCoinKey

func GenerateSaveCoinKey(
	keybase keyring.Keyring,
	keyName string,
	overwrite bool,
	algo keyring.SignatureAlgo,
) (sdk.AccAddress, string, error)

Deprecated: GenerateSaveCoinKey generates a new key mnemonic with its addrress. If mnemonic is provided then it's used for key generation. The key is saved in the keyring. The function returns error if overwrite=true and the key already exists. Please use testutils.GenerateSaveCoinKey instead.

func GetPruningOptionsFromFlags

func GetPruningOptionsFromFlags(appOpts types.AppOptions) (storetypes.PruningOptions, error)

GetPruningOptionsFromFlags parses command flags and returns the correct PruningOptions. If a pruning strategy is provided, that will be parsed and returned, otherwise, it is assumed custom pruning options are provided.

func InterceptConfigsPreRunHandler

func InterceptConfigsPreRunHandler(cmd *cobra.Command, customAppConfigTemplate string, customAppConfig interface{}) error

InterceptConfigsPreRunHandler performs a pre-run function for the root daemon application command. It will create a Viper literal and a default server Context. The server Tendermint configuration will either be read and parsed or created and saved to disk, where the server Context is updated to reflect the Tendermint configuration. It takes custom app config template and config settings to create a custom Tendermint configuration. If the custom template is empty, it uses default-template provided by the server. The Viper literal is used to read and parse the application configuration. Command handlers can fetch the server Context to get the Tendermint configuration or to get access to Viper.

func ListenForQuitSignals

func ListenForQuitSignals(g *errgroup.Group, block bool, cancelFn context.CancelFunc, logger tmlog.Logger)

ListenForQuitSignals listens for SIGINT and SIGTERM. When a signal is received, the cleanup function is called, indicating the caller can gracefully exit or return.

Note, the blocking behavior of this depends on the block argument. The caller must ensure the corresponding context derived from the cancelFn is used correctly.

func NewRollbackCmd

func NewRollbackCmd(appCreator types.AppCreator, defaultNodeHome string) *cobra.Command

NewRollbackCmd creates a command to rollback tendermint and multistore state by one height.

func SetCmdServerContext

func SetCmdServerContext(cmd *cobra.Command, serverCtx *Context) error

SetCmdServerContext sets a command's Context value to the provided argument.

func SetupTraceWriter

func SetupTraceWriter(logger tmlog.Logger, traceWriterFile string) (traceWriter io.WriteCloser, cleanup func(), err error)

SetupTraceWriter sets up the trace writer and returns a cleanup function.

func ShowAddressCmd

func ShowAddressCmd() *cobra.Command

ShowAddressCmd - show this node's validator address

func ShowNodeIDCmd

func ShowNodeIDCmd() *cobra.Command

ShowNodeIDCmd - ported from Ostracon, dump node ID to stdout

func ShowValidatorCmd

func ShowValidatorCmd() *cobra.Command

ShowValidatorCmd - ported from Ostracon, show this node's validator info

func StartCmd

func StartCmd(appCreator types.AppCreator, defaultNodeHome string) *cobra.Command

StartCmd runs the service passed in, either stand-alone or in-process with Ostracon.

func TrapSignal

func TrapSignal(cleanupFunc func())

TrapSignal traps SIGINT and SIGTERM and terminates the server correctly.

func VersionCmd

func VersionCmd() *cobra.Command

VersionCmd prints ostracon and ABCI version numbers.

Types

type Context

type Context struct {
	Viper  *viper.Viper
	Config *tmcfg.Config
	Logger tmlog.Logger
}

server context

func GetServerContextFromCmd

func GetServerContextFromCmd(cmd *cobra.Command) *Context

GetServerContextFromCmd returns a Context from a command or an empty Context if it has not been set.

func NewContext

func NewContext(v *viper.Viper, config *tmcfg.Config, logger tmlog.Logger) *Context

func NewDefaultContext

func NewDefaultContext() *Context

type ErrorCode

type ErrorCode struct {
	Code int
}

ErrorCode contains the exit code for server exit.

func (ErrorCode) Error

func (e ErrorCode) Error() string