Mark changes to Functional (SAM) interfaces or any interface as a "Breaking Change"

[michaelbrewer]

As an example the recent change to IAliasRecordTarget, was a breaking change, as IAliasRecordTarget in Java (Kotlin) stopped being a Single Abstract Method.

See the below example that compiles in AWS CDK 1.107.0 but does not compile with AWS CDK 1.108.0 and above. And there was no notification of breaking changes in the AWS CDK 1.108.0 release.

    private fun createARecord(
        baseDomainName: String,
        hostedZoneId: String,
        recordName: String,
        distribution: CfnDistribution,
        comment: String,
    ) {
        val zone = HostedZone.fromHostedZoneAttributes(
            this,
            baseDomainName,
            HostedZoneAttributes.builder()
                .zoneName(baseDomainName)
                .hostedZoneId(hostedZoneId)
                .build()
        )
        ARecord(
            this,
            "fleARecord",
            ARecordProps
                .builder()
                .zone(zone)
                .comment(comment)
                .recordName(recordName)
                // In AWS-CDK 1.107.0 this would work with IAliasRecordTarget
                .target(RecordTarget.fromAlias {
                    AliasRecordTargetConfig
                        .builder()
                        .dnsName(distribution.attrDomainName)
                        .hostedZoneId(CLOUDFRONT_ZONE_ID)
                        .build()
                }
                .build()
        )
    }

Changes:

Defaults behind the changes

Typescript before:

/**
 * Classes that are valid alias record targets, like CloudFront distributions and load
 * balancers, should implement this interface.
 */
export interface IAliasRecordTarget {
  /**
   * Return hosted zone ID and DNS name, usable for Route53 alias targets
   */
  bind(record: IRecordSet): AliasRecordTargetConfig;
}

Typescript after:

/**
 * Classes that are valid alias record targets, like CloudFront distributions and load
 * balancers, should implement this interface.
 */
export interface IAliasRecordTarget {
  /**
   * Return hosted zone ID and DNS name, usable for Route53 alias targets
   */
  bind(record: IRecordSet, zone?: IHostedZone): AliasRecordTargetConfig;
}

Resulting in a change from this:

package software.amazon.awscdk.services.route53;

@javax.annotation.Generated(value = "jsii-pacmak/1.29.0 (build 41df200)", date = "2021-06-02T17:52:56.957Z")
@software.amazon.jsii.Jsii(module = software.amazon.awscdk.services.route53.$Module.class, fqn = "@aws-cdk/aws-route53.IAliasRecordTarget")
@software.amazon.jsii.Jsii.Proxy(IAliasRecordTarget.Jsii$Proxy.class)
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public interface IAliasRecordTarget extends software.amazon.jsii.JsiiSerializable {

    /**
     * Return hosted zone ID and DNS name, usable for Route53 alias targets.
     * <p>
     * @param record This parameter is required.
     */
    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
    @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.route53.AliasRecordTargetConfig bind(final @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.route53.IRecordSet record);
}

To this

package software.amazon.awscdk.services.route53;

@javax.annotation.Generated(value = "jsii-pacmak/1.31.0 (build 6fa403d)", date = "2021-07-21T15:56:31.170Z")
@software.amazon.jsii.Jsii(module = software.amazon.awscdk.services.route53.$Module.class, fqn = "@aws-cdk/aws-route53.IAliasRecordTarget")
@software.amazon.jsii.Jsii.Proxy(IAliasRecordTarget.Jsii$Proxy.class)
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
public interface IAliasRecordTarget extends software.amazon.jsii.JsiiSerializable {

    /**
     * Return hosted zone ID and DNS name, usable for Route53 alias targets.
     * <p>
     * @param record This parameter is required.
     * @param zone
     */
    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
    @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.route53.AliasRecordTargetConfig bind(final @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.route53.IRecordSet record, final @org.jetbrains.annotations.Nullable software.amazon.awscdk.services.route53.IHostedZone zone);

    /**
     * Return hosted zone ID and DNS name, usable for Route53 alias targets.
     * <p>
     * @param record This parameter is required.
     */
    @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
    @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.route53.AliasRecordTargetConfig bind(final @org.jetbrains.annotations.NotNull software.amazon.awscdk.services.route53.IRecordSet record);
}

And therefore no longer a SAM

The fix

So in order to fix this in AWS CDK 1.108.0 and above the following changes needed to be made to the code

    private fun createARecord(
        baseDomainName: String,
        hostedZoneId: String,
        recordName: String,
        distribution: CfnDistribution,
        comment: String,
    ) {
        val zone = HostedZone.fromHostedZoneAttributes(
            this,
            baseDomainName,
            HostedZoneAttributes.builder()
                .zoneName(baseDomainName)
                .hostedZoneId(hostedZoneId)
                .build()
        )
        ARecord(
            this,
            "fleARecord",
            ARecordProps
                .builder()
                .zone(zone)
                .comment(comment)
                .recordName(recordName)
                .target(RecordTarget.fromAlias(object : IAliasRecordTarget {
                    private val config = AliasRecordTargetConfig
                        .builder()
                        .dnsName(distribution.attrDomainName)
                        .hostedZoneId(CLOUDFRONT_ZONE_ID)
                        .build()
                    override fun bind(record: IRecordSet, zone: IHostedZone?) = config
                    override fun bind(record: IRecordSet) =  config
                }))
                .build()
        )
    }

NOTE: Maybe using CloudFrontTarget is better solution, but in this stack we needed a CfnDistribution and not a Distribution.

Example PR:

• feat(route53-targets): route53 record target #14820

[alexpulver]

@michaelbrewer can you please also mention whether it was a breaking change? If so, what did it break?

[michaelbrewer]

@alexpulver ok i tried to expand on the example.

[alexpulver]

So, after the change it no longer compiled as is?

[michaelbrewer]

Yes, without making modifications as shown above.

[skinny85]

Hey @michaelbrewer,

thanks for opening the issue. This is mostly a JSII concern, so I would recommend opening an issue to that project, and seeing what they say: https://github.com/aws/jsii/issues.

Perhaps there's a way to generate that interface as:

public interface IAliasRecordTarget extends software.amazon.jsii.JsiiSerializable {
    @Stability(Stable)
    @NotNull AliasRecordTargetConfig bind(@NotNull IRecordSet record, @Nullable IHostedZone zone);

    @Stability(Stable)
    default @NotNull AliasRecordTargetConfig bind(@NotNull IRecordSet record) {
      return this.bind(record, null);
    }
}

However, that's up to the JSII team to decide.

Thanks,
Adam

[michaelbrewer]

Sure. Maybe in the meantime, would it make sense to notify CDK users when an interface changes. Because regardless of how JSII implements this, downstream in some languages, this would be a breaking change.

[skinny85]

That's fair. We generally try to avoid these sort of changes, but apparently they sometimes sneak through. Apologies for the bad experience. We'll be more diligent in noting them as 'breaking changes' in the future.

[skinny85]

(For reference, this was the change that caused this issue)