0
# ARN Parsing
1

2
The ARN parsing functionality provides utilities for parsing AWS ARNs (Amazon Resource Names) into their component parts and working with ARN data structures. This is essential for resource identification and endpoint resolution based on ARN information.
3

4
## Capabilities
5

6
### ParseArn Function
7

8
The core library function for parsing AWS ARNs in endpoint rules.
9

10
```java { .api }
11
/**
12
 * An AWS rule-set function for parsing an AWS ARN into its component parts.
13
 */
14
public final class ParseArn extends LibraryFunction {
15
    /** Function identifier used in endpoint rules */
16
    public static final String ID = "aws.parseArn";
17
    
18
    /** Result field identifiers */
19
    public static final Identifier PARTITION = Identifier.of("partition");
20
    public static final Identifier SERVICE = Identifier.of("service");
21
    public static final Identifier REGION = Identifier.of("region");
22
    public static final Identifier ACCOUNT_ID = Identifier.of("accountId");
23
    
24
    /**
25
     * Gets the function definition for use in the rules engine
26
     * @return Function definition instance
27
     */
28
    public static Definition getDefinition();
29
    
30
    /**
31
     * Creates a parse ARN function from the given ARN expression
32
     * @param arn Expression that evaluates to an ARN string
33
     * @return ParseArn function instance
34
     */
35
    public static ParseArn ofExpressions(ToExpression arn);
36
}
37
```
38

39
### AwsArn Class
40

41
A utility class for parsing and working with AWS ARNs outside of the rules engine context.
42

43
```java { .api }
44
/**
45
 * An AWS ARN representation with component access and builder support.
46
 */
47
public final class AwsArn implements ToSmithyBuilder<AwsArn> {
48
    /**
49
     * Parses and returns the ARN components if the provided value is a valid AWS ARN
50
     * @param arn The ARN string to parse
51
     * @return Optional containing the parsed ARN, or empty if invalid
52
     */
53
    public static Optional<AwsArn> parse(String arn);
54
    
55
    /**
56
     * Gets the partition component of the ARN
57
     * @return Partition name (e.g., "aws", "aws-us-gov", "aws-cn")
58
     */
59
    public String getPartition();
60
    
61
    /**
62
     * Gets the service component of the ARN
63
     * @return Service name (e.g., "s3", "ec2", "iam")
64
     */
65
    public String getService();
66
    
67
    /**
68
     * Gets the region component of the ARN
69
     * @return Region name (e.g., "us-east-1", or empty string for global services)
70
     */
71
    public String getRegion();
72
    
73
    /**
74
     * Gets the account ID component of the ARN
75
     * @return AWS account ID (12-digit string, or empty for some resource types)
76
     */
77
    public String getAccountId();
78
    
79
    /**
80
     * Gets the resource component parts of the ARN
81
     * @return List of resource path components
82
     */
83
    public List<String> getResource();
84
    
85
    /**
86
     * Creates a builder for modifying the ARN
87
     * @return Builder instance
88
     */
89
    public Builder toBuilder();
90
    
91
    /**
92
     * Returns the full ARN string representation
93
     * @return Complete ARN string
94
     */
95
    public String toString();
96
}
97
```
98

99
### AwsArn Builder
100

101
Builder pattern for constructing ARN instances.
102

103
```java { .api }
104
/**
105
 * Builder for constructing AwsArn instances
106
 */
107
public static final class Builder implements SmithyBuilder<AwsArn> {
108
    /**
109
     * Sets the partition component
110
     * @param partition Partition name
111
     * @return This builder
112
     */
113
    public Builder partition(String partition);
114
    
115
    /**
116
     * Sets the service component
117
     * @param service Service name
118
     * @return This builder
119
     */
120
    public Builder service(String service);
121
    
122
    /**
123
     * Sets the region component
124
     * @param region Region name
125
     * @return This builder
126
     */
127
    public Builder region(String region);
128
    
129
    /**
130
     * Sets the account ID component
131
     * @param accountId Account ID
132
     * @return This builder
133
     */
134
    public Builder accountId(String accountId);
135
    
136
    /**
137
     * Sets the resource components
138
     * @param resource Resource path components
139
     * @return This builder
140
     */
141
    public Builder resource(List<String> resource);
142
    
143
    /**
144
     * Adds a resource component
145
     * @param resourcePart Resource path component to add
146
     * @return This builder
147
     */
148
    public Builder addResource(String resourcePart);
149
    
150
    /**
151
     * Builds the AwsArn instance
152
     * @return Constructed AwsArn
153
     */
154
    public AwsArn build();
155
}
156
```
157

158
**Usage Examples:**
159

