Normalize requests and responses

[mstade]

From @mstade on August 13, 2014 16:31

Fielding's dissertation states:

A representation is a sequence of bytes, plus representation metadata to describe those bytes. Other commonly used but less precise names for a representation include: document, file, and HTTP message entity, instance, or variant.

A representation consists of data, metadata describing the data, and, on occasion, metadata to describe the metadata (usually for the purpose of verifying message integrity). Metadata is in the form of name-value pairs, where the name corresponds to a standard that defines the value's structure and semantics. Response messages may include both representation metadata and resource metadata: information about the resource that is not specific to the supplied representation.

(Emphasis mine.)

Currently, nap doesn't enforce any structure on responses, and it's up to whoever responds to make sure that responses adhere to this structure. I think we can go a step further and make sure response handlers return messages which include both headers and the body. We don't have to include any headers, and we don't have to verify that they are correct -- both of these could, and probably should, be the responsibility of middleware -- but we can and should make sure the message itself has the correct format. Possibly, this is a much larger discussion, which should also involve how we do async control flow in the first place.

Copied from original issue: sammyt/nap#18

[mstade]

Random thoughts; a request/response:

• is a channel
• when created, must provide request metadata (URL, method, version? more?) or response metadata (status, message, version? more?)
• must send metadata (headers) before sending any parts of the body
• should allow sending the headers and body in chunks
• should allow both ends of the channel to close the connection
• should have convenient APIs for automagical chunking/buffering (particularly useful for messages sent across boundaries)

[mstade]

Consider compatibility with the fetch API's definitions of request and response. This could be normalized, yet still afford us the ability to use whatever API we'd like, if we were to introduce an implementation of Clojure-like protocols.