© Copyright 2009 Ryan Dahl
You are granted a license to use, reproduce and create derivative works of this document.
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).
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.
Global data is shared between callbacks.
spawn() to start a new context/event loop?
[Constructor(in String host, in String port)]
interface HTTPServer {
readonly attribute String host;
readonly attribute String port;
// networking
attribute Function onrequest;
void close(); // yet not implemented
};
error handling?
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
[["Content-Type", "text/plain"], ["Content-Length", 10]]
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.
[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.
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.
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.