You are granted a license to use, reproduce and create
- derivative works of this document.
-
-
-
-
-
Abstract
-
-
This specification defines a javascript API for creating
- servers and clients based around an event loop. It is provided to document
- Node's interface and provide a specification for similar efforts.
-
-
This specification defines an API for creating evented servers and
- clients in javascript. It can be considered documentation for the Node
- project and will be versioned with that software. However, in places the
- API is only a specification and does not reflect Node's
- behavior—there I will try to note the difference.
-
-
Unless otherwise noted, a function is non-blocking. Non-blocking means
- that program execution will continue without waiting for an I/O event
- (be that network or device).
-
-
-
1.1 The event loop
-
-
The program is run event loop. There are no concurrent
- operations. As long as there are pending events the program will continue
- running. If however there arn't any pending callbacks waiting for
- something to happen, the program will exit.
-
-
1.2 Execution context
-
-
Global data is shared between callbacks.
-
-
- spawn() to start a new context/event loop?
-
-
2 HTTP Server
-
[Constructor(in String host, in String port, in Function
- onrequest)]
-interface HTTPServer {
- readonly attribute String host;
- readonly attribute String port;
-
- // networking
- attribute Function onrequest;
- void close(); // yet not implemented
-};
-
-
-
HTTPServer(host, port, onrequest)
-
-
-
error handling?
-
-
-
2.1 Request object
-
interface HTTPRequest {
- readonly attribute String path;
- readonly attribute String uri;
- readonly attribute String query_string;
- readonly attribute String fragment;
- readonly attribute String method;
- readonly attribute String http_version;
- readonly attribute Array headers;
-
- // ready state
- const unsigned short HEADERS_RECEIVED = 0;
- const unsigned short LOADING = 1;
- const unsigned short DONE = 2;
- readonly attribute long readyState;
-
- attribute Function onbody;
-
- void respondHeader (in short status, in Array headers);
- void respondBody (in ByteArray data);
-};
-
-
issue: client ip address
-
-
A request object is what is passed to HTTPServer.onrequest.
- it represents a single HTTP request. Clients might preform HTTP
- pipelining (Keep-Alive) and send multiple requests per TCP
- connection—this does not affect this interface.
-
-
If any error is encountered either with the request or while using the
- two response methods the connection to client immediately terminated.
-
-
-
respondHeader(status, headers)
-
-
This method sends the response status line and headers.
- This method may only be called once. After the first, calling it
- will raise an INVALID_STATE_ERR exception.
-
-
The status argument is an integer HTTP status response code as
- defined in 6.1 of RFC 2616.
-
-
The header argument is an Array of
- tuples (a two-element Array). For example
-
-
This array determines the response headers. If the
- header parameter includes elements that are not tuples it
- raises SYNTAX_ERR. If the elements of the tuples do not
- respond to toString() the method raises
- SYNTAX_ERR.
-
-
Besides the author response headers interpreters should not
- include additional response headers. This ensures that authors
- have a reasonably predictable API.
-
-
If the client connection was closed for any reason, calling
- respondHeader() will raise a NETWORK_ERR
- exception.
-
-
-
respondBody(data)
-
-
This method must be called after respondHeader(). If
- respondHeader() has not been called it will raise an
- INVALID_STATE_ERR exception.
-
-
When given a String or ByteArray the
- interpreter will send the data.
-
-
Given a null argument signals end-of-response.
-
-
The author must call respondBody(null)
- for each response, even if the response has no body.
-
-
After the end-of-response, calling respondHeader() or
- respondBody() will raise an INVALID_STATE_ERR exception.
-
-
If the client connection was closed for any reason, calling
- respondBody() will raise a NETWORK_ERR
- exception.
-
-
-
-
-
-
-
3 TCP Client
-
[Constructor(in String host, in String port)]
-interface TCPClient {
- readonly attribute String host;
- readonly attribute String port;
-
- // ready state
- const unsigned short CONNECTING = 0;
- const unsigned short OPEN = 1;
- const unsigned short CLOSED = 2;
- readonly attribute long readyState;
-
- // networking
- attribute Function onopen;
- attribute Function onread;
- attribute Function onclose;
- void write(in ByteArray data);
- void disconnect();
-};
-
-
-
TCPClient(host, port)
-
-
When a TCPClient object is
- created, the the interpreter must try to establish a connection.
- If the host parameter is not an IP address it
- will be looked up using the DNS.
-
-
-
write(data)
-
-
Transmits data using the connection. If the connection is not yet
- established or the connection is closed, calling write()
- will raise an INVALID_STATE_ERR exception.
-
-
write(null) sends an EOF to the peer. Further writing
- is disabled. However the onread callback may still
- be executed.
-
-
-
disconnect()
-
-
Closes the connection, if it is open. If the connection is already
- closed, it does nothing. Closing the connection causes a
- onclose callback to be made and the
- readyState attribute's value to
- change to CLOSED.
- Note that a connection might not be closed instantaniously. In the
- case of secure connection some "goodbye" transmission might be sent.
-
-
-
-
The readyState attribute
- represents the state of the connection. When the object is created it must
- be set to CONNECTING.
-
-
Once a connection is established, the
- readyState attribute's value must be changed to
- OPEN, and the onopen callback will be made.
-
-
When data is received, the onread callback
- will be made with a single parameter: a ByteArray containing a
- chunk of data. The author does not have the ability to control how much data
- is received nor the ability to stop the input besides disconnecting.
-
-
-
-
When the connection is closed, the readyState
-attribute's value must be changed to CLOSED, and the onclose callback
-will be made.
-
-
-
4 Timers
-
-
-
Timers allow one to schedule an event at a later date.
- There are four globally exposed functions
- setTimeout,
- clearTimeout,
- setInterval, and
- clearInterval.
- These functions work similarly
- as in the browser except that
- the timerID and intervalID do not necessarily have
- type long but are rather opaque objects.
-
-
-
setTimeout(function, milliseconds)
-
-
This method calls the function once after a specified number of
- milliseconds elapses, until canceled by a call to clearTimeout.
- The methods returns a timerID which may be used in a
- subsequent call to clearTimeout to cancel the callback.
-
-
-
-
setInterval(function, milliseconds)
-
-
This method calls the function every time a specified number of
- milliseconds elapses, until canceled by a call to clearInterval.
- The methods returns a intervalID which may be used in a
- subsequent call to clearInterval to cancel the interval.
-
-
-
clearTimeout(timerID)
-
-
Cancels a timeout that was set with the setTimeout
- method.
-
-
-
-
clearInterval(intervalID)
-
-
Cancels an interval that was set with the setInterval method.
-
-
-
-
-
5 Blocking Functions
-
-
Node includes a number of blocking functions in its API. Some of these
- will be removed in the future as the software improves.
-
-
-
log(string)
-
-
This function outputs the string to the stadard output device
- (usually the console).
- Its speed is dependent on where stdout is piped to.
-
-
-
-
blockingFileRead(filename)
-
-
This method opens a file from the file system and returns its
- contents as a ByteArray. This function can be extremely
- expensive depending on the response time of the file system. It should
- only be used in start up.
-