0
# HTTP Transport
1

2
Complete HTTP server implementation for Elasticsearch's REST API. Handles HTTP requests, response processing, request pipelining, and CORS support for web-based clients using Netty 3.
3

4
## Capabilities
5

6
### Netty3HttpServerTransport Class
7

8
Main HTTP server transport implementation that handles all REST API communication for Elasticsearch.
9

10
```java { .api }
11
/**
12
 * Netty 3-based HTTP server transport for Elasticsearch REST API.
13
 * Supports HTTP request pipelining, CORS, compression, and various TCP optimizations.
14
 */
15
public class Netty3HttpServerTransport extends AbstractLifecycleComponent 
16
                                       implements HttpServerTransport {
17
    
18
    /**
19
     * Constructor for creating a new HTTP server transport instance
20
     * @param settings Elasticsearch configuration settings
21
     * @param networkService Network utility service
22
     * @param bigArrays Memory management for large arrays
23
     * @param threadPool Thread pool for async operations
24
     * @param xContentRegistry Registry for content parsers (JSON, YAML, etc.)
25
     * @param dispatcher HTTP request dispatcher for routing requests
26
     */
27
    public Netty3HttpServerTransport(Settings settings, NetworkService networkService,
28
                                   BigArrays bigArrays, ThreadPool threadPool,
29
                                   NamedXContentRegistry xContentRegistry,
30
                                   HttpServerTransport.Dispatcher dispatcher);
31
    
32
    /**
33
     * Returns the current configuration settings
34
     * @return Settings object with current configuration
35
     */
36
    public Settings settings();
37
    
38
    /**
39
     * Returns the bound transport address information
40
     * @return BoundTransportAddress containing publish and bound addresses
41
     */
42
    public BoundTransportAddress boundAddress();
43
    
44
    /**
45
     * Returns HTTP server information and statistics
46
     * @return HttpInfo object with server details
47
     */
48
    public HttpInfo info();
49
    
50
    /**
51
     * Returns current HTTP server statistics
52
     * @return HttpStats object with request/response metrics
53
     */
54
    public HttpStats stats();
55
    
56
    /**
57
     * Returns the current CORS configuration
58
     * @return Netty3CorsConfig object with CORS policy settings
59
     */
60
    public Netty3CorsConfig getCorsConfig();
61
    
62
    /**
63
     * Configures the server channel pipeline factory
64
     * @return ChannelPipelineFactory for HTTP server channels
65
     */
66
    public ChannelPipelineFactory configureServerChannelPipelineFactory();
67
    
68
    /**
69
     * Resolves the publish port for the HTTP transport
70
     * @param settings Configuration settings
71
     * @param boundAddresses List of bound addresses
72
     * @param publishAddress Address to publish
73
     * @return Resolved port number for publishing
74
     */
75
    public static int resolvePublishPort(Settings settings, 
76
                                       List<InetSocketTransportAddress> boundAddresses,
77
                                       InetAddress publishAddress);
78
}
79
```
80

81
### HTTP Configuration Settings
82

83
Comprehensive settings for HTTP server performance, TCP optimization, and buffer management.
84

