Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

96 lines (89 sloc) 3.999 kb

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)

Jump to Line
Something went wrong with that request. Please try again.