fix(codecatalyst): dev env error messages not being displayed

Problem:

The following issue was started due to a change needed
for Velox, but this will be able to apply to all AWS
services.

When certain exceptions are thrown by AWS services
we want them to be displayed directly to the user in
a vscode window.

Currently we only display Toolkit errors to the user,
otherwise only logging the error to the logs.

There are some AWS errors that we want to show to the
user, but on top of that AWS errors can be wrapped
inside a Toolkit error.

Solution:

When deciding which error message to show to users:

- Show the exact error message if it is an AWS error
  and is in our defined list of 'prioritizied' errors.
- If we get a Toolkit error, check if it wraps a prioritized
  error, extract it, then display that.

Signed-off-by: Nikolas Komonen <[email protected]>

Author: nkomonen-amazon

src/extension.ts

@@ -63,7 +63,7 @@ import { join } from 'path'
 import { Experiments, Settings } from './shared/settings'
 import { getCodeCatalystDevEnvId, isReleaseVersion } from './shared/vscode/env'
 import { Commands, registerErrorHandler } from './shared/vscode/commands2'
-import { isUserCancelledError, ToolkitError } from './shared/errors'
+import { isUserCancelledError, resolveErrorMessageToDisplay } from './shared/errors'
 import { Logging } from './shared/logger/commands'
 import { UriHandler } from './shared/vscode/uriHandler'
 import { telemetry } from './shared/telemetry/telemetry'
