Packages

  • package root
    Definition Classes
    root
  • package args4c

    Args4c (arguments for configuration) is intended to add some helpers and utilities in obtaining a typesafe configuration from user arguments.

    Args4c (arguments for configuration) is intended to add some helpers and utilities in obtaining a typesafe configuration from user arguments.

    The core is simply to convert an Array[String] to a Config where the arguments are either paths to configuration resources or simple key=value pairs via args4c.configForArgs

    Left-most arguments take precedence. In this example, we assume 'prod.conf' is a resource on the classpath:

    MyApp foo.x=bar foo.x=ignored /opt/etc/overrides.conf prod.conf

    In addition to this core concept, this library also provides some additional configuration utilities via args4c.RichConfigOps which can be made available by extending args4c.LowPriorityArgs4cImplicits or importing args4c.implicits:

    import args4c.implicits._
    object MyApp {
       override def main(args : Array[String]) : Unit = {
         val config = args.asConfig()
         println("Starting MyApp with config:")
    
         // let's "log" our app's config on startup:
         val flatSummary : String = config.filter(_.startsWith("myapp")).summary()
         println(flatSummary) // "logging" our config
       }
    }

    Where the 'summary' will produce sorted args4c.StringEntry values with potentially sensitive entries (e.g. passwords) obscured and a source comment for some sanity as to where each entry comes from:

    myapp.foo : bar # command-line
    myapp.password : **** obscured **** # command-line
    myapp.saveTo : afile # file:/opt/etc/myapp/[email protected]3

    Also, when extracting user arguments into a configuration, an additional 'fallback' config is specified. Typically this would just be the ConfigFactory.load() configuration, but args4c uses the args4c.defaultConfig, which is essentially just the system environment variables converted from snake-caes to dotted lowercase values first, then falling back on ConfigFactory.load().

    Applications can elect to not have this behaviour and provide their own fallback configs when parsing args, but the default provides a convenience for system environment variables to override e.g. 'foo.bar.x=default' by specifying

    FOO_BAR_X=override

    as a system environment variable. Otherwise you may end up having to repeat this sort of thing all over you config:

    foo.bar=default
    foo.bar=$${?FOO_BAR}
    
    foo.bazz=default2
    foo.bazz=$${?FOO_BAZZ}
    
    ...

    Finally, args4c also provides a args4c.ConfigApp which provides some additional functionality to configuration-based applications.

    Definition Classes
    root
  • ConfigApp
  • Encryption
  • LowPriorityArgs4cImplicits
  • PasswordPrompt
  • Prompt
  • PromptForConfigFilePermissions
  • PromptForExistingPassword
  • PromptForPassword
  • PromptForUpdatedPassword
  • ReadNextKeyValuePair
  • ReadNextKeyValuePairAfterError
  • RichConfig
  • RichConfigOps
  • SaveSecretPrompt
  • SecureConfig
  • Selected
  • StringEntry
  • implicits
t

args4c

ConfigApp

trait ConfigApp extends LowPriorityArgs4cImplicits

A convenience mix-in utility for a main entry point.

It parsed the user arguments using the default config (which is ConfigFactory.load() but w/ system environment variables overlaid)

If the config has a 'show=<path>' in it, then that path will be printed out and the program with return.

e.g. MyAppWhichExtendsConfigApp show=myapp.database.url

will display the value of myapp.database.url

It also interprets a single '--setup' to enable the configuration of sensitive configuration entries into a locally encrypted file.

Subsequent runs of your application would then use '--secure=path/to/encrypted.conf' to load that encrypted configuration and either take the password from an environment variable or standard input.

For example, running 'MyApp --setup' would then prompt like this:

Save secure config to (/opt/etc/myapp/.config/secure.conf):config/secure.conf
Config Permissions (defaults to rwx------): rwxrw----
Add config path in the form <key>=<value> (leave blank when finished):myapp.secure.password=hi
Add config path in the form <key>=<value> (leave blank when finished):myapp.another.config.entry=123
Add config path in the form <key>=<value> (leave blank when finished):
Config Password:password

Then, running 'MyApp --secure=config/secure.conf -myapp.whocares=visible -show=myapp'

would prompt for the password from standard input, then produce the following, hiding the values which were present in the secure config:

myapp.another.config.entry : **** obscured **** # secure.conf: 1
myapp.secure.password : **** obscured **** # secure.conf: 1
myapp.whocares : visible # command-line

NOTE: even though the summary obscures the values, they ARE present as PLAIN TEXT STRINGS in the configuration, so take care in limiting the scope of where the configuration is used, either by filtering back out those values, otherwise separating the secure config from the remaining config, or just ensuring to limit the scope of the config itself.

Linear Supertypes
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. ConfigApp
  2. LowPriorityArgs4cImplicits
  3. AnyRef
  4. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Type Members

  1. abstract type Result

    The result of running this application

  2. case class SecureConfigDoesntExist(path: Path) extends SecureConfigState with Product with Serializable
    Attributes
    protected
  3. case class SecureConfigParsed(path: Path, config: Config) extends SecureConfigState with Product with Serializable
    Attributes
    protected
  4. sealed abstract class SecureConfigState extends AnyRef

    Represents the state of the '--secure' config

    Represents the state of the '--secure' config

    Attributes
    protected
  5. implicit class RichArgs extends AnyRef
    Definition Classes
    LowPriorityArgs4cImplicits
  6. implicit class RichString extends AnyRef
    Definition Classes
    LowPriorityArgs4cImplicits

Abstract Value Members

  1. abstract def run(config: Config): Result

    Instead of 'main', this 'apply' should run w/ a config

    Instead of 'main', this 'apply' should run w/ a config

    config

    the configuration to run with

