(GH-538) Define newtypes for exit_codes fields

Prior to this change, the `exit_codes` fields for the resource and
extension manifests defined the map of exit codes to their semantic
meanings as `Option<HashMap<String, String>>`.

As part of schema canonicalization, we need to provide a canonical
JSON Schema for that object. Unfortunately, because we don't own either
the `JsonSchema` trait or `HashMap<T>` type, we need to use a newtype
wrapper.

This change defines two new types:

- `ExitCode` as a lightweight wrapper around `i32` where we can control
  serialization and deserialization with strings as the serialized
  format instead of an integer.
- `ExitCodeMap` as a lightweight wrapper for `HashMap<ExitCode, String>`.
  It implements a helper function for determining whether the map is
  empty or default and defines the default map for exit `0` (success)
  and `1` (error).

  The `ExitCodeMap` includes a hand-implementation of `JsonSchema` to
  match the canonical JSON Schema, which `schemars` won't generate from
  the struct definition.

This change not only enables us to provide the canonical JSON Schema
for exit code fields in a reusable way, it also removes the need to
maintain a converter function for transforming the exit codes map from
`HashMap<String, String>` to `HashMap<i32, String>`.

Author: michaeltlombardi

lib/dsc-lib/locales/en-us.toml

@@ -729,6 +729,7 @@ forExecutable = "for executable"
 function = "Function"
 integerConversion = "Function integer argument conversion"
 invalidConfiguration = "Invalid configuration"
+invalidExitCode = "Invalid key in 'exitCodes' map"
 invalidTypeNamePrefix = "Invalid type name"
 invalidTypeNameSuffix = "valid resource type names must match the following pattern"
 unsupportedManifestVersion = "Unsupported manifest version"
@@ -777,6 +778,9 @@ notFoundSetting = "Setting '%{name}' not found in %{path}"
 failedToGetExePath = "Can't get 'dsc' executable path"
 settingNotFound = "Setting '%{name}' not found"
 failedToAbsolutizePath = "Failed to absolutize path '%{path}'"
-invalidExitCodeKey = "Invalid exit code key '%{key}'"
 executableNotFoundInWorkingDirectory = "Executable '%{executable}' not found with working directory '%{cwd}'"
 executableNotFound = "Executable '%{executable}' not found"
+
+[types.exit_codes_map]
+successText = "Success"
+failureText = "Error"

lib/dsc-lib/locales/schemas.definitions.yaml

@@ -1,6 +1,36 @@
 _version: 2
 schemas:
   definitions:
+    exitCodes:
+      title:
+        en-us: Exit codes
+      description:
+        en-us: >-
+          Defines a map of valid exit codes for operation commands.
+      markdownDescription:
+        en-us: |-
+          Defines a map of valid exit codes for operation commands. DSC always interprets exit code
+          `0` as a successful operation and any other exit code as an error. Use this property to
+          indicate human-readable semantic meanings for the DSC resource's exit codes.
+
+          When this field isn't defined, DSC can only report "Success" (for exit code `0`) and
+          "Error" (for all other exit codes).
+
+          Define the keys in this property as strings representing a valid 32-bit signed integer.
+          You can't use alternate formats for the exit code. For example, instead of the
+          hexadecimal value `0x80070005` for "Access denied", specify the exit code as
+          `-2147024891`.
+          
+          If you're authoring your resource manifest in YAML, be sure to wrap the exit code in
+          single quotes, like `'0': Success` instead of `0: Success` to ensure the YAML file can be
+          parsed correctly.
+
+          Define the value for each key as a string explaining what the exit code indicates.
+      invalidKeyErrorMessage:
+        en-us: >-
+          Invalid exit code. Each exit code must be defined as a string representing a 32-bit
+          signed integer, like `5` or `-2147024891`.
+
     resourceType:
       title: Fully qualified type name
       description: >-

lib/dsc-lib/src/dscerror.rs

