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
  • 2.1 Request object
• 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

[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
};

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 Object headers;

    attribute Function onBody;

  void respond(in String data);
};

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.

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.