Hoplite

Preprocessors are functions applied to every value as it is read from the configuration source. They can transform values (e.g., performing environment variable substitution, database lookups, or secret retrieval) or act as an identity function.

To add a custom preprocessor, use the withPreprocessor method on the ConfigLoader class and provide an instance of the Preprocessor interface.

If you need one preprocessor to resolve a value that then requires another preprocessor to resolve, you can enable looped application by setting withPreprocessingIterations on the ConfigLoaderBuilder to a value greater than 1.

val config = ConfigLoaderBuilder.default()
  .withPreprocessingIterations(2)
  .withPreprocessor(MyCustomPreprocessor())
  .build()
  .loadConfigOrThrow<MyConfig>()

Hoplite uses ParameterMapper implementations to transform parameter names before looking them up in a source. By default, KebabCaseParamMapper and SnakeCaseParamMapper are registered, allowing you to use idiomatic config keys that don't match your Kotlin field names exactly.

// Kotlin field
data class Database(val instanceHostName: String)

// Works with kebab-case in YAML
database:
  instance-host-name: server1.prd

// Works with snake_case in YAML
database:
  instance_host_name: server1.prd

For modular configuration (e.g., plugins or independent modules), you can bind specific sub-trees of your configuration to independent data classes using a ConfigBinder. This allows you to parse the configuration sources only once and then extract specific sections using a prefix.

Example: If your YAML contains:

module1:
  foo: bar
module2:
  baz: qux

You can bind them like this:

val configBinder = ConfigLoaderBuilder.default()
  .addResourceSource("/application-prod.yml")
  .build()
  .configBinder()

val module1Config = configBinder.bindOrThrow<Module1Config>("module1")
val module2Config = configBinder.bindOrThrow<Module2Config>("module2")

A prefix can also be passed directly to loadConfig variants if only one prefix is needed. Prefixes can be nested (e.g., foo.bar).

A PropertySource is the mechanism Hoplite uses to read configuration values. Hoplite provides several built-in implementations that are automatically registered in a specific precedence order:

1. EnvironmentVariablesPropertySource
2. SystemPropertiesPropertySource
3. UserSettingsPropertySource
4. XdgConfigPropertySource

You can add custom property sources or additional built-in ones to the ConfigLoaderBuilder as needed.

Hoplite supports parsing duration types from strings using lower-case unit names. An optional space is allowed between the value and the unit. Supported units are:

• Nanoseconds: ns, nano, nanos, nanosecond, nanoseconds
• Microseconds: us, micro, micros, microsecond, microseconds
• Milliseconds: ms, milli, millis, millisecond, milliseconds
• Seconds: s, second, seconds
• Minutes: m, minute, minutes
• Hours: h, hour, hours
• Days: d, day, days

Examples: 10s, 3 days, or 12 hours.

Hoplite supports cascading configuration by passing multiple sources to the loader. When resolving keys, Hoplite searches through the sources in the order they were provided. The first source that defines a key wins.

Important Rule for Lists: Lists cannot be merged. If a key pointing to a list is found in a higher-priority source, the entire list from that source is used, and values from lower-priority sources are ignored.

// 'prod.json' values will take priority over 'default.json' values
val config = ConfigLoader.load("prod.json", "default.json")

Hoplite supports Kotlin inline classes, allowing you to use strong types (e.g., Port instead of Int) without requiring nested configuration keys. The loader will map the flat configuration value directly to the inline class constructor.

inline class Port(val value: Int)
inline class Hostname(val value: String)

data class Database(val port: Port, val host: Hostname)

// yaml config: // port: 9200 // host: localhost

val config = ConfigLoader().loadConfigOrThrow<Database>("config.file") println(config.port) // Port(9200)

To prevent sensitive information like passwords or API keys from appearing in logs when using Kotlin's toString() on configuration data classes, use the Masked type. A field declared as Masked will be loaded normally but will be represented as **** in the generated toString() output.

Note on JSON Serialization: The masking effect only applies to toString(). If you use a reflection-based tool like Jackson to marshal your config to a String, the underlying value will still be visible. To mask values in JSON output, register the HopliteModule (available in the hoplite-json module) with your Jackson ObjectMapper.

data class Database(val host: String, val user: String, val password: Masked)

{
  "host": "localhost",
  "user": "root",
  "password": "letmein"
}

// Output via toString(): // Database(host=localhost, user=root, password=****)