@@ -52,6 +52,9 @@ pub enum DscError {
     #[error("{t} '{0}', {t2} {1}, {t3} {2}", t = t!("dscerror.invalidFunctionParameterCount"), t2 = t!("dscerror.expected"), t3 = t!("dscerror.got"))]
     InvalidFunctionParameterCount(String, usize, usize),
 
+    #[error("{t} '{0}': {1}", t = t!("dscerror.invalidExitCode"))]
+    InvalidExitCode(String, core::num::ParseIntError),
+
     #[error("{0}")]
     InvalidManifest(String),
 

lib/dsc-lib/src/types/exit_code.rs

@@ -0,0 +1,117 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+use std::{borrow::Borrow, fmt::Display, ops::Deref, str::FromStr};
+
+use serde::{Deserialize, Serialize};
+
+use crate::dscerror::DscError;
+
+/// Defines a program exit code as a 32-bit integer ([`i32`]).
+///
+/// DSC uses exit codes to determine whether invoked commands, including resource and extension
+/// operations, are successful. DSC treats exit code `0` as successful and all other exit codes
+/// as indicating a failure.
+#[derive(Debug, Copy, Clone, Hash, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(try_from = "String", into = "String")]
+pub struct ExitCode(i32);
+
+impl ExitCode {
+    /// Creates an instance of [`ExitCode`] from an [`i32`].
+    pub fn new(code: i32) -> Self {
+        Self(code)
+    }
+
+    /// Parses a string into an [`ExitCode`].
+    /// 
+    /// If the string can be parsed as an [`i32`], the function returns an [`ExitCode`]. Otherwise,
+    /// the function raises the [`DscError::InvalidExitCode`] error.
+    pub fn parse(text: &str) -> Result<ExitCode, DscError> {
+        match i32::from_str(text) {
+            Ok(code) => Ok(Self(code)),
+            Err(err) => Err(DscError::InvalidExitCode(text.to_string(), err)),
+        }
+    }
+}
+
+impl AsRef<i32> for ExitCode {
+    fn as_ref(&self) -> &i32 {
+        &self.0
+    }
+}
+
+impl Deref for ExitCode {
+    type Target = i32;
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl Borrow<i32> for ExitCode {
+    fn borrow(&self) -> &i32 {
+        &self.0
+    }
+}
+
+impl Display for ExitCode {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.0.fmt(f)
+    }
+}
+
+impl FromStr for ExitCode {
+    type Err = DscError;
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Self::parse(s)
+    }
+}
+
+impl TryFrom<String> for ExitCode {
+    type Error = DscError;
+    fn try_from(value: String) -> Result<Self, Self::Error> {
+        Self::parse(value.as_str())
+    }
+}
+
+impl TryFrom<&str> for ExitCode {
+    type Error = DscError;
+    fn try_from(value: &str) -> Result<Self, Self::Error> {
+        Self::parse(value)
+    }
+}
+
+impl From<ExitCode> for String {
+    fn from(value: ExitCode) -> Self {
+        value.to_string()
+    }
+}
+
+impl From<i32> for ExitCode {
+    fn from(value: i32) -> Self {
+        Self(value)
+    }
+}
+
+impl From<ExitCode> for i32 {
+    fn from(value: ExitCode) -> Self {
+        value.0
+    }
+}
+
+impl PartialEq for ExitCode {
+    fn eq(&self, other: &Self) -> bool {
+        self.0.eq(&other.0)
+    }
+}
+
+impl PartialEq<i32> for ExitCode {
+    fn eq(&self, other: &i32) -> bool {
+        self.0.eq(other)
+    }
+}
+
+impl PartialEq<ExitCode> for i32 {
+    fn eq(&self, other: &ExitCode) -> bool {
+        self.eq(&other.0)
+    }
+}

lib/dsc-lib/src/types/exit_codes_map.rs

