or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

arn-parsing.mdauthentication-utilities.mdaws-built-ins.mdaws-rule-set-extension.mdindex.mdpartition-resolution.mds3-virtual-hosting.mdsmithy-traits.mdvalidation-components.md
tile.json

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

AWS specific components for managing endpoints in Smithy

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/software.amazon.smithy/smithy-aws-endpoints@1.58.x

To install, run

npx @tessl/cli install tessl/maven-software-amazon-smithy--smithy-aws-endpoints@1.58.0

index.mddocs/

Smithy AWS Endpoints

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