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

AWS specific components for managing endpoints in Smithy

Overview

Eval results

Files

Validation Components

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

The validation components provide validators for AWS-specific endpoint rules, built-in parameters, and special case configurations. These validators ensure proper configuration and usage of AWS endpoint features in Smithy models.

Capabilities

AWS Built-in Validator

RuleSetAwsBuiltInValidator

/**
 * Validator for AWS built-in parameters in rule sets.
 * Ensures proper usage of AWS-specific built-in parameters in endpoint rules.
 */
public final class RuleSetAwsBuiltInValidator implements Validator {
    /**
     * Validates AWS built-in parameter usage across the model
     * @param model Smithy model to validate
     * @return Stream of validation events
     */
    public Stream<ValidationEvent> validate(Model model);
    
    /**
     * Gets the validator name
     * @return Validator identifier
     */
    public String getName();
}

Special Case Validator

AwsSpecialCaseEndpointValidator

/**
 * Validator for AWS endpoint special case configurations.
 * Validates special case endpoint configurations for AWS services.
 */
public final class AwsSpecialCaseEndpointValidator implements Validator {
    /**
     * Validates AWS special case endpoint configurations
     * @param model Smithy model to validate
     * @return Stream of validation events
     */
    public Stream<ValidationEvent> validate(Model model);
    
    /**
     * Gets the validator name
     * @return Validator identifier
     */
    public String getName();
}

Migration Utilities

EndpointSigV4Migration

/**
 * Migration utility for SigV4 endpoint configurations.
 * Handles migration of endpoint authentication configurations.
 */
public final class EndpointSigV4Migration implements DiffEvaluator {
    /**
     * Evaluates differences in endpoint SigV4 configurations
     * @param context Diff evaluation context
     * @return List of differences found
     */
    public List<ValidationEvent> evaluate(DiffEvaluator.Context context);
    
    /**
     * Gets the evaluator name
     * @return Evaluator identifier
     */
    public String getName();
}

Usage Examples:

import software.amazon.smithy.rulesengine.aws.validators.*;
import software.amazon.smithy.model.validation.ValidatedResult;
import software.amazon.smithy.model.Model;

// Validate a model with AWS validators
Model model = // ... load your model
ValidatedResult<Model> result = Model.assembler()
    .addValidator(new RuleSetAwsBuiltInValidator())
    .addValidator(new AwsSpecialCaseEndpointValidator())
    .assemble();

// Check for validation errors
if (result.isBroken()) {
    result.getValidationEvents().forEach(event -> {
        System.err.println(event.getSeverity() + ": " + event.getMessage());
    });
}

// Use in diff evaluation for migrations
EndpointSigV4Migration migration = new EndpointSigV4Migration();
// Applied automatically during model diffing

Validation Rules

AWS Built-in Parameter Validation

The RuleSetAwsBuiltInValidator enforces these rules:

Required Parameter Validation

Validates that required AWS built-ins are properly configured
Ensures built-in parameters have correct types and default values
Checks that built-in references match available parameters

Parameter Usage Validation

Validates that service-specific built-ins are only used by appropriate services
Ensures S3 built-ins (S3_*) are only used in S3 endpoint rules
Validates STS built-ins (STS_*) are only used in STS endpoint rules
Checks S3Control built-ins (S3_CONTROL_*) usage

Type Consistency

Ensures boolean built-ins are used as booleans
Validates string built-ins are used as strings
Checks parameter references match declared types

Common Validation Errors

// Example validation events that might be generated:

// Invalid built-in usage
ValidationEvent error1 = ValidationEvent.builder()
    .severity(Severity.ERROR)
    .message("S3-specific built-in 'AWS::S3::Accelerate' cannot be used in non-S3 service")
    .sourceLocation(SourceLocation.none())
    .build();

// Missing required parameter
ValidationEvent error2 = ValidationEvent.builder()
    .severity(Severity.ERROR) 
    .message("Required built-in parameter 'AWS::Region' is not defined")
    .sourceLocation(SourceLocation.none())
    .build();

// Type mismatch
ValidationEvent error3 = ValidationEvent.builder()
    .severity(Severity.ERROR)
    .message("Built-in 'AWS::UseDualStack' expects boolean value, got string")
    .sourceLocation(SourceLocation.none())
    .build();

Special Case Endpoint Validation

The AwsSpecialCaseEndpointValidator enforces these rules:

Partition Validation