@@ -0,0 +1,145 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+use std::{collections::HashMap, ops::{Deref, DerefMut}};
+
+use rust_i18n::t;
+use schemars::{JsonSchema, json_schema};
+use serde::{Deserialize, Serialize};
+
+use crate::{schemas::dsc_repo::DscRepoSchema, types::ExitCode};
+
+/// Defines a map of exit codes to their semantic meaning for operation commands.
+///
+/// DSC resources and extensions may define any number of operation commands like `get` or
+/// `secret`. DSC always considers commands that exit with code `0` to be successful operations and
+/// commands that exit with any nonzero code to have failed.
+///
+/// Resource and extension authors can provide more useful information to users by defining an
+/// [`ExitCodesMap`]. When a resource or extension defines the `exitCodes` field in its manifest,
+/// DSC surfaces the associated string as part of the error message.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, DscRepoSchema)]
+#[dsc_repo_schema(base_name = "exitCodes", folder_path = "definitions")]
+pub struct ExitCodesMap(HashMap<ExitCode, String>);
+
+impl ExitCodesMap {
+    /// Defines the regular expression for validating a string as an exit code.
+    ///
+    /// The string must consist only of ASCII digits (`[0-9]`) with an optional leading hyphen
+    /// (`-`). If the string can't be parsed as an [`i32`], the value is invalid.
+    ///
+    /// This value is only used in the JSON Schema for validating the property names for the map
+    /// of exit codes to their descriptions. For JSON and YAML, DSC expects the keys to always be
+    /// strings but they _must_ map to 32-bit integers.
+    pub const KEY_VALIDATING_PATTERN: &str = r"^-?[0-9]+$";
+
+    /// Creates a new instance of [`ExitCodesMap`] with the default capacity.
+    pub fn new() -> Self {
+        Self(HashMap::new())
+    }
+
+    /// Creates a new instance of [`ExitCodesMap`] with the given capacity.
+    pub fn with_capacity(capacity: usize) -> Self {
+        Self(HashMap::with_capacity(capacity))
+    }
+
+    /// Looks up an [`ExitCode`] in the map and returns a reference to its description, if the map
+    /// contains the given exit code.
+    pub fn get_code(&self, code: i32) -> Option<&String> {
+        self.0.get(&ExitCode::new(code))
+    }
+
+    /// Looks up an [`ExitCode`] in the map and returns its description, if the map contains the
+    /// given exit code, or the default description.
+    /// 
+    /// The default description is retrieved from the `default()` map:
+    /// 
+    /// - Exit code `0` returns the description for `0` in the default map.
+    /// - All other exit codes return the description for `1` in the default map.
+    pub fn get_code_or_default(&self, code: i32) -> String {
+        match self.0.get(&ExitCode::new(code)) {
+            Some(description) => description.clone(),
+            None => match code {
+                0 => Self::default().get_code(0).expect("default always defines exit code 0").clone(),
+                _ => Self::default().get_code(1).expect("default always defines exit code 1").clone(),
+            }
+        }
+    }
+
+    /// Indicates whether the [`ExitCodesMap`] is identical to the default map.
+    pub fn is_default(&self) -> bool {
+        self == &Self::default()
+    }
+
+    /// Indicates whether the [`ExitCodesMap`] is empty or identical to the default map.
+    /// 
+    /// Use this method with the `skip_serializing_if` attribute for serde to avoid serializing
+    /// empty and default maps.
+    pub fn is_empty_or_default(&self) -> bool {
+        self.is_empty() || self.is_default()
+    }
+}
+
+impl Default for ExitCodesMap {
+    fn default() -> Self {
+        let mut map: HashMap<ExitCode, String> = HashMap::with_capacity(2);
+        map.insert(ExitCode::new(0), t!("types.exit_codes_map.successText").into());
+        map.insert(ExitCode::new(1), t!("types.exit_codes_map.failureText").into());
+
+        Self(map)
+    }
+}
+
+impl JsonSchema for ExitCodesMap {
+    fn schema_name() -> std::borrow::Cow<'static, str> {
+        Self::default_schema_id_uri().into()
+    }
+
+    fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
+        json_schema!({
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "title": t!("schemas.definitions.exitCodes.title"),
+            "description": t!("schemas.definitions.exitCodes.description"),
+            "markdownDescription": t!("schemas.definitions.exitCodes.markdownDescription"),
+            "type": "object",
+            "minProperties": 1,
+            "propertyNames": {
+                "pattern": Self::KEY_VALIDATING_PATTERN,
+                "patternErrorMessage": t!("schemas.definitions.exitCodes.invalidKeyErrorMessage")
+            },
+            "patternProperties": {
+                Self::KEY_VALIDATING_PATTERN: {
+                    "type": "string"
+                }
+            },
+            "unevaluatedProperties": false,
+            "default": Self::default(),
+            "examples": [{
+                "0": "Success",
+                "1": "Invalid parameter",
+                "2": "Invalid input",
+                "3": "Registry error",
+                "4": "JSON serialization failed"
+            }]
+        })
+    }
+}
+
+impl AsRef<ExitCodesMap> for ExitCodesMap {
+    fn as_ref(&self) -> &ExitCodesMap {
+        &self
+    }
+}
+
+impl Deref for ExitCodesMap {
+    type Target = HashMap<ExitCode, String>;
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl DerefMut for ExitCodesMap {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.0
+    }
+}

lib/dsc-lib/src/types/mod.rs

@@ -1,6 +1,10 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+mod exit_code;
+pub use exit_code::ExitCode;
+mod exit_codes_map;
+pub use exit_codes_map::ExitCodesMap;
 mod fully_qualified_type_name;
 pub use fully_qualified_type_name::FullyQualifiedTypeName;
 mod resource_version;