0
# HTTP Server Transport
1

2
The HTTP Server Transport provides the REST API interface for Elasticsearch, handling HTTP requests from clients and applications. Built on Netty 4, it supports HTTP/1.1 with features like request pipelining, compression, and efficient resource management.
3

4
## Capabilities
5

6
### Netty4HttpServerTransport Main Implementation
7

8
Core HTTP server implementation extending Elasticsearch's AbstractHttpServerTransport with Netty4-specific HTTP handling.
9

10
```java { .api }
11
/**
12
 * Netty4 implementation of HTTP server transport for REST API access
13
 * Handles HTTP requests, response processing, and client connections
14
 */
15
public class Netty4HttpServerTransport extends AbstractHttpServerTransport {
16
    // HTTP-specific configuration settings
17
    public static Setting<Integer> SETTING_HTTP_NETTY_MAX_COMPOSITE_BUFFER_COMPONENTS;
18
    public static final Setting<Integer> SETTING_HTTP_WORKER_COUNT;
19
    public static final Setting<ByteSizeValue> SETTING_HTTP_NETTY_RECEIVE_PREDICTOR_SIZE;
20
}
21
```
22

23
### HTTP Configuration Settings
24

25
Performance and resource configuration settings for optimal HTTP request handling.
26

27
```java { .api }
28
/**
29
 * Maximum number of components in composite buffers for HTTP responses
30
 * Higher values allow more efficient memory usage for large responses
31
 */
32
public static Setting<Integer> SETTING_HTTP_NETTY_MAX_COMPOSITE_BUFFER_COMPONENTS = new Setting<>(
33
    "http.netty.max_composite_buffer_components",
34
    (s) -> {
35
        // Calculate based on max content length
36
        ByteSizeValue maxContentLength = SETTING_HTTP_MAX_CONTENT_LENGTH.get(s);
37
        return Integer.toString(Math.max((int) (maxContentLength.getBytes() / 1024), 64));
38
    },
39
    (s) -> Setting.parseInt(s, 2, "http.netty.max_composite_buffer_components"),
40
    Property.NodeScope
41
);
42

43
/**
44
 * Number of worker threads for HTTP request processing
45
 * 0 means shared with transport layer, >0 creates dedicated HTTP workers
46
 */
47
public static final Setting<Integer> SETTING_HTTP_WORKER_COUNT = Setting.intSetting(
48
    "http.netty.worker_count", 
49
    0, 
50
    Property.NodeScope
51
);
52

53
/**
54
 * Initial buffer size for HTTP receive buffer prediction
55
 * Netty adaptively adjusts based on actual request sizes
56
 */
57
public static final Setting<ByteSizeValue> SETTING_HTTP_NETTY_RECEIVE_PREDICTOR_SIZE = Setting.byteSizeSetting(
58
    "http.netty.receive_predictor_size",
59
    new ByteSizeValue(64, ByteSizeUnit.KB),
60
    Property.NodeScope
61
);
62
```
63

64
**Configuration Example:**
65

66
```java
67
Settings httpSettings = Settings.builder()
68
    .put("http.netty.worker_count", 0) // Share with transport
69
    .put("http.netty.max_composite_buffer_components", 128)
70
    .put("http.netty.receive_predictor_size", "64kb")
71
    .build();
72
```
73

74
### HTTP Request Processing
75

76
HTTP request representation wrapping Netty HTTP requests with Elasticsearch-specific functionality.
77

