Add Microsoft.DSC/Include resource with way to have resource accept trace level

SteveL-MSFT · SteveL-MSFT · commit 93a9428f9db8 · 2024-05-03T17:30:48.000-07:00
diff --git a/dsc/examples/include.dsc.yaml b/dsc/examples/include.dsc.yaml
@@ -0,0 +1,8 @@
+# This is a simple example of how to Include another configuration into this one
+
+$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+resources:
+- name: get os info
+  type: Microsoft.DSC/Include
+  properties:
+    configurationFile: osinfo_parameters.dsc.yaml
diff --git a/dsc/include.dsc.resource.json b/dsc/include.dsc.resource.json
@@ -0,0 +1,68 @@
+{
+    "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json",
+    "type": "Microsoft.DSC/Include",
+    "version": "0.1.0",
+    "description": "Allows including a configuration file into current configuration.",
+    "kind": "Group",
+    "get": {
+      "executable": "dsc",
+      "args": [
+        {
+            "traceLevelArg": "--trace-level"
+        },
+        "config",
+        "--as-group",
+        "--as-include",
+        "get"
+      ],
+      "input": "stdin"
+    },
+    "set": {
+      "executable": "dsc",
+      "args": [
+        {
+            "traceLevelArg": "--trace-level"
+        },
+        "config",
+        "--as-group",
+        "--as-include",
+        "set"
+      ],
+      "input": "stdin",
+      "implementsPretest": true,
+      "return": "state"
+    },
+    "test": {
+      "executable": "dsc",
+      "args": [
+        {
+            "traceLevelArg": "--trace-level"
+        },
+        "config",
+        "--as-group",
+        "--as-include",
+        "test"
+      ],
+      "input": "stdin",
+      "return": "state"
+    },
+    "exitCodes": {
+      "0": "Success",
+      "1": "Invalid argument",
+      "2": "Resource error",
+      "3": "JSON Serialization error",
+      "4": "Invalid input format",
+      "5": "Resource instance failed schema validation",
+      "6": "Command cancelled"
+    },
+    "schema": {
+        "command": {
+            "executable": "dsc",
+            "args": [
+                "schema",
+                "--type",
+                "include"
+            ]
+        }
+    }
+  }
diff --git a/dsc/src/args.rs b/dsc/src/args.rs
@@ -54,11 +54,12 @@ pub enum SubCommand {
         parameters: Option<String>,
         #[clap(short = 'f', long, help = "Parameters to pass to the configuration as a JSON or YAML file", conflicts_with = "parameters")]
         parameters_file: Option<String>,
+        // Used to inform when DSC is used as a group resource to modify it's output
         #[clap(long, hide = true)]
         as_group: bool,
         // Used for the Microsoft.DSC/Include resource
         #[clap(long, hide = true)]
-        include: Option<String>,
+        as_include: bool,
     },
     #[clap(name = "resource", about = "Invoke a specific DSC resource")]
     Resource {
@@ -208,6 +209,7 @@ pub enum DscType {
     TestResult,
     DscResource,
     ResourceManifest,
+    Include,
     Configuration,
     ConfigurationGetResult,
     ConfigurationSetResult,
diff --git a/dsc/src/include.rs b/dsc/src/include.rs
@@ -1,3 +1,15 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
+pub struct Include {
+    /// The path to the file to include.  Path is relative to the file containing the include
+    /// and not allowed to reference parent directories.  If a configuration document is used
+    /// instead of a file, then the path is relative to the current working directory.
+    #[serde(rename = "configurationFile")]
+    pub configuration_file: String,
+    pub parameters_file: Option<String>,
+}
diff --git a/dsc/src/main.rs b/dsc/src/main.rs
@@ -5,7 +5,11 @@ use args::{Args, SubCommand};
 use atty::Stream;
 use clap::{CommandFactory, Parser};
 use clap_complete::generate;
+use dsc_lib::configure::config_doc::Configuration;
+use crate::include::Include;
 use std::io::{self, Read};
+use std::fs::File;
+use std::path::Path;
 use std::process::exit;
 use sysinfo::{Process, ProcessExt, RefreshKind, System, SystemExt, get_current_pid, ProcessRefreshKind};
 use tracing::{error, info, warn, debug};
@@ -36,7 +40,7 @@ fn main() {
 
     debug!("Running dsc {}", env!("CARGO_PKG_VERSION"));
 
-    let input = if atty::is(Stream::Stdin) {
+    let mut input = if atty::is(Stream::Stdin) {
         None
     } else {
         info!("Reading input from STDIN");
@@ -66,19 +70,23 @@ fn main() {
             let mut cmd = Args::command();
             generate(shell, &mut cmd, "dsc", &mut io::stdout());
         },
-        SubCommand::Config { subcommand, parameters, parameters_file, as_group } => {
+        SubCommand::Config { subcommand, parameters, parameters_file, as_group, as_include} => {
+            if as_include {
+                input = Some(read_include_file(&input));
+            }
+
             if let Some(file_name) = parameters_file {
                 info!("Reading parameters from file {}", file_name);
                 match std::fs::read_to_string(file_name) {
-                    Ok(parameters) => subcommand::config(&subcommand, &Some(parameters), &input, &as_group),
+                    Ok(parameters) => subcommand::config(&subcommand, &Some(parameters), &input, &as_group, &as_include),
                     Err(err) => {
                         error!("Error: Failed to read parameters file: {err}");
                         exit(util::EXIT_INVALID_INPUT);
                     }
                 }
             }
             else {
-                subcommand::config(&subcommand, &parameters, &input, &as_group);
+                subcommand::config(&subcommand, &parameters, &input, &as_group, &as_include);
             }
         },
         SubCommand::Resource { subcommand } => {
@@ -100,6 +108,96 @@ fn main() {
     exit(util::EXIT_SUCCESS);
 }
 
+fn read_include_file(input: &Option<String>) -> String {
+    let Some(include) = input else {
+        error!("Error: Include requires input from STDIN");
+        exit(util::EXIT_INVALID_INPUT);
+    };
+
+    // deserialize the Include input
+    let include: Include = match serde_json::from_str(include) {
+        Ok(include) => include,
+        Err(err) => {
+            error!("Error: Failed to deserialize Include input: {err}");
+            exit(util::EXIT_INVALID_INPUT);
+        }
+    };
+
+    let path = Path::new(&include.configuration_file);
+    if path.is_absolute() {
+        error!("Error: Include path must be relative: {}", include.configuration_file);
+        exit(util::EXIT_INVALID_INPUT);
+    }
+
+    // check that no components of the path are '..'
+    if path.components().any(|c| c == std::path::Component::ParentDir) {
+        error!("Error: Include path must not contain '..': {}", include.configuration_file);
+        exit(util::EXIT_INVALID_INPUT);
+    }
+
+    // use DSC_CONFIG_ROOT env var as current directory
+    let current_directory = match std::env::var("DSC_CONFIG_ROOT") {
+        Ok(current_directory) => current_directory,
+        Err(err) => {
+            error!("Error: Could not read DSC_CONFIG_ROOT env var: {err}");
+            exit(util::EXIT_INVALID_INPUT);
+        }
+    };
+
+    // combine the current directory with the Include path
+    let include_path = Path::new(&current_directory).join(&include.configuration_file);
+
+    // read the file specified in the Include input
+    let mut buffer: Vec<u8> = Vec::new();
+    match File::open(&include_path) {
+        Ok(mut file) => {
+            match file.read_to_end(&mut buffer) {
+                Ok(_) => (),
+                Err(err) => {
+                    error!("Error: Failed to read file '{include_path:?}': {err}");
+                    exit(util::EXIT_INVALID_INPUT);
+                }
+            }
+        },
+        Err(err) => {
+            error!("Error: Failed to included file '{include_path:?}': {err}");
+            exit(util::EXIT_INVALID_INPUT);
+        }
+    }
+    // convert the buffer to a string
+    let include_content = match String::from_utf8(buffer) {
+        Ok(input) => input,
+        Err(err) => {
+            error!("Error: Invalid UTF-8 sequence in included file '{include_path:?}': {err}");
+            exit(util::EXIT_INVALID_INPUT);
+        }
+    };
+
+    // try to deserialize the Include content as YAML first
+    let configuration: Configuration = match serde_yaml::from_str(&include_content) {
+        Ok(configuration) => configuration,
+        Err(_err) => {
+            // if that fails, try to deserialize it as JSON
+            match serde_json::from_str(&include_content) {
+                Ok(configuration) => configuration,
+                Err(err) => {
+                    error!("Error: Failed to read the configuration file '{include_path:?}' as YAML or JSON: {err}");
+                    exit(util::EXIT_INVALID_INPUT);
+                }
+            }
+        }
+    };
+
+    // serialize the Configuration as JSON
+    match serde_json::to_string(&configuration) {
+        Ok(json) => json,
+        Err(err) => {
+            error!("Error: JSON Error: {err}");
+            exit(util::EXIT_JSON_ERROR);
+        }
+    }
+}
+
 fn ctrlc_handler() {
     warn!("Ctrl-C received");
 
diff --git a/dsc/src/subcommand.rs b/dsc/src/subcommand.rs
@@ -198,22 +198,27 @@ pub fn config_export(configurator: &mut Configurator, format: &Option<OutputForm
     }
 }
 
-pub fn config(subcommand: &ConfigSubCommand, parameters: &Option<String>, stdin: &Option<String>, as_group: &bool) {
+pub fn config(subcommand: &ConfigSubCommand, parameters: &Option<String>, stdin: &Option<String>, as_group: &bool, use_stdin: &bool) {
     let json_string = match subcommand {
         ConfigSubCommand::Get { document, path, .. } |
         ConfigSubCommand::Set { document, path, .. } |
         ConfigSubCommand::Test { document, path, .. } |
         ConfigSubCommand::Validate { document, path, .. } |
         ConfigSubCommand::Export { document, path, .. } => {
-            let mut new_path = path;
-            let opt_new_path;
-            if path.is_some()
-            {
+            let new_path = if path.is_some() {
                 let config_path = path.clone().unwrap_or_default();
-                opt_new_path = Some(set_dscconfigroot(&config_path));
-                new_path = &opt_new_path;
+                Some(set_dscconfigroot(&config_path))
+            } else {
+                // use current working directory
+                let current_directory = std::env::current_dir().unwrap_or_default();
+                Some(current_directory.to_string_lossy().to_string())
+            };
+
+            if *use_stdin {
+                stdin.clone().unwrap_or_default()
+            } else {
+                get_input(document, stdin, &new_path)
             }
-            get_input(document, stdin, new_path)
         }
     };
 
@@ -226,8 +231,12 @@ pub fn config(subcommand: &ConfigSubCommand, parameters: &Option<String>, stdin:
     };
 
     let parameters: Option<serde_json::Value> = match parameters {
-        None => None,
+        None => {
+            debug!("No parameters specified");
+            None
+        },
         Some(parameters) => {
+            debug!("Parameters specified");
             match serde_json::from_str(parameters) {
                 Ok(json) => Some(json),
                 Err(_) => {
diff --git a/dsc/src/util.rs b/dsc/src/util.rs
@@ -4,6 +4,7 @@
 use crate::args::{DscType, OutputFormat, TraceFormat, TraceLevel};
 
 use atty::Stream;
+use crate::include::Include;
 use dsc_lib::{
     configure::{
         config_doc::Configuration,
@@ -15,13 +16,11 @@ use dsc_lib::{
     },
     dscerror::DscError,
     dscresources::{
-        dscresource::DscResource,
-        invoke_result::{
+        dscresource::DscResource, invoke_result::{
             GetResult,
             SetResult,
             TestResult,
-        },
-        resource_manifest::ResourceManifest
+        }, resource_manifest::ResourceManifest
     }
 };
 use jsonschema::JSONSchema;
@@ -158,6 +157,9 @@ pub fn get_schema(dsc_type: DscType) -> RootSchema {
         DscType::ResourceManifest => {
             schema_for!(ResourceManifest)
         },
+        DscType::Include => {
+            schema_for!(Include)
+        },
         DscType::Configuration => {
             schema_for!(Configuration)
         },
diff --git a/dsc_lib/src/configure/mod.rs b/dsc_lib/src/configure/mod.rs
@@ -509,7 +509,9 @@ impl Configurator {
         };
 
         for (name, parameter) in parameters {
+            debug!("Processing parameter '{name}'");
             if let Some(default_value) = &parameter.default_value {
+                debug!("Set default parameter '{name}'");
                 // default values can be expressions
                 let value = if default_value.is_string() {
                     if let Some(value) = default_value.as_str() {
@@ -526,15 +528,18 @@ impl Configurator {
         }
 
         let Some(parameters_input) = parameters_input else {
+            debug!("No parameters input");
             return Ok(());
         };
 
+        trace!("parameters_input: {parameters_input}");
         let parameters: HashMap<String, Value> = serde_json::from_value::<Input>(parameters_input.clone())?.parameters;
         let Some(parameters_constraints) = &config.parameters else {
             return Err(DscError::Validation("No parameters defined in configuration".to_string()));
         };
         for (name, value) in parameters {
             if let Some(constraint) = parameters_constraints.get(&name) {
+                debug!("Validating parameter '{name}'");
                 check_length(&name, &value, constraint)?;
                 check_allowed_values(&name, &value, constraint)?;
                 check_number_limits(&name, &value, constraint)?;
diff --git a/dsc_lib/src/dscresources/command_resource.rs b/dsc_lib/src/dscresources/command_resource.rs
diff --git a/dsc_lib/src/dscresources/resource_manifest.rs b/dsc_lib/src/dscresources/resource_manifest.rs
