0
# Elasticsearch Transport-Netty3 Plugin
1

2
A comprehensive Elasticsearch plugin that provides Netty 3-based transport layer implementation for both TCP and HTTP communications within Elasticsearch clusters. This plugin serves as an alternative to the default Netty 4-based transport, enabling compatibility with systems that specifically require Netty 3 networking framework.
3

4
## Package Information
5

6
- **Package Name**: org.elasticsearch.plugin:transport-netty3-client
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Version**: 5.6.16
10
- **License**: Apache License 2.0
11
- **Installation**: Add as Elasticsearch plugin dependency in your build configuration
12

13
## Core Imports
14

15
```java
16
import org.elasticsearch.transport.Netty3Plugin;
17
import org.elasticsearch.transport.netty3.Netty3Transport;
18
import org.elasticsearch.http.netty3.Netty3HttpServerTransport;
19
```
20

21
## Basic Usage
22

23
```java
24
// Plugin registration (handled automatically by Elasticsearch)
25
// The plugin provides "netty3" transport implementations
26

27
// Configuration in elasticsearch.yml
28
// transport.type: netty3
29
// http.type: netty3
30

31
// Programmatic access to transport instances
32
Settings settings = Settings.builder()
33
    .put("transport.type", "netty3")
34
    .put("http.type", "netty3")
35
    .build();
36

37
// Plugin provides transport factories through NetworkPlugin interface
38
Netty3Plugin plugin = new Netty3Plugin();
39
List<Setting<?>> pluginSettings = plugin.getSettings();
40
```
41

42
## Architecture
43

44
The transport-netty3 plugin is built around several key components:
45

46
- **Plugin Entry Point**: `Netty3Plugin` class implementing Elasticsearch's `NetworkPlugin` interface
47
- **TCP Transport Layer**: `Netty3Transport` providing internal cluster communication via Netty 3
48
- **HTTP Transport Layer**: `Netty3HttpServerTransport` handling REST API requests via Netty 3  
49
- **Configuration System**: Extensive settings for tuning network performance, buffer management, and CORS
50
- **Utility Framework**: Buffer conversion, channel management, and error handling utilities
51
- **CORS Support**: Complete cross-origin resource sharing configuration for web clients
52

53
## Capabilities
54

55
### Plugin Registration
56

57
Main plugin entry point providing transport factories for Elasticsearch's networking layer. This capability registers the plugin with Elasticsearch and exposes available configuration settings.
58

59
```java { .api }
60
public class Netty3Plugin extends Plugin implements NetworkPlugin {
61
    public static final String NETTY_TRANSPORT_NAME = "netty3";
62
    public static final String NETTY_HTTP_TRANSPORT_NAME = "netty3";
63
    
64
    public List<Setting<?>> getSettings();
65
    public Map<String, Supplier<Transport>> getTransports(
66
        Settings settings, ThreadPool threadPool, BigArrays bigArrays,
67
        CircuitBreakerService circuitBreakerService,
68
        NamedWriteableRegistry namedWriteableRegistry, 
69
        NetworkService networkService
70
    );
71
    public Map<String, Supplier<HttpServerTransport>> getHttpTransports(
72
        Settings settings, ThreadPool threadPool, BigArrays bigArrays,
73
        CircuitBreakerService circuitBreakerService,
74
        NamedWriteableRegistry namedWriteableRegistry,
75
        NamedXContentRegistry xContentRegistry,
76
        NetworkService networkService,
77
        HttpServerTransport.Dispatcher dispatcher
78
    );
79
}
80
```
81

82
[Plugin Registration](./plugin-registration.md)
83

84
### TCP Transport
85

86
Core TCP transport implementation for internal Elasticsearch cluster communication. Provides connection management, message handling, and network optimization for node-to-node communication.
87

88
```java { .api }
89
public class Netty3Transport extends TcpTransport<Channel> {
90
    public static final Setting<Integer> WORKER_COUNT;
91
    public static final Setting<ByteSizeValue> NETTY_MAX_CUMULATION_BUFFER_CAPACITY;
92
    public static final Setting<Integer> NETTY_MAX_COMPOSITE_BUFFER_COMPONENTS;
93
    
94
    public Netty3Transport(Settings settings, ThreadPool threadPool, 
95
                          NetworkService networkService, BigArrays bigArrays,
96
                          NamedWriteableRegistry namedWriteableRegistry, 
97
                          CircuitBreakerService circuitBreakerService);
98
    public long serverOpen();
99
    public ChannelPipelineFactory configureClientChannelPipelineFactory();
100
    public ChannelPipelineFactory configureServerChannelPipelineFactory(String name, Settings settings);
101
}
102
```
103

104
[TCP Transport](./tcp-transport.md)
105

106
### HTTP Transport
107

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

