Define semantic exit codes for the PowerShell adapters

Summary of the new feature / enhancement

As a user and integrating vendor, I want to be able to quickly map the exit code from the PowerShell and Windows PowerShell adapters to their semantics, so I can understand what went wrong at a high-level before I investigate the error specifically.

Currently, the Microsoft.DSC/PowerShell and Microsoft.Windows/WindowsPowerShell adapters only define exit codes 0 (success) and 1 (error).

Proposed technical implementation details (optional)

Define reusable semantic exit codes for the adapter in psDscAdapter.psm1 and use them in the adapter code.

For example,

enum DscAdapterExitCode {
    Success = 0
    Failure
    InvocationError
    ImportPsdscModuleError
    ScriptBasedResourcesWindowsOnly
    BinaryResourceWindowsPowerShellOnly
    BinaryResourceUnsupported
    ImplementationDetailUnsupported
    ResourceNotFound
    InputJsonErrorCreatingConfigurationObject
    InputJsonErrorListingDscResourceTypes
    DscResourceModuleNotFound
    IncompleteGetResult
}

<# public function Write-JsonMessage
.SYNOPSIS
    This function writes a JSON formatted trace message to the host stderr.
.DESCRIPTION
    This function is designed to write a JSON formatted trace message to the host stderr. The trace
    message is intended to be used for debugging purposes and can be parsed by other tools, like
    DSC itself.
.PARAMETER Message
    The message to be written to the host stderr. This message will be written as a JSON object
    with the key being the value of the Level parameter.
.PARAMETER Level
    The level of the trace message. The default value is 'Debug'. The valid values are 'Trace',
    'Debug', 'Info', 'Warning', and 'Error'. These levels map to the levels that DSC uses for
    trace messages.
#>
function Write-JsonMessage {
    [CmdletBinding(HelpUri = '')]
    param(
        [Parameter(Mandatory = $true, Position = 0)]
        [string]$Message,

        [Parameter(Position = 1)]
        [ValidateSet('Trace', 'Debug', 'Info', 'Warning', 'Error')]
        [string]$Level = 'Debug'
    )

    $json = @{ $Level = $Message } | ConvertTo-Json -Compress

    $host.ui.WriteErrorLine($json)
}

class DscAdapterError {
    [int]    $ExitCode
    [string] $ErrorMessage

    WriteAndExit() {
        Write-JsonMessage -Level Error -Message $this.ErrorMessage
        exit $this.ExitCode
    }

    static [DscAdapterError] ImportPsdscModuleError([string]$importModuleError) {
        return [DscAdapterError]@{
            ExitCode     = [DscAdapterExitCode]::ImportPsdscModuleError
            ErrorMessage = "Could not import PSDesiredStateConfiguration 1.1 in Windows PowerShell. $importModuleError"
        }
    }

    static [DscAdapterError] ScriptBasedResourcesWindowsOnly([DscResourceInfo]$resource) {
        return [DscAdapterError]@{
            ExitCode     = [DscAdapterExitCode]::ScriptBasedResourcesWindowsOnly
            ErrorMessage = "Resource $resource is script-based. Script-based resources are only supported on Windows."
        }
    }

    static [DscAdapterError] InvocationError([string]$operation, [DscResourceInfo]$resource, [string]$errorMessage) {
        return [DscAdapterError]@{
            ExitCode     = [DscAdapterExitCode]::InvocationError
            ErrorMessage = "Error invoking '$operation' on ${resource}: $errorMessage"
        }
    }

    static [DscAdapterError] BinaryResourceWindowsPowerShellOnly([DscResourceInfo]$resource) {
        return [DscAdapterError]@{
            ExitCode     = [DscAdapterExitCode]::BinaryResourceWindowsPowerShellOnly
            ErrorMessage = "Resource $resource is a binary resource. Only the File, Log, and SignatureValidation binary resources are supported. To use a supported binary resource, use the Microsoft.DSC/WindowsPowerShell adapter."
        }
    }

