tessl/maven-software-amazon-smithy--smithy-aws-endpoints

AWS specific components for managing endpoints in Smithy

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Smithy AWS Endpoints

Name: tessl/maven-software-amazon-smithy--smithy-aws-endpoints
Author: tessl

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.

Package Information

Package Name: software.amazon.smithy:smithy-aws-endpoints
Package Type: maven
Language: Java
Installation: Add to your build.gradle.kts:
```
dependencies {
    implementation("software.amazon.smithy:smithy-aws-endpoints:1.58.0")
}
```

Core Imports

import software.amazon.smithy.rulesengine.aws.language.functions.AwsRuleSetExtension;
import software.amazon.smithy.rulesengine.aws.language.functions.AwsPartition;
import software.amazon.smithy.rulesengine.aws.language.functions.ParseArn;
import software.amazon.smithy.rulesengine.aws.language.functions.IsVirtualHostableS3Bucket;
import software.amazon.smithy.rulesengine.aws.language.functions.EndpointAuthUtils;
import software.amazon.smithy.rulesengine.aws.traits.*;

Basic Usage

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

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

// Parse an AWS ARN to extract components
Optional<AwsArn> parsedArn = AwsArn.parse("arn:aws:s3:us-east-1:123456789012:bucket/my-bucket");
if (parsedArn.isPresent()) {
    AwsArn arn = parsedArn.get();
    String partition = arn.getPartition();  // "aws"
    String service = arn.getService();      // "s3"
    String region = arn.getRegion();        // "us-east-1"
    String accountId = arn.getAccountId();  // "123456789012"
}

Architecture

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

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

Capabilities

AWS Rule Set Extension

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

public final class AwsRuleSetExtension implements EndpointRuleSetExtension {
    public List<Parameter> getBuiltIns();
    public List<FunctionDefinition> getLibraryFunctions();
    public List<AuthSchemeValidator> getAuthSchemeValidators();
}

AWS Rule Set Extension

AWS Built-in Parameters

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

public final class AwsBuiltIns {
    public static final Parameter REGION;
    public static final Parameter DUALSTACK;
    public static final Parameter FIPS;
    public static final Parameter ACCOUNT_ID;
    // ... additional parameters
}

AWS Built-in Parameters

Partition Resolution

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

public final class AwsPartition extends LibraryFunction {
    public static final String ID = "aws.partition";
    public static Definition getDefinition();
    public static AwsPartition ofExpressions(ToExpression region);
}

Partition Resolution

ARN Parsing and Utilities

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

public final class ParseArn extends LibraryFunction {
    public static final String ID = "aws.parseArn";
    public static Definition getDefinition();
    public static ParseArn ofExpressions(ToExpression arn);
}

public final class AwsArn implements ToSmithyBuilder<AwsArn> {
    public static Optional<AwsArn> parse(String arn);
    public String getPartition();
    public String getService();
    public String getRegion();
    public String getAccountId();
    public List<String> getResource();
}

ARN Parsing

S3 Virtual Hosting

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

public final class IsVirtualHostableS3Bucket extends LibraryFunction {
    public static final String ID = "aws.isVirtualHostableS3Bucket";
    public static Definition getDefinition();
    public static IsVirtualHostableS3Bucket ofExpressions(ToExpression bucket, ToExpression allowSubdomains);
}

S3 Virtual Hosting

Authentication Utilities

Helper methods for constructing AWS authentication schemes in endpoint rules.

public final class EndpointAuthUtils {
    public static Endpoint.Builder sigv4(Endpoint.Builder builder, Literal signingRegion, Literal signingService);
    public static Endpoint.Builder sigv4a(Endpoint.Builder builder, List<Literal> signingRegionSet, Literal signingService);
    public static boolean isSigV4EquivalentAuthScheme(String authScheme);
}

Authentication Utilities

Smithy Traits

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

public final class RuleBasedEndpointsTrait extends AnnotationTrait {
    public static final ShapeId ID = ShapeId.from("aws.endpoints#rulesBasedEndpoints");
}

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

public final class EndpointModifierTrait extends AbstractTrait {
    public static final ShapeId ID = ShapeId.from("aws.endpoints#endpointModifier");
    public EndpointPatternType getPattern();
    public List<PartitionSpecialCase> getSpecialCases();
}

Smithy Traits

Validation Components

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

public final class RuleSetAwsBuiltInValidator implements Validator {
    // Validates AWS built-in parameter usage in rule sets
}

public final class AwsSpecialCaseEndpointValidator implements Validator {
    // Validates AWS endpoint special case configurations
}

Validation Components