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

[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 String 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, it must 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 String containing a chunk of data. The user 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.