0
# AWS Endpoint
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: aws-endpoint  
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: Add to build.gradle.kts dependencies block: `implementation("aws.sdk.kotlin:aws-endpoint:1.5.33")`
10

11
## Core Imports
12

13
```kotlin
14
import aws.sdk.kotlin.runtime.endpoint.functions.*
15
```
16

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

19
## Basic Usage
20

21
```kotlin
22
import aws.sdk.kotlin.runtime.endpoint.functions.*
23

24
// Define partitions configuration
25
val partitions = listOf(
26
    Partition(
27
        id = "aws",
28
        regionRegex = Regex("^(us|eu|ap|sa|ca|me|af)-\\w+-\\d+$"),
29
        regions = mapOf(
30
            "us-east-1" to PartitionConfig()
31
        ),
32
        baseConfig = PartitionConfig(
33
            name = "aws",
34
            dnsSuffix = "amazonaws.com",
35
            supportsFIPS = true,
36
            supportsDualStack = true
37
        )
38
    )
39
)
40

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

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

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

54
## Capabilities
55

56
### Partition Resolution
57

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

60
```kotlin { .api }
61
fun partition(partitions: List<Partition>, region: String?): PartitionConfig?
62
```
63

64
**Parameters:**
65
- `partitions`: List of available partitions to match against
66
- `region`: AWS region string to identify partition for (nullable)
67

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

70
### ARN Parsing
71

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

74
```kotlin { .api }
75
fun parseArn(value: String?): Arn?
76
```
77

78
**Parameters:**
79
- `value`: ARN string to parse (nullable)
80

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

83
### S3 Bucket Validation
84

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

87
```kotlin { .api }
88
fun isVirtualHostableS3Bucket(value: String?, allowSubdomains: Boolean): Boolean
89
```
90

91
**Parameters:**
92
- `value`: Bucket name string to validate (nullable)
93
- `allowSubdomains`: Whether to allow subdomain-style bucket names (dot-separated)
94

95
**Returns:** `Boolean` - True if bucket name is compatible with virtual hosted-style addressing
96

97
## Types
98

99
### Arn
100

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

103
```kotlin { .api }
104
data class Arn(
105
    val partition: String,
106
    val service: String, 
107
    val region: String,
108
    val accountId: String,
109
    val resourceId: List<String>
110
)
111
```
112

113
**Properties:**
114
- `partition`: AWS partition identifier (e.g., "aws", "aws-us-gov", "aws-cn")
115
- `service`: AWS service name (e.g., "s3", "ec2", "lambda")
116
- `region`: AWS region identifier (e.g., "us-east-1", "eu-west-1")
117
- `accountId`: AWS account ID (12-digit string)
118
- `resourceId`: Resource identifier components split by colon and forward slash
119

120
### Partition
121

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

124
```kotlin { .api }
125
data class Partition(
126
    val id: String,
127
    val regions: Map<String, PartitionConfig>,
128
    val regionRegex: Regex,
129
    val baseConfig: PartitionConfig
130
)
131
```
132

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

139
### PartitionConfig
140

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

143
```kotlin { .api }
144
data class PartitionConfig(
145
    val name: String? = null,
146
    val dnsSuffix: String? = null,
147
    val dualStackDnsSuffix: String? = null,
148
    val supportsFIPS: Boolean? = null,
149
    val supportsDualStack: Boolean? = null,
150
    val implicitGlobalRegion: String? = null
151
) {
152
    fun mergeWith(other: PartitionConfig): PartitionConfig
153
}
154
```
155

156
**Properties:**
157
- `name`: Human-readable partition name (nullable, default: null)
158
- `dnsSuffix`: DNS suffix for standard endpoints (nullable, default: null)
159
- `dualStackDnsSuffix`: DNS suffix for dual-stack IPv4/IPv6 endpoints (nullable, default: null)
160
- `supportsFIPS`: Whether FIPS 140-2 compliant endpoints are supported (nullable, default: null)
161
- `supportsDualStack`: Whether dual-stack IPv4/IPv6 endpoints are supported (nullable, default: null)
162
- `implicitGlobalRegion`: Default region for global services (nullable, default: null)
163

164
**Methods:**
165
- `mergeWith(other: PartitionConfig)`: Merges configuration with another, prioritizing non-null values from the `other` parameter
166

167
## Error Handling
168

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

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

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

179
**Examples of invalid inputs:**
180
```kotlin
181
// Invalid ARN examples
182
parseArn("invalid") // returns null - doesn't start with "arn:"
183
parseArn("arn:aws") // returns null - insufficient components
184
parseArn("arn::service:region:account:") // returns null - empty partition or resource
185

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