    static [DscAdapterError] BinaryResourceUnsupported([DscResourceInfo]$resource) {
        return [DscAdapterError]@{
            ExitCode     = [DscAdapterExitCode]::BinaryResourceUnsupported
            ErrorMessage = "Resource $resource is not a supported binary resource. Only the File, Log, and SignatureValidation binary resources are supported."
        }
    }

    static [DscAdapterError] ImplementationDetailUnsupported([DscResourceInfo]$resource) {
        return [DscAdapterError]@{
            ExitCode     = [DscAdapterExitCode]::ImplementationDetailUnsupported
            ErrorMessage = "Resource $resource has an unsupported implementation '$($resource.ImplementationDetail)'. Supported implementations are: $([dscResourceType].GetEnumNames())"
        }
    }

    static [DscAdapterError] ResourceNotFound([string]$type, [string]$json) {
        return [DscAdapterError]@{
            ExitCode     = [DscAdapterExitCode]::ResourceNotFound
            ErrorMessage = "Can not find type '$type' for resource '$json'. Please ensure that Get-DscResource returns this resource type."
        }
    }

    static [DscAdapterError] InputJsonErrorCreatingConfigurationObject([string]$jsonInput) {
        return [DscAdapterError]@{
            ExitCode     = [DscAdapterExitCode]::InputJsonError
            ErrorMessage = "Failed to create configuration object from provided input JSON: $jsonInput"
        }
    }

    static [DscAdapterError] InputJsonErrorListingDscResourceTypes() {
        return [DscAdapterError]@{
            ExitCode     = [DscAdapterExitCode]::InputJsonError
            ErrorMessage = "Could not get list of DSC resource types from provided JSON."
        }
    }

    static [DscAdapterError] DscResourceModuleNotFound() {
        return [DscAdapterError]@{
            ExitCode     = [DscAdapterExitCode]::DscResourceModuleNotFound
            ErrorMessage = "DSC resource module not found."
        }
    }

    static [DscAdapterError] IncompleteGetResult([string]$resourceType) {
        return [DscAdapterError]@{
            ExitCode     = [DscAdapterExitCode]::IncompleteGetResult
            ErrorMessage = "Incomplete GET for resource $resourceType"
        }
    }

    static [DscAdapterError] UnknownError([string]$errorMessage) {
        return [DscAdapterError]@{
            ExitCode     = [DscAdapterExitCode]::Failure
            ErrorMessage = $errorMessage
        }
    }
}

Then, when you need to use a specific exit code:

# in psDscAdapter.psm1

# For Linux/MacOS, only class based resources are supported and are called directly.
if ($IsLinux) {
    [DscAdapterError]::ScriptBasedResourcesWindowsOnly($cachedDscResourceInfo).WriteAndExit()
}

# in  powershell.resource.ps1

# load private functions of psDscAdapter stub module
$psDscAdapter = Import-Module "$PSScriptRoot/psDscAdapter.psd1" -Force -PassThru
# get handle to adapter errors for semantic exit codes/messages
$psDscAdapterError = $psDscAdapter.Invoke({ [DscAdapterError] })

# ...

$psDscAdapterError::IncompleteGetForResource($ds.Name).WriteAndExit()

Then we could map the exit codes to their semantic meanings and reuse errors as needed. This proposal also includes the helper function Write-JsonMessage for sending a JSON Line back to DSC for debug, warnings, errors, etc.

While out of scope for now, we should also consider whether and how to do i18n for exit codes and error messages. In this proposal I'm just matching the use of en-US already in place for the module and adapter.

Start by tracing the current exit-code handling in psDscAdapter.psm1 and powershell.resource.ps1, including how the two PowerShell adapters load and invoke shared adapter code. Done means reusable semantic exit codes and error handling are defined there and used consistently for the listed adapter failure cases.