AWS rules engine library functions#

AWS-specific rules engine library functions make it possible to integrate AWS concepts like Amazon Resource Names (ARNs) and Partitions. An additional dependency is required to access these functions:

The following example adds smithy-aws-endpoints as a dependency to a Smithy project:

smithy-build.json#
{
    "maven": {
        "dependencies": [
            "software.amazon.smithy:smithy-aws-endpoints:1.48.0"
        ]
    }
}
build.gradle.kts#
dependencies {
    ...
    implementation("software.amazon.smithy:smithy-aws-endpoints:1.48.0")
    ...
}
build.gradle#
dependencies {
    ...
    implementation 'software.amazon.smithy:smithy-aws-endpoints:1.48.0'
    ...
}

aws.partition function#

Summary
Provides a Partition structure of content for the
Argument type
  • region: string
Return type

option<Partition>

Contains the region's partition, or an empty optional if the region is unknown.

The following example uses aws.partition to provide partition information from the region in the value of the foo parameter:

{
    "fn": "aws.partition",
    "argv": [
        {"ref": "foo"}
    ]
}

Partition structure#

The Partition structure is returned from the aws.partition function when its input is a known region. The Partition object contains the following properties:

Property Type Description
name string The partition's name.
dnsSuffix string The partition's default DNS suffix.
dualStackDnsSuffix string The partition's dual-stack specific DNS suffix.
supportsFIPS bool Indicates whether the partition supports a FIPS compliance mode.
supportsDualStack bool Indicates whether the partition supports dual-stack endpoints.
implicitGlobalRegion string The region used by partitional (non-regionalized/global) services for signing.

aws.parseArn function#

Summary
Computes an ARN structure given an input string.
Argument type
  • value: string
Return type

option<ARN>

Contains the parsed ARN, or an empty optional if the ARN could not be parsed

The following example uses aws.parseArn to parse the value of the foo parameter into its component parts:

{
    "fn": "aws.parseArn",
    "argv": [
        {"ref": "foo"}
    ]
}

ARN structure#

The ARN structure is returned from the aws.parseArn function when its input is a valid ARN. The ARN object contains the following properties:

Property Type Description
partition string The partition where the resource is located.
service string The service namespace where the resource is located.
region string The region where the resource is located. May be an empty length value if the resource is not region-based.
accountId string The account that the resource is managed by. May be an empty length value if the resource is not account-based.
resourceId array<string> An array of resourceId components, where the final segment of the ARN is split on : and / characters.

Examples#

The following table shows valid and invalid values for an input to the aws.parseArn function:

Input Valid? partition service region accountId resourceId
arn:aws:sns:us-west-2:012345678910:example-sns-topic-name true aws sns us-west-2 012345678910 example-sns-topic-name
11111111-2222-3333-4444-555555555555 false          
arn:aws:ec2:us-east-1:012345678910:vpc/vpc-0e9801d129EXAMPLE true aws ec2 us-east-1 012345678910 [vpc, vpc-0e9801d129EXAMPLE]
arn:aws:iam::012345678910:user/johndoe true aws iam An empty string. 012345678910 [user, johndoe]
arn:aws:s3:::bucket_name true aws s3 An empty string. An empty string. bucket_name

aws.isVirtualHostableS3Bucket function#

Summary
Evaluates whether the input string is a compliant RFC 1123 host segment and contains a segment that is a valid bucket name. When allowSubDomains is true, evaluates whether the input string is composed of values that are each compliant values joined by dot (.) characters.
Argument type
  • value: string
  • allowSubDomains: bool
Return type
bool

The following example uses aws.isVirtualHostableS3Bucket to check if the value of the foo parameter is an RFC 1123 compliant host segment and a valid bucket name.

{
    "fn": "aws.isVirtualHostableS3Bucket",
    "argv": [
        {"ref": "foo"},
        false
    ]
}