Permalink
Browse files

Fixes for streams, docs, and convenience methods.

  • Loading branch information...
1 parent f7c0379 commit 897a7ef020cefcb7a36c04a11e286238df8ecdaa @mikeal mikeal committed Feb 11, 2011
Showing with 70 additions and 13 deletions.
  1. +50 −4 README.md
  2. +20 −9 main.js
View
@@ -28,13 +28,12 @@ The first argument is an options object. The only required option is uri, all ot
* `body` - entity body for POST and PUT requests. Must be buffer or string.
* `json` - sets `body` but to JSON representation of value and adds `Content-type: application/json` header.
* `multipart` - (experimental) array of objects which contains their own headers and `body` attribute. Sends `multipart/related` request. See example below.
-* `client` - existing http client object (when undefined a new one will be created and assigned to this property so you can keep around a reference to it if you would like use keep-alive on later request)
* `followRedirect` - follow HTTP 3xx responses as redirects. defaults to true.
* `maxRedirects` - the maximum number of redirects to follow, defaults to 10.
* `onResponse` - If true the callback will be fired on the "response" event instead of "end". If a function it will be called on "response" and not effect the regular semantics of the main callback on "end".
* `encoding` - Encoding to be used on response.setEncoding when buffering the response data.
-* `requestBodyStream` - Stream to read request body chunks from.
-* `responseBodyStream` - Stream to write body chunks to. When set this option will be passed as the last argument to the callback instead of the entire body.
+* `pool` - A hash object containing the agents for these requests. If omitted this request will use the global pool which is set to node's default maxSockets.
+* `pool.maxSockets` - Integer containing the maximum amount of sockets in the pool.
The callback argument gets 3 arguments. The first is an error when applicable (usually from the http.Client option not the http.ClientRequest object). The second in an http.ClientResponse object. The third is the response body buffer.
@@ -72,4 +71,51 @@ Examples:
)
</pre>
-It's also worth noting that the options argument will mutate. When following a redirect the uri values will change. After setting up client options it will set options.client.
+**Notice for 2.0**
+
+You should no longer recycle mutations in the options object. Because node 0.4.0 has an internal pooling mechanism the preferred way of sharing a connection is using agents which request simplifies with it's new pool API. Therefor options.client and some other mutations have been deprecated.
+
+requestBodyStream and responseBodyStream are also deprecated in favor of a more standard pipe interface documented below.
+
+### stream.pipe(request(options)) and request(options).pipe(stream)
+
+Previous versions of request had no return value and only accepted callbacks and streams for pumping in the options object.
+
+Node has solidified it's Stream interface and request 2.0 is now compliant with that interface.
+
+The return value of request() is now a Request object, which is a valid stream.
+
+As a writable stream it accepts the body of an HTTP request. As a readable stream it emits the data events for the response.
+
+<pre>
+ var r = request(
+ { url: "http://mysite.com/image.png"
+ , method: 'PUT'
+ , headers: {'content-type': 'image/png'}
+ }
+ )
+ fs.createReadStream('image.png').pipe(r)
+ r.pipe(fs.createWriteStream('pushlog.txt'))
+</pre>
+
+# Convenience methods
+
+## request.defaults(options)
+
+This method returns a wrapper around the normal request API that defaults to whatever options you pass in to it.
+
+## request.put
+
+Same as request() but defaults to <pre>method: "PUT"</pre>.
+
+## request.post
+
+Same as request() but defaults to <pre>method: "POST"</pre>.
+
+## request.head
+
+Same as request() but defaults to <pre>method: "HEAD"</pre>.
+
+## request.get
+
+Alias to normal request method for uniformity.
View
29 main.js
@@ -221,6 +221,7 @@ Request.prototype.request = function () {
options.req.on('error', clientErrorHandler);
this.once('pipe', function (src) {
+ if (options.ntick) throw new Error("You cannot pipe to this stream after the first nextTick() after creation of the request stream.")
options.src = src;
})
@@ -234,6 +235,7 @@ Request.prototype.request = function () {
} else if (!options.src) {
options.req.end();
}
+ options.ntick = true;
})
}
@@ -242,8 +244,17 @@ Request.prototype.write = function (chunk) {
this.req.write(chunk);
}
Request.prototype.end = function () {
+ if (!this.req) throw new Error("This request has been piped before http.request() was called.");
this.req.end();
}
+Request.prototype.pause = function () {
+ if (!this.req) throw new Error("This request has been piped before http.request() was called.");
+ this.req.pause();
+}
+Request.prototype.resume = function () {
+ if (!this.req) throw new Error("This request has been piped before http.request() was called.");
+ this.req.resume();
+}
@@ -278,22 +289,22 @@ request.defaults = function (options) {
request.get = request;
request.post = function (options, callback) {
options.method = 'POST';
- if (!options.body && !options.requestBodyStream && !options.json && !options.multipart) {
- console.error("HTTP POST requests need a body or requestBodyStream");
- }
- request(options, callback);
+ // if (!options.body && !options.requestBodyStream && !options.json && !options.multipart) {
+ // console.error("HTTP POST requests need a body or requestBodyStream");
+ // }
+ return request(options, callback);
};
request.put = function (options, callback) {
options.method = 'PUT';
- if (!options.body && !options.requestBodyStream && !options.json && !options.multipart) {
- console.error("HTTP PUT requests need a body or requestBodyStream");
- }
- request(options, callback);
+ // if (!options.body && !options.requestBodyStream && !options.json && !options.multipart) {
+ // console.error("HTTP PUT requests need a body or requestBodyStream");
+ // }
+ return request(options, callback);
};
request.head = function (options, callback) {
options.method = 'HEAD';
if (options.body || options.requestBodyStream || options.json || options.multipart) {
throw new Error("HTTP HEAD requests MUST NOT include a request body.");
}
- request(options, callback);
+ return request(options, callback);
};

0 comments on commit 897a7ef

Please sign in to comment.