q-http

Q promise based HTTP client and server interface

npm install q-http
2 downloads in the last day
155 downloads in the last week
1 307 downloads in the last month
Provides a Q promise API for HTTP requests and responses.  This should
resemble JSGI and its hypothetical inverse, but I haven't pored
through the specification to ensure this.

The API
-------

-   ``Server(app)``
    -   accepts an application, returns a server.
    -   calls the application function when requests are received.
        -   if the application returns a response object, sends that
            response.
    -   ``listen(port)``
        -   accepts a port number.
        -   returns a promise for undefined when the server has begun
            listening.
    -   ``stop()``
        -   returns a promise for undefined when the server has stopped.
-   ``request(request)``
    -   accepts a request or a URL string.
    -   returns a promise for a response.
-   ``read(request)``
    -   accepts a request or a URL string.
    -   returns a promise for the response body as a string provided
        that the request is successful with a 200 status.
        -   rejects the promise with the response as the reason for
            failure if the request fails.
-   ``normalizeRequest(request)``
    -   coerces URLs into request objects.
-   ``normalizeResponse(response)
    -   coerces strings, arrays, and other objects supporting
        ``forEach`` into proper response objects.
    -   passes ``undefined`` through as a signal that a request
        will not receive a response directly.
-   request
    -   ``url`` the full URL of the request as a string
    -   ``path`` the full path as a string
    -   ``scriptName`` the routed portion of the path, like ``""`` for
        ``http://example.com/`` if no routing has occurred.
    -   ``pathInfo`` the part of the path that remains to be routed,
        like ``/`` for ``http://example.com`` or ``http://example.com/``
        if no routing has occurred.
    -   ``version`` the requested HTTP version as an array of strings.
    -   ``method`` like ``"GET"``
    -   ``scheme`` like ``"http:"``
    -   ``host`` like ``"example.com"``
    -   ``port`` the port number, like ``80``
    -   ``remoteHost``
    -   ``remotePort``
    -   ``headers``
        corresponding values, possibly an array for multiple headers
        of the same name.
    -   ``body``
    -   ``node`` the wrapped Node request object
-   response
    -   ``status`` the HTTP status code as a number, like ``200``.
    -   ``headers``
    -   ``body``
    -   ``onclose`` is an optional function that this library will call
        when a response concludes.
    -   ``node`` the wrapped Node response object.
-   headers are an object mapping lower-case header-names to
    corresponding values, possibly an array for multiple headers of the
    same name, for both requests and responses.
-   body is a representation of a readable stream, either for the
    content of a request or a response.
    -   ``forEach(callback)``
        -   accepts a ``callback(chunk)`` function
            -   accepts a chunk as either a string or a ``Buffer``
            -   returns undefined or a promise for undefined when the
                chunk has been flushed.
        -   returns undefined or a promise for undefined when the stream
            is finished writing.
        -   the ``forEach`` function for arrays of strings or buffers is
            sufficient for user-provided bodies
    -   the ``forEach`` function is the only necessary function for
        bodies provided to this library.
    -   in addition to ``forEach``, bodies provided by this library
        support the entire readable stream interface provided by
        ``q-io``.
    -   ``read()``
        -   returns a promise for the entire body as a string or a
            buffer.
-   application
    -   accepts a request
    -   accepts Node's responder object as a second argument.
    -   returns a response, a promise for a response, or nothing if no
        response should be sent.

# Copyright

Copyright 2009, 2010, 2011 Kristopher Michael Kowal
MIT License (enclosed)

npm loves you