ARN Parsing

/**
 * An AWS rule-set function for parsing an AWS ARN into its component parts.
 */
public final class ParseArn extends LibraryFunction {
    /** Function identifier used in endpoint rules */
    public static final String ID = "aws.parseArn";
    
    /** Result field identifiers */
    public static final Identifier PARTITION = Identifier.of("partition");
    public static final Identifier SERVICE = Identifier.of("service");
    public static final Identifier REGION = Identifier.of("region");
    public static final Identifier ACCOUNT_ID = Identifier.of("accountId");
    
    /**
     * Gets the function definition for use in the rules engine
     * @return Function definition instance
     */
    public static Definition getDefinition();
    
    /**
     * Creates a parse ARN function from the given ARN expression
     * @param arn Expression that evaluates to an ARN string
     * @return ParseArn function instance
     */
    public static ParseArn ofExpressions(ToExpression arn);
}

/**
 * An AWS ARN representation with component access and builder support.
 */
public final class AwsArn implements ToSmithyBuilder<AwsArn> {
    /**
     * Parses and returns the ARN components if the provided value is a valid AWS ARN
     * @param arn The ARN string to parse
     * @return Optional containing the parsed ARN, or empty if invalid
     */
    public static Optional<AwsArn> parse(String arn);
    
    /**
     * Gets the partition component of the ARN
     * @return Partition name (e.g., "aws", "aws-us-gov", "aws-cn")
     */
    public String getPartition();
    
    /**
     * Gets the service component of the ARN
     * @return Service name (e.g., "s3", "ec2", "iam")
     */
    public String getService();
    
    /**
     * Gets the region component of the ARN
     * @return Region name (e.g., "us-east-1", or empty string for global services)
     */
    public String getRegion();
    
    /**
     * Gets the account ID component of the ARN
     * @return AWS account ID (12-digit string, or empty for some resource types)
     */
    public String getAccountId();
    
    /**
     * Gets the resource component parts of the ARN
     * @return List of resource path components
     */
    public List<String> getResource();
    
    /**
     * Creates a builder for modifying the ARN
     * @return Builder instance
     */
    public Builder toBuilder();
    
    /**
     * Returns the full ARN string representation
     * @return Complete ARN string
     */
    public String toString();
}

/**
 * Builder for constructing AwsArn instances
 */
public static final class Builder implements SmithyBuilder<AwsArn> {
    /**
     * Sets the partition component
     * @param partition Partition name
     * @return This builder
     */
    public Builder partition(String partition);
    
    /**
     * Sets the service component
     * @param service Service name
     * @return This builder
     */
    public Builder service(String service);
    
    /**
     * Sets the region component
     * @param region Region name
     * @return This builder
     */
    public Builder region(String region);
    
    /**
     * Sets the account ID component
     * @param accountId Account ID
     * @return This builder
     */
    public Builder accountId(String accountId);
    
    /**
     * Sets the resource components
     * @param resource Resource path components
     * @return This builder
     */
    public Builder resource(List<String> resource);
    
    /**
     * Adds a resource component
     * @param resourcePart Resource path component to add
     * @return This builder
     */
    public Builder addResource(String resourcePart);
    
    /**
     * Builds the AwsArn instance
     * @return Constructed AwsArn
     */
    public AwsArn build();
}

import software.amazon.smithy.rulesengine.aws.language.functions.AwsArn;
import software.amazon.smithy.rulesengine.aws.language.functions.ParseArn;

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

if (parsedArn.isPresent()) {
    AwsArn arn = parsedArn.get();
    
    // Extract components
    String partition = arn.getPartition();   // "aws"
    String service = arn.getService();       // "s3"
    String region = arn.getRegion();         // "us-east-1"
    String accountId = arn.getAccountId();   // "123456789012"
    List<String> resource = arn.getResource(); // ["bucket", "my-bucket"]
    
    // Get full ARN string
    String fullArn = arn.toString();
}

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

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

// Build an ARN using the builder
AwsArn customArn = AwsArn.builder()
    .partition("aws")
    .service("ec2")
    .region("us-west-2")
    .accountId("123456789012")
    .addResource("instance")
    .addResource("i-1234567890abcdef0")
    .build();

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

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

arn:partition:service:region:account-id:resource-type/resource-id

// S3 bucket
"arn:aws:s3:::my-bucket"

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

// IAM role
"arn:aws:iam::123456789012:role/MyRole"

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

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

// DynamoDB table
"arn:aws:dynamodb:us-east-1:123456789012:table/MyTable"

Optional<AwsArn> result = AwsArn.parse("invalid-arn");
if (result.isEmpty()) {
    // Handle invalid ARN
    System.out.println("Invalid ARN format");
}

# Endpoint rule example (conceptual)
aws.parseArn("arn:aws:s3:us-east-1:123456789012:bucket/my-bucket") -> {
  partition: "aws",
  service: "s3", 
  region: "us-east-1",
  accountId: "123456789012",
  resourceId: ["bucket", "my-bucket"]
}