github.com/Finschia/finschia-sdk@v0.48.1/server/README.md (about)

     1  # Server
     2  
     3  The `server` package is responsible for providing the mechanisms necessary to
     4  start an ABCI Tendermint application and provides the CLI framework (based on [cobra](github.com/spf13/cobra))
     5  necessary to fully bootstrap an application. The package exposes two core functions: `StartCmd`
     6  and `ExportCmd` which creates commands to start the application and export state respectively.
     7  
     8  ## Preliminary
     9  
    10  The root command of an application typically is constructed with:
    11  
    12  + command to start an application binary
    13  + three meta commands: `query`, `tx`, and a few auxiliary commands such as `genesis`.
    14  utilities.
    15  
    16  It is vital that the root command of an application uses `PersistentPreRun()` cobra command
    17  property for executing the command, so all child commands have access to the server and client contexts.
    18  These contexts are set as their default values initially and maybe modified,
    19  scoped to the command, in their respective `PersistentPreRun()` functions. Note that
    20  the `client.Context` is typically pre-populated with "default" values that may be
    21  useful for all commands to inherit and override if necessary.
    22  
    23  Example:
    24  
    25  ```go
    26  var (
    27  	initClientCtx  = client.Context{...}
    28  
    29  	rootCmd = &cobra.Command{
    30  		Use:   "simd",
    31  		Short: "simulation app",
    32  		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
    33  			if err := client.SetCmdClientContextHandler(initClientCtx, cmd); err != nil {
    34  				return err
    35  			}
    36  
    37  			return server.InterceptConfigsPreRunHandler(cmd)
    38  		},
    39  	}
    40      // add root sub-commands ...
    41  )
    42  ```
    43  
    44  The `SetCmdClientContextHandler` call reads persistent flags via `ReadPersistentCommandFlags`
    45  which creates a `client.Context` and sets that on the root command's `Context`.
    46  
    47  The `InterceptConfigsPreRunHandler` call creates a viper literal, default `server.Context`,
    48  and a logger and sets that on the root command's `Context`. The `server.Context`
    49  will be modified and saved to disk via the internal `interceptConfigs` call, which
    50  either reads or creates a Tendermint configuration based on the home path provided.
    51  In addition, `interceptConfigs` also reads and loads the application configuration,
    52  `app.toml`, and binds that to the `server.Context` viper literal. This is vital
    53  so the application can get access to not only the CLI flags, but also to the
    54  application configuration values provided by this file.
    55  
    56  ## `StartCmd`
    57  
    58  The `StartCmd` accepts an `AppCreator` function which returns an `Application`.
    59  The `AppCreator` is responsible for constructing the application based on the
    60  options provided to it via `AppOptions`. The `AppOptions` interface type defines
    61  a single method, `Get() interface{}`, and is implemented as a [viper](https://github.com/spf13/viper)
    62  literal that exists in the `server.Context`. All the possible options an application
    63  may use and provide to the construction process are defined by the `StartCmd`
    64  and by the application's config file, `app.toml`.
    65  
    66  The application can either be started in-process or as an external process. The
    67  former creates a Tendermint service and the latter creates a Tendermint Node.
    68  
    69  Under the hood, `StartCmd` will call `GetServerContextFromCmd`, which provides
    70  the command access to a `server.Context`. This context provides access to the
    71  viper literal, the Tendermint config and logger. This allows flags to be bound
    72  the viper literal and passed to the application construction.
    73  
    74  Example:
    75  
    76  ```go
    77  func newApp(logger log.Logger, db dbm.DB, traceStore io.Writer, appOpts server.AppOptions) server.Application {
    78  	var cache sdk.MultiStorePersistentCache
    79  
    80  	if cast.ToBool(appOpts.Get(server.FlagInterBlockCache)) {
    81  		cache = store.NewCommitKVStoreCacheManager()
    82  	}
    83  
    84  	skipUpgradeHeights := make(map[int64]bool)
    85  	for _, h := range cast.ToIntSlice(appOpts.Get(server.FlagUnsafeSkipUpgrades)) {
    86  		skipUpgradeHeights[int64(h)] = true
    87  	}
    88  
    89  	pruningOpts, err := server.GetPruningOptionsFromFlags(appOpts)
    90  	if err != nil {
    91  		panic(err)
    92  	}
    93  
    94  	return simapp.NewSimApp(
    95  		logger, db, traceStore, true, skipUpgradeHeights,
    96  		cast.ToString(appOpts.Get(flags.FlagHome)),
    97  		cast.ToUint(appOpts.Get(server.FlagInvCheckPeriod)),
    98          simapp.EmptyAppOptions{},
    99  		nil,
   100  		baseapp.SetPruning(pruningOpts),
   101  		baseapp.SetMinGasPrices(cast.ToString(appOpts.Get(server.FlagMinGasPrices))),
   102  		baseapp.SetHaltHeight(cast.ToUint64(appOpts.Get(server.FlagHaltHeight))),
   103  		baseapp.SetHaltTime(cast.ToUint64(appOpts.Get(server.FlagHaltTime))),
   104  		baseapp.SetInterBlockCache(cache),
   105  		baseapp.SetTrace(cast.ToBool(appOpts.Get(server.FlagTrace))),
   106  	)
   107  }
   108  ```
   109  
   110  Note, some of the options provided are exposed via CLI flags in the start command
   111  and some are also allowed to be set in the application's `app.toml`. It is recommend
   112  to use the `cast` package for type safety guarantees and due to the limitations of
   113  CLI flag types.