Validates that partition names in special cases are valid AWS partitions
Ensures partition-specific configurations are appropriate
Checks partition compatibility with endpoint patterns

Endpoint Template Validation

Validates endpoint template syntax and placeholders
Ensures required template variables are available
Checks endpoint template compatibility with service patterns

Capability Validation

Validates FIPS and dual-stack capability declarations
Ensures capability combinations are supported
Checks capability consistency across partitions

Common Special Case Validation Errors

// Example special case validation events:

// Invalid partition
ValidationEvent error1 = ValidationEvent.builder()  
    .severity(Severity.ERROR)
    .message("Unknown AWS partition 'aws-invalid' in special case configuration")
    .sourceLocation(SourceLocation.none())
    .build();

// Invalid endpoint template
ValidationEvent error2 = ValidationEvent.builder()
    .severity(Severity.ERROR)
    .message("Endpoint template contains undefined variable: {invalid}")
    .sourceLocation(SourceLocation.none())
    .build();

// Inconsistent capabilities
ValidationEvent error3 = ValidationEvent.builder()
    .severity(Severity.WARNING)
    .message("FIPS capability declared but not supported in partition 'aws-cn'")
    .sourceLocation(SourceLocation.none())
    .build();

Service Registration

The validators are automatically registered through the Java Service Provider Interface:

META-INF/services/software.amazon.smithy.model.validation.Validator

Registration includes:

RuleSetAwsBuiltInValidator
AwsSpecialCaseEndpointValidator

The migration utility is registered through:

META-INF/services/software.amazon.smithy.diff.DiffEvaluator

Registration includes:

EndpointSigV4Migration

Integration with Model Assembly

Automatic Validation

// Validators are automatically applied during model assembly
Model model = Model.assembler()
    .discoverModels(getClass().getClassLoader())
    .assemble()
    .unwrap(); // Validators run automatically

// Manual validator application
ValidatedResult<Model> result = Model.assembler()
    .addValidator(new RuleSetAwsBuiltInValidator())
    .addValidator(new AwsSpecialCaseEndpointValidator())
    .discoverModels()
    .assemble();

Custom Validation Context

// Create custom validation context for specific scenarios
ValidationEvent.Builder eventBuilder = ValidationEvent.builder()
    .severity(Severity.ERROR)
    .sourceLocation(shape.getSourceLocation())
    .shapeId(shape.getId());

// Apply context-specific validation rules
if (isAwsService(shape)) {
    // Apply AWS-specific validation
    validator.validateAwsService(shape, eventBuilder);
}

Migration Evaluation

// Evaluate model differences for migrations
ModelDiff diff = ModelDiff.builder()
    .oldModel(oldModel)
    .newModel(newModel)
    .build();

DiffEvaluator.Context context = DiffEvaluator.Context.builder()
    .diff(diff)
    .oldModel(oldModel)
    .newModel(newModel)
    .build();

EndpointSigV4Migration migration = new EndpointSigV4Migration();
List<ValidationEvent> migrationEvents = migration.evaluate(context);

Best Practices

Model Validation Workflow

Early Validation: Run validators during development
Comprehensive Testing: Include validation in CI/CD pipelines
Error Handling: Properly handle and report validation events
Incremental Validation: Validate changes during model evolution

Custom Validator Integration

// Extend validation for custom requirements
public class CustomAwsValidator implements Validator {
    @Override
    public Stream<ValidationEvent> validate(Model model) {
        return model.shapes()
            .filter(this::hasAwsTraits)
            .flatMap(this::validateAwsConfiguration);
    }
    
    private boolean hasAwsTraits(Shape shape) {
        return shape.hasTrait(RuleBasedEndpointsTrait.class) ||
               shape.hasTrait(EndpointModifierTrait.class);
    }
}

Migration Best Practices

// Safe migration patterns
public void performMigration(Model oldModel, Model newModel) {
    // 1. Validate both models
    validateModel(oldModel);
    validateModel(newModel);
    
    // 2. Evaluate migration
    List<ValidationEvent> migrationIssues = evaluateMigration(oldModel, newModel);
    
    // 3. Handle breaking changes
    migrationIssues.stream()
        .filter(event -> event.getSeverity() == Severity.ERROR)
        .forEach(this::handleBreakingChange);
}

Install with Tessl CLI

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

docs

arn-parsing.md

authentication-utilities.md

aws-built-ins.md

aws-rule-set-extension.md

index.md

partition-resolution.md

s3-virtual-hosting.md

smithy-traits.md

validation-components.md

tile.json

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