0
# Smithy AWS Endpoints
1

2
Smithy AWS Endpoints provides AWS-specific endpoint components for the Smithy framework, focusing on rule-set functions for AWS partitions, ARN parsing, endpoint authentication utilities, and S3 virtual hosting capabilities. It integrates with Smithy's rules engine to enable AWS-aware endpoint resolution and is designed for use in AWS service modeling, SDK generation, and endpoint rule evaluation.
3

4
## Package Information
5

6
- **Package Name**: software.amazon.smithy:smithy-aws-endpoints
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your `build.gradle.kts`:
10
  ```kotlin
11
  dependencies {
12
      implementation("software.amazon.smithy:smithy-aws-endpoints:1.58.0")
13
  }
14
  ```
15

16
## Core Imports
17

18
```java
19
import software.amazon.smithy.rulesengine.aws.language.functions.AwsRuleSetExtension;
20
import software.amazon.smithy.rulesengine.aws.language.functions.AwsPartition;
21
import software.amazon.smithy.rulesengine.aws.language.functions.ParseArn;
22
import software.amazon.smithy.rulesengine.aws.language.functions.IsVirtualHostableS3Bucket;
23
import software.amazon.smithy.rulesengine.aws.language.functions.EndpointAuthUtils;
24
import software.amazon.smithy.rulesengine.aws.traits.*;
25
```
26

27
## Basic Usage
28

29
```java
30
import software.amazon.smithy.rulesengine.aws.language.functions.AwsPartition;
31
import software.amazon.smithy.rulesengine.aws.language.functions.ParseArn;
32
import software.amazon.smithy.rulesengine.aws.language.functions.AwsArn;
33

34
// Use AWS partition function to resolve regional information
35
var partitionFunction = AwsPartition.getDefinition();
36

37
// Parse an AWS ARN to extract components
38
Optional<AwsArn> parsedArn = AwsArn.parse("arn:aws:s3:us-east-1:123456789012:bucket/my-bucket");
39
if (parsedArn.isPresent()) {
40
    AwsArn arn = parsedArn.get();
41
    String partition = arn.getPartition();  // "aws"
42
    String service = arn.getService();      // "s3"
43
    String region = arn.getRegion();        // "us-east-1"
44
    String accountId = arn.getAccountId();  // "123456789012"
45
}
46
```
47

48
## Architecture
49

50
The Smithy AWS Endpoints package is built around several key components:
51

52
- **Rule Set Extension**: `AwsRuleSetExtension` provides AWS-specific built-ins and functions to the Smithy rules engine
53
- **Built-in Parameters**: `AwsBuiltIns` defines AWS-specific parameters like region, FIPS, dual-stack configuration
54
- **Library Functions**: Core functions for AWS partition resolution, ARN parsing, and S3 bucket validation
55
- **Smithy Traits**: Annotation traits for describing AWS endpoint behavior in Smithy models
56
- **Authentication Utilities**: Helper methods for constructing AWS authentication schemes in endpoints
57
- **Validators**: Validation components for AWS-specific endpoint rules and configurations
58

59
## Capabilities
60

61
### AWS Rule Set Extension
62

63
Main extension class that integrates AWS-specific functionality into the Smithy rules engine, providing built-in parameters, library functions, and authentication validators.
64

65
```java { .api }
66
public final class AwsRuleSetExtension implements EndpointRuleSetExtension {
67
    public List<Parameter> getBuiltIns();
68
    public List<FunctionDefinition> getLibraryFunctions();
69
    public List<AuthSchemeValidator> getAuthSchemeValidators();
70
}
71
```
72

73
[AWS Rule Set Extension](./aws-rule-set-extension.md)
74

75
### AWS Built-in Parameters
76

77
Defines AWS-specific built-in parameters for endpoint rules including region, dual-stack, FIPS, and service-specific configurations.
78

