0
# CORS Configuration
1

2
Cross-Origin Resource Sharing support for web-based Elasticsearch clients. Provides comprehensive CORS policy configuration including origins, methods, headers, and credential handling for secure web application integration.
3

4
## Capabilities
5

6
### Netty3CorsConfig Class
7

8
Immutable configuration object that defines CORS policy settings for the HTTP transport.
9

10
```java { .api }
11
/**
12
 * Immutable configuration for Cross-Origin Resource Sharing (CORS) policies
13
 */
14
public class Netty3CorsConfig {
15
    /**
16
     * Checks if CORS support is enabled
17
     * @return true if CORS processing is enabled
18
     */
19
    public boolean isCorsSupportEnabled();
20
    
21
    /**
22
     * Checks if wildcard origin (*) is supported
23
     * @return true if any origin is allowed
24
     */
25
    public boolean isAnyOriginSupported();
26
    
27
    /**
28
     * Returns the set of allowed origins
29
     * @return Set<String> containing allowed origin URLs
30
     */
31
    public Set<String> origins();
32
    
33
    /**
34
     * Checks if a specific origin is allowed
35
     * @param origin Origin URL to check
36
     * @return true if the origin is allowed
37
     */
38
    public boolean isOriginAllowed(String origin);
39
    
40
    /**
41
     * Checks if null origin is allowed (for file:// requests)
42
     * @return true if null origin is permitted
43
     */
44
    public boolean isNullOriginAllowed();
45
    
46
    /**
47
     * Checks if credentials (cookies, authorization headers) are allowed
48
     * @return true if credentials are permitted in CORS requests
49
     */
50
    public boolean isCredentialsAllowed();
51
    
52
    /**
53
     * Returns the max age for preflight cache
54
     * @return long maximum age in seconds for preflight response caching
55
     */
56
    public long maxAge();
57
    
58
    /**
59
     * Returns the set of allowed HTTP methods
60
     * @return Set<HttpMethod> containing permitted HTTP methods
61
     */
62
    public Set<HttpMethod> allowedRequestMethods();
63
    
64
    /**
65
     * Returns the set of allowed request headers
66
     * @return Set<String> containing permitted request header names
67
     */
68
    public Set<String> allowedRequestHeaders();
69
    
70
    /**
71
     * Returns headers to include in preflight responses
72
     * @return Map<CharSequence, Callable<?>> of preflight response headers
73
     */
74
    public Map<CharSequence, Callable<?>> preflightResponseHeaders();
75
    
76
    /**
77
     * Checks if invalid CORS requests should be short-circuited
78
     * @return true if invalid requests are immediately rejected
79
     */
80
    public boolean isShortCircuit();
81
}
82
```
83

84
### Netty3CorsConfigBuilder Class
85

86
Builder pattern implementation for creating CORS configurations with fluent API.
87

