Details
-
Improvement
-
Status: Closed
-
Major
-
Resolution: Fixed
-
0.9.2
-
None
-
all
Description
Improve Node Server Library
=======================
Background
----------------
In the last 7 months Node.js has gone from one server constructor:
• createServer()
to seven, adding:
• createSSLServer()
• createMultiplexServer()
• createMultiplexSSLServer()
• createHttpServer()
• createHttpsSSLServer()
• createWebServer()
there are really only two implementations:
• createMultiplexSSLServer()
• createWebServer()
Several of these servers have undocumented options and share options objects with other libraries.
Proposal
-------------
1. Remove all of the create signatures except these three:
o createServer()
o createMultiplexServer()
o createWebServer()
with createServer() implemented by createMultiplexServer(). All signatures will support optional multiplexing and optional SSL/TLS. Eliminate no present functionality and maintain signature compatibility in the three signatures preserved.
2. Document and standardize all server options and parameters with notes describing any deprecated features being preserved for backward compatibility.
Motivation
-------------
The dispersion of create methods makes it harder for developers to know which server to use and leads to diffusion in the way that options and features are provided. This also complicates testing. Reducing the servers to the two currently supported end point transports (TCP and HTTP) will enforce standardization and simplify adoption. Now is the time to address these issues before the new create signatures show up in a released version.
Approach to Options
----------------------------
Presently the non-web server options objects may have transport and protocol properties. Undocumented key and cert properties are used to enable the options object to be passed to the Node.js tls and https createServer() methods. This approach requires Apache Thrift options to be visible to the Node.js library methods and vice versa. A better approach might be to place Node.js tls options in a tlsOptions object which is itself a property of the server options object. This will allow any tlsOptions to be passed through to Node.js without concerns for conflicts on the Node.js or Apache Thrift side, now or in the future. The presence of a tlsOptions object can also be used to enable SSL/TLS in the two server implementations rather than having separate functions.
Would like to know what others think about this.
Given the proposed approach the Node server create signatures would include the following:
var server = thrift.createServer(processor, handler, options);
var server = thrift.createServer(processor, options);
var server = thrift.createServer(options);
var server = thrift.createMultiplexServer(processor, options);
var server = thrift.createMultiplexServer(options);
var server = thrift.createWebServer(options);
The shared ServerOptions accepted by all servers would look something like this (not all properties are used by all servers but no server should redefine the semantics of any existing property):
/**
*
*
* @property {object}
processor - [optional] Thrift service class or processor generated by
* @property {object}
transport - [optional] layered transport to use (defaults to TBufferedTransport)
* at least a key and a cert must be defined on this object to use SSL/TLS
* (see: nodejs.org/api/tls.html for documentation)
* @property {object}
services - [optional] an object hash which maps (service URI strings) -> (ServiceOptions objects)
staticFilePath - [optional] Path to serve static files from, if absent or "" static file service is disabled
* transmitted in response to static file GET requests
* @property {array} corsOrigins - [optional] Array of CORS origin strings to permit requests from.
*/
In the context of the WebServer an additional ServiceOptions object is defined to specify per route service I/O stack details:
/**
* @class
* @name ServiceOptions
* Used to define the I/O stack for a particular service.
*
* @property {object}
handler - [optional] The handler object containing Thrift service methods
* @property {object}
protocol - [optional] protocol to use (defaults to TBinaryProtocol)
transport - [optional] layered transport to use (defaults to TBufferedTransport)
*/