79
```java { .api }
80
public final class AwsBuiltIns {
81
    public static final Parameter REGION;
82
    public static final Parameter DUALSTACK;
83
    public static final Parameter FIPS;
84
    public static final Parameter ACCOUNT_ID;
85
    // ... additional parameters
86
}
87
```
88

89
[AWS Built-in Parameters](./aws-built-ins.md)
90

91
### Partition Resolution
92

93
Functions for mapping AWS regions to partitions and resolving partition-specific endpoint information.
94

95
```java { .api }
96
public final class AwsPartition extends LibraryFunction {
97
    public static final String ID = "aws.partition";
98
    public static Definition getDefinition();
99
    public static AwsPartition ofExpressions(ToExpression region);
100
}
101
```
102

103
[Partition Resolution](./partition-resolution.md)
104

105
### ARN Parsing and Utilities
106

107
Components for parsing and working with AWS ARNs, including validation and component extraction.
108

109
```java { .api }
110
public final class ParseArn extends LibraryFunction {
111
    public static final String ID = "aws.parseArn";
112
    public static Definition getDefinition();
113
    public static ParseArn ofExpressions(ToExpression arn);
114
}
115

116
public final class AwsArn implements ToSmithyBuilder<AwsArn> {
117
    public static Optional<AwsArn> parse(String arn);
118
    public String getPartition();
119
    public String getService();
120
    public String getRegion();
121
    public String getAccountId();
122
    public List<String> getResource();
123
}
124
```
125

126
[ARN Parsing](./arn-parsing.md)
127

128
### S3 Virtual Hosting
129

130
Utilities for determining S3 virtual hosting capabilities and bucket name validation.
131

132
```java { .api }
133
public final class IsVirtualHostableS3Bucket extends LibraryFunction {
134
    public static final String ID = "aws.isVirtualHostableS3Bucket";
135
    public static Definition getDefinition();
136
    public static IsVirtualHostableS3Bucket ofExpressions(ToExpression bucket, ToExpression allowSubdomains);
137
}
138
```
139

140
[S3 Virtual Hosting](./s3-virtual-hosting.md)
141

142
### Authentication Utilities
143

144
Helper methods for constructing AWS authentication schemes in endpoint rules.
145

146
```java { .api }
147
public final class EndpointAuthUtils {
148
    public static Endpoint.Builder sigv4(Endpoint.Builder builder, Literal signingRegion, Literal signingService);
149
    public static Endpoint.Builder sigv4a(Endpoint.Builder builder, List<Literal> signingRegionSet, Literal signingService);
150
    public static boolean isSigV4EquivalentAuthScheme(String authScheme);
151
}
152
```
153

154
[Authentication Utilities](./authentication-utilities.md)
155

156
### Smithy Traits
157

158
Annotation traits for describing AWS endpoint behavior and configuration in Smithy models.
159

160
```java { .api }
161
public final class RuleBasedEndpointsTrait extends AnnotationTrait {
162
    public static final ShapeId ID = ShapeId.from("aws.endpoints#rulesBasedEndpoints");
163
}
164

165
public final class StandardRegionalEndpointsTrait extends AnnotationTrait {
166
    public static final ShapeId ID = ShapeId.from("aws.endpoints#standardRegionalEndpoints");
167
}
168

169
public final class EndpointModifierTrait extends AbstractTrait {
170
    public static final ShapeId ID = ShapeId.from("aws.endpoints#endpointModifier");
171
    public EndpointPatternType getPattern();
172
    public List<PartitionSpecialCase> getSpecialCases();
173
}
174
```
175

176
[Smithy Traits](./smithy-traits.md)
177

178
### Validation Components
179

180
Validators for AWS-specific endpoint rules, built-in parameters, and special case configurations.
181

182
```java { .api }
183
public final class RuleSetAwsBuiltInValidator implements Validator {
184
    // Validates AWS built-in parameter usage in rule sets
185
}
186

187
public final class AwsSpecialCaseEndpointValidator implements Validator {
188
    // Validates AWS endpoint special case configurations
189
}
190
```
191

192
[Validation Components](./validation-components.md)