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

Current Tags

0.1.16 ... latest (13 years ago)

The API

Copyright

Current Tags

22 Versions