85
```java { .api }
86
/**
87
 * Maximum capacity for HTTP cumulation buffers to prevent memory issues
88
 * Default: unlimited (-1)
89
 */
90
public static final Setting<ByteSizeValue> SETTING_HTTP_NETTY_MAX_CUMULATION_BUFFER_CAPACITY =
91
    byteSizeSetting("http.netty.max_cumulation_buffer_capacity", new ByteSizeValue(-1), ...);
92

93
/**
94
 * Maximum number of components in HTTP composite buffers
95
 * Default: -1 (unlimited)
96
 */
97
public static final Setting<Integer> SETTING_HTTP_NETTY_MAX_COMPOSITE_BUFFER_COMPONENTS =
98
    intSetting("http.netty.max_composite_buffer_components", -1, ...);
99

100
/**
101
 * Number of worker threads for handling HTTP I/O operations
102
 * Default: 2 * number of available processors  
103
 */
104
public static final Setting<Integer> SETTING_HTTP_WORKER_COUNT =
105
    intSetting("http.netty.worker_count", ...);
106

107
/**
108
 * TCP no delay setting for HTTP connections
109
 * Default: true (Nagle's algorithm disabled)
110
 */
111
public static final Setting<Boolean> SETTING_HTTP_TCP_NO_DELAY =
112
    boolSetting("http.tcp_no_delay", NetworkService.TcpSettings.TCP_NO_DELAY, ...);
113

114
/**
115
 * TCP keep alive setting for HTTP connections
116
 * Default: true
117
 */
118
public static final Setting<Boolean> SETTING_HTTP_TCP_KEEP_ALIVE =
119
    boolSetting("http.tcp.keep_alive", NetworkService.TcpSettings.TCP_KEEP_ALIVE, ...);
120

121
/**
122
 * Use blocking server implementation (OIO instead of NIO)
123
 * Default: false (use NIO)
124
 */
125
public static final Setting<Boolean> SETTING_HTTP_TCP_BLOCKING_SERVER =
126
    boolSetting("http.tcp.blocking_server", NetworkService.TcpSettings.TCP_BLOCKING_SERVER, ...);
127

128
/**
129
 * TCP socket reuse address setting
130
 * Default: true
131
 */
132
public static final Setting<Boolean> SETTING_HTTP_TCP_REUSE_ADDRESS =
133
    boolSetting("http.tcp.reuse_address", NetworkService.TcpSettings.TCP_REUSE_ADDRESS, ...);
134

135
/**
136
 * TCP send buffer size for HTTP connections
137
 * Default: 0 (use system default)
138
 */
139
public static final Setting<ByteSizeValue> SETTING_HTTP_TCP_SEND_BUFFER_SIZE =
140
    byteSizeSetting("http.tcp.send_buffer_size", NetworkService.TcpSettings.TCP_SEND_BUFFER_SIZE, ...);
141

142
/**
143
 * TCP receive buffer size for HTTP connections
144
 * Default: 0 (use system default)
145
 */
146
public static final Setting<ByteSizeValue> SETTING_HTTP_TCP_RECEIVE_BUFFER_SIZE =
147
    byteSizeSetting("http.tcp.receive_buffer_size", NetworkService.TcpSettings.TCP_RECEIVE_BUFFER_SIZE, ...);
148
```
149

150
**Usage Example:**
151

152
```java
153
import org.elasticsearch.http.netty3.Netty3HttpServerTransport;
154
import org.elasticsearch.common.settings.Settings;
155

156
// Configure HTTP transport with custom settings
157
Settings settings = Settings.builder()
158
    .put("http.netty.worker_count", 8)
159
    .put("http.tcp_no_delay", true)
160
    .put("http.tcp.keep_alive", true)
161
    .put("http.tcp.send_buffer_size", "64kb")
162
    .put("http.tcp.receive_buffer_size", "64kb")
163
    .put("http.netty.max_cumulation_buffer_capacity", "256mb")
164
    .build();
165

166
// Create HTTP transport (typically done by Elasticsearch internally)
167
Netty3HttpServerTransport httpTransport = new Netty3HttpServerTransport(
168
    settings, 
169
    networkService,
170
    bigArrays, 
171
    threadPool,
172
    xContentRegistry, 
173
    dispatcher
174
);
175

176
// Access transport information
177
HttpInfo info = httpTransport.info();
178
HttpStats stats = httpTransport.stats();
179
BoundTransportAddress address = httpTransport.boundAddress();
180
```
181

182
### HTTP Request and Response Handling
183

184
The transport provides classes for handling HTTP requests and responses with full Netty 3 integration.
185

186
```java { .api }
187
/**
188
 * HTTP request wrapper that extends Elasticsearch's RestRequest
189
 */
190
public class Netty3HttpRequest extends RestRequest {
191
    /**
192
     * Constructor for wrapping Netty HTTP requests
193
     * @param xContentRegistry Registry for content parsing
194
     * @param request Netty HTTP request object
195
     * @param channel Netty channel for the request
196
     */
197
    public Netty3HttpRequest(NamedXContentRegistry xContentRegistry, 
198
                           HttpRequest request, Channel channel);
199
    
200
    /**
201
     * Returns the underlying Netty HTTP request
202
     * @return HttpRequest object from Netty
203
     */
204
    public HttpRequest request();
205
    
206
    /**
207
     * Returns the HTTP method for this request
208
     * @return RestRequest.Method (GET, POST, PUT, DELETE, etc.)
209
     */
210
    public RestRequest.Method method();
211
    
212
    /**
213
     * Returns the request URI
214
     * @return String containing the full request URI
215
     */
216
    public String uri();
217
    
218
    /**
219
     * Checks if the request has content body
220
     * @return true if request contains content data
221
     */
222
    public boolean hasContent();
223
    
224
    /**
225
     * Returns the request content as bytes
226
     * @return BytesReference containing request body
227
     */
228
    public BytesReference content();
229
    
230
    /**
231
     * Returns the remote client address
232
     * @return SocketAddress of the client
233
     */
234
    public SocketAddress getRemoteAddress();
235
    
236
    /**
237
     * Returns the local server address
238
     * @return SocketAddress of the server
239
     */
240
    public SocketAddress getLocalAddress();
241
    
242
    /**
243
     * Returns the underlying Netty channel
244
     * @return Channel object for this request
245
     */
246
    public Channel getChannel();
247
}
248
```
249