160
```java
161
import software.amazon.smithy.rulesengine.aws.language.functions.AwsArn;
162
import software.amazon.smithy.rulesengine.aws.language.functions.ParseArn;
163

164
// Parse an S3 bucket ARN
165
String s3BucketArn = "arn:aws:s3:us-east-1:123456789012:bucket/my-bucket";
166
Optional<AwsArn> parsedArn = AwsArn.parse(s3BucketArn);
167

168
if (parsedArn.isPresent()) {
169
    AwsArn arn = parsedArn.get();
170
    
171
    // Extract components
172
    String partition = arn.getPartition();   // "aws"
173
    String service = arn.getService();       // "s3"
174
    String region = arn.getRegion();         // "us-east-1"
175
    String accountId = arn.getAccountId();   // "123456789012"
176
    List<String> resource = arn.getResource(); // ["bucket", "my-bucket"]
177
    
178
    // Get full ARN string
179
    String fullArn = arn.toString();
180
}
181

182
// Parse an IAM role ARN (global service)
183
String iamRoleArn = "arn:aws:iam::123456789012:role/MyRole";
184
Optional<AwsArn> iamArn = AwsArn.parse(iamRoleArn);
185

186
if (iamArn.isPresent()) {
187
    AwsArn arn = iamArn.get();
188
    
189
    String partition = arn.getPartition();   // "aws"
190
    String service = arn.getService();       // "iam"
191
    String region = arn.getRegion();         // "" (empty for global)
192
    String accountId = arn.getAccountId();   // "123456789012"
193
    List<String> resource = arn.getResource(); // ["role", "MyRole"]
194
}
195

196
// Build an ARN using the builder
197
AwsArn customArn = AwsArn.builder()
198
    .partition("aws")
199
    .service("ec2")
200
    .region("us-west-2")
201
    .accountId("123456789012")
202
    .addResource("instance")
203
    .addResource("i-1234567890abcdef0")
204
    .build();
205

206
String arnString = customArn.toString();
207
// "arn:aws:ec2:us-west-2:123456789012:instance/i-1234567890abcdef0"
208

209
// Using ParseArn function in rules (conceptual)
210
ParseArn parseFunction = ParseArn.ofExpressions(
211
    Expression.of("arn:aws:s3:us-east-1:123456789012:bucket/my-bucket")
212
);
213
```
214

215
## ARN Format
216

217
AWS ARNs follow a standardized format:
218
```
219
arn:partition:service:region:account-id:resource-type/resource-id
220
```
221

222
### Components:
223

224
1. **arn**: Always "arn" (literal prefix)
225
2. **partition**: AWS partition ("aws", "aws-us-gov", "aws-cn")
226
3. **service**: AWS service ("s3", "ec2", "iam", etc.)
227
4. **region**: AWS region (empty for global services like IAM)
228
5. **account-id**: 12-digit AWS account ID (empty for some resources)
229
6. **resource**: Service-specific resource identifier (can have multiple parts)
230

231
### Common ARN Examples:
232

233
```java
234
// S3 bucket
235
"arn:aws:s3:::my-bucket"
236

237
// S3 object  
238
"arn:aws:s3:::my-bucket/path/to/object"
239

240
// IAM role
241
"arn:aws:iam::123456789012:role/MyRole"
242

243
// EC2 instance
244
"arn:aws:ec2:us-east-1:123456789012:instance/i-1234567890abcdef0"
245

246
// Lambda function
247
"arn:aws:lambda:us-east-1:123456789012:function:MyFunction"
248

249
// DynamoDB table
250
"arn:aws:dynamodb:us-east-1:123456789012:table/MyTable"
251
```
252

253
## Error Handling
254

255
The `AwsArn.parse()` method returns an `Optional<AwsArn>` which will be empty if:
256

257
- The ARN doesn't start with "arn:"
258
- The ARN doesn't have exactly 6 colon-separated parts
259
- Required components (partition, service) are empty
260
- The ARN format is otherwise malformed
261

262
```java
263
Optional<AwsArn> result = AwsArn.parse("invalid-arn");
264
if (result.isEmpty()) {
265
    // Handle invalid ARN
266
    System.out.println("Invalid ARN format");
267
}
268
```
269

270
## Function Usage in Rules
271

272
The `aws.parseArn` function is used in endpoint rules to extract ARN components for endpoint resolution:
273

274
```
275
# Endpoint rule example (conceptual)
276
aws.parseArn("arn:aws:s3:us-east-1:123456789012:bucket/my-bucket") -> {
277
  partition: "aws",
278
  service: "s3", 
279
  region: "us-east-1",
280
  accountId: "123456789012",
281
  resourceId: ["bucket", "my-bucket"]
282
}
283
```
284

285
This enables endpoint rules to make decisions based on the specific resource being accessed.