0
# HTTP Channel and Pipeline
1

2
HTTP channel management and pipelining functionality for the Netty 3 transport layer. This capability provides comprehensive HTTP request/response processing, pipelining support, and channel lifecycle management.
3

4
## Capabilities
5

6
### HTTP Channel Management
7

8
HTTP channel implementation that bridges Elasticsearch's REST layer with Netty 3's HTTP handling.
9

10
```java { .api }
11
/**
12
 * HTTP channel implementation for handling REST requests and responses
13
 * Extends AbstractRestChannel to provide Netty 3-specific HTTP processing
14
 */
15
public final class Netty3HttpChannel extends AbstractRestChannel {
16
    /**
17
     * Constructor for creating an HTTP channel
18
     * @param transport The parent HTTP server transport
19
     * @param request The HTTP request being processed
20
     * @param orderedUpstreamMessageEvent Optional pipelining event for request ordering
21
     * @param detailedErrorsEnabled Whether to include detailed error information
22
     * @param threadContext Thread context for request processing
23
     */
24
    public Netty3HttpChannel(Netty3HttpServerTransport transport, Netty3HttpRequest request,
25
                           OrderedUpstreamMessageEvent orderedUpstreamMessageEvent,
26
                           boolean detailedErrorsEnabled, ThreadContext threadContext);
27
    
28
    /**
29
     * Creates a new bytes output stream for response content
30
     * @return BytesStreamOutput for writing response data
31
     */
32
    public BytesStreamOutput newBytesOutput();
33
    
34
    /**
35
     * Sends the REST response to the client
36
     * @param response RestResponse containing status, headers, and content
37
     */
38
    public void sendResponse(RestResponse response);
39
}
40
```
41

42
### HTTP Request Processing
43

44
HTTP request wrapper that adapts Netty HTTP requests to Elasticsearch's REST request model.
45

46
```java { .api }
47
/**
48
 * HTTP request implementation that wraps Netty HttpRequest for Elasticsearch processing
49
 * Provides access to request method, URI, headers, content, and connection information
50
 */
51
public class Netty3HttpRequest extends RestRequest {
52
    /**
53
     * Constructor for wrapping a Netty HTTP request
54
     * @param xContentRegistry Registry for parsing request content
55
     * @param request The underlying Netty HTTP request
56
     * @param channel The Netty channel for this request
57
     */
58
    public Netty3HttpRequest(NamedXContentRegistry xContentRegistry, HttpRequest request, Channel channel);
59
    
60
    /**
61
     * Returns the underlying Netty HTTP request
62
     * @return HttpRequest the original Netty request object
63
     */
64
    public HttpRequest request();
65
    
66
    /**
67
     * Returns the HTTP method for this request
68
     * @return Method enum value (GET, POST, PUT, DELETE, etc.)
69
     */
70
    public Method method();
71
    
72
    /**
73
     * Returns the request URI including query parameters
74
     * @return String containing the full request URI
75
     */
76
    public String uri();
77
    
78
    /**
79
     * Checks if the request has content body
80
     * @return boolean true if request contains content
81
     */
82
    public boolean hasContent();
83
    
84
    /**
85
     * Returns the request content as bytes
86
     * @return BytesReference containing the request body
87
     */
88
    public BytesReference content();
89
    
90
    /**
91
     * Returns the remote client address
92
     * @return SocketAddress of the client connection
93
     */
94
    public SocketAddress getRemoteAddress();
95
    
96
    /**
97
     * Returns the local server address
98
     * @return SocketAddress of the server connection
99
     */
100
    public SocketAddress getLocalAddress();
101
    
102
    /**
103
     * Returns the underlying Netty channel
104
     * @return Channel object for direct channel operations
105
     */
106
    public Channel getChannel();
107
}
108
```
109

110
### HTTP Pipelining Support
111

112
HTTP pipelining handler that ensures responses are sent in the same order as requests were received.
113

114
```java { .api }
115
/**
116
 * Implements HTTP pipelining ordering to ensure responses are served
117
 * in the same order as their corresponding requests. This is critical
118
 * for HTTP/1.1 pipelining compliance and performance.
119
 */
120
public class HttpPipeliningHandler extends SimpleChannelHandler {
121
    /**
122
     * Initial number of events held in the pipelining queue
123
     */
124
    public static final int INITIAL_EVENTS_HELD = 3;
125
    
126
    /**
127
     * Constructor for HTTP pipelining handler
128
     * @param maxEventsHeld Maximum number of events to hold before aborting connection
129
     *                      This prevents memory exhaustion from unlimited queueing
130
     */
131
    public HttpPipeliningHandler(int maxEventsHeld);
132
    
133
    /**
134
     * Handles upstream channel events for request ordering
135
     * @param ctx Channel handler context
136
     * @param e Channel event to process
137
     */
138
    public void handleUpstream(ChannelHandlerContext ctx, ChannelEvent e);
139
    
140
    /**
141
     * Handles downstream channel events for response ordering
142
     * @param ctx Channel handler context
143
     * @param e Channel event to process
144
     */
145
    public void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e);
146
}
147
```
148