@@ -273,7 +273,7 @@ async function handleError(error: unknown, topic: string, defaultMessage: string
 
     const logsItem = localize('AWS.generic.message.viewLogs', 'View Logs...')
     const logId = getLogger().error(`${topic}: %s`, error)
-    const message = error instanceof ToolkitError ? error.message : defaultMessage
+    const message = resolveErrorMessageToDisplay(error, defaultMessage)
 
     await vscode.window.showErrorMessage(message, logsItem).then(async resp => {
         if (resp === logsItem) {

src/shared/clients/codecatalystClient.ts

@@ -306,7 +306,7 @@ class CodeCatalystClientInternal {
             return this.call(this.sdkClient.createAccessToken(args), false)
         } catch (e) {
             if ((e as Error).name === 'ServiceQuotaExceededException') {
-                throw new ToolkitError('Access token limit exceeded', { code: 'ServiceQuotaExceeded' })
+                throw new ToolkitError('Access token limit exceeded', { cause: e as Error })
             }
             throw e
         }

src/shared/errors.ts

@@ -275,18 +275,104 @@ export function getTelemetryReason(error: unknown | undefined): string | undefin
     return 'Unknown'
 }
 
-export function isAwsError(error: unknown | undefined): error is AWSError {
+/**
+ * Determines the appropriate error message to display to the user.
+ *
+ * We do not want to display every error message to the user, this
+ * resolves what we actually want to show them based off the given
+ * input.
+ */
+export function resolveErrorMessageToDisplay(error: unknown, defaultMessage: string): string {
+    const mainMessage = error instanceof ToolkitError ? error.message : defaultMessage
+    // We want to explicitly show certain AWS Error messages if they are raised
+    const prioritizedMessage = findPrioritizedAwsError(error)?.message
+    return prioritizedMessage ? `${mainMessage}: ${prioritizedMessage}` : mainMessage
+}
+
+/**
+ * Patterns that match the value of {@link AWSError.code}
+ */
+export const prioritizedAwsErrors: RegExp[] = [
+    /^ConflictException$/,
+    /^ValidationException$/,
+    /^ResourceNotFoundException$/,
+    /^ServiceQuotaExceededException$/,
+]
+
+/**
+ * Sometimes there are AWS specific errors that we want to explicitly
+ * show to the user, these are 'prioritized' errors.
+ *
+ * In certain cases we may unknowingly wrap these errors in a Toolkit error
+ * as the 'cause', in return masking the the underlying error from being
+ * reported to the user.
+ *
+ * Since we do not want developers to worry if they are allowed to wrap
+ * a specific AWS error in a Toolkit error, we will instead handle
+ * it in this function by extracting the 'prioritized' error if it is
+ * found.
+ *
+ * @returns new ToolkitError with prioritized error message, otherwise original error
+ */
+export function findPrioritizedAwsError(
+    error: unknown,
+    prioritizedErrors = prioritizedAwsErrors
+): AWSError | undefined {
+    const awsError = findAwsErrorInCausalChain(error)
+
+    if (awsError === undefined || !prioritizedErrors.some(regex => regex.test(awsError.code))) {
+        return undefined
+    }
+
+    return awsError
+}
+
+/**
+ * This will search through the causal chain of errors (if it exists)
+ * until it finds an {@link AWSError}.
+ *
+ * {@link ToolkitError} instances can wrap a 'cause', which is the underlying
+ * error that caused it.
+ *
+ * @returns AWSError if found, otherwise undefined
+ */
+export function findAwsErrorInCausalChain(error: unknown): AWSError | undefined {
+    let currentError = error
+
+    while (currentError !== undefined) {
+        if (isAwsError(currentError)) {
+            return currentError
+        }
+
+        // TODO: Base Error has 'cause' in ES2022. If we upgrade this can be made
+        // non-ToolkitError specific
+        if (currentError instanceof ToolkitError && currentError.cause !== undefined) {
+            currentError = currentError.cause
+            continue
+        }
+
+        return undefined
+    }
+
+    return undefined
+}
+
+export function isAwsError(error: unknown): error is AWSError {
     if (error === undefined) {
         return false
     }
 
-    return error instanceof Error && hasCode(error) && (error as { time?: unknown }).time instanceof Date
+    return error instanceof Error && hasCode(error) && hasTime(error)
 }
 
 function hasCode(error: Error): error is typeof error & { code: string } {
     return typeof (error as { code?: unknown }).code === 'string'
 }
 
+function hasTime(error: Error): error is typeof error & { time: Date } {
+    return (error as { time?: unknown }).time instanceof Date
+}
+
 export function isUserCancelledError(error: unknown): boolean {
     return CancellationError.isUserCancelled(error) || (error instanceof ToolkitError && error.cancelled)
 }

src/test/shared/errors.test.ts

@@ -4,9 +4,10 @@
  */
 
 import * as assert from 'assert'
-import { getTelemetryReason, getTelemetryResult, ToolkitError } from '../../shared/errors'
+import { getTelemetryReason, getTelemetryResult, resolveErrorMessageToDisplay, ToolkitError } from '../../shared/errors'
 import { CancellationError } from '../../shared/utilities/timeoutUtils'
 import { UnauthorizedException } from '@aws-sdk/client-sso'
+import { AWSError } from 'aws-sdk'
 
 describe('ToolkitError', function () {
     it('can store an error message', function () {
@@ -219,3 +220,81 @@ describe('Telemetry', function () {
         })
     })
 })
+
+describe('resolveErrorMessageToDisplay()', function () {
+    const defaultMessage = 'My Default Message!'
+    const normalErrorMessage = 'Normal error message'
+    const toolkitErrorMessage = 'Toolkit error message'
+    const awsErrorMessage = 'AWS error message'
+
+    it('returns default message if no error is given', function () {
+        const message = resolveErrorMessageToDisplay(undefined, defaultMessage)
+        assert.strictEqual(message, defaultMessage)
+    })
+
+    it('returns default message if normal error is given', function () {
+        const message = resolveErrorMessageToDisplay(new Error(normalErrorMessage), defaultMessage)
+        assert.strictEqual(message, defaultMessage)
+    })
+
+    it('returns toolkit message if toolkit error is given', function () {
+        const message = resolveErrorMessageToDisplay(new ToolkitError(toolkitErrorMessage), defaultMessage)
+        assert.strictEqual(message, toolkitErrorMessage)
+    })
+
+    describe('prioritized AWS errors', function () {
+        class TestAwsError extends Error implements AWSError {
+            constructor(readonly code: string, message: string, readonly time: Date) {
+                super(message)
+            }
+        }
+
+        const errorTime: Date = new Date()
+        const prioritizedAwsErrorNames: string[] = [
+            'ServiceQuotaExceededException',
+            'ConflictException',
+            'ValidationException',
+            'ResourceNotFoundException',
+        ]
+        const prioritiziedAwsErrors: TestAwsError[] = prioritizedAwsErrorNames.map(name => {
+            return new TestAwsError(name, awsErrorMessage, errorTime)
+        })
+
+        // Sanity check specific errors are resolved as expected
+        prioritiziedAwsErrors.forEach(error => {
+            it(`resolves ${error.code} message when provided directly`, function () {
+                const message = resolveErrorMessageToDisplay(error, defaultMessage)
+                assert.strictEqual(message, `${defaultMessage}: ${awsErrorMessage}`)
+            })
+        })
+
+        it('resolves AWS Error when nested in a ToolkitError cause', function () {
+            const awsError = prioritiziedAwsErrors[0]
+            const toolkitError = new ToolkitError(toolkitErrorMessage, { cause: awsError })
+
+            const message = resolveErrorMessageToDisplay(toolkitError, defaultMessage)
+
+            assert.strictEqual(message, `${toolkitErrorMessage}: ${awsErrorMessage}`)
+        })
+
+        it('resolves AWS Error when nested multiple levels in a ToolkitError cause', function () {
+            const awsError = prioritiziedAwsErrors[0]
+            const toolkitErrorTail = new ToolkitError(`${toolkitErrorMessage}-tail`, { cause: awsError })
+            const toolkitErrorMiddle = new ToolkitError(`${toolkitErrorMessage}-middle`, { cause: toolkitErrorTail })
+            const toolkitErrorHead = new ToolkitError(`${toolkitErrorMessage}-head`, { cause: toolkitErrorMiddle })
+
+            const message = resolveErrorMessageToDisplay(toolkitErrorHead, defaultMessage)
+
+            assert.strictEqual(message, `${toolkitErrorMessage}-head: ${awsErrorMessage}`)
+        })
+
+        it('resolves toolkit message if cause is non-prioritized AWS error', function () {
+            const nonPrioritizedAwsError = new TestAwsError('NonPrioritizedAwsException', awsErrorMessage, errorTime)
+            const toolkitError = new ToolkitError(toolkitErrorMessage, { cause: nonPrioritizedAwsError })
+
+            const message = resolveErrorMessageToDisplay(toolkitError, defaultMessage)
+
+            assert.strictEqual(message, toolkitErrorMessage)
+        })
+    })
+})