From 6a582a4d9a5fb0dce70252cfbb511d039370e3b2 Mon Sep 17 00:00:00 2001 From: Ryan Date: Wed, 20 May 2009 13:42:26 +0200 Subject: [PATCH] Begin node.http.Client docs --- website/node.html | 135 +++++++++++++++++++++------------------------- 1 file changed, 62 insertions(+), 73 deletions(-) diff --git a/website/node.html b/website/node.html index 2226393ab66..c7464ac1145 100644 --- a/website/node.html +++ b/website/node.html @@ -76,7 +76,6 @@ a:hover { text-decoration: underline; }
    -
  1. Motivation
  2. Benchmarks
  3. Download
  4. Build
    5. @@ -101,7 +100,7 @@ a:hover { text-decoration: underline; }

    Node

    -

    Purely asynchronous I/O for Purely asynchronous I/O for V8 javascript.

    This is an example of a web server written with Node which responds with @@ -116,73 +115,21 @@ a:hover { text-decoration: underline; } }).listen(8000); puts("Server running at http://127.0.0.1:8000/"); -

    Execution does not block on setTimeout() -nor -listen(8000). -In fact, not a single function in Node blocks execution. +

    +Node is an evented sandbox where users cannot execute blocking I/O. +This is +already natural for Javascript programmers, as the DOM is almost entirely +asynchronous and allows for effieceny. The goal is to provide an easy way to create +efficient network applications. -

    Check out the API documentation for more examples. + +

    See the API documentation for more examples.

    Node is free to download, use, and build upon.

    -

    Motivation

    - -

    -I/O is hard and almost no one gets it right. -This is an attempt to make you to do it right by taking away all those -sharp, dangerous tools called threads. - -

    -Node is forced evented programming—so by default you are doing the -right thing. -Well, actually, Javascript -itself is forced evented programming. Node brings Javascript, in the way -it was meant to be, out of the browser. - -

    -There -is a major difference in the latency between memory and disk I/O. It looks -approximately like this: - -

    -l1 cache ~ 3          (CPU cycles)
-l2 cache ~ 14
-     ram ~ 250
-    disk ~ 41000000
- network ~ 240000000
-
    - -

    Disk and network I/O need to be treated differently than simple memory -operations. But POSIX obscures the latency with system calls like - -

    close(file_descriptor);
    - -

    For a TCP file descriptor, this is a round trip message to a remote -computer that can cost billions of CPU cycles. For a hard drive file descriptor, -close() could mean a couple million cycles of disk spinning. -The man pages don't even mention that a call might be preforming very -long I/O operations. This ambiguity in POSIX is propagated into higher APIs. - -

    In the Node API all I/O happens on the event loop and thus requires a -callback of some sort. Calls to access foreign database do not look like -simple side-effect free functions. The programmer does not need advanced -knowledge of POSIX to know that I/O is being performed because it looks -differently. - -

    Some find event programming cumbersome. I find threaded programming -cumbersome—it's not a good abstraction of what is really happening. -Because of this bad abstraction it's confusing and difficult to get right. -Threaded programs only look good in the simpliest and most trivial -situations—in real-life applications events lead to better -architecture. -

    Benchmarks

    @@ -225,14 +172,9 @@ See node.http

    Node provides a web server and client interface. The interface is rather -low-level but complete. (By complete, I mean that it does not limit you from -any of HTTP's features.) The interface abstracts the Transfer-Encoding (i.e. -chuncked or identity), message boundaries, and persistent connections. -Message header and body parsing needs to be done in high-level abstractions. - -

    There are even lower level versions of both the server and client. You -very likely do not need the level of granuality provided by them. There are -no docs for those interfaces. +low-level but complete (it does not limit you from +any of HTTP's features). The interface abstracts the transfer-encoding (i.e. +chunked or identity), message boundaries, and persistent connections.

    node.http.Server

    @@ -281,7 +223,7 @@ class="sh_javascript">request_handler callback. "DELETE".
    req.uri -
    URI object. +
    Request URI. (Object.)
    req.uri.anchor
    req.uri.query
    req.uri.file @@ -294,9 +236,8 @@ class="sh_javascript">request_handler callback.
    req.uri.user
    req.uri.authority
    req.uri.protocol -
    req.uri.source
    req.uri.queryKey -
    req.uri.toString() +
    req.uri.toString(), req.uri.source
    The original URI found in the status line.
    req.headers @@ -377,6 +318,54 @@ res.sendHeader(200, [ ["Content-Length", body.length] +

    node.http.Client

    + +

    An HTTP client is constructed with a server address as its argument, then +the user issues one or more requests. Depending on the server connected to, +the client might pipeline the requests or reestablish the connection after each +connection. (CURRENTLY: The client does not pipeline.) + +

    Example of connecting to google.com +

    +var google = new node.http.Client(80, "google.com");
+var req = google.get("/");
+req.finish(function (res) {
+  puts("STATUS: " + res.status_code);
+  puts("HEADERS: " + JSON.stringify(res.headers));
+  res.setBodyEncoding("utf8");
+  res.onBody = function (chunk) {
+    puts("BODY: " + chunk);
+  };
+});
+
    + +
    +
    new node.http.Client(port, host);
    +
    Constructs a new HTTP client. port and host +refer to the server to be connected to. A connection is not established until a +request is issued. +
    + +
    client.get(path, request_headers);
    +
    client.head(path, request_headers);
    +
    client.post(path, request_headers);
    +
    client.del(path, request_headers);
    +
    client.put(path, request_headers);
    +
    Issues a request. + request_headers is optional. + request_headers should be an array of 2-element arrays. + Additional request headers might be added internally by Node. + Returns a ClientRequest object. + +

    Important: the request is not complete. This method only sends the +header of the request. One needs to call req.finish() to finalize +the request and retrieve the response. (This sounds convoluted but it provides +a chance for the user to stream a body to the server with +req.sendBody. GET and HEAD requests +normally are without bodies but HTTP does not forbid it, so neither do we.) + +

    +

    Modules

    Node has a simple module loading system. In Node, files and modules are