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

AWS specific components for managing endpoints in Smithy

Overview

Eval results

Files

S3 Virtual Hosting

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

The S3 virtual hosting functionality provides utilities for determining whether S3 bucket names can use virtual hosted-style URLs and validating bucket names for DNS compatibility.

Capabilities

IsVirtualHostableS3Bucket Function

The core library function for validating S3 bucket names for virtual hosting compatibility.

/**
 * An AWS rule-set function for determining whether a given string can be promoted to an S3 virtual bucket host label.
 */
public final class IsVirtualHostableS3Bucket extends LibraryFunction {
    /** Function identifier used in endpoint rules */
    public static final String ID = "aws.isVirtualHostableS3Bucket";
    
    /**
     * Gets the function definition for use in the rules engine
     * @return Function definition instance
     */
    public static Definition getDefinition();
    
    /**
     * Creates a virtual hostable S3 bucket function from the given expressions
     * @param bucketName Expression that evaluates to the bucket name to check
     * @param allowSubdomains Expression that evaluates to whether to allow subdomains
     * @return IsVirtualHostableS3Bucket function instance
     */
    public static IsVirtualHostableS3Bucket ofExpressions(ToExpression bucketName, ToExpression allowSubdomains);
    
    /**
     * Creates a virtual hostable S3 bucket function from the given expressions
     * @param bucketName Expression that evaluates to the bucket name to check  
     * @param allowSubdomains Expression that evaluates to whether to allow subdomains
     * @return IsVirtualHostableS3Bucket function instance
     */
    public static IsVirtualHostableS3Bucket ofExpressions(ToExpression bucketName, ToExpression allowSubdomains);
}

Usage Examples:

import software.amazon.smithy.rulesengine.aws.language.functions.IsVirtualHostableS3Bucket;
import software.amazon.smithy.rulesengine.language.syntax.expressions.Expression;

// Create function to check if bucket supports virtual hosting
IsVirtualHostableS3Bucket hostableFunction = IsVirtualHostableS3Bucket.ofExpressions(
    Expression.of("my-bucket-name"),  // bucket name to check
    Expression.of(true)               // allow subdomains
);

// The function evaluates bucket names according to DNS hostname rules
// Returns true if the bucket name can be used as a virtual host subdomain

Virtual Hosting Rules

S3 supports two URL styles for accessing buckets and objects:

Path-Style URLs

https://s3.region.amazonaws.com/bucket-name/object-key

Virtual Hosted-Style URLs

https://bucket-name.s3.region.amazonaws.com/object-key

Virtual Hosting Requirements

For a bucket to support virtual hosted-style URLs, the bucket name must:

Be DNS-compliant: Follow DNS hostname naming rules
Be 3-63 characters long: Standard DNS length limits
Contain only lowercase letters, numbers, periods, and hyphens
Start and end with a letter or number: Cannot start/end with hyphen or period
Not contain consecutive periods: No ".." sequences
Not be formatted as an IP address: Not like "192.168.1.1"
Not contain uppercase letters: Must be lowercase only

Examples of Virtual Hostable Bucket Names

// Valid virtual hosting bucket names:
"my-bucket"           // ✓ Simple alphanumeric with hyphens
"example.bucket"      // ✓ Contains periods (but not consecutive)
"test123"             // ✓ Alphanumeric only
"my-app-logs-2024"    // ✓ Descriptive with year

// Invalid virtual hosting bucket names:
"MyBucket"            // ✗ Contains uppercase letters
"my..bucket"          // ✗ Consecutive periods
"-my-bucket"          // ✗ Starts with hyphen
"my-bucket-"          // ✗ Ends with hyphen
"192.168.1.1"         // ✗ Formatted as IP address
"ab"                  // ✗ Too short (less than 3 characters)

Function Usage in Rules

The aws.isVirtualHostableS3Bucket function is used in endpoint rules to determine the appropriate URL style:

# Endpoint rule example (conceptual)
if aws.isVirtualHostableS3Bucket(bucketName, true):
  # Use virtual hosted-style URL
  endpoint = "https://{bucketName}.s3.{region}.amazonaws.com"
else:
  # Use path-style URL
  endpoint = "https://s3.{region}.amazonaws.com/{bucketName}"

Parameters

bucketName (ToExpression)

The bucket name to validate for virtual hosting compatibility. Should evaluate to a string containing the S3 bucket name.

allowSubdomains (ToExpression)

Whether to allow subdomain-style bucket names. Should evaluate to a boolean:

true: Allow bucket names that can be used as DNS subdomains
false: Apply stricter validation rules

Integration with S3 Built-ins

This function works in conjunction with S3-specific built-in parameters:

// Related S3 built-ins from AwsBuiltIns:
AwsBuiltIns.S3_FORCE_PATH_STYLE    // Forces path-style URLs
AwsBuiltIns.S3_USE_GLOBAL_ENDPOINT // Uses global endpoint for us-east-1
AwsBuiltIns.S3_ACCELERATE          // Uses S3 Transfer Acceleration

Example Rule Logic

// Conceptual endpoint rule logic:
if (S3_FORCE_PATH_STYLE) {
    // Always use path-style regardless of bucket name
    usePathStyle = true;
} else if (aws.isVirtualHostableS3Bucket(bucketName, true)) {
    // Bucket supports virtual hosting
    useVirtualHosting = true;
} else {
    // Fall back to path-style for non-compliant bucket names
    usePathStyle = true;
}

DNS Compatibility

The function implements DNS hostname validation rules to ensure bucket names can be safely used as DNS subdomain labels. This is critical for:

SSL/TLS Certificate Validation: Wildcard certificates work with virtual hosting
DNS Resolution: Bucket names must resolve as valid hostnames
CDN Integration: CloudFront and other CDNs require DNS-compliant names
Cross-Origin Requests: CORS policies rely on proper hostname formatting

Best Practices

Recommended Bucket Naming

// Recommended patterns for virtual hosting compatibility:
"company-app-logs"        // Company and purpose
"user-uploads-prod"       // Environment-specific  
"backup.2024.january"     // Date-based with periods
"static-assets-cdn"       // CDN-friendly naming

Patterns to Avoid

// Patterns that break virtual hosting:
"Company_App_Logs"        // Underscores and uppercase
"my--special--bucket"     // Consecutive hyphens/periods  
"bucket.with..dots"       // Consecutive periods
"10.0.0.1"               // IP address format

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