78
```java { .api }
79
/**
80
 * Netty4 implementation of HTTP request interface
81
 * Wraps Netty HttpRequest with Elasticsearch-specific methods
82
 */
83
public class Netty4HttpRequest implements HttpRequest {
84
    /**
85
     * Gets HTTP method for this request
86
     * @return REST request method (GET, POST, PUT, DELETE, etc.)
87
     */
88
    RestRequest.Method method();
89
    
90
    /**
91
     * Gets request URI including path and query parameters
92
     * @return Full request URI string
93
     */
94
    String uri();
95
    
96
    /**
97
     * Gets request body content as bytes
98
     * @return BytesReference containing request body
99
     */
100
    BytesReference content();
101
    
102
    /**
103
     * Releases request resources immediately
104
     * Must be called when request processing is complete
105
     */
106
    void release();
107
    
108
    /**
109
     * Creates a copy of request and releases original
110
     * Useful for async processing where original request lifecycle differs
111
     * @return New HttpRequest copy with independent lifecycle
112
     */
113
    HttpRequest releaseAndCopy();
114
    
115
    /**
116
     * Gets all HTTP headers as map
117
     * @return Map of header names to list of values
118
     */
119
    Map<String, List<String>> getHeaders();
120
    
121
    /**
122
     * Gets cookies from request headers
123
     * @return List of cookie strings
124
     */
125
    List<String> strictCookies();
126
    
127
    /**
128
     * Gets HTTP protocol version
129
     * @return HttpVersion (HTTP/1.0, HTTP/1.1, etc.)
130
     */
131
    HttpVersion protocolVersion();
132
    
133
    /**
134
     * Removes specific header from request
135
     * @param header Header name to remove
136
     * @return Modified HttpRequest instance
137
     */
138
    HttpRequest removeHeader(String header);
139
    
140
    /**
141
     * Creates HTTP response for this request
142
     * @param status HTTP status code
143
     * @param contentRef Response body content
144
     * @return Netty4HttpResponse ready to send
145
     */
146
    Netty4HttpResponse createResponse(RestStatus status, BytesReference contentRef);
147
    
148
    /**
149
     * Gets exception from inbound request processing if any
150
     * @return Exception or null if no error
151
     */
152
    Exception getInboundException();
153
    
154
    /**
155
     * Gets underlying Netty HTTP request object
156
     * @return Native Netty HttpRequest for low-level access
157
     */
158
    io.netty.handler.codec.http.HttpRequest getNettyRequest();
159
}
160
```
161

162
**Usage Example:**
163

164
```java
165
// Request received by HTTP transport
166
Netty4HttpRequest request = // from transport pipeline
167

168
// Process request details
169
RestRequest.Method method = request.method(); // GET, POST, etc.
170
String uri = request.uri(); // "/index/_search?q=query"
171
BytesReference body = request.content(); // Request payload
172

173
// Access headers
174
Map<String, List<String>> headers = request.getHeaders();
175
String contentType = headers.get("Content-Type").get(0);
176

177
// Create response
178
Netty4HttpResponse response = request.createResponse(
179
    RestStatus.OK, 
180
    new BytesArray("{\"result\":\"success\"}")
181
);
182

183
// Always release request resources
184
request.release();
185
```
186

187
### HTTP Method Translation
188

189
Static utility methods for converting between Netty and Elasticsearch HTTP method representations.
190

191
```java { .api }
192
/**
193
 * Translates Netty HTTP method to Elasticsearch REST method
194
 * @param httpMethod Netty HttpMethod instance
195
 * @return Corresponding RestRequest.Method
196
 */
197
public static RestRequest.Method translateRequestMethod(HttpMethod httpMethod);
198

199
/**
200
 * Converts Netty HTTP headers to standard Java map format
201
 * @param httpHeaders Netty HttpHeaders instance
202
 * @return Map with header names and values
203
 */
204
public static Map<String, List<String>> getHttpHeadersAsMap(HttpHeaders httpHeaders);
205
```
206

207
### HTTP Response Handling
208

209
HTTP response implementation providing efficient response generation and transmission.
210

211
```java { .api }
212
/**
213
 * Netty4 implementation of HTTP response
214
 * Extends Netty's DefaultFullHttpResponse with Elasticsearch functionality
215
 */
216
public class Netty4HttpResponse extends DefaultFullHttpResponse implements HttpResponse {
217
    // Response creation and content management
218
    // Headers manipulation and status setting
219
    // Resource lifecycle management
220
}
221
```
222

223
### HTTP Channel Management
224

225
HTTP channel implementations for managing client connections and server binding.
226