110
```java { .api }
111
public class Netty3HttpServerTransport extends AbstractLifecycleComponent 
112
                                       implements HttpServerTransport {
113
    public static final Setting<ByteSizeValue> SETTING_HTTP_NETTY_MAX_CUMULATION_BUFFER_CAPACITY;
114
    public static final Setting<Integer> SETTING_HTTP_WORKER_COUNT;
115
    public static final Setting<Boolean> SETTING_HTTP_TCP_NO_DELAY;
116
    
117
    public Netty3HttpServerTransport(Settings settings, NetworkService networkService,
118
                                   BigArrays bigArrays, ThreadPool threadPool,
119
                                   NamedXContentRegistry xContentRegistry,
120
                                   HttpServerTransport.Dispatcher dispatcher);
121
    public Settings settings();
122
    public BoundTransportAddress boundAddress();
123
    public HttpInfo info();
124
    public HttpStats stats();
125
    public Netty3CorsConfig getCorsConfig();
126
}
127
```
128

129
[HTTP Transport](./http-transport.md)
130

131
### Network Utilities
132

133
Utility functions for buffer management, channel handling, and Netty 3 integration. Provides conversion between Elasticsearch's BytesReference and Netty's ChannelBuffer types.
134

135
```java { .api }
136
public class Netty3Utils {
137
    public static final boolean DEFAULT_GATHERING = true;
138
    
139
    public static void setup();
140
    public static ChannelBuffer toChannelBuffer(BytesReference bytes);
141
    public static BytesReference toBytesReference(ChannelBuffer buffer);
142
    public static BytesReference toBytesReference(ChannelBuffer buffer, int size);
143
    public static void closeChannels(Collection<Channel> channels);
144
    public static void maybeDie(Throwable t);
145
}
146
```
147

148
[Network Utilities](./network-utilities.md)
149

150
### CORS Configuration
151

152
Cross-Origin Resource Sharing support for web-based Elasticsearch clients. Provides comprehensive CORS policy configuration including origins, methods, headers, and credential handling.
153

154
```java { .api }
155
public class Netty3CorsConfig {
156
    public boolean isCorsSupportEnabled();
157
    public boolean isAnyOriginSupported();
158
    public Set<String> origins();
159
    public boolean isOriginAllowed(String origin);
160
    public boolean isCredentialsAllowed();
161
    public long maxAge();
162
    public Set<HttpMethod> allowedRequestMethods();
163
    public Set<String> allowedRequestHeaders();
164
}
165

166
public class Netty3CorsConfigBuilder {
167
    public static Netty3CorsConfigBuilder forAnyOrigin();
168
    public static Netty3CorsConfigBuilder forOrigin(String origin);
169
    public Netty3CorsConfigBuilder allowCredentials();
170
    public Netty3CorsConfigBuilder maxAge(long maxAge);
171
    public Netty3CorsConfig build();
172
}
173
```
174

175
[CORS Configuration](./cors-configuration.md)
176

177
### HTTP Channel and Pipeline
178

179
HTTP request/response processing, pipelining support, and channel lifecycle management for REST API communication.
180

181
```java { .api }
182
public final class Netty3HttpChannel extends AbstractRestChannel {
183
    public Netty3HttpChannel(Netty3HttpServerTransport transport, Netty3HttpRequest request,
184
                           OrderedUpstreamMessageEvent orderedUpstreamMessageEvent,
185
                           boolean detailedErrorsEnabled, ThreadContext threadContext);
186
    public BytesStreamOutput newBytesOutput();
187
    public void sendResponse(RestResponse response);
188
}
189

190
public class Netty3HttpRequest extends RestRequest {
191
    public Netty3HttpRequest(NamedXContentRegistry xContentRegistry, HttpRequest request, Channel channel);
192
    public HttpRequest request();
193
    public Method method();
194
    public String uri();
195
    public boolean hasContent();
196
    public BytesReference content();
197
    public SocketAddress getRemoteAddress();
198
    public SocketAddress getLocalAddress();
199
    public Channel getChannel();
200
}
201

202
public class HttpPipeliningHandler extends SimpleChannelHandler {
203
    public static final int INITIAL_EVENTS_HELD = 3;
204
    public HttpPipeliningHandler(int maxEventsHeld);
205
    public void handleUpstream(ChannelHandlerContext ctx, ChannelEvent e);
206
    public void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e);
207
}
208
```
209

210
[HTTP Channel and Pipeline](./http-channel-pipeline.md)
211

212
## Configuration Settings
213

214
The plugin exposes numerous configuration settings for fine-tuning network performance:
215

216
### TCP Transport Settings
217
- `transport.netty.worker_count` - Number of worker threads (default: 2 * processors)
218
- `transport.netty.max_cumulation_buffer_capacity` - Maximum cumulation buffer capacity
219
- `transport.netty.max_composite_buffer_components` - Maximum composite buffer components
220
- `transport.netty.receive_predictor_size` - Receive buffer size predictor
221
- `transport.netty.boss_count` - Number of boss threads (default: 1)
222

223
### HTTP Transport Settings
224
- `http.netty.worker_count` - HTTP worker thread count
225
- `http.tcp.no_delay` - TCP no delay setting
226
- `http.tcp.keep_alive` - TCP keep alive setting
227
- `http.tcp.send_buffer_size` - TCP send buffer size
228
- `http.tcp.receive_buffer_size` - TCP receive buffer size
229

230
**Note**: This plugin is deprecated in favor of the newer Netty 4 implementation. It maintains backward compatibility for systems requiring Netty 3 specifically.