Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Define semantic exit codes for the PowerShell adapters #421

Open
michaeltlombardi opened this issue Apr 23, 2024 · 2 comments
Open

Define semantic exit codes for the PowerShell adapters #421

michaeltlombardi opened this issue Apr 23, 2024 · 2 comments
Labels
Issue-Enhancement The issue is a feature or idea Needs Triage

Comments

@michaeltlombardi
Copy link
Collaborator

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.

@michaeltlombardi michaeltlombardi added Issue-Enhancement The issue is a feature or idea Needs Triage labels Apr 23, 2024
@StartAutomating
Copy link

@michaeltlombardi this sounds useful! Would the enum be able to specific non-sequential specific error codes? Would it be able to provide them as a negative integer or hexadecimal? ( I think "yes, yes, and yes", because it's just an [enum] )

@michaeltlombardi
Copy link
Collaborator Author

@StartAutomating - Yup, DSC Resources can return any valid int32 as an exit code. In this case, I'm specifically talking about the PowerShell adapter resource, which hasn't defined semantic exit codes in the resource manifest with the exitCodes property - the resource manifest only defines success and failure:

"exitCodes": {
"0": "Success",
"1": "Error"
}

Although as we discovered in #407 (addressed in #410), you have to specify the exit codes in the manifest as integers, you can't specify them as hexadecimals.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Issue-Enhancement The issue is a feature or idea Needs Triage
Projects
None yet
Development

No branches or pull requests

2 participants