[Feature Request] Functionality to Retrieve All Enumeration Values

[bflad]

Is your feature request related to a problem? Please describe.

(The below uses CodeBuild as an example, but this applies to all AWS Go SDK service packages and type string enumerations 👍 )

AWS service teams can and often do provide enumerations of available values for API parameters. For example, given these API References:

• https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectEnvironment.html#CodeBuild-Type-ProjectEnvironment-type
  • Valid Values: WINDOWS_CONTAINER | LINUX_CONTAINER | LINUX_GPU_CONTAINER | ARM_CONTAINER | WINDOWS_SERVER_2019_CONTAINER
• https://docs.aws.amazon.com/codebuild/latest/APIReference/API_EnvironmentVariable.html
  • Valid Values: PLAINTEXT | PARAMETER_STORE | SECRETS_MANAGER

These are equivalent (and presumably generated in the API Reference documentation) from these in the API model:

• https://github.com/aws/aws-sdk-go/blob/4c5b59fab7cd60ba611bde59ea953bc87fa8cf94/models/apis/codebuild/2016-10-06/api-2.json#L908-L917
• https://github.com/aws/aws-sdk-go/blob/4c5b59fab7cd60ba611bde59ea953bc87fa8cf94/models/apis/codebuild/2016-10-06/api-2.json#L930-L937

The AWS Go SDK generators currently translate these enumeration values into Go constants:

• https://github.com/aws/aws-sdk-go/blob/4c5b59fab7cd60ba611bde59ea953bc87fa8cf94/service/codebuild/api.go#L11005-L11020
• https://github.com/aws/aws-sdk-go/blob/4c5b59fab7cd60ba611bde59ea953bc87fa8cf94/service/codebuild/api.go#L11022-L11031

Downstream in Terraform and the Terraform AWS Provider, one feature we provide is the ability to invalidate an infrastructure configuration upfront (during plan time in Terraform terminology), should an argument value not be in a predetermined slice of strings (amongst many other validation features). For example:

• https://github.com/terraform-providers/terraform-provider-aws/issues/11331
• https://github.com/terraform-providers/terraform-provider-aws/issues/14335

Here is the above validation in the Terraform AWS Provider codebase:

• https://github.com/terraform-providers/terraform-provider-aws/blob/0e840b5cb97c286afa5a0bb0fe03c27948b4bbf4/aws/resource_aws_codebuild_project.go#L193-L197
• https://github.com/terraform-providers/terraform-provider-aws/blob/0e840b5cb97c286afa5a0bb0fe03c27948b4bbf4/aws/resource_aws_codebuild_project.go#L210-L215

These upfront validations are valuable to operators over finding configuration errors when making the API requests, potentially very far into creating their infrastructure or otherwise causing unexpected changes/downtime. Given the consequences, we have found over time that many operators have come to expect us to support this upfront validation at the expense of maintaining them with a slight delay as AWS service APIs support additional values.

This is super fuzzy metric (not representing reuse, etc.), but we have 483 of these string enumeration validators across our codebase today and many more places we don't support this validation where we could.

Describe the solution you'd like

We would like to reduce the manual work associated with including all known enumeration values at the time of the AWS Go SDK release in our codebase. It would be great if the AWS Go SDK service generators could output some form of retrieving all enumeration values for a given API model type.

A very naive approach could be generating a variable slice in addition to the constants, e.g.

const (
    // EnvironmentTypeWindowsContainer is a EnvironmentType enum value
    EnvironmentTypeWindowsContainer = "WINDOWS_CONTAINER"

    // EnvironmentTypeLinuxContainer is a EnvironmentType enum value
    EnvironmentTypeLinuxContainer = "LINUX_CONTAINER"

    // EnvironmentTypeLinuxGpuContainer is a EnvironmentType enum value
    EnvironmentTypeLinuxGpuContainer = "LINUX_GPU_CONTAINER"

    // EnvironmentTypeArmContainer is a EnvironmentType enum value
    EnvironmentTypeArmContainer = "ARM_CONTAINER"

    // EnvironmentTypeWindowsServer2019Container is a EnvironmentType enum value
    EnvironmentTypeWindowsServer2019Container = "WINDOWS_SERVER_2019_CONTAINER"
)

var EnvironmentTypeEnum = []string{
    EnvironmentTypeWindowsContainer,
    EnvironmentTypeLinuxContainer,
    EnvironmentTypeArmContainer,
    EnvironmentTypeWindowsServer2019Container,
}

const (
    // EnvironmentVariableTypePlaintext is a EnvironmentVariableType enum value
    EnvironmentVariableTypePlaintext = "PLAINTEXT"

    // EnvironmentVariableTypeParameterStore is a EnvironmentVariableType enum value
    EnvironmentVariableTypeParameterStore = "PARAMETER_STORE"

    // EnvironmentVariableTypeSecretsManager is a EnvironmentVariableType enum value
    EnvironmentVariableTypeSecretsManager = "SECRETS_MANAGER"
)