88
```java { .api }
89
/**
90
 * Builder for creating CORS configuration objects with fluent API
91
 */
92
public class Netty3CorsConfigBuilder {
93
    /**
94
     * Creates a builder that allows any origin (wildcard)
95
     * @return Netty3CorsConfigBuilder configured for any origin
96
     */
97
    public static Netty3CorsConfigBuilder forAnyOrigin();
98
    
99
    /**
100
     * Creates a builder for a specific origin
101
     * @param origin Specific origin URL to allow
102
     * @return Netty3CorsConfigBuilder configured for the specific origin
103
     */
104
    public static Netty3CorsConfigBuilder forOrigin(String origin);
105
    
106
    /**
107
     * Creates a builder for regex pattern-based origins
108
     * @param pattern Regex pattern for matching allowed origins
109
     * @return Netty3CorsConfigBuilder configured with pattern matching
110
     */
111
    public static Netty3CorsConfigBuilder forPattern(Pattern pattern);
112
    
113
    /**
114
     * Creates a builder for multiple specific origins
115
     * @param origins Variable arguments of origin URLs to allow
116
     * @return Netty3CorsConfigBuilder configured for the specified origins
117
     */
118
    public static Netty3CorsConfigBuilder forOrigins(String... origins);
119
    
120
    /**
121
     * Disables CORS support entirely
122
     * @return Netty3CorsConfigBuilder with CORS disabled
123
     */
124
    public Netty3CorsConfigBuilder disable();
125
    
126
    /**
127
     * Allows credentials (cookies, authorization headers) in CORS requests
128
     * @return Netty3CorsConfigBuilder with credentials enabled
129
     */
130
    public Netty3CorsConfigBuilder allowCredentials();
131
    
132
    /**
133
     * Sets the maximum age for preflight response caching
134
     * @param maxAge Maximum age in seconds
135
     * @return Netty3CorsConfigBuilder with max age configured
136
     */
137
    public Netty3CorsConfigBuilder maxAge(long maxAge);
138
    
139
    /**
140
     * Sets the allowed HTTP methods for CORS requests
141
     * @param methods Set of HttpMethod objects to allow
142
     * @return Netty3CorsConfigBuilder with allowed methods configured
143
     */
144
    public Netty3CorsConfigBuilder allowedRequestMethods(Set<HttpMethod> methods);
145
    
146
    /**
147
     * Sets the allowed request headers for CORS requests
148
     * @param headers Set of header names to allow
149
     * @return Netty3CorsConfigBuilder with allowed headers configured
150
     */
151
    public Netty3CorsConfigBuilder allowedRequestHeaders(Set<String> headers);
152
    
153
    /**
154
     * Adds a static header to preflight responses
155
     * @param name Header name
156
     * @param values Variable arguments of header values
157
     * @return Netty3CorsConfigBuilder with preflight header added
158
     */
159
    public Netty3CorsConfigBuilder preflightResponseHeader(CharSequence name, Object... values);
160
    
161
    /**
162
     * Adds a header with iterable values to preflight responses
163
     * @param name Header name
164
     * @param values Iterable of header values
165
     * @return Netty3CorsConfigBuilder with preflight header added
166
     */
167
    public <T> Netty3CorsConfigBuilder preflightResponseHeader(CharSequence name, Iterable<T> values);
168
    
169
    /**
170
     * Adds a header with callable value to preflight responses
171
     * @param name Header name
172
     * @param valueGenerator Callable that generates header value
173
     * @return Netty3CorsConfigBuilder with preflight header added
174
     */
175
    public <T> Netty3CorsConfigBuilder preflightResponseHeader(CharSequence name, Callable<T> valueGenerator);
176
    
177
    /**
178
     * Disables preflight response headers
179
     * @return Netty3CorsConfigBuilder with preflight headers disabled
180
     */
181
    public Netty3CorsConfigBuilder noPreflightResponseHeaders();
182
    
183
    /**
184
     * Enables short-circuiting of invalid CORS requests
185
     * @return Netty3CorsConfigBuilder with short-circuiting enabled
186
     */
187
    public Netty3CorsConfigBuilder shortCircuit();
188
    
189
    /**
190
     * Builds the final CORS configuration
191
     * @return Netty3CorsConfig immutable configuration object
192
     */
193
    public Netty3CorsConfig build();
194
}
195
```
196

197
**Usage Examples:**
198