Concrete Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  5. def clone(): AnyRef
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @native() @throws( ... )
  6. implicit def configAsRichConfig(c: Config): RichConfig
    Definition Classes
    LowPriorityArgs4cImplicits
  7. val configKeyForRequiredEntries: String
    Attributes
    protected
  8. def defaultConfig(): Config

    returns

    the default config to overlay the user args over.

  9. def defaultIgnoreDefaultSecureConfigArg: String

    returns

    he command-line argument flag which tells the application NOT to load the default secure config file if it exists. e.g., try running the app without the secure config.

    Attributes
    protected
  10. def defaultSecureConfigArgFlag: String

    returns

    the command-line argument to specify the path to an encrypted secure config file (e.g. MyApp --secure=.passwords.conf)

    Attributes
    protected
  11. def defaultSetupUserArgFlag: String

    returns

    the flag which should indicate that we should prompt to setup secure configurations

    Attributes
    protected
  12. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  13. def equals(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  14. def finalize(): Unit
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  15. final def getClass(): Class[_]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  16. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  17. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  18. def isSetupSpecified(userArgs: Array[String], setupArg: String): Boolean
    Attributes
    protected
  19. def main(args: Array[String]): Unit

    exposes a main entry point which will then:

    exposes a main entry point which will then:

    1) parse the user args as a configuration 2) check the user args if we should just 'show' a particular configuration setting (obscuring sensitive entries) 3) check the user args if we should run 'setup' to configure an encrypted configuration

    args

    the user arguments

  20. def missingRequiredConfigEntriesForConfig(resolvedConfig: Config): Seq[String]

    resolvedConfig

    the configuration we are to run with

    returns

    any paths for invalid/missing configurations (e.g. a 'password' field is left empty, or a hostPort field)

  21. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  22. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  23. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  24. def obscure(securePathsOpt: Option[Seq[String]])(configPath: String, value: String): String
    Attributes
    protected
  25. def onUnrecognizedUserArg(allowedArgs: Set[String])(arg: String): Config
    Attributes
    protected
  26. def pathToSecureConfigFromArgs(userArgs: Array[String], pathToSecureConfigArg: String): Option[String]
    Attributes
    protected
  27. def runMain(userArgs: Array[String], setupUserArgFlag: String = defaultSetupUserArgFlag, ignoreDefaultSecureConfigArg: String = defaultIgnoreDefaultSecureConfigArg, pathToSecureConfigArgFlag: String = defaultSecureConfigArgFlag): Option[Result]

    launch the application, which will create a typesafe config instance from the user arguments by :

    launch the application, which will create a typesafe config instance from the user arguments by :

    $ try to parse the user arguments into a config entry, interpreting them as key=value pairs or locations of config files $ try to load an encrypted 'secure' config if one has been setup to overlay over the other config $ try to map system environment variables as lowercase dot-separated paths so e.g. (FOO_BAR=x) can be used to override foo.bar

    In addition to providing a configuration from the user arguments and environment variables, the user arguments are also checked for one of three special arguments:

    $ The argument 'show=<key substring>' flag, in which case the configuration matching <key substring> is shown. This can be especially convenient to verify the right config values are picked up if there are multiple arguments, such as alternative property files, key=value pairs, etc.

    $ The argument '--setup' in order to populate a password-encrypted secure config file from standard input. For example, running "MyMainEntryPoint --setup" will proceed to prompt the user for config entries which will be saved in a password-encrypted file with restricted permissions. Subsequent runs of the application will check for this file, either in the default location or from -secure=<path/to/encrypted/config>

    If either the default or specified encrypted files are found, then the password is taken either from the CONFIG_SECRET if set, or else it prompted for from standard input

    userArgs

    the user arguments

    setupUserArgFlag

    the argument to check for in order to run the secure config setup

    ignoreDefaultSecureConfigArg

    the argument which, if 'userArgs' contains this string, then we will NOT try

    pathToSecureConfigArgFlag

    the value for the key in the form <key>=<path to secure password config> (e.g. defaults to "--secure", as in --secure=/etc/passwords.conf)

  28. def runWithConfig(userArgs: Array[String], pathToSecureConfig: Path, secureConfigState: SecureConfigState, parsedConfig: Config): Option[Result]

    Exposes a run function which checks the parsedConfig for a 'show' user setting to display the config, otherwise invokes 'run' with the parsed config.

    Exposes a run function which checks the parsedConfig for a 'show' user setting to display the config, otherwise invokes 'run' with the parsed config.

    This method exposes access to the secure config parse result should the application need to do something with it

    userArgs

    the original user args

    pathToSecureConfig

    the path where the secure config should be stored

    secureConfigState

    the result of the secure config user arguments

    parsedConfig

    the total configuration, potentially including the secure config

    Attributes
    protected
  29. def secureConfig: SecureConfig

    returns

    a means to read/write a secure (encrypted) config

    Attributes
    protected
  30. def secureConfigForArgs(userArgs: Array[String], ignoreDefaultSecureConfigArg: String, pathToSecureConfigArg: String): SecureConfigState
    Attributes
    protected
  31. def showValue(value: String, config: Config): Unit

    displays the value for the given config for when the 'show' command-line arg was specified

    displays the value for the given config for when the 'show' command-line arg was specified

    value

    the value to show

    config

    the config value at a particular path

    Attributes
    protected
  32. final def synchronized[T0](arg0: ⇒ T0): T0
    Definition Classes
    AnyRef
  33. def toString(): String
    Definition Classes
    AnyRef → Any
  34. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  35. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  36. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @native() @throws( ... )
  37. object SecureConfigNotSpecified extends SecureConfigState with Product with Serializable
    Attributes
    protected

Inherited from AnyRef

Inherited from Any

Ungrouped