The main ways for users to configure any service they run is through command-line flags and a configuration file (and possibly environment variables). Therefore these should (a) work well, (b) be easy to use, (c) be predictable, and (d) be well documented.
Owner
@homotopycolimit
Stakeholder Point of Contact
Dependencies
Swarm originally inherited its CLI flag processing from geth and inherited this as technical debt. It is worth considering moving to a different library. Generating and processing a config file may also require choice of a good library.
Description
On the command line, the swarm command serves multiple purposes. On the one hand it launches the swarm process - in this case the command looks like swarm --bzzaccount <address> - and on the other hand it provides access to a running swarm node through subcommands such as swarm up <filename>, swarm down <hash>, swarm hash <file>, or swarm version.
The subcommands of swarm (up, down, fs, hash, etc.) each can take cli flags and subcommands of their own.
The problem is that our current CLI library is not very graceful when it comes to parsing multiple commands and flags. It requires a very strict order, and the error messages when the order is incorrect are unhelpful.
Meanwhile the configuration file is not being used or maintained currently. Sometimes the values in the configuration file are ignored or the wrong values are returned from the dumpconfig subcommand. There is confusion about the order of precedence between ENV variables, CLI flags and the config file.
This entire configuration interface needs to be cleaned up.
Swarm used to be part of the go-ethereum geth binary. It has inherited some CLI flags (for example https://github.com/ethersphere/swarm-guide/issues/136) that Swarm no longer uses.
Furthermore, the fact that swarm on its own attempts to start a new node - as opposed to this being a subcommand swarm start can be traced to these origins.
Flags that are passed to swarm are processed in a different place than flags passed to subcommands such as swarm up. This results in swarm --recursive up working while swarm up --recursive fails.
By default, no configuration file is generated at all when swarm is first run, and indeed only a data directory - and no config directory - are ever defined.
Acceptance criteria
All Swarm CLI commands shall have clear usage documentation that is shown when the command help is given, or whenever the flag --help is given.
The output of --help shall only include relevant flags and be kept short.
The Swarm CLI command shall no longer give errors relating to a different subcommand (i.e. errors in swarm up shall not complain about a missing --bzzaccount as the latter does not concern uploads.
A configuration file shall be generated on first run. The file shall contain all default values in a commented-out form as well as documentation explaining what each variable does.
The config file should not contain unused variables.
The priority of CLI flags, config file entries, and environment variables shall be clearly defined and consistently applied.
A special case can perhaps be made for first start that handles the correct setting of the --bzzaccount. (perhaps a swarm init command?). In any case, the result shall be that the --bzzaccount flag should be required no more than once.
Rationale
The main ways for users to configure any service they run is through command-line flags and a configuration file (and possibly environment variables). Therefore these should (a) work well, (b) be easy to use, (c) be predictable, and (d) be well documented.
Owner
@homotopycolimit
Stakeholder Point of Contact
Dependencies
Swarm originally inherited its CLI flag processing from geth and inherited this as technical debt. It is worth considering moving to a different library. Generating and processing a config file may also require choice of a good library.
Description
On the command line, the
swarmcommand serves multiple purposes. On the one hand it launches the swarm process - in this case the command looks likeswarm --bzzaccount <address>- and on the other hand it provides access to a running swarm node through subcommands such asswarm up <filename>,swarm down <hash>,swarm hash <file>, orswarm version.The subcommands of
swarm(up,down,fs,hash, etc.) each can take cli flags and subcommands of their own.The problem is that our current CLI library is not very graceful when it comes to parsing multiple commands and flags. It requires a very strict order, and the error messages when the order is incorrect are unhelpful.
Meanwhile the configuration file is not being used or maintained currently. Sometimes the values in the configuration file are ignored or the wrong values are returned from the
dumpconfigsubcommand. There is confusion about the order of precedence between ENV variables, CLI flags and the config file.This entire configuration interface needs to be cleaned up.
This has lead to many issues in the past. Currently still marked 'open' are https://github.com/ethersphere/go-ethereum/issues/699 https://github.com/ethersphere/go-ethereum/issues/666 https://github.com/ethersphere/go-ethereum/issues/1143 https://github.com/ethersphere/go-ethereum/issues/873 https://github.com/ethersphere/go-ethereum/issues/917 https://github.com/ethersphere/go-ethereum/issues/982 https://github.com/ethersphere/go-ethereum/issues/1100
other issues include https://github.com/ethersphere/go-ethereum/issues/1023 https://github.com/ethersphere/go-ethereum/issues/477 https://github.com/ethersphere/go-ethereum/issues/447 and more...
Context
Swarm used to be part of the go-ethereum geth binary. It has inherited some CLI flags (for example https://github.com/ethersphere/swarm-guide/issues/136) that Swarm no longer uses. Furthermore, the fact that
swarmon its own attempts to start a new node - as opposed to this being a subcommandswarm startcan be traced to these origins.Flags that are passed to
swarmare processed in a different place than flags passed to subcommands such asswarm up. This results inswarm --recursive upworking whileswarm up --recursivefails.By default, no configuration file is generated at all when swarm is first run, and indeed only a data directory - and no config directory - are ever defined.
Acceptance criteria
All Swarm CLI commands shall have clear usage documentation that is shown when the command
helpis given, or whenever the flag--helpis given. The output of--helpshall only include relevant flags and be kept short.The Swarm CLI command shall no longer give errors relating to a different subcommand (i.e. errors in
swarm upshall not complain about a missing--bzzaccountas the latter does not concern uploads.A configuration file shall be generated on first run. The file shall contain all default values in a commented-out form as well as documentation explaining what each variable does. The config file should not contain unused variables.
The priority of CLI flags, config file entries, and environment variables shall be clearly defined and consistently applied.
A special case can perhaps be made for first start that handles the correct setting of the
--bzzaccount. (perhaps aswarm initcommand?). In any case, the result shall be that the--bzzaccountflag should be required no more than once.