lukechilds
/
node
mirror of https://github.com/lukechilds/node.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Remove docs. 

API is changing too quickly for me to keep up with.  I will recreate them as
things start to stablize.
v0.7.4-release
Ryan 16 years ago
parent
e8ce6ef790
commit
0ab4f5c276
2 changed files with 0 additions and 572 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 355
      spec/index.html
  2. 217
      spec/specification.css

355
spec/index.html
View File

@ -1,355 +0,0 @@
<html lang=en-US-x-hixie>
<head>
<title>Node API</title>
<!-- <link href="specification.css" rel=stylesheet>-->
<link href="http://www.whatwg.org/style/specification" 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>&copy; 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>
<ul class=toc>
<li><a href="index.html#http_request"><span class=secno>2.1 </span>Request object</a>
</ul>
<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>
<li><a href="index.html#blocking"><span class=secno>5 </span>Blocking
Functions</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&mdash;there I will try to note the difference.
<p>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).
<h3 id=the-event-loop><span class=secno>1.1 </span>The event loop</h3>
<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.
<h3 id=execution-context><span class=secno>1.2 </span>Execution context</h3>
<p>Global data is shared between callbacks.
<p>
<code>spawn()</code> to start a new context/event loop?
<h2 id=http_server><span class=secno>2 </span>HTTP Server</h2>
<pre class=idl>[Constructor(in String host, in String port, in Function
onrequest)]
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>
<dl>
<dt><code>HTTPServer(host, port, onrequest)</code></dt>
</dl>
<p class="big-issue"> error handling? </p>
<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 Array <a href="index.html#headers">headers</a>;
// ready state
const unsigned short HEADERS_RECEIVED = 0;
const unsigned short LOADING = 1;
const unsigned short DONE = 2;
readonly attribute long readyState;
attribute Function <a href="index.html#onbody">onbody</a>;
void respondHeader (in short status, in Array headers);
void respondBody (in ByteArray data);
};</pre>
<p class="big-issue">issue: client ip address</p>
<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&mdash;this does not affect this interface.
<p> If any error is encountered either with the request or while using the
two response methods the connection to client immediately terminated.
<dl>
<dt><code>respondHeader(status, headers)</code></dt>
<dd>
<p>This method sends the response status line and headers.
This method may only be called once. After the first, calling it
will raise an <code>INVALID_STATE_ERR</code> exception.
<p>The <code>status</code> argument is an integer HTTP status response code as
defined in 6.1 of <a href="#rfc2616">RFC 2616</a>.
<p>The <code>header</code> argument is an <code>Array</code> of
tuples (a two-element <code>Array</code>). For example
<pre>[["Content-Type", "text/plain"], ["Content-Length", 10]]</pre>
<p>This array determines the response headers. If the
<code>header</code> parameter includes elements that are not tuples it
raises <code>SYNTAX_ERR</code>. If the elements of the tuples do not
respond to <code>toString()</code> the method raises
<code>SYNTAX_ERR</code>.
<p>Besides the author response headers interpreters should not
include additional response headers. This ensures that authors
have a reasonably predictable API.
<p>If the client connection was closed for any reason, calling
<code>respondHeader()</code> will raise a <code>NETWORK_ERR</code>
exception.
</dd>
<dt><code>respondBody(data)</code></dt>
<dd>
<p>This method must be called after <code>respondHeader()</code>. If
<code>respondHeader()</code> has not been called it will raise an
<code>INVALID_STATE_ERR</code> exception.
<p>When given a <code>String</code> or <code>ByteArray</code> the
interpreter will send the data.
<p>Given a <code>null</code> argument signals end-of-response.
<p class="note"> The author must call <code>respondBody(null)</code>
for each response, even if the response has no body.</p>
<p>After the end-of-response, calling <code>respondHeader()</code> or
<code>respondBody()</code> will raise an <code>INVALID_STATE_ERR</code> exception.
<p>If the client connection was closed for any reason, calling
<code>respondBody()</code> will raise a <code>NETWORK_ERR</code>
exception.
</dd>
</dl>
<h2 id=tcp_client><span class=secno>3 </span>TCP Client</h2>
<pre class=idl>[Constructor(in String host, in String port)]
interface <dfn id=tcpclient>TCPClient</dfn> {
readonly attribute String <a href="index.html#host">host</a>;
readonly attribute String <a href="index.html#port">port</a>;
// ready state
const unsigned short CONNECTING = 0;
const unsigned short OPEN = 1;
const unsigned short CLOSED = 2;
readonly attribute long readyState;
// networking
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 ByteArray data);
void disconnect();
};</pre>
<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>
<dt><code>write(data)</code></dt>
<dd>
<p>Transmits data using the connection. If the connection is not yet
established or the connection is closed, calling <code>write()</code>
will raise an <code>INVALID_STATE_ERR</code> exception. </p>
<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>
<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>The <dfn id="readystate0"><code>readyState</code></dfn> attribute
represents the state of the connection. When the object is created it must
be set to <code>CONNECTING</code>.
<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.
<p id="onread">When data is received, the <code>onread</code> callback
will be made with a single parameter: a <code>ByteArray</code> 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.
<!-- conf crit for this
statement is in the various protocol-specific sections below. -->
<p id="onclose">When the connection is closed, the <code
>readyState</a></code>
attribute's value must be changed to <code>CLOSED</code>, and the <code
>onclose</a></code> callback
will be made.
<h2 id=timers><span class=secno>4 </span>Timers</h2>
<p>Timers allow one to schedule an event at a later date.
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>
<h2 id=blocking><span class=secno>5 </span>Blocking Functions</h2>
<p>Node includes a number of blocking functions in its API. Some of these
will be removed in the future as the software improves.
<dl>
<dt><code>log(string)</code></dt>
<dd>
<p>This function outputs the string to the stadard output device
(usually the console).
Its speed is dependent on where stdout is piped to.
</dd>
<dt><code>blockingFileRead(filename)</code></dt>
<dd>
<p>This method opens a file from the file system and returns its
contents as a <code>ByteArray</code>. This function can be extremely
expensive depending on the response time of the file system. It should
only be used in start up.
</dd>
</dl>
<h2 class=no-num id=references>References</h2>
<dl>
<dt>[<dfn id=rfc2616>RFC2616</dfn>]
<dd><cite><a href="http://ietf.org/rfc/rfc2616">Hypertext Transfer
Protocol -- HTTP/1.1</a></cite>, R. Fielding, J. Gettys, J. Mogul,
H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, editors. IETF,
June 1999.

