Merge pull request #2322 from stevenengler/serde-yaml-upgrade

Support yaml merge keys and extension fields

Author: stevenengler

docs/shadow_config_overview.md

@@ -76,3 +76,75 @@ Acceptable unit *prefixes* are:
 - tebi / Ti
 
 Examples: `20 B`, `100 MB`, `100 megabyte`, `10 kibibytes`, `30 MiB`, `1024 Mbytes`
+
+## YAML Extensions (Experimental)
+
+Shadow has experimental support for extended YAML conventions. These can be
+enabled using the `--use-extended-yaml true` command line option.
+
+### Merge/Override Mappings
+
+To help reduce repeated configuration options, Shadow supports the YAML ["merge
+key (`<<`)"](https://yaml.org/type/merge.html) convention. This merges the keys
+of the child mapping into the parent mapping, and is useful when combined with
+[YAML anchors (`&` and `*`)](https://yaml.org/spec/1.2.2/#692-node-anchors).
+
+Example:
+
+```yaml
+general:
+  # --snip--
+
+network:
+  # --snip--
+
+hosts:
+  server:
+    # --snip--
+  client-uk: &client
+    network_node_id: 0
+    processes:
+    - path: /usr/bin/curl
+      args: server --silent
+      start_time: 5
+  client-us:
+    network_node_id: 1
+    <<: *client
+```
+
+For a longer example, see
+https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/.
+
+### Extension Fields
+
+When using the "merge key" feature above, putting common options in a separate
+configuration fragment may help make the configuration more readable. Shadow
+supports the "extension field" convention used by [Docker
+Compose](https://docs.docker.com/compose/compose-file/compose-file-v3/). Any
+top-level field containing a key that begins with `x-` will be ignored by
+Shadow.
+
+Example:
+
+```yaml
+x-client: &client-defaults
+  processes:
+  - path: /usr/bin/curl
+    args: server --silent
+    start_time: 5
+
+general:
+  # --snip--
+
+network:
+  # --snip--
+
+hosts:
+  server:
+    # --snip--
+  client-uk:
+    network_node_id: 0
+    <<: *client-defaults
+  client-us:
+    network_node_id: 1
+    <<: *client-defaults

docs/shadow_config_spec.md

@@ -84,6 +84,7 @@ hosts:
 - [`experimental.use_cpu_pinning`](#experimentaluse_cpu_pinning)
 - [`experimental.use_dynamic_runahead`](#experimentaluse_dynamic_runahead)
 - [`experimental.use_explicit_block_message`](#experimentaluse_explicit_block_message)
+- [`experimental.use_extended_yaml`](#experimentaluse_extended_yaml)
 - [`experimental.use_legacy_working_dir`](#experimentaluse_legacy_working_dir)
 - [`experimental.use_libc_preload`](#experimentaluse_libc_preload)
 - [`experimental.use_memory_manager`](#experimentaluse_memory_manager)
@@ -480,6 +481,14 @@ Type: Bool
 Send message to managed process telling it to stop spinning when a syscall
 blocks.
 
+#### `experimental.use_extended_yaml`
+
+Default: false  
+Type: Bool
+
+Enable extended YAML conventions (merge keys and extension fields). Can only be
+enabled on the command line (enabling in the configuration file is a no-op).
+
 #### `experimental.use_legacy_working_dir`
 
 Default: false