AWS Endpoint

AWS Endpoint provides AWS-specific endpoint resolution and manipulation functions for the AWS SDK for Kotlin runtime. It extends the Smithy endpoints standard library with AWS-specific functions including ARN parsing, S3 virtual host bucket validation, and AWS partition identification.

Package Information

• Package Name: aws-endpoint
• Package Type: maven
• Language: Kotlin
• Installation: Add to build.gradle.kts dependencies block: implementation("aws.sdk.kotlin:aws-endpoint:1.5.33")

Core Imports

import aws.sdk.kotlin.runtime.endpoint.functions.*

Note: All functions in this package are marked with @InternalSdkApi and are intended for internal AWS SDK usage.

Basic Usage

import aws.sdk.kotlin.runtime.endpoint.functions.*

// Define partitions configuration
val partitions = listOf(
    Partition(
        id = "aws",
        regionRegex = Regex("^(us|eu|ap|sa|ca|me|af)-\\w+-\\d+$"),
        regions = mapOf(
            "us-east-1" to PartitionConfig()
        ),
        baseConfig = PartitionConfig(
            name = "aws",
            dnsSuffix = "amazonaws.com",
            supportsFIPS = true,
            supportsDualStack = true
        )
    )
)

// Get partition configuration for a region
val config = partition(partitions, "us-east-1")
println("DNS suffix: ${config?.dnsSuffix}")

// Parse an ARN
val arn = parseArn("arn:aws:s3:us-east-1:123456789012:bucket/my-bucket")
println("Service: ${arn?.service}, Region: ${arn?.region}")

// Validate S3 bucket name for virtual hosting
val canUseVirtualHost = isVirtualHostableS3Bucket("my-bucket", false)
println("Can use virtual hosting: $canUseVirtualHost")

Capabilities

Partition Resolution

Identifies the appropriate AWS partition configuration for a given region, supporting explicit region matching, regex-based matching, and fallback behavior.

fun partition(partitions: List<Partition>, region: String?): PartitionConfig?

Parameters:

• partitions: List of available partitions to match against
• region: AWS region string to identify partition for (nullable)

Returns: PartitionConfig? - Configuration for the matched partition, or null if no match found

ARN Parsing

Splits an ARN (Amazon Resource Name) into its component parts with validation and structured access to each component.

fun parseArn(value: String?): Arn?

Parameters:

• value: ARN string to parse (nullable)

Returns: Arn? - Parsed ARN object with component access, or null if invalid format

S3 Bucket Validation

Evaluates whether a string is a DNS-compatible bucket name that can be used with S3 virtual hosted-style addressing.

fun isVirtualHostableS3Bucket(value: String?, allowSubdomains: Boolean): Boolean

Parameters:

• value: Bucket name string to validate (nullable)
• allowSubdomains: Whether to allow subdomain-style bucket names (dot-separated)

Returns: Boolean - True if bucket name is compatible with virtual hosted-style addressing

Types

Arn

Represents a parsed form of an ARN (Amazon Resource Name) with structured access to all components.

data class Arn(
    val partition: String,
    val service: String, 
    val region: String,
    val accountId: String,
    val resourceId: List<String>
)

Properties:

• partition: AWS partition identifier (e.g., "aws", "aws-us-gov", "aws-cn")
• service: AWS service name (e.g., "s3", "ec2", "lambda")
• region: AWS region identifier (e.g., "us-east-1", "eu-west-1")
• accountId: AWS account ID (12-digit string)
• resourceId: Resource identifier components split by colon and forward slash

Partition

Defines a broader set of AWS regions with their configuration and matching rules.

data class Partition(
    val id: String,
    val regions: Map<String, PartitionConfig>,
    val regionRegex: Regex,
    val baseConfig: PartitionConfig
)

Properties:

• id: Partition identifier (e.g., "aws", "aws-us-gov", "aws-cn")
• regions: Mapping of known region names to their specific configurations
• regionRegex: Regular expression pattern for identifying regions in this partition
• baseConfig: Default configuration used when no region-specific config exists

PartitionConfig

Core configuration details for a partition, including DNS settings and feature support.

data class PartitionConfig(
    val name: String? = null,
    val dnsSuffix: String? = null,
    val dualStackDnsSuffix: String? = null,
    val supportsFIPS: Boolean? = null,
    val supportsDualStack: Boolean? = null,
    val implicitGlobalRegion: String? = null
) {
    fun mergeWith(other: PartitionConfig): PartitionConfig
}

Properties:

• name: Human-readable partition name (nullable, default: null)
• dnsSuffix: DNS suffix for standard endpoints (nullable, default: null)
• dualStackDnsSuffix: DNS suffix for dual-stack IPv4/IPv6 endpoints (nullable, default: null)
• supportsFIPS: Whether FIPS 140-2 compliant endpoints are supported (nullable, default: null)
• supportsDualStack: Whether dual-stack IPv4/IPv6 endpoints are supported (nullable, default: null)
• implicitGlobalRegion: Default region for global services (nullable, default: null)

Methods:

• mergeWith(other: PartitionConfig): Merges configuration with another, prioritizing non-null values from the other parameter

Error Handling

All functions handle null inputs gracefully and return null for invalid data:

• partition() returns null when no partition matches the region
• parseArn() returns null for malformed ARNs (wrong format, missing components, empty required fields)
• isVirtualHostableS3Bucket() returns false for null input or invalid bucket names

Common validation failures:

• ARN parsing fails for strings not starting with "arn:" or having incorrect component count (6 components required)
• S3 bucket validation fails for names outside 3-63 character range, containing uppercase letters, or resembling IP addresses

Examples of invalid inputs:

// Invalid ARN examples
parseArn("invalid") // returns null - doesn't start with "arn:"
parseArn("arn:aws") // returns null - insufficient components
parseArn("arn::service:region:account:") // returns null - empty partition or resource

// Invalid S3 bucket examples  
isVirtualHostableS3Bucket("AB", false) // returns false - too short
isVirtualHostableS3Bucket("MyBucket", false) // returns false - contains uppercase
isVirtualHostableS3Bucket("192.168.1.1", false) // returns false - looks like IP address