149
### Pipelining Event Objects
150

151
Event objects used for maintaining request/response ordering in HTTP pipelining.
152

153
```java { .api }
154
/**
155
 * Upstream message event with ordering information for pipelining
156
 */
157
public class OrderedUpstreamMessageEvent {
158
    /**
159
     * Returns the sequence number for this request
160
     * @return int sequence number for ordering
161
     */
162
    public int getSequence();
163
    
164
    /**
165
     * Returns the subsequence number for this request
166
     * @return int subsequence number for fine-grained ordering
167
     */
168
    public int getSubsequence();
169
}
170

171
/**
172
 * Downstream channel event with ordering information for pipelining
173
 */
174
public class OrderedDownstreamChannelEvent {
175
    /**
176
     * Returns the sequence number for this response
177
     * @return int sequence number matching the original request
178
     */
179
    public int getSequence();
180
    
181
    /**
182
     * Returns the subsequence number for this response
183
     * @return int subsequence number for fine-grained ordering
184
     */
185
    public int getSubsequence();
186
    
187
    /**
188
     * Checks if this is the last event in the sequence
189
     * @return boolean true if this completes the response sequence
190
     */
191
    public boolean isLast();
192
}
193
```
194

195
## Usage Examples
196

197
### Basic HTTP Channel Usage
198

199
```java
200
import org.elasticsearch.http.netty3.Netty3HttpChannel;
201
import org.elasticsearch.http.netty3.Netty3HttpRequest;
202
import org.elasticsearch.rest.RestResponse;
203
import org.elasticsearch.rest.RestStatus;
204

205
// HTTP request processing (typically handled internally)
206
Netty3HttpRequest httpRequest = new Netty3HttpRequest(xContentRegistry, nettyRequest, channel);
207
Netty3HttpChannel httpChannel = new Netty3HttpChannel(transport, httpRequest, null, false, threadContext);
208

209
// Create and send response
210
RestResponse response = new RestResponse(RestStatus.OK, "application/json", "{\"status\":\"ok\"}");
211
httpChannel.sendResponse(response);
212
```
213

214
### HTTP Pipelining Configuration
215

216
```java
217
import org.elasticsearch.http.netty3.pipelining.HttpPipeliningHandler;
218

219
// Configure pipelining handler in channel pipeline
220
ChannelPipeline pipeline = Channels.pipeline();
221

222
// Add pipelining handler with maximum 100 held events
223
HttpPipeliningHandler pipeliningHandler = new HttpPipeliningHandler(100);
224
pipeline.addLast("pipelining", pipeliningHandler);
225

226
// Add other HTTP handlers
227
pipeline.addLast("decoder", new HttpRequestDecoder());
228
pipeline.addLast("encoder", new HttpResponseEncoder());
229
pipeline.addLast("handler", new HttpRequestHandler());
230
```
231

232
### Channel Information Access
233

234
```java
235
import org.elasticsearch.http.netty3.Netty3HttpRequest;
236

237
// Access connection information
238
Netty3HttpRequest request = // ... obtained from processing
239
SocketAddress clientAddress = request.getRemoteAddress();
240
SocketAddress serverAddress = request.getLocalAddress();
241
Channel nettyChannel = request.getChannel();
242

243
// Check request properties
244
String method = request.method().name();
245
String uri = request.uri();
246
boolean hasBody = request.hasContent();
247
BytesReference content = request.content();
248

249
System.out.println("Request: " + method + " " + uri + " from " + clientAddress);
250
```
251

252
## Architecture Notes
253

254
### Pipelining Behavior
255

256
The HTTP pipelining handler ensures that:
257

258
1. **Request Order Preservation**: Responses are sent in the exact order requests were received
259
2. **Memory Management**: Limits the number of queued events to prevent memory exhaustion  
260
3. **Connection Integrity**: Aborts connections that exceed the maximum event threshold
261
4. **Performance Optimization**: Allows multiple requests to be processed concurrently while maintaining order
262

263
### Channel Lifecycle
264

265
1. **Request Reception**: Netty receives HTTP request and creates Netty3HttpRequest
266
2. **Channel Creation**: Netty3HttpChannel is created to handle the request/response cycle
267
3. **Processing**: Request is processed by Elasticsearch's REST layer
268
4. **Response Generation**: Response is created and sent via the channel
269
5. **Cleanup**: Channel resources are released after response completion
270

271
### Error Handling
272

273
The HTTP channel implementation includes comprehensive error handling for:
274

275
- **Malformed Requests**: Invalid HTTP syntax or structure
276
- **Content Processing Errors**: Issues with request body parsing
277
- **Response Generation Failures**: Problems creating or sending responses
278
- **Connection Issues**: Network problems or client disconnections
279
- **Resource Exhaustion**: Memory or connection limit scenarios