2009-03-04 19:15:39 +01:00
|
|
|
|
|
|
|
|
<html lang=en-US-x-hixie>
|
|
|
|
|
<head>
|
|
|
|
|
<title>Node API</title>
|
|
|
|
|
<link href="specification.css" rel=stylesheet>
|
|
|
|
|
|
|
|
|
|
<body class=draft>
|
|
|
|
|
<div class=head>
|
|
|
|
|
<!--
|
|
|
|
|
<p><a class=logo href="http://www.whatwg.org/" rel=home><img alt=WHATWG
|
|
|
|
|
src="../../../images/logo"></a></p>
|
|
|
|
|
-->
|
|
|
|
|
|
|
|
|
|
<h1>Node API</h1>
|
|
|
|
|
|
|
|
|
|
<h2 class="no-num no-toc"
|
|
|
|
|
id=draft-recommendation-mdash-date-01-jan-1>Draft</h2>
|
|
|
|
|
|
|
|
|
|
<dl>
|
|
|
|
|
<dt>This version:
|
|
|
|
|
|
|
|
|
|
<dd><a href="index.html">http://tinyclouds.org/node</a>
|
|
|
|
|
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
<p class=copyright>© Copyright 2009 Ryan Dahl</p>
|
|
|
|
|
|
|
|
|
|
<p class=copyright>You are granted a license to use, reproduce and create
|
|
|
|
|
derivative works of this document.</p>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
|
|
|
|
|
<h2 class="no-num no-toc" id=abstract>Abstract</h2>
|
|
|
|
|
|
|
|
|
|
<p>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.
|
|
|
|
|
|
|
|
|
|
<h2 class="no-num no-toc" id=contents>Table of contents</h2>
|
|
|
|
|
<!--begin-toc-->
|
|
|
|
|
|
|
|
|
|
<ul class=toc>
|
|
|
|
|
<li><a href="index.html#introduction"><span class=secno>1 </span>Introduction</a>
|
|
|
|
|
<ul class=toc>
|
|
|
|
|
<li><a href="index.html#the-event-loop"><span class=secno>1.1 </span>The event loop</a>
|
|
|
|
|
<li><a href="index.html#execution-context"><span class=secno>1.2 </span>Execution context</a>
|
|
|
|
|
</ul>
|
|
|
|
|
<li><a href="index.html#http_server"><span class=secno>2 </span>HTTP Server</a>
|
2009-03-05 14:45:11 +01:00
|
|
|
<ul class=toc>
|
|
|
|
|
<li><a href="index.html#http_request"><span class=secno>2.1 </span>Request object</a>
|
|
|
|
|
</ul>
|
2009-03-04 19:15:39 +01:00
|
|
|
<li><a href="index.html#tcp_client"><span class=secno>3 </span>TCP Client</a>
|
|
|
|
|
<li><a href="index.html#timers"><span class=secno>4 </span>Timers</a>
|
|
|
|
|
</ul>
|
|
|
|
|
<!--end-toc-->
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
|
|
|
|
|
<h2 id=introduction><span class=secno>1 </span>Introduction</h2>
|
|
|
|
|
|
|
|
|
|
<p>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.
|
|
|
|
|
|
|
|
|
|
<p>Unless otherwise noted, all functions can be considered
|
|
|
|
|
non-blocking. Non-blocking means that program execution will continue
|
2009-03-05 13:41:10 +01:00
|
|
|
without waiting for some I/O event (be that network or device).
|
|
|
|
|
|
|
|
|
|
|
2009-03-04 19:15:39 +01:00
|
|
|
|
|
|
|
|
<h3 id=the-event-loop><span class=secno>1.1 </span>The event loop</h3>
|
|
|
|
|
|
2009-03-05 13:41:10 +01:00
|
|
|
<p>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.
|
|
|
|
|
|
|
|
|
|
<p>Only one callback is executed at a time.
|
|
|
|
|
|
2009-03-04 19:15:39 +01:00
|
|
|
|
|
|
|
|
<h3 id=execution-context><span class=secno>1.2 </span>Execution context</h3>
|
2009-03-05 13:41:10 +01:00
|
|
|
|
|
|
|
|
<p>Global data is shared between callbacks.
|
2009-03-04 19:15:39 +01:00
|
|
|
|
2009-03-05 13:41:10 +01:00
|
|
|
<p>
|
|
|
|
|
<code>spawn()</code> to start a new context/event loop?
|
2009-03-04 19:15:39 +01:00
|
|
|
|
|
|
|
|
<h2 id=http_server><span class=secno>2 </span>HTTP Server</h2>
|
2009-03-05 14:35:54 +01:00
|
|
|
<pre class=idl>[Constructor(in String host, in String port)]
|
|
|
|
|
interface <dfn id=httpserver>HTTPServer</dfn> {
|
|
|
|
|
readonly attribute String <a href="index.html#host">host</a>;
|
|
|
|
|
readonly attribute String <a href="index.html#port">port</a>;
|
|
|
|
|
|
|
|
|
|
// networking
|
|
|
|
|
attribute Function <a href="index.html#onrequest">onRequest</a>;
|
|
|
|
|
void close(); // yet not implemented
|
|
|
|
|
};</pre>
|
2009-03-04 19:15:39 +01:00
|
|
|
|
2009-03-05 14:45:11 +01:00
|
|
|
<h3 id=http_request><span class=secno>2.1 </span>Request object</h3>
|
|
|
|
|
<pre class=idl>interface <dfn id=httprequest>HTTPRequest</dfn> {
|
|
|
|
|
readonly attribute String <a href="index.html#path">path</a>;
|
|
|
|
|
readonly attribute String <a href="index.html#uri">uri</a>;
|
|
|
|
|
readonly attribute String <a href="index.html#query_string">query_string</a>;
|
|
|
|
|
readonly attribute String <a href="index.html#fragment">fragment</a>;
|
|
|
|
|
readonly attribute String <a href="index.html#method">method</a>;
|
|
|
|
|
readonly attribute String <a href="index.html#http_version">http_version</a>;
|
|
|
|
|
|
|
|
|
|
readonly attribute Object <a href="index.html#headers">headers</a>;
|
|
|
|
|
|
|
|
|
|
attribute Function <a href="index.html#onBody">onBody</a>;
|
|
|
|
|
|
|
|
|
|
void respond(in String data);
|
|
|
|
|
};</pre>
|
|
|
|
|
|
|
|
|
|
<p> A request object is what is passed to <code>HTTPServer.onRequest</code>.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
2009-03-04 19:15:39 +01:00
|
|
|
<h2 id=tcp_client><span class=secno>3 </span>TCP Client</h2>
|
2009-03-05 14:22:09 +01:00
|
|
|
<pre class=idl>[Constructor(in String host, in String port)]
|
2009-03-05 14:35:54 +01:00
|
|
|
interface <dfn id=tcpclient>TCPClient</dfn> {
|
2009-03-05 14:22:09 +01:00
|
|
|
readonly attribute String <a href="index.html#host">host</a>;
|
|
|
|
|
readonly attribute String <a href="index.html#port">port</a>;
|
2009-03-04 19:15:39 +01:00
|
|
|
|
|
|
|
|
// ready state
|
|
|
|
|
const unsigned short CONNECTING = 0;
|
|
|
|
|
const unsigned short OPEN = 1;
|
|
|
|
|
const unsigned short CLOSED = 2;
|
|
|
|
|
readonly attribute long readyState;
|
|
|
|
|
|
|
|
|
|
// networking
|
2009-03-05 14:22:09 +01:00
|
|
|
attribute Function <a href="index.html#onopen">onopen</a>;
|
|
|
|
|
attribute Function <a href="index.html#onread">onread</a>;
|
|
|
|
|
attribute Function <a href="index.html#onclose">onclose</a>;
|
|
|
|
|
void write(in String data);
|
2009-03-04 19:15:39 +01:00
|
|
|
void disconnect();
|
|
|
|
|
};</pre>
|
|
|
|
|
|
2009-03-05 14:22:09 +01:00
|
|
|
<dl>
|
|
|
|
|
<dt><code>TCPClient(host, port)</code></dt>
|
|
|
|
|
<dd>
|
|
|
|
|
<p>When a <code><a href="#connection0">TCPClient</a></code> object is
|
|
|
|
|
created, the the interpreter must try to establish a connection.
|
|
|
|
|
If the <code>host</code> parameter is not an IP address it
|
|
|
|
|
will be looked up using the DNS.
|
|
|
|
|
</dd>
|
2009-03-05 13:41:10 +01:00
|
|
|
|
2009-03-05 14:22:09 +01:00
|
|
|
<dt><code>write(data)</code></dt>
|
|
|
|
|
<dd>
|
|
|
|
|
<p>Transmits data using the connection. If the connection is not yet
|
|
|
|
|
established, it must raise an <code>INVALID_STATE_ERR</code> exception.
|
2009-03-05 13:41:10 +01:00
|
|
|
|
2009-03-05 14:22:09 +01:00
|
|
|
<p><code>write(null)</code> sends an EOF to the peer. Further writing
|
|
|
|
|
is disabled. However the <code>onread</code> callback may still
|
|
|
|
|
be executed.
|
|
|
|
|
</dd>
|
2009-03-05 13:41:10 +01:00
|
|
|
|
2009-03-05 14:22:09 +01:00
|
|
|
<dt><code>disconnect()</code></dt>
|
|
|
|
|
<dd>
|
|
|
|
|
<p>Closes the connection, if it is open. If the connection is already
|
|
|
|
|
closed, it does nothing. Closing the connection causes a
|
|
|
|
|
<code>onclose</code> callback to be made and the
|
|
|
|
|
<code><a href="#readystate0">readyState</a></code> attribute's value to
|
|
|
|
|
change to <code>CLOSED</code>.
|
|
|
|
|
Note that a connection might not be closed instantaniously. In the
|
|
|
|
|
case of secure connection some "goodbye" transmission might be sent.
|
|
|
|
|
</dd>
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
</p><p>The <dfn id="readystate0"><code>readyState</code></dfn> attribute
|
2009-03-05 13:41:10 +01:00
|
|
|
represents the state of the connection. When the object is created it must
|
|
|
|
|
be set to <code>CONNECTING</code>.
|
|
|
|
|
|
2009-03-05 14:22:09 +01:00
|
|
|
<p id="onopen">Once a connection is established, the <code
|
|
|
|
|
>readyState</a></code>
|
|
|
|
|
attribute's value must be changed to <code>OPEN</code>, and the
|
|
|
|
|
<code>onopen</code> callback will be made.
|
2009-03-05 13:41:10 +01:00
|
|
|
|
2009-03-05 14:22:09 +01:00
|
|
|
<p id="onread">When data is received, the <code>onread</code> callback
|
|
|
|
|
will be made with a single parameter: a <code>String</code> 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.
|
2009-03-05 13:41:10 +01:00
|
|
|
|
|
|
|
|
<!-- conf crit for this
|
|
|
|
|
statement is in the various protocol-specific sections below. -->
|
|
|
|
|
|
2009-03-05 14:22:09 +01:00
|
|
|
<p id="onclose">When the connection is closed, the <code
|
|
|
|
|
>readyState</a></code>
|
2009-03-05 13:41:10 +01:00
|
|
|
attribute's value must be changed to <code>CLOSED</code>, and the <code
|
2009-03-05 14:22:09 +01:00
|
|
|
>onclose</a></code> callback
|
2009-03-05 13:41:10 +01:00
|
|
|
will be made.
|
|
|
|
|
|
|
|
|
|
|
2009-03-04 19:15:39 +01:00
|
|
|
<h2 id=timers><span class=secno>4 </span>Timers</h2>
|
|
|
|
|
|
|
|
|
|
|
2009-03-05 13:41:10 +01:00
|
|
|
<p>Timers allow one to schedule an event at a later date.
|
2009-03-04 19:15:39 +01:00
|
|
|
There are four globally exposed functions
|
|
|
|
|
<code>setTimeout</code>,
|
|
|
|
|
<code>clearTimeout</code>,
|
|
|
|
|
<code>setInterval</code>, and
|
|
|
|
|
<code>clearInterval</code>.
|
|
|
|
|
These functions work similarly
|
|
|
|
|
<a href="http://www.w3.org/TR/Window/#window-timers">as in the browser</a> except that
|
|
|
|
|
the <code>timerID</code> and <code>intervalID</code> do not necessarily have
|
|
|
|
|
type <code>long</code> but are rather opaque objects.
|
|
|
|
|
|
|
|
|
|
<dl>
|
|
|
|
|
<dt><code>setTimeout(function, milliseconds)</code></dt>
|
|
|
|
|
<dd>
|
|
|
|
|
<p>This method calls the function once after a specified number of
|
|
|
|
|
milliseconds elapses, until canceled by a call to <code>clearTimeout</code>.
|
|
|
|
|
The methods returns a <code>timerID</code> which may be used in a
|
|
|
|
|
subsequent call to <code>clearTimeout</code> to cancel the callback.
|
|
|
|
|
</dd>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<dt><code>setInterval(function, milliseconds)</code></dt>
|
|
|
|
|
<dd>
|
|
|
|
|
<p>This method calls the function every time a specified number of
|
|
|
|
|
milliseconds elapses, until canceled by a call to <code>clearInterval</code>.
|
|
|
|
|
The methods returns a <code>intervalID</code> which may be used in a
|
|
|
|
|
subsequent call to <code>clearInterval</code> to cancel the interval.
|
|
|
|
|
</dd>
|
|
|
|
|
|
|
|
|
|
<dt><code>clearTimeout(timerID)</code></dt>
|
|
|
|
|
<dd>
|
|
|
|
|
<p>Cancels a timeout that was set with the <code>setTimeout</code>
|
|
|
|
|
method.
|
|
|
|
|
</dd>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<dt><code>clearInterval(intervalID)</code></dt>
|
|
|
|
|
<dd>
|
|
|
|
|
<p>Cancels an interval that was set with the <code>setInterval</code> method.
|
|
|
|
|
</dd>
|
|
|
|
|
|
|
|
|
|
</dl>
|
