+++ /dev/null
-
-<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>© 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—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—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.
-
+++ /dev/null
-/* 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; }
-}
projects / platform / upstream / nodejs.git / commitdiff