From 02638103f79c96d60a4676b4ab120900c547c74c Mon Sep 17 00:00:00 2001 From: Ryan Date: Wed, 4 Mar 2009 19:15:39 +0100 Subject: [PATCH] add beginnings of a specification doc --- spec/index.html | 142 +++++++++++++++++++++++++++ spec/specification.css | 217 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 359 insertions(+) create mode 100644 spec/index.html create mode 100644 spec/specification.css diff --git a/spec/index.html b/spec/index.html new file mode 100644 index 0000000000..0d61613de2 --- /dev/null +++ b/spec/index.html @@ -0,0 +1,142 @@ + + + + Node API + + + +
+ + +

Node API

+ +

Draft

+ +
+
This version: + +
http://tinyclouds.org/node + +
+ +

© Copyright 2009 Ryan Dahl

+ +

You are granted a license to use, reproduce and create + derivative works of this document.

+
+ +
+ +

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

+ +

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 I/O (be that network or device). + +

1.1 The event loop

+ +

... + +

1.2 Execution context

+ +

... + +

2 HTTP Server

+ +

3 TCP Client

+ 
interface TCP.Client  {
+  readonly attribute DOMString host;
+  readonly attribute DOMString 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 onrecv;
+           attribute Function onclose;
+  void send(in DOMString data);
+  void disconnect();           
+};
+ +

4 Timers

+ + +

Timers and Intervals 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. +

+ +
diff --git a/spec/specification.css b/spec/specification.css new file mode 100644 index 0000000000..f99f38a305 --- /dev/null +++ b/spec/specification.css @@ -0,0 +1,217 @@ +/* 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(/images/WD); } + body.cfc { background-image: url(/images/CFC); } + body.cfi { background-image: url(/images/CFI); } + body.spec { background-image: url(/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; } +}