var EnvironmentVariableTypeEnum = []string{
    EnvironmentVariableTypePlaintext,
    EnvironmentVariableTypeParameterStore,
    EnvironmentVariableTypeSecretsManager,
}

Where downstream consumers such as our example above could be:

ValidateFunc: validation.StringInSlice(codebuild.EnvironmentVariableTypeEnum, false),

Otherwise, providing a new Go type for the enumeration with a receiver method for fetching the values, also could be an option:

const (
    // EnvironmentTypeWindowsContainer is a EnvironmentType enum value
    EnvironmentTypeWindowsContainer = "WINDOWS_CONTAINER"

    // EnvironmentTypeLinuxContainer is a EnvironmentType enum value
    EnvironmentTypeLinuxContainer = "LINUX_CONTAINER"

    // EnvironmentTypeLinuxGpuContainer is a EnvironmentType enum value
    EnvironmentTypeLinuxGpuContainer = "LINUX_GPU_CONTAINER"

    // EnvironmentTypeArmContainer is a EnvironmentType enum value
    EnvironmentTypeArmContainer = "ARM_CONTAINER"

    // EnvironmentTypeWindowsServer2019Container is a EnvironmentType enum value
    EnvironmentTypeWindowsServer2019Container = "WINDOWS_SERVER_2019_CONTAINER"
)

type EnvironmentType struct{}

func (EnvironmentType) Values() []string {
    return []string{
        EnvironmentTypeWindowsContainer,
        EnvironmentTypeLinuxContainer,
        EnvironmentTypeArmContainer,
        EnvironmentTypeWindowsServer2019Container,
    }
}

const (
    // EnvironmentVariableTypePlaintext is a EnvironmentVariableType enum value
    EnvironmentVariableTypePlaintext = "PLAINTEXT"

    // EnvironmentVariableTypeParameterStore is a EnvironmentVariableType enum value
    EnvironmentVariableTypeParameterStore = "PARAMETER_STORE"

    // EnvironmentVariableTypeSecretsManager is a EnvironmentVariableType enum value
    EnvironmentVariableTypeSecretsManager = "SECRETS_MANAGER"
)

type EnvironmentVariableType struct{}

func (EnvironmentVariableType) Values() []string {
    return []string{
        EnvironmentVariableTypePlaintext,
        EnvironmentVariableTypeParameterStore,
        EnvironmentVariableTypeSecretsManager,
    }
}

Where downstream consumers such as our example above could be:

ValidateFunc: validation.StringInSlice(codebuild.EnvironmentVariableType{}.Values(), false),

Describe alternatives you've considered

• Creating our own generator that creates these enumeration helpers from the API models directly
• Creating our own generator that attempts to reconstitute these enumerations from the constants
• Manually managing these lists

Additional context

Thank you for the consideration!

[jasdel]

Thanks for creating this this feature request @bflad. Adding the ability to get a slice of enums makes sense. I think this is something we can add to the code generation for enum types. Ideally we can port this idea to the v2 SDK tool.

Var - Exposing the slice directly as a package variable is a straight forward approach, but what impact that would have on the resident member, or binary since of the compile application to put all SDKs into memory. I'm not actually tested that, but is a hunch.

Type - Creating a new type with method is probably a good way to expose these as well. This is what the v2 SDK is doing with string aliases. Using structs is alternative to string aliases. Having a Values() []string method on the type returning a slice would accomplish the goal. Using type alias or struct most likely has the least likely hood of name clashing with other generated identifier since the modeled enum shape has a unique name within the API. Either of these may instill some confusion in their usage since the type it self is not usable anywhere.

type Foo string
// or
type Foo struct{}

func (Foo) Values() []string {
     return []string{
          FooBar,
          FooBaz,
      }
}

const (
     FooBar = "Bar" // Not actually of type `Foo`
     FooBaz = "Baz"
)

Usage:

values := Foo("").Values() // Wish Go allowed scalar type zero value initialization with `{}` 
values := Foo{}.Values()

Func - The final alternative I can think of is a standalone function that returns the slice of enum values. While simpler than the type alias or struct, a function name most likely will have a higher risk of clashing with some other generated identifier since a new unique name would need to be generated that is beyond the modeled names. Potential workaround for the name collisions would probably be some non-idiomatic naming scheme, e.g. Foo_Values().

func FooValues() []string {
      return []string{
          FooBar,
          FooBaz,
      }
}

Usage:

values := FooValues()

As much as the func approach would be nice, I think the risk of name collision will be prohibitive without some unique naming scheme for the function. The V2 SDK will address this feature via methods, since its already using a type alias.