args4c

package args4c

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:
     config.filter(_.startsWith("myapp")).summary().foreach(println)
   }
}

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/test.conf@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.

Linear Supertypes

AnyRef, Any

Ordering

Alphabetic
By Inheritance

Inherited

args4c
AnyRef
Any

Hide All
Show All

Visibility

Public
All

Type Members

trait ConfigApp extends LowPriorityArgs4cImplicits
A convenience mix-in utility for a main entry point.
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 '--secret=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 secret config to (/opt/etc/myapp/.config/secret.conf):config/secret.conf
Config Permissions (defaults to rwx------): rwxrw----
Add config path in the form <key>=<value> (leave blank when finished):myapp.secret.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 --secret=config/secret.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 secret config:
```
myapp.another.config.entry : **** obscured **** # secret.conf: 1
myapp.secret.password : **** obscured **** # secret.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 secret config from the remaining config, or just ensuring to limit the scope of the config itself.
trait LowPriorityArgs4cImplicits extends AnyRef
class RichConfig extends RichConfigOps
Adds some scala utility around a typesafe config
trait RichConfigOps extends LowPriorityArgs4cImplicits
Provider operations on a 'config'
case class StringEntry(comments: List[String], origin: String, key: String, value: String) extends Product with Serializable

Value Members

def configForArgs(args: Array[String], fallback: Config = defaultConfig(), onUnrecognizedArg: (String) ⇒ Config = ParseArg.Throw): Config
Given the user arguments, produce a loaded configuration which interprets the user-args from left to right as:
Given the user arguments, produce a loaded configuration which interprets the user-args from left to right as:
$ a configuration file on the classpath or file system $ a key=value pair
Left-most values take precedence over right
args
the user command-line arguments
fallback
the default configuration to fall back to
onUnrecognizedArg
the handler for unrecognized user arguments
returns
a parsed configuration
def configForMap(confMap: Map[String, String]): Config
returns
a config for this map
def defaultConfig(): Config
returns
essentially ConfigFactory.load() but with sysEnvAsConfig layered over the default application
val defaultObscuredText: String
def env(key: String): Option[String]
def envOrProp(key: String): Option[String]
def obscurePassword(configPath: String, value: String, blacklist: Set[String] = passwordBlacklist, obscuredValue: String = defaultObscuredText): String
configPath
the config key (e.g. foo.bar.bazz)
value
the config value, as a string
blacklist
a 'blacklist' which, if any of the entries are found anywhere in the configPath, then the value will be obscured
returns
the
def passwordBlacklist: Set[String]
def pathAsFile(path: String): Option[Path]
def pathAsUrl(path: String): Option[URL]
def pathToBytes(path: String): Option[Array[Byte]]
def prop(key: String): Option[String]
def propOrEnv(key: String): Option[String]
def sysEnvAsConfig(env: Map[String, String] = sys.env): Config
Converts environment variables into a configuration in order to more easily override any config setting based on an environment variable.
Converts environment variables into a configuration in order to more easily override any config setting based on an environment variable.
e.g. instead of having the config:
```
foo.bar.x = 123
foo.bar.x = $${?FOO_BAR_X}
```
repeated for each setting we can just convert all environment variables split on '_' into lower-case configuration values.
e.g. 'FOO_BAR_X' would get converted into 'foo.bar.x'.
object Encryption
object RichConfig
object SecretConfig
Makes available a means to initialize a sensitive, encrypted config file via SecretConfig.writeSecretsUsingPrompt and ConfigApp.secretConfigForArgs
Makes available a means to initialize a sensitive, encrypted config file via SecretConfig.writeSecretsUsingPrompt and ConfigApp.secretConfigForArgs
The idea is that a (service) user-only readable, password-protected AES encrypted config file can be set up via reading entries from standard input, and an application an use those configuration entries thereafter by taking the password from standard input.
object implicits extends LowPriorityArgs4cImplicits
Exposes the entry point for using a RichConfig,
Exposes the entry point for using a RichConfig,
mostly for converting user-args into a config

Packages

args4c

package args4c

Type Members

Value Members

Inherited from AnyRef

Inherited from Any

Ungrouped

Packages

args4c 

package args4c

Type Members

Value Members

Inherited from AnyRef

Inherited from Any

Ungrouped

args4c