199
```java
200
import org.elasticsearch.http.netty3.cors.Netty3CorsConfigBuilder;
201
import org.elasticsearch.http.netty3.cors.Netty3CorsConfig;
202
import org.jboss.netty.handler.codec.http.HttpMethod;
203

204
// Allow any origin with credentials
205
Netty3CorsConfig corsConfig = Netty3CorsConfigBuilder
206
    .forAnyOrigin()
207
    .allowCredentials()
208
    .maxAge(3600)
209
    .build();
210

211
// Allow specific origins with custom methods and headers
212
Netty3CorsConfig specificConfig = Netty3CorsConfigBuilder
213
    .forOrigins("https://example.com", "https://app.example.com")
214
    .allowedRequestMethods(Set.of(HttpMethod.GET, HttpMethod.POST, HttpMethod.PUT))
215
    .allowedRequestHeaders(Set.of("Authorization", "Content-Type", "X-Custom-Header"))
216
    .preflightResponseHeader("X-Server", "Elasticsearch")
217
    .maxAge(86400)
218
    .build();
219

220
// Disable CORS entirely
221
Netty3CorsConfig disabledConfig = Netty3CorsConfigBuilder
222
    .forAnyOrigin()
223
    .disable()
224
    .build();
225

226
// Use regex pattern for origins
227
Pattern domainPattern = Pattern.compile("https://.*\\.example\\.com");
228
Netty3CorsConfig patternConfig = Netty3CorsConfigBuilder
229
    .forPattern(domainPattern)
230
    .allowCredentials()
231
    .shortCircuit()
232
    .build();
233
```
234

235
### Netty3CorsHandler Class
236

237
Netty channel handler that processes CORS requests according to the configured policy.
238

239
```java { .api }
240
/**
241
 * Netty channel handler for processing CORS requests
242
 */
243
public class Netty3CorsHandler extends SimpleChannelUpstreamHandler {
244
    /**
245
     * Constant for wildcard origin header value
246
     */
247
    public static final String ANY_ORIGIN = "*";
248
    
249
    /**
250
     * Constructor for CORS handler
251
     * @param config CORS configuration to apply
252
     */
253
    public Netty3CorsHandler(Netty3CorsConfig config);
254
    
255
    /**
256
     * Handles upstream channel events and processes CORS headers
257
     * @param ctx Channel handler context
258
     * @param e Channel event to process
259
     */
260
    @Override
261
    public void handleUpstream(ChannelHandlerContext ctx, ChannelEvent e);
262
}
263
```
264

265
### CORS Processing Flow
266

267
The CORS handler processes requests according to the following flow:
268

269
1. **Origin Validation**: Checks if the request origin is allowed according to the configuration
270
2. **Preflight Handling**: Processes OPTIONS requests for CORS preflight validation
271
3. **Header Addition**: Adds appropriate CORS headers to responses
272
4. **Credential Handling**: Manages cookie and authorization header permissions
273
5. **Error Handling**: Short-circuits invalid requests if configured
274

275
### Integration with Elasticsearch Settings
276

277
CORS configuration integrates with Elasticsearch's standard HTTP settings:
278

279
```java
280
// Standard Elasticsearch CORS settings that map to Netty3CorsConfig
281
// http.cors.enabled - Enables/disables CORS support
282
// http.cors.allow-origin - Sets allowed origins (supports patterns)
283
// http.cors.max-age - Sets preflight cache max age
284
// http.cors.allow-methods - Sets allowed HTTP methods
285
// http.cors.allow-headers - Sets allowed request headers
286
// http.cors.allow-credentials - Enables credential support
287
```
288

289
**Configuration Example:**
290

291
```yaml
292
# elasticsearch.yml configuration
293
http.cors.enabled: true
294
http.cors.allow-origin: "https://*.example.com"
295
http.cors.max-age: 86400
296
http.cors.allow-methods: "GET,POST,PUT,DELETE,OPTIONS,HEAD"
297
http.cors.allow-headers: "Authorization,Content-Type,X-Requested-With"
298
http.cors.allow-credentials: true
299
```
300

301
### Security Considerations
302

303
When configuring CORS, consider these security implications:
304

305
- **Origin Validation**: Use specific origins instead of wildcards when possible
306
- **Credential Handling**: Only enable credentials for trusted origins
307
- **Method Restrictions**: Limit allowed methods to those actually needed
308
- **Header Restrictions**: Only allow necessary request headers
309
- **Preflight Caching**: Set appropriate max-age to balance performance and security