passenger 5.1.7 → 5.1.8

data/src/cxx_supportlib/ConfigKit/README.md

@@ -29,14 +29,12 @@ ConfigKit is a configuration management system that lets you define configuratio
   - [Fetching data](#fetching-data)
   - [Default values](#default-values)
   - [Inspecting all data](#inspecting-all-data)
-- [Putting it all together: synchronous version](#putting-it-all-together-synchronous-version)
-  - [SecurityChecker example: a configurable, low-level component](#securitychecker-example-a-configurable-low-level-component)
-  - [DnsQuerier example: a low-level component with post-configuration application operations](#dnsquerier-example-a-low-level-component-with-post-configuration-application-operations)
-  - [Downloader example: a high-level component that combines subcomponents](#downloader-example-a-high-level-component-that-combines-subcomponents)
-    - [The special problem of conflicting overlapping configuration names and translation](#the-special-problem-of-conflicting-overlapping-configuration-names-and-translation)
-    - [Code example](#code-example)
-  - [Main function example](#main-function-example)
-- [Putting it all together: asynchronous version](#putting-it-all-together-asynchronous-version)
+  - [Inspection filters](#inspection-filters)
+- [Normalizing data](#normalizing-data)
+  - [Normalization example 1](#normalization-example-1)
+  - [Normalization example 2](#normalization-example-2)
+  - [Normalizers and validation](#normalizers-and-validation)
+- [ConfigKit in practice & design patterns](#configkit-in-practice--design-patterns)
 
 <!-- /MarkdownTOC -->
 
@@ -80,7 +78,7 @@ ConfigKit implements these aspects, and also provides various other useful featu
 
 ### Unifying configuration management
 
-Another challenge pertains having different ways to configure a component. Should components be configured using getters and setters for each option? Or should they have a single method that accepts a struct (or some kind of key-value map) that specifies multiple options? Should components be configurable at all after construction. It would be great if we have a unified answer for all components in Passenger.
+Another challenge pertains having different ways to configure a component. Should components be configured using getters and setters for each option? Or should they have a single method that accepts a struct (or some kind of key-value map) that specifies multiple options? Should components be configurable at all after construction? It would be great if we have a unified answer for all components in Passenger.
 
 ConfigKit provides this unified answer:
 
@@ -96,7 +94,10 @@ ConfigKit provides this unified answer:
 
       So we want some kind of key-value data structure. JSON is a pretty popular format nowadays, and is likely to be the format used in the I/O channel, so may as well optimize for JSON.
 
-ConfigKit backs these answers with code that helps you implement these principles, as well as with documented design patterns that provide guidance.
+    - JSON's various data types allow us to easily describe complex configuration settings.
+    - JSON is a widely-accepted format.
+
+ConfigKit backs these answers with code that helps you implement these principles, as well as with [documented design patterns](IN_PRACTICE.md) that provide guidance.
 
 ## Status inside the Passenger codebase
 
@@ -106,17 +107,17 @@ At the time of writing (25 Feb 2017), ConfigKit was just introduced, so these pr
 
 ### ConfigKit::Schema
 
-Everything starts with `ConfigKit::Schema`. This is a class that lets you define a schema of supported configuration keys, their types and other properties like default values. Default values may either be static or dynamically calculated. `ConfigKit::Schema` also allows data validation against the schema.
+Everything starts with `ConfigKit::Schema`. This is a class that lets you define a schema of supported configuration keys, their types and other properties like default values. Default values may either be static or dynamically calculated. The type information defined in a `ConfigKit::Schema` allows data validation against the schema.
 
 ### ConfigKit::Store
 
-There is also `ConfigKit::Store`. This is a class that stores configuration values in such a way that it respects a schema.  The values supplied to and stored in `ConfigKit::Store` are JSON values (i.e. of the `Json::Value` type), although Store uses the schema to validate that you are actually putting the right JSON types in the Store.
+`ConfigKit::Store` is a class that stores configuration values in such a way that it respects a schema. The values supplied to and stored in `ConfigKit::Store` are JSON values (i.e. of the `Json::Value` type), although Store uses the schema to validate that you are actually putting the right JSON types in the Store.
 
 `ConfigKit::Store` also keeps track of which values are explicitly supplied and which ones are not.
 
 ### Translators
 
-And finally there are "translator" classes: `ConfigKit::TableTranslator` and `ConfigKit::PrefixTranslator`. The role of translators are described in the section "The special problem of conflicting overlapping configuration names and translation".
+And finally there are "translator" classes: `ConfigKit::TableTranslator` and `ConfigKit::PrefixTranslator`. The role of translators are described in `IN_PRACTICE.md`, section "The special problem of conflicting overlapping configuration names and translation".
 
 ## Using the schema
 
@@ -136,11 +137,14 @@ schema.add("bar", ConfigKit::FLOAT_TYPE, ConfigKit::OPTIONAL);
 // An optional integer key, with default value 123.
 schema.add("baz", ConfigKit::INTEGER_TYPE, ConfigKit::OPTIONAL, 123);
 
+// An optional string key, without default value, marked as containing a secret.
+schema.add("password", ConfigKit::STRING_TYPE, ConfigKit::OPTIONAL | ConfigKit::SECRET);
+
 // Call this when done, otherwise the object cannot be used yet.
 schema.finalize();
 ~~~
 
-The second one, and the one we recommend, is to subclass ConfigKit::Schema and to add the definitions inside the subclass's constructor. It will become apparent in the section "Putting it all together: synchronous version" why this is the recommended approach.
+The second one, and the one we recommend, is to subclass ConfigKit::Schema and to add the definitions inside the subclass's constructor. It will become apparent in `IN_PRACTICE.md`, section "Synchronous examples" why this is the recommended approach.
 
 ~~~c++
 struct YourSchema: public ConfigKit::Schema {
@@ -149,6 +153,7 @@ struct YourSchema: public ConfigKit::Schema {
         add("foo", STRING_TYPE, REQUIRED);
         add("bar", FLOAT_TYPE, OPTIONAL);
         add("baz", INT_TYPE, OPTIONAL, 123);
+        add("password", STRING_TYPE, OPTIONAL | SECRET);
         finalize();
     }
 };
@@ -162,13 +167,14 @@ YourSchema schema;
 The following types are available:
 
  * `STRING_TYPE` -- a string.
- * `PASSWORD_TYPE` -- a password string. Unlike `STRING_TYPE`, the value of password fields will be filtered out in the output generated by `ConfigKit::Store::inspect()`. Learn more about `inspect()` in [Using the store -- Inspecting all data](#inspecting-all-data).
  * `INT_TYPE` -- a signed integer.
  * `UINT_TYPE` -- an unsigned integer.
  * `FLOAT_TYPE` -- a floating point number.
  * `BOOL_TYPE` -- a boolean.
  * `ARRAY_TYPE` -- an generic array. May contain any values.
  * `STRING_ARRAY_TYPE` -- an array of strings.
+ * `OBJECT_TYPE` -- a generic JSON object. May contain any values.
+ * `ANY_TYPE` -- any JSON value.
 
 #### Flags
 
@@ -176,6 +182,7 @@ The following types are available:
  * `OPTIONAL` -- this field is optional. Mutually exclusive with `REQUIRED`.
  * `CACHE_DEFAULT_VALUE` -- use in combination with [dynamic default values](#defining-default-values). When this flag is set, the value returned by the dynamic value function is cached so that the function won't be called over and over again.
  * `READ_ONLY` -- this field can only be set once. Only the first `ConfigKit::Store::update()` call actually updates the value; subsequent calls won't. Learn more about `update()` in [Using the store -- Putting data in the store](#putting-data-in-the-store).
+ * `SECRET` -- this field contains a secret. `ConfigKit::Store::previewUpdate()` and `ConfigKit::Store::inspect()` will filter out the values of such fields. Learn more this in [Using the store -- Inspecting all data](#inspecting-all-data).
 
 ### Defining default values
 
@@ -215,6 +222,11 @@ schema.addValidator(myValidator);
 schema.finalize();
 ~~~
 
+Miscellaneous notes about custom validators:
+
+ - They are always run, even if the normal type validation fails. For example if the caller tries to set the "foo" key to an array value (which is incompatible with the string type), then `myValidator` will still be called.
+ - All registered validators are called. A validator cannot prevent other validators from running.
+
 ### Inspecting the schema
 
 You can inspect the schema using the `inspect()` method. It returns a Json::Value in the following format:
@@ -224,22 +236,28 @@ You can inspect the schema using the `inspect()` method. It returns a Json::Valu
   "foo": {
     "type": "string",
     "required": true,
-    "has_default_value": true
+    "has_default_value": "static",
+    "default_value": "hello"
   },
   "bar": {
     "type": "float"
   },
   "baz": {
     "type": "integer"
+  },
+  "password": {
+    "type": "string",
+    "secret": true
   }
 }
 ~~~
 
 Description of the members:
 
- - `type`: the schema definition's type. Could be one of "string", "integer", "unsigned integer", "float" or "boolean".
+ - `type`: the schema definition's type. Could be one of "string", "integer", "unsigned integer", "float", "boolean", "array", "array of strings", "object" or "any".
  - `required`: whether this key is required.
- - `has_default_value`: whether a default value is defined.
+ - `has_default_value`: "static" if a static a default value is defined, "dynamic" if a dynamic default value is defined.
+ - `default_value`: the static default value. This field is absent when there is no default value, or if the default value is dynamic.
 
 ## Using the store
 
@@ -346,8 +364,9 @@ store.get("unknown").isNull();  // => true
 
 ### Inspecting all data
 
-You can fetch an overview of all data in the store using `inspect()`.
-This will return a Json::Value in the following format:
+You can fetch an overview of all data in the store using `inspect()`. This function is normally used to allow users of a component to inspect the configuration options set for that component, without allowing them direct access to the embedded store.
+
+This function will return a Json::Value in the following format:
 
 ~~~javascript
 // Assuming we are using the store that went through
@@ -369,6 +388,11 @@ This will return a Json::Value in the following format:
     "default_value": 123,
     "effective_value": 123,
     // ...members from ConfigKit::Schema::inspect() go here...
+  },
+  "password": {
+    "user_value": "[FILTERED]",
+    "effective_value": "[FILTERED]",
+    // ...members from ConfigKit::Schema::inspect() go here...
   }
 }
 ~~~
@@ -379,6 +403,8 @@ Description of the members:
  - `default_value`: the default value as defined in the schema. May be absent.
  - `effective_value`: the effective value, i.e. the value that `get()` will return.
 
+Note that `inspect()` filters out the values of fields with the `SECRET` flag (by setting the returned value to `"[FILTERED]"`), except for null values.
+
 If you want to fetch the effective values only, then use `inspectEffectiveValues()`:
 
 ~~~javascript
@@ -392,529 +418,118 @@ If you want to fetch the effective values only, then use `inspectEffectiveValues
 }
 ~~~
 
-## Putting it all together: synchronous version
-
-Now that you've learned how to use ConfigKit by itself, how does fit in the bigger picture? This section describes good practices and design patterns can that can be used throughout the overall Passenger C++ codebase. At the time of writing (25 Feb 2017), ConfigKit was just introduced, so these practices and patterns aren't yet used everywhere, but the long-term plan is to adopt these practices/patterns throughout the entire codebase.
-
-Let's demonstrate the good practices and design patterns through a number of annotated example classes:
-
- - `SecurityChecker` checks whether the given URL is secure to connect to, by checking a database of vulnerable sites. This example demonstrates basic usage of ConfigKit in a low-level component.
- - `DnsQuerier` looks up DNS information for a given URL, from multiple DNS servers. Because the algorithm that DnsQuerier uses is a performance-critical hot path (or so we claim for the sake of the example), it should cache certain configuration values in a variables instead of looking up the config store over and over, because the latter involve unnecessary hash table lookups. This example demonstrates caching of configuration values. More generally, it demonstrates how to perform arbitrary operations necessary for applying a configuration change.
- - `Downloader` is a high-level class for downloading a specific URL. Under the hood it utilizes `SecurityChecker` and `DnsQuerier`. This example demonstrates how to combine its own configuration with the configuration of multiple lower-level classes.
+### Inspection filters
 
-### SecurityChecker example: a configurable, low-level component
+Since `inspect()` is usually used to allow users of a component to inspect that component's configuration, you may run into situations where you want the inspected return value to be different from its actual value. Inspection filters allow you to transform `inspect()` results.
 
-SecurityChecker checks whether the given URL is secure to connect to, by checking a database of vulnerable sites. This example demonstrates basic usage of ConfigKit in a low-level component.
+A typical use case for inspection filters can be found in LoggingKit. One can configure LoggingKit to log to a specific file descriptor of an open log file. The format is like this:
 
-A configurable component should have the following methods.
-
- - `previewConfigUpdate()`
- - `configure()`
- - `inspectConfig()`
-
-These methods are further explained in the code example
-
-~~~c++
-class SecurityChecker {
-private:
-    // This is the internal configuration store. This is also the
-    // recommended naming scheme: `config`.
-    ConfigKit::Store config;
-
-public:
-    // This defines the SecurityChecker's configuration schema.
-    // This is also the recommended naming scheme:
-    // <YourComponentName>::Schema.
-    struct Schema: public ConfigKit::Schema {
-        Schema() {
-            using namespace ConfigKit;
-            add("db_path", STRING_TYPE, REQUIRED);
-            add("url", STRING_TYPE, REQUIRED);
-            add("timeout", INT_TYPE, OPTIONAL, 60);
-            finalize();
-        }
-    };
-
-    // The constructor takes a Schema so that we can initialize the
-    // configuration store. It should also immediately accept some
-    // initial configuration.
-    //
-    // You might wonder, how about instead of taking a Schema as a parameter,
-    // we define the Schema as a global variable? After all, a
-    // ConfigKit::Schema is immutable after finalization, and different
-    // instances of <YourComponentName>::Schema contain the same content.
-    //
-    // Defining as a global variable is *also* a valid approach, but requires
-    // you to declare it inside a .cpp file and adding that file to the linker
-    // invocation. It's up to you really. I've found taking a schema as a
-    // parameter to be the easiest.
-    SecurityChecker(const Schema &schema, const Json::Value &initialConfig)
-        : config(schema)
-    {
-        vector<ConfigKit::Error> errors;
-
-        if (!config.update(initialConfig, errors)) {
-            throw ArgumentException("Invalid initial configuration: "
-                + toString(errors));
-        }
-    }
-
-    // This method allows checking whether the given configuration updates
-    // would result in any validation errors, without actually changing the
-    // configuration.
-    //
-    // Every configurable component should define such a method, because
-    // higher-level components need this method in order to make configuration
-    // updates across multiple low-level components transactional. You
-    // will learn more about this in the Downloader example.
-    Json::Value previewConfigUpdate(const Json::Value &updates,
-        vector<ConfigKit::Error> &errors)
-    {
-        // In low-level components, it's as simple as forwarding
-        // the call to the configuration store.
-        return config.previewUpdate(updates, errors);
-    }
-
-    // This method actually configures the component.
-    bool configure(const Json::Value &updates, vector<ConfigKit::Error> &errors) {
-        // In low-level components, it's as simple as forwarding
-        // the call to the configuration store.
-        return config.update(updates, errors);
-    }
-
-    // This method inspects the component's configuration.
-    Json::Value inspectConfig() const {
-        // In low-level components, it's as simple as forwarding
-        // the call to the configuration store.
-        return config.inspect();
-    }
-
-    bool check() const {
-        // Fictional code here for performing the lookup.
-        openDatabase(config["db_path"].asString());
-        Entry entry = lookupEntry(config["url"].asString(),
-            config["timeout"].asInt());
-        closeDatabase();
-        return !entry.isNull();
-    }
-};
-~~~
-
-Use SecurityChecker like this:
-
-~~~c++
-SecurityChecker::Schema schema;
-Json::Value config;
-config["db_path"] = "/db";
-config["url"] = "http://www.google.com";
-
-// Initiate SecurityChecker with initial configuration
-SecurityChecker securityChecker(schema, config);
-securityChecker.check();
-
-// Change configuration
-vector<ConfigKit::Error> errors;
-config["url"] = "http://www.example.com";
-if (!securityChecker.configure(config, errors)) {
-    cout << "Configuration change failed: " << toString(errors) << endl;
+~~~json
+{
+  "path": "/foo.log",
+  "fd": 12
 }
-
-// Inspect configuration
-cout << "Final configuration:" << endl;
-cout << securityChecker.inspectConfig().toStyledString() << endl;
 ~~~
 
-### DnsQuerier example: a low-level component with post-configuration application operations
+LoggingKit will internally take over ownership of the file descriptor and will perform a bunch of actions on the fd, such as redirecting stderr to that fd and closing the original fd. Because of this, the fd value is only valid at the time of configuration; it makes no sense to output the fd value in `inspect()`. Inspect filters allows LoggingKit to filter out the "fd" field when `store.inspect()` is called, but the "fd" field can still be accessed internally by LoggingKit by calling `store["target"]["fd"]`.
 
-DnsQuerier looks up DNS information for a given URL, from multiple DNS servers. Because the algorithm that DnsQuerier uses is a performance-critical hot path (or so we claim for the sake of the example), it should cache certain configuration values in a variables instead of looking up the config store over and over, because the latter involve unnecessary hash table lookups. This example demonstrates caching of configuration values. More generally, it demonstrates how to perform arbitrary operations necessary for applying a configuration change.
+An inspect filter is a function takes a value and returns a transformed value. It is installed by calling `setInspectFilter()` on the object returned by `schema.add()`, like this:
 
 ~~~c++
-class DnsQuerier {
-private:
-    // The configuration store, same as with SecurityChecker.
-    ConfigKit::Store config;
-
-    // Caches the "url" configuration value.
-    string url;
-
-    // Populates the cache using values from the configuration store.
-    void updateConfigCache() {
-        url = config["url"].asString();
-    }
-
-public:
-    // The schema, same as with SecurityChecker.
-    struct Schema: public ConfigKit::Schema {
-        Schema() {
-            using namespace ConfigKit;
-            add("url", STRING_TYPE, REQUIRED);
-            add("timeout", INT_TYPE, OPTIONAL, 60);
-            finalize();
-        }
-    };
-
-    // The constructor, same as with SecurityChecker with only one change:
-    // it populates the configuration cache before returning.
-    DnsQuerier(const Schema &schema, const Json::Value &initialConfig)
-        : config(schema)
-    {
-        vector<ConfigKit::Error> errors;
-
-        if (!config.update(initialConfig, errors)) {
-            throw ArgumentException("Invalid initial configuration: "
-                + toString(errors));
-        }
-        updateConfigCache();
-    }
-
-    // Same as with SecurityChecker.
-    Json::Value previewConfigUpdate(const Json::Value &updates,
-        vector<ConfigKit::Error> &errors)
-    {
-        return config.previewUpdate(updates, errors);
-    }
-
-    // Configures the DnsQuerier. Same as with SecurityChecker with only one
-    // modification: it populates the configuration cache if updating succeeds.
-    bool configure(const Json::Value &updates, vector<ConfigKit::Error> &errors) {
-        if (config.update(updates, errors)) {
-            updateConfigCache();
-            // In addition to updating the config cache, this is
-            // the right place for performing any other operations
-            // necessary for applying a configuration change.
-            return true;
-        } else {
-            return false;
-        }
-    }
+static Json::Value filterTargetFd(const Json::Value &value) {
+  Json::Value result = value;
+  result.removeMember("fd");
+  return result;
+}
 
-    // Same as with SecurityChecker.
-    Json::Value inspectConfig() const {
-        return config.inspect();
-    }
+ConfigKit::Schema schema;
 
-    string query() {
-        // Fictional code here for performing the lookup.
-        setSocketTimeout(config["timeout"].asInt());
-        for (unsigned i = 0; i < 1000; i++) {
-            // Fictional hot code path that requires the url config option.
-            queryNextDnsServer(url);
-            receiveResponse();
-        }
-        return result;
-    }
-};
+schema.add("target", ANY_TYPE, OPTIONAL).
+  setInspectFilter(filterTargetFd);
+schema.finalize();
 ~~~
 
-### Downloader example: a high-level component that combines subcomponents
+Note that inspect filter is called *after* [normalizers](#normalizing-data), so `value` refers to a normalized value.
 
-`Downloader` is a high-level class for downloading a specific URL. Under the hood it utilizes `SecurityChecker` and `DnsQuerier`. This example demonstrates how to combine its own configuration with the configuration of multiple lower-level classes.
+## Normalizing data
 
-Downloader completely *encapsulates* its subcomponents. Users that use Downloader don't have to know that the subcomponents exist. Downloader also completely encapsulates subcomponents' configuration: subcomponents can only be configured (and their configuration only inspected) through Downloader.
+You sometimes may want to allow users to supply data in multiple formats. Normalizers allow you to transform user-supplied data in a canonical format, so that your configuration value handling code only has to deal with data in the canonical format instead of all possibly allowed formats.
 
-Because of this, downloader's configuration schema includes not only options directly pertaining Downloader itself, but also includes options pertaining the subcomponents it uses.
+The examples below demonstrate two possible use cases and how to implement them.
 
-Similarly, the Downloader's internal configuration store stores not only the configuration values directly pertaining to Downloader itself, but also (a copy of) the configuration values pertaining to the subcomponents.
+### Normalization example 1
 
-Whenever Downloader is configured, it configures subcomponents too. But whenever Downloader's configuration is inspected, it only returns the data from its own configuration store. Because only the Downloader is allowed to configure its subcomponents, we know that the Downloader's internal configuration store contains the most up-to-date values.
+Suppose that you have a "target" config option, which can be in one of these formats:
 
-#### The special problem of conflicting overlapping configuration names and translation
+ 1. `"/filename"`
+ 2. `{ "path": "/filename" }` (semantics equivalent to 1)
+ 3. `{ "stderr": true }`
 
-There is one special problem that deserves attention: a high-level component may not necessarily want to expose their subcomponents' configuration options using the same names. For example, both `SecurityChecker` and `DnsQuerier` expose a `timeout` option, but they are *different* timeouts, and are even distinct from the Downloader's own download timeout. To solve this special problem of **conflicting overlapping configuration names**, we utilize a **translation system**. We define how the Downloader's configuration keys are to be mapped a specific subcomponent's configuration keys. We obviously can't define the entire mapping, because that would return us to the original problem of having to manually write so much repeated code. There are several ways to deal with this, such as:
+You can write a normalizer that transforms format 1 into format 2. That way, no matter whether the user has actually supplied format 1, 2 or 3, your config handling code only has to deal with format 2 and 3.
 
- - Assuming that most options don't have to be renamed, and only define exceptions to this rule. This is the approach that is demonstrated in this example. The `ConfigKit::TableTranslator` class implements this translation strategy.
- - Prefixing the subcomponents' options. The `ConfigKit::PrefixTranslator` class implements this translation strategy.
+A normalizer is a function that accepts a JSON document of effective values (in the format outputted by `ConfigKit::Store::inspectEffectiveValues()`). It is expected to return either Json::nullValue (indicating that no normalization work needs to be done), or a JSON object containing proposed normalization changes.
 
-#### Code example
+Normalizers are added to the corresponding schema.
 
 ~~~c++
-class Downloader {
-private:
-    // The subcomponents used by Downloader.
-    SecurityChecker securityChecker;
-    DnsQuerier dnsQuerier;
-
-    // The internal configuration store. As explained, this also contains (a
-    // copy of) the configuration options pertaining SecurityChecker and the
-    // DnsQuerier.
-    ConfigKit::Store config;
+static Json::Value myNormalizer(const Json::Value &effectiveValues) {
+    Json::Value updates(Json::objectValue);
 
-public:
-    // Defines the Downloader's configuration schema. As explained, this schema
-    // includes not only options directly pertaining Downloader itself, but also
-    // options the subcomponents.
-    struct Schema: public ConfigKit::Schema {
-        // For each subcomponent that Downloader uses, we define a struct member
-        // that contains that subcomponent's schema, as well as a translation table
-        // for mapping Downloader's config keys to the subcomponent's config keys.
-        struct {
-            SecurityChecker::Schema schema;
-            ConfigKit::TableTranslator translator;
-        } securityChecker;
-        struct {
-            DnsQuerier::Schema schema;
-            ConfigKit::TableTranslator translator;
-        } dnsQuerier;
-
-        Schema() {
-            using namespace ConfigKit;
-
-            // Here we define how to map Downloader configuration keys to
-            // SecurityChecker configuration keys. We add the SecurityChecker's
-            // configuration schema to our own, taking into account the
-            // translations.
-            //
-            // Note that everything not defined in these translation mapping
-            // definitions are simply not translated (i.e. left as-is). So
-            // the Downloader's "url" option maps directly to SecurityChecker's
-            // "url" option.
-            securityChecker.translator.add("security_checker_db_path", "db_path");
-            securityChecker.translator.add("security_checker_timeout", "timeout");
-            securityChecker.translator.finalize();
-            addSubSchema(securityChecker.schema, securityChecker.translator);
-
-            // Ditto for DnsQuerier.
-            dnsQuerier.translator.add("dns_timeout", "timeout");
-            dnsQuerier.translator.finalize();
-            addSubSchema(dnsQuerier.schema, dnsQuerier.translator);
-
-            // Here we define Downloader's own configuration keys.
-            add("download_timeout", INT_TYPE, OPTIONAL, 60);
-            finalize();
-        }
-    };
-
-    // The constructor creates subcomponents, passing to them translated
-    // versions of the initial configuration passed.
-    Downloader(const Schema &schema, const Json::Value &initialConfig)
-        : securityChecker(schema.securityChecker.schema,
-              schema.securityChecker.translator.translate(initialConfig)),
-          dnsQuerier(schema.dnsQuerier.schema,
-              schema.dnsQuerier.translator.translate(initialConfig)),
-          config(schema)
-    {
-        vector<ConfigKit::Error> errors;
-
-        if (!config.update(initialConfig, errors)) {
-            throw ArgumentException("Invalid initial configuration: "
-                + toString(errors));
-        }
+    if (effectiveValues["target"].isString()) {
+        updates["target"]["path"] = effectiveValues["target"];
     }
 
-    void download() {
-        // Fictional code here for performing the download
-
-        cout << "Downloading " << config["url"].asString() << endl;
-        securityChecker.check();
-        dnsQuerier.query();
-
-        openSocket(config["url"].asString());
-        sendRequest();
-        receiveData(config["download_timeout"].asInt());
-        closeSocket();
-    }
-
-    // In addition to calling previewUpdate() on the internal configuration
-    // store, we also perform similar operations on our subcomponents.
-    // We use the `ConfigKit::previewConfigUpdateSubComponent()` utility
-    // function to achieve this, passing to it a corresponding translator.
-    // This function assumes that the subcomponent implements the
-    // `previewConfigUpdate()` method.
-    Json::Value previewConfigUpdate(const Json::Value &updates,
-        vector<ConfigKit::Error> &errors)
-    {
-        using namespace ConfigKit;
-        const Schema &schema = static_cast<const Schema &>(config.getSchema());
+    return updates;
+}
 
-        previewConfigUpdateSubComponent(securityChecker, updates,
-            schema.securityChecker.translator, errors);
-        previewConfigUpdateSubComponent(dnsQuerier, updates,
-            schema.dnsQuerier.translator, errors);
-        return config.previewUpdate(updates, errors);
-    }
 
-    // In addition to updating the internal configuration store, we also
-    // configure the subcomponents. But we only do this after having verified
-    // that *all* subcomponents (as well as Downloader itself) successfully
-    // validates of the new configuration data. This is how we make
-    // `configure()` *transactional*: if we don't do this then we can end up in
-    // a situation where one subcomponent is configured, but another is not.
-    //
-    // We use the `ConfigKit::configureSubComponent()` utility function to
-    // achieve this, passing it a corresponding translator. This function
-    // assumes that the subcomponent implements the `configure()` method.
-    bool configure(const Json::Value &updates, vector<ConfigKit::Error> &errors) {
-        using namespace ConfigKit;
-        const Schema &schema = static_cast<const Schema &>(config.getSchema());
-
-        previewConfigUpdate(updates, errors);
-
-        if (errors.empty()) {
-            configureSubComponent(securityChecker, updates,
-                schema.securityChecker.translator, errors);
-            configureSubComponent(dnsQuerier, updates,
-                schema.dnsQuerier.translator, errors);
-            config.update(updates, errors);
-        }
-
-        if (errors.empty()) {
-            // In addition to updating the subcomponents and the
-            // internal configuration store, this is the right
-            // place for performing any other operations
-            // necessary for applying a configuration change.
-        }
-
-        return errors.empty();
-    }
+ConfigKit::Schema schema;
 
-    // As explained, simply returning our internal configuration store
-    // is enough to expose all the subcomponents' configuration values too.
-    Json::Value inspectConfig() const {
-        return config.inspect();
-    }
-};
+schema.add("target", ANY_TYPE, OPTIONAL);
+schema.addValidator(validateThatTargetIsStringOrObject);
+schema.addNormalizer(myNormalizer);
+schema.finalize();
 ~~~
 
-### Main function example
+### Normalization example 2
 
-To close this section, here is an example of how the main function would look like to utilize the aforementioned components:
+Suppose that you have a "security" config option that accepts this format:
 
-~~~c++
-int
-main() {
-    // Set configuration
-    Json::Value config;
-    config["url"] = "http://www.google.com";
-    config["security_checker_db_path"] = "/db";
-    config["dns_timeout"] = 30;
-    config["download_timeout"] = 20;
-
-    // Instantiate and print schema
-    Downloader::Schema schema;
-    cout << "Configuration schema:" << endl;
-    cout << schema.inspect().toStyledString() << endl;
-
-    // Instantiate a Downloader and perform a download
-    Downloader downloader(schema, config);
-    downloader.download();
-
-    // Change configuration, perform another download
-    cout << "Changing configuration" << endl;
-    vector<ConfigKit::Error> errors;
-    config["url"] = "http://www.slashdot.org";
-    if (!downloader.configure(config, errors)) {
-        cout << "Configure failed!" << endl;
-    }
-    downloader.download();
-
-    // Print final configuration
-    cout << "Final configuration:" << endl;
-    cout << downloader.inspectConfig().toStyledString() << endl;
-
-    return 0;
+~~~json
+{
+  "username": "a string",          // required
+  "password": "a string",          // required
+  "level": "full" | "readonly"     // optional; default value: "full"
 }
 ~~~
 
-## Putting it all together: asynchronous version
-
-The above examples demonstrate how things would work with synchronous components. What about components that deal with asynchronous I/O? They usually run inside an event loop, and all access to their internal data should be performed from the event loop.
-
-Our recommendation is that you implement synchronous as well as asynchronous versions of the `previewConfigUpdate()`, `configure()`, and `inspectConfig()` methods. The synchronous versions must be called from the event loop. The asynchronous versions...
-
- - accept a callback which is to be called with the result. 
- - schedule an operation via the event loop the perform the equivalent synchronous operation and call the callback.
- - are to be thread-safe.
-
-The following example demonstrates how SecurityChecker would look like if introduces asynchronous methods as described above. Other classes, like Downloader, should also be modified in a similar manner.
+If the user did not specify "level", then will want to automatically insert "level: full".
 
 ~~~c++
-class SecurityChecker {
-private:
-    EventLoop &eventLoop;
-
-    // No change from synchronous version.
-    ConfigKit::Store config;
+static Json::Value myNormalizer(const Json::Value &effectiveValues) {
+    Json::Value updates(Json::objectValue);
 
-public:
-    // No change from synchronous version.
-    struct Schema: public ConfigKit::Schema {
-        Schema() {
-            using namespace ConfigKit;
-            add("db_path", STRING_TYPE, REQUIRED);
-            add("url", STRING_TYPE, REQUIRED);
-            add("timeout", INTEGER_TYPE, OPTIONAL, 60);
-            finalize();
-        }
-    };
-
-    // Only change from synchronous version is that we now accept
-    // an event loop object.
-    SecurityChecker(const Schema &schema, const EventLoopType &_eventLoop,
-        const Json::Value &initialConfig)
-        : eventLoop(eventLoop),
-          config(schema)
-    {
-        // ...code omitted for sake of brevity...
+    if (effectiveValues["security"]["level"].isNull()) {
+        updates["security"] = effectiveValues["security"];
+        updates["security"]["level"] = "full";
     }
 
-    // No change from synchronous version.
-    Json::Value previewConfigUpdate(const Json::Value &updates,
-        vector<ConfigKit::Error> &errors)
-    {
-        // ...code omitted for sake of brevity...
-    }
+    return updates;
+}
 
-    // No change from synchronous version.
-    bool configure(const Json::Value &updates, vector<ConfigKit::Error> &errors) {
-        // ...code omitted for sake of brevity...
-    }
 
-    // No change from synchronous version.
-    Json::Value inspectConfig() const {
-        // ...code omitted for sake of brevity...
-    }
+ConfigKit::Schema schema;
 
+schema.add("security", OBJECT_TYPE, OPTIONAL);
+schema.addValidator(validateSecurity);
+schema.addNormalizer(myNormalizer);
+schema.finalize();
+~~~
 
-    /****** Introduction of asynchronous methods below ******/
-
-    // Performs the same thing as the synchronous version, but
-    // over the event loop.
-    void asyncPreviewConfigUpdate(const Json::Value &updates,
-        const ConfigKit::ConfigCallback &callback)
-    {
-        // The exact API depends on which event loop implementation
-        // you use. When using libev, use SafeLibev::runLater().
-        // When using Boost Asio, use io_service.post().
-        //
-        // We use the utility function ConfigKit::callPreviewConfigUpdateAndCallback.
-        // This function assumes that SecurityChecker supports previewConfigUpdate().
-        eventLoop.threadSafeRunInNextTick(boost::bind(
-            ConfigKit::callPreviewConfigUpdateAndCallback<SecurityChecker>,
-            this, updates, callback));
-    }
+### Normalizers and validation
 
-    // Performs the same thing as the synchronous version, but
-    // over the event loop.
-    void asyncConfigure(const Json::Value &updates,
-        const ConfigKit::ConfigCallback &callback)
-    {
-        // We use the utility function ConfigKit::callPreviewConfigUpdateAndCallback.
-        // This function assumes that SecurityChecker supports configure().
-        eventLoop.threadSafeRunInNextTick(boost::bind(
-            ConfigKit::callConfigureAndCallback<SecurityChecker>,
-            this, updates, callback));
-    }
+Normalizers are only run when validation passes! That way normalizers don't have to worry about validation problems.
 
-    // Performs the same thing as the synchronous version, but
-    // over the event loop.
-    void asyncInspectConfig(const ConfigKit::InspectCallback &callback) const {
-        // We use the utility function ConfigKit::callPreviewConfigUpdateAndCallback.
-        // This function assumes that SecurityChecker supports inspectConfig().
-        eventLoop.threadSafeRunInNextTick(boost::bind(
-            ConfigKit::callInspectConfigAndCallback<SecurityChecker>,
-            this, callback));
-    }
+## ConfigKit in practice & design patterns
 
-    // ...further fictional code here for performing the lookup...
-};
-~~~
+This README has taught you how to use ConfigKit by itself. But how does ConfigKit fit in the bigger picture? [IN_PRACTICE.md](IN_PRACTICE.md) describes *good practices* and *design patterns* can that can be used throughout the overall Passenger C++ codebase. It provides practical guidance on how to use ConfigKit in the Passenger codebase.