250
```java { .api }
251
/**
252
 * HTTP response channel for sending responses back to clients
253
 */
254
public class Netty3HttpChannel implements RestChannel {
255
    /**
256
     * Constructor for HTTP response channel
257
     * @param transport Parent HTTP server transport
258
     * @param request Original HTTP request
259
     * @param messageEvent Netty message event
260
     * @param detailedErrorsEnabled Whether to include detailed error info
261
     * @param threadContext Thread context for request handling
262
     */
263
    public Netty3HttpChannel(Netty3HttpServerTransport transport,
264
                           Netty3HttpRequest request,
265
                           OrderedUpstreamMessageEvent messageEvent,
266
                           boolean detailedErrorsEnabled,
267
                           ThreadContext threadContext);
268
    
269
    /**
270
     * Creates a new bytes output stream for response content
271
     * @return BytesStreamOutput for writing response data
272
     */
273
    public BytesStreamOutput newBytesOutput();
274
    
275
    /**
276
     * Sends the HTTP response to the client
277
     * @param response RestResponse containing response data and headers
278
     */
279
    public void sendResponse(RestResponse response);
280
}
281
```
282

283
### HTTP Pipeline Configuration
284

285
The server configures a comprehensive pipeline for handling HTTP requests with support for compression, CORS, pipelining, and custom handlers.
286

287
```java { .api }
288
/**
289
 * Server channel pipeline includes:
290
 * - HTTP request decoder for parsing incoming requests
291
 * - HTTP response encoder for formatting outgoing responses  
292
 * - Content aggregator for handling chunked requests
293
 * - Optional compression/decompression handlers
294
 * - CORS handler for cross-origin requests
295
 * - Pipelining handler for managing multiple concurrent requests
296
 * - Custom request handler for Elasticsearch-specific processing
297
 */
298
public ChannelPipelineFactory configureServerChannelPipelineFactory() {
299
    return new ChannelPipelineFactory() {
300
        @Override
301
        public ChannelPipeline getPipeline() throws Exception {
302
            ChannelPipeline pipeline = Channels.pipeline();
303
            
304
            // Basic HTTP handling
305
            pipeline.addLast("decoder", new HttpRequestDecoder());
306
            pipeline.addLast("encoder", new ESNetty3HttpResponseEncoder());
307
            pipeline.addLast("aggregator", new HttpChunkAggregator(maxContentLength));
308
            
309
            // Optional compression
310
            if (compression) {
311
                pipeline.addLast("decoder_compress", new HttpContentDecompressor());
312
                pipeline.addLast("encoder_compress", new HttpContentCompressor(compressionLevel));
313
            }
314
            
315
            // CORS support
316
            if (corsConfig.isCorsSupportEnabled()) {
317
                pipeline.addLast("cors", new Netty3CorsHandler(corsConfig));
318
            }
319
            
320
            // HTTP pipelining
321
            if (pipelining) {
322
                pipeline.addLast("pipelining", new HttpPipeliningHandler(logger, maxEventsHeld));
323
            }
324
            
325
            // Elasticsearch request handler
326
            pipeline.addLast("handler", requestHandler);
327
            
328
            return pipeline;
329
        }
330
    };
331
}
332
```
333

334
### Performance Features
335

336
The HTTP transport includes several performance optimizations:
337

338
- **Request Pipelining**: Supports HTTP/1.1 pipelining for improved throughput
339
- **Content Compression**: Automatic gzip compression for response payloads
340
- **Buffer Management**: Configurable buffer sizes and memory management
341
- **Connection Pooling**: Efficient connection reuse and management
342
- **CORS Optimization**: Fast CORS preflight handling with caching