What's the better pattern? Throwing errors or adding error Annotations in constructs

[dontirun]

Summary

There are cases where I want to add specific configurations to resources passed into constructs that I vend. I'd like to add some sort of Error when those configurations fail to apply. I could either add an Error Annotation or I could throw an Error. There seem to be pros and cons to each approach, so I thought I'd start a discussion.

Annotations

Pros

1. Very easy to read
2. All annotations are rendered at once

Cons

1. Annotations don't render on npx cdk synth or npx cdk deploy for Stages (Unless the stack id is specified in the CLI)
2. Doesn't stop synthesis (Though I don't think this is really much of an issue)

Thrown Error

Pros

1. Errors are thrown in all expected scenarios

Cons

1. Stack Trace makes it hard to read
2. Thrown errors must be handled one at a time

Example Code

#!/usr/bin/env node
import { Stack, StackProps, App, Annotations, Stage } from 'aws-cdk-lib';
import { Effect, PolicyStatement, ServicePrincipal } from 'aws-cdk-lib/aws-iam';
import { Bucket, IBucket } from 'aws-cdk-lib/aws-s3';
import { Construct } from 'constructs';

export class CdkTestStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const bucket = Bucket.fromBucketName(this, 'ImportedBucket', 'foobar');
    new BucketPolicyAdderAnnotation(this, 'AdderAnnotation', { bucket });

    // Uncomment for a thrown Error
    //new BucketPolicyAdderThrow(this, 'AdderThrow', { bucket });
  }
}

export interface BucketPolicyAdderProps {
  bucket: IBucket;
}

export class BucketPolicyAdderAnnotation extends Construct {
  constructor(scope: Construct, id: string, props: BucketPolicyAdderProps) {
    super(scope, id);

    const result = props.bucket.addToResourcePolicy(
      new PolicyStatement({
        effect: Effect.ALLOW,
        principals: [new ServicePrincipal('lambda.amazonaws.com')],
        actions: ['s3:GetObject'],
        resources: [`${props.bucket.bucketArn}/*`],
      }),
    );

    if (!result.statementAdded) {
      Annotations.of(props.bucket).addError("Couldn't add the Policy!");
    }
  }
}

export class BucketPolicyAdderThrow extends Construct {
  constructor(scope: Construct, id: string, props: BucketPolicyAdderProps) {
    super(scope, id);

    const result = props.bucket.addToResourcePolicy(
      new PolicyStatement({
        effect: Effect.ALLOW,
        principals: [new ServicePrincipal('lambda.amazonaws.com')],
        actions: ['s3:GetObject'],
        resources: [`${props.bucket.bucketArn}/*`],
      }),
    );

    if (!result.statementAdded) {
      throw new Error("Couldn't add the Policy!");
    }
  }
}

export class TestStage extends Stage {
  constructor(scope: Construct, id: string) {
    super(scope, id);
    new CdkTestStack(this, 'foobar');
  }
}

const app = new App();

// Comment out when testing with Stages
new CdkTestStack(app, 'ErrorExampleStack');

// Uncomment for testing with Stages
// new TestStage(app, 'TestStage');

[suds-sky]

Nice one, In the second approach does it stop at synth

[dontirun]

Throwing a runtime Error will stop everything so it won't synth