227
```java { .api }
228
/**
229
 * HTTP channel for client connections
230
 * Handles request/response exchange with individual HTTP clients
231
 */
232
public class Netty4HttpChannel implements HttpChannel {
233
    /**
234
     * Sends HTTP response to client asynchronously
235
     * @param response HTTP response to send
236
     * @param listener Callback for send completion
237
     */
238
    void sendResponse(HttpResponse response, ActionListener<Void> listener);
239
    
240
    /**
241
     * Gets local address for this HTTP connection
242
     * @return Local InetSocketAddress
243
     */
244
    InetSocketAddress getLocalAddress();
245
    
246
    /**
247
     * Gets remote client address for this connection
248
     * @return Remote InetSocketAddress of HTTP client
249
     */
250
    InetSocketAddress getRemoteAddress();
251
    
252
    /**
253
     * Closes HTTP connection to client
254
     */
255
    void close();
256
}
257

258
/**
259
 * HTTP server channel for accepting client connections
260
 * Binds to configured port and accepts HTTP connections
261
 */
262
public class Netty4HttpServerChannel implements HttpServerChannel {
263
    /**
264
     * Gets local socket address server is bound to
265
     * @return Local InetSocketAddress for HTTP server
266
     */
267
    InetSocketAddress getLocalAddress();
268
    
269
    /**
270
     * Adds listener for server channel close events
271
     * @param listener Callback for close notification
272
     */
273
    void addCloseListener(ActionListener<Void> listener);
274
    
275
    /**
276
     * Checks if HTTP server is currently accepting connections
277
     * @return true if server is open, false otherwise
278
     */
279
    boolean isOpen();
280
    
281
    /**
282
     * Closes HTTP server and stops accepting connections
283
     */
284
    void close();
285
}
286
```
287

288
### HTTP Pipeline Management
289

290
Request processing pipeline handlers for HTTP protocol processing.
291

292
```java { .api }
293
/**
294
 * HTTP request pipelining handler supporting concurrent request processing
295
 * Ensures responses are sent in same order as requests even with async processing
296
 */
297
public class Netty4HttpPipeliningHandler extends ChannelDuplexHandler {
298
    // Manages request/response ordering for HTTP pipelining
299
    // Handles concurrent request processing with proper sequencing
300
}
301

302
/**
303
 * HTTP header validation handler
304
 * Validates headers according to HTTP specifications and security policies
305
 */
306
public class Netty4HttpHeaderValidator extends ChannelInboundHandlerAdapter {
307
    // Validates HTTP headers for security and compliance
308
    // Rejects malformed or dangerous header combinations
309
}
310
```
311

312
## HTTP Transport Features
313

314
The HTTP server transport provides comprehensive HTTP/1.1 support:
315

316
**Content Encoding**: Automatic gzip compression for large responses
317

318
**Request Pipelining**: Multiple concurrent requests on single connection
319

320
**Keep-Alive**: Connection reuse for improved performance
321

322
**Content-Type Handling**: JSON, YAML, CBOR, and other content types
323

324
**CORS Support**: Cross-origin resource sharing for web applications
325

326
**Security Headers**: Configurable security headers for enhanced protection
327

328
**Request Size Limits**: Configurable limits to prevent resource exhaustion
329

330
**Timeout Management**: Request and connection timeout handling
331

332
## Integration with Elasticsearch REST Layer
333

334
The HTTP transport integrates deeply with Elasticsearch's REST infrastructure:
335

336
1. **Request Routing**: Dispatches requests to appropriate REST handlers based on URL patterns
337

338
2. **Content Negotiation**: Handles different content types and response formats
339

340
3. **Authentication Integration**: Works with security plugins for request authentication
341

342
4. **Rate Limiting**: Integrates with circuit breakers and throttling mechanisms
343

344
5. **Monitoring Integration**: Provides detailed HTTP metrics and statistics
345

346
6. **Error Handling**: Converts internal exceptions to appropriate HTTP error responses
347

348
The HTTP transport serves as the primary interface for:
349
- Search and query operations
350
- Index management
351
- Cluster administration
352
- Monitoring and statistics
353
- Plugin and extension APIs