BREAKING: Scope control applied to DSL builders

[ianbotsf]

An upcoming release of the AWS SDK for Kotlin will introduce scope control to DSL builders used to create instances of request/response structures.

Release date

This feature will ship with the v1.1.20 release planned for 4/16/2024.

What's changing

Kotlin provides a DSL syntax for constructing structures used in operation requests and responses by way of type-safe builders. These builders did not use any form of compile-time scope control meaning that members of parent scopes could be accessed in child scopes, potentially leading to errors and unintended behavior at runtime.

These builders are now being annotated with @SdkDsl, a new SDK-specific annotation which introduces a unique DSL scope. The compiler will throw an error when attempting to access a member of a parent scope.

How to migrate

If you are accessing members of parent scopes in your DSL builders, you will need to rewrite your code to either move the member access to the correct scope or qualify the receiver.

For example, previous code to create a bucket may have looked like this:

s3.createBucket {
    bucket = "foo"
    createBucketConfiguration { 
        acl = BucketCannedAcl.AuthenticatedRead // Likely a bug: setting `acl` from within `createBucketConfiguration`
        …
    }
    …
}

The code above is likely erroneous because it sets the CreateBucketRequest.acl member inside the createBucketConfiguration scope. Visually it appears to be a member of the child scope but it's not.

After the breaking change, this code will no longer compile. The correct code would be:

s3.createBucket {
    bucket = "foo"
    acl = BucketCannedAcl.AuthenticatedRead
    createBucketConfiguration { 
        …
    }
    …
}

Note that there may be times when it is desirable to access members of parent scopes inside of child scopes. If you have such a requirement you must explicitly state the member scope using this@<scope> syntax:

s3.createBucket {
    bucket = "foo"
    createBucketConfiguration { 
        this@createBucket.Builder.acl = BucketCannedAcl.AuthenticatedRead
        …
    }
    …
}

Additional information

For more information about this change, see smithy-lang/smithy-kotlin#428 and Kotlin's official documentation on scope control in type-safe builders.

Feedback

If you have any questions concerning this change, please feel free to engage with us in this discussion. If you encounter a bug with these changes, please file an issue.