Node API

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.

Table of contents

• 1 Introduction
  • 1.1 The event loop
  • 1.2 Execution context
• 2 HTTP Server
• 3 TCP Client
• 4 Timers

1 Introduction

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, all functions can be considered non-blocking. Non-blocking means that program execution will continue without waiting for some 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.

Only one callback is executed at a time.

1.2 Execution context

Global data is shared between callbacks.

spawn() to start a new context/event loop?

2 HTTP Server

3 TCP Client

interface TCPClient  {
  readonly attribute DOMString host;
  readonly attribute DOMString 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 DOMString data);
  void disconnect();           
};

When a TCPClient object is created, the the interpreter must try to establish a connection.

The host attribute is the domain name of the network connection. The port attribute identifies the port.

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.

When the connection is closed, the readyState attribute's value must be changed to CLOSED, and the onclose callback will be made.

The write() method transmits data using the connection. If the connection is not yet established, it must raise an INVALID_STATE_ERR exception.

The disconnect() method must close the connection, if it is open. If the connection is already closed, it must do nothing. Closing the connection causes a onclose callback to be made and the readyState attribute's value to change, as described above.

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.