217
spec/specification.css
View File

@ -1,217 +0,0 @@
/* WHATWG Green: sRGB #3c790a, rgb(60, 121, 10) */
html { margin: 0; padding: 0; color: black; background: #eeeeee; }
body { margin: 0 0 30%; padding: 0 1em 2em 8.5em; line-height: 1.35; color: black; background: white top left repeat-y; border-bottom: thin solid #3c790a; }
:link { color: #00C; background: transparent }
:visited { color: #609; background: transparent }
:link:active, :visited:active { color: #C00; background: transparent }
:link:hover, :visited:hover { background: #ffa; }
code :link, code :visited { color: inherit; }
body, th, td { font-family: sans-serif; }
h1, h2, h3, h4, h5, h6 { text-align: left }
h1, h2, h3 { color: #3c790a; background: transparent; }
h1 { font: 900 170% sans-serif }
h2 { font: 800 140% sans-serif }
h3 { font: 800 125% sans-serif }
h4 { font: 800 110% sans-serif }
h5 { font: 800 100% sans-serif }
h6 { font: 600 italic 100% sans-serif }
pre { margin-left: 2em; white-space: pre-wrap; }
h2 { margin: 3em 0 1em 0; }
h3 { margin: 2.5em 0 1em 0; }
h4 { margin: 2.5em 0 0.75em 0; }
h5, h6 { margin: 2.5em 0 1em; }
h1 + h2, h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
p { margin: 1em 0; }
hr { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
dl, dd { margin-top: 0; margin-bottom: 0; }
dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
dt + dt { margin-top: 0; }
dd dt { margin-top: 0.25em; margin-bottom: 0; }
dd p { margin-top: 0; }
dd dl + p { margin-top: 1em; }
dd table + p { margin-top: 1em; }
p + * > li, dd li { margin: 1em 0; }
dt, dfn { font-weight: bold; font-style: normal; }
dt dfn { font-style: italic; }
pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
pre em { font-weight: bolder; font-style: normal; }
@media screen { code { color: orangered; } }
var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
table { border-collapse: collapse; border-style: hidden hidden none hidden; }
table thead { border-bottom: solid; }
table tbody th:first-child { border-left: solid; }
table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
ins { background: green; color: white; /* color: green; border: solid thin lime; padding: 0.3em; line-height: 1.6em; */ text-decoration: none; }
del { background: maroon; color: white; /* color: maroon; border: solid thin red; padding: 0.3em; line-height: 1.6em; */ text-decoration: line-through; }
body ins, body del { display: block; }
body * ins, body * del { display: inline; }
/* classes and other specifics */
.toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
img.extra { float: right; }
hr.bookmark { border: dashed 2em black; background: yellow; }
pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; }
pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
pre.css:first-line { color: #AAAA50; }
dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #EEFFEE; }
hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
dl.domintro dd p { margin: 0.5em 0; }
dl.switch { padding-left: 2em; }
dl.switch > dt { text-indent: -1.5em; }
dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
.diff-old { text-decoration: line-through; color: silver; background: transparent; }
.diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
a .diff-new { border-bottom: 1px blue solid; }
h2 { page-break-before: always; }
h1 + h2, hr + h2.no-toc { page-break-before: auto; }
div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
div.head p { margin: 0; }
div.head h1 { margin: 0; }
div.head .logo { float: right; margin: 0 1em; }
div.head .logo img { border: none } /* remove border from top image */
div.head dl { margin: 1em 0; }
p.copyright { font-size: x-small; font-style: oblique; margin: 0; }
body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
body > .toc > li > * { margin-bottom: 0.5em; }
body > .toc > li > * > li > * { margin-bottom: 0.25em; }
.toc, .toc li { list-style: none; }
.brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
.brief li { margin: 0; padding: 0; }
.brief li p { margin: 0; padding: 0; }
[title=WIP], [title=TBW] { background: red; color: yellow; padding: 0.1em 0.3em; border: dotted white; margin: 0 0.7em 0 0.2em; }
[title=SCS] { background: green; color: white; padding: 0.1em 0.3em; border-style: none dashed; margin: 0 0.7em 0 0.2em; }
[title=WIP] :link, [title=WIP] :visited,
[title=TBW] :link, [title=TBW] :visited,
[title=SCS] :link, [title=SCS] :visited { background: transparent; color: inherit; }
.big-issue, .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
.big-issue > :first-child, .XXX > :first-child { margin-top: 0; }
p .big-issue, p .XXX { line-height: 3em; }
.note { color: green; background: transparent; font-family: sans-serif; }
.warning { color: red; background: transparent; }
.note, .warning { font-weight: bolder; font-style: italic; }
p.note, div.note { padding: 0.5em 2em; }
span.note { padding: 0 2em; }
.note p:first-child, .warning p:first-child { margin-top: 0; }
.note p:last-child, .warning p:last-child { margin-bottom: 0; }
.warning:before { font-style: normal; }
.XXX:before, .XXX:after { content: " ** "; position: absolute; left: 0; width: 8em; text-align: right; }
p.note:before { content: 'Note: '; }
p.warning:before { content: '\26A0 Warning! '; }
.applies thead code { display: block; }
.applies td { text-align: center; }
.applies .yes { background: yellow; }
.bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
.bookkeeping { font-size: 0.8em; margin: 2em 0; }
.bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
.critical { margin: 1em; border: double thick red; padding: 1em; background: #FFFFCC; }
.critical > :first-child { margin-top: 0; }
h4 { position: relative; z-index: 3; }
h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
.element { background: #EEFFEE; color: black; margin: 0 0 1em 0.15em; padding: 0 1em 0.25em 0.75em; border-left: solid #99FF99 0.25em; position: relative; z-index: 1; }
.element:before { position: absolute; z-index: 2; top: 0; left: -1.15em; height: 2em; width: 0.9em; background: #EEFFEE; content: ' '; border-style: none none solid solid; border-color: #99FF99; border-width: 0.25em; }
.example {
display: block;
color: #222222;
background: #FCFCFC;
border-left: double;
margin-left: 2em;
padding-left: 1em;
}
.tall-and-narrow {
font-size: 0.6em;
column-width: 25em;
column-gap: 1em;
-moz-column-width: 25em;
-moz-column-gap: 1em;
-webkit-column-width: 25em;
-webkit-column-gap: 1em;
}
.hide { display: none }
body.dfnEnabled dfn { cursor: pointer; }
.dfnPanel {
display: inline;
position: absolute;
height: auto;
width: auto;
padding: 0.5em 0.75em;
font: small sans-serif;
background: #DDDDDD;
color: black;
border: outset 0.2em;
}
.dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
.dfnPanel :link, .dfnPanel :visited { color: black; }
.dfnPanel p { font-weight: bolder; }
.dfnPanel * + p { margin-top: 0.25em; }
.dfnPanel li { list-style-position: inside; }
@media aural {
h1, h2, h3 { stress: 20; richness: 90 }
.hide { speak: none }
p.copyright { volume: x-soft; speech-rate: x-fast }
dt { pause-before: 20% }
code, pre { speak-punctuation: code }
}
@media screen {
body.draft { background-image: url(http://whatwg.org/images/WD); }
body.cfc { background-image: url(http://whatwg.org/images/CFC); }
body.cfi { background-image: url(http://whatwg.org/images/CFI); }
body.spec { background-image: url(http://whatwg.org/images/REC); }
}
@media print {
html { font-size: 10pt; }
@page { margin: 2cm 0.5cm 2cm 0.5cm; }
@page :left {
@bottom-left {
font: 10pt sans-serif;
content: counter(page);
padding-top: 0em;
vertical-align: top;
}
}
@page :right {
@bottom-right {
font: 10pt sans-serif;
content: counter(page);
text-align: right;
vertical-align: top;
padding-top: 0em;
}
}
.toc a::after { content: leader('.') target-counter(attr(href), page); }
a[href^="#"]::after { content: " (page " target-counter(attr(href), page) ")"; }
pre a[href^="#"]::after, blockquote a[href^="#"]::after, var a[href^="#"]::after,
code a[href^="#"]::after, a[href^="#refs"]::after { content: ""; }
table { font-size: smaller; }
:link, :visited { text-decoration: none; color: inherit; background: transparent; }
}
Write Preview
Loading…
Cancel
Save