0
# S3 Virtual Hosting
1
2
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.
3
4
## Capabilities
5
6
### IsVirtualHostableS3Bucket Function
7
8
The core library function for validating S3 bucket names for virtual hosting compatibility.
9
10
```java { .api }
11
/**
12
* An AWS rule-set function for determining whether a given string can be promoted to an S3 virtual bucket host label.
13
*/
14
public final class IsVirtualHostableS3Bucket extends LibraryFunction {
15
/** Function identifier used in endpoint rules */
16
public static final String ID = "aws.isVirtualHostableS3Bucket";
17
18
/**
19
* Gets the function definition for use in the rules engine
20
* @return Function definition instance
21
*/
22
public static Definition getDefinition();
23
24
/**
25
* Creates a virtual hostable S3 bucket function from the given expressions
26
* @param bucketName Expression that evaluates to the bucket name to check
27
* @param allowSubdomains Expression that evaluates to whether to allow subdomains
28
* @return IsVirtualHostableS3Bucket function instance
29
*/
30
public static IsVirtualHostableS3Bucket ofExpressions(ToExpression bucketName, ToExpression allowSubdomains);
31
32
/**
33
* Creates a virtual hostable S3 bucket function from the given expressions
34
* @param bucketName Expression that evaluates to the bucket name to check
35
* @param allowSubdomains Expression that evaluates to whether to allow subdomains
36
* @return IsVirtualHostableS3Bucket function instance
37
*/
38
public static IsVirtualHostableS3Bucket ofExpressions(ToExpression bucketName, ToExpression allowSubdomains);
39
}
40
```
41
42
**Usage Examples:**
43
44
```java
45
import software.amazon.smithy.rulesengine.aws.language.functions.IsVirtualHostableS3Bucket;
46
import software.amazon.smithy.rulesengine.language.syntax.expressions.Expression;
47
48
// Create function to check if bucket supports virtual hosting
49
IsVirtualHostableS3Bucket hostableFunction = IsVirtualHostableS3Bucket.ofExpressions(
50
Expression.of("my-bucket-name"), // bucket name to check
51
Expression.of(true) // allow subdomains
52
);
53
54
// The function evaluates bucket names according to DNS hostname rules
55
// Returns true if the bucket name can be used as a virtual host subdomain
56
```
57
58
## Virtual Hosting Rules
59
60
S3 supports two URL styles for accessing buckets and objects:
61
62
### Path-Style URLs
63
```
64
https://s3.region.amazonaws.com/bucket-name/object-key
65
```
66
67
### Virtual Hosted-Style URLs
68
```
69
https://bucket-name.s3.region.amazonaws.com/object-key
70
```
71
72
### Virtual Hosting Requirements
73
74
For a bucket to support virtual hosted-style URLs, the bucket name must:
75
76
1. **Be DNS-compliant**: Follow DNS hostname naming rules
77
2. **Be 3-63 characters long**: Standard DNS length limits
78
3. **Contain only lowercase letters, numbers, periods, and hyphens**
79
4. **Start and end with a letter or number**: Cannot start/end with hyphen or period
80
5. **Not contain consecutive periods**: No ".." sequences
81
6. **Not be formatted as an IP address**: Not like "192.168.1.1"
82
7. **Not contain uppercase letters**: Must be lowercase only
83
84
### Examples of Virtual Hostable Bucket Names
85
86
```java
87
// Valid virtual hosting bucket names:
88
"my-bucket" // ✓ Simple alphanumeric with hyphens
89
"example.bucket" // ✓ Contains periods (but not consecutive)
90
"test123" // ✓ Alphanumeric only
91
"my-app-logs-2024" // ✓ Descriptive with year
92
93
// Invalid virtual hosting bucket names:
94
"MyBucket" // ✗ Contains uppercase letters
95
"my..bucket" // ✗ Consecutive periods
96
"-my-bucket" // ✗ Starts with hyphen
97
"my-bucket-" // ✗ Ends with hyphen
98
"192.168.1.1" // ✗ Formatted as IP address
99
"ab" // ✗ Too short (less than 3 characters)
100
```
101
102
## Function Usage in Rules
103
104
The `aws.isVirtualHostableS3Bucket` function is used in endpoint rules to determine the appropriate URL style:
105
106
```
107
# Endpoint rule example (conceptual)
108
if aws.isVirtualHostableS3Bucket(bucketName, true):
109
# Use virtual hosted-style URL
110
endpoint = "https://{bucketName}.s3.{region}.amazonaws.com"
111
else:
112
# Use path-style URL
113
endpoint = "https://s3.{region}.amazonaws.com/{bucketName}"
114
```
115
116
## Parameters
117
118
### bucketName (ToExpression)
119
The bucket name to validate for virtual hosting compatibility. Should evaluate to a string containing the S3 bucket name.
120
121
### allowSubdomains (ToExpression)
122
Whether to allow subdomain-style bucket names. Should evaluate to a boolean:
123
- `true`: Allow bucket names that can be used as DNS subdomains
124
- `false`: Apply stricter validation rules
125
126
## Integration with S3 Built-ins
127
128
This function works in conjunction with S3-specific built-in parameters:
129
130
```java
131
// Related S3 built-ins from AwsBuiltIns:
132
AwsBuiltIns.S3_FORCE_PATH_STYLE // Forces path-style URLs
133
AwsBuiltIns.S3_USE_GLOBAL_ENDPOINT // Uses global endpoint for us-east-1
134
AwsBuiltIns.S3_ACCELERATE // Uses S3 Transfer Acceleration
135
```
136
137
### Example Rule Logic
138
139
```java
140
// Conceptual endpoint rule logic:
141
if (S3_FORCE_PATH_STYLE) {
142
// Always use path-style regardless of bucket name
143
usePathStyle = true;
144
} else if (aws.isVirtualHostableS3Bucket(bucketName, true)) {
145
// Bucket supports virtual hosting
146
useVirtualHosting = true;
147
} else {
148
// Fall back to path-style for non-compliant bucket names
149
usePathStyle = true;
150
}
151
```
152
153
## DNS Compatibility
154
155
The function implements DNS hostname validation rules to ensure bucket names can be safely used as DNS subdomain labels. This is critical for:
156
157
- **SSL/TLS Certificate Validation**: Wildcard certificates work with virtual hosting
158
- **DNS Resolution**: Bucket names must resolve as valid hostnames
159
- **CDN Integration**: CloudFront and other CDNs require DNS-compliant names
160
- **Cross-Origin Requests**: CORS policies rely on proper hostname formatting
161
162
## Best Practices
163
164
### Recommended Bucket Naming
165
```java
166
// Recommended patterns for virtual hosting compatibility:
167
"company-app-logs" // Company and purpose
168
"user-uploads-prod" // Environment-specific
169
"backup.2024.january" // Date-based with periods
170
"static-assets-cdn" // CDN-friendly naming
171
```
172
173
### Patterns to Avoid
174
```java
175
// Patterns that break virtual hosting:
176
"Company_App_Logs" // Underscores and uppercase
177
"my--special--bucket" // Consecutive hyphens/periods
178
"bucket.with..dots" // Consecutive periods
179
"10.0.0.1" // IP address format
180
```