q-http

    0.1.16 • Public • Published

    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)

    Keywords

    none

    Install

    npm i q-http

    DownloadsWeekly Downloads

    1

    Version

    0.1.16

    License

    none

    Last publish

    Collaborators

    • kriskowal