Improve documentation and/or error messages around request headers

[technomancy]

I've found that there are some easy mistakes you can make when using lua-http as a client which give error messages that are not very clear.

The documentation does not explain how to add request headers either in the introduction section or under new_from_uri. Most other HTTP clients allow you to pass a normal table in when creating your request. It's reasonable that someone might guess this is how lua-http works, but it fails:

local request = req.new_from_uri(url, {["content-accept"]="application/json"})
-- attempt to call a nil value (method 'get')

I think it would be best if a normal table were accepted here, but I understand there are downsides to this due to their lack of orderedness, etc. In any case, the documentation for new_from_uri should definitely mention the fact that it takes two arguments. I think it would also be worth mentioning in the introduction section too. Perhaps the error message could be improved as well to point people in the right direction.

Once you figure out this and construct an actual headers table, its behavior is still subject to some undocumented and unintuitive restrictions. It seems like you must first set the method, then construct the request, then set any other headers you have:

local req_headers = http_headers.new()

-- if you try to set the method pseudo-header *after* the request has been created, the error
-- message is not very good: PROTOCOL_ERROR(0x1): Protocol error detected:
-- All pseudo-header fields MUST appear in the header block before regular header fields
req_headers:append(":method", "POST")

local request = req.new_from_uri("https://example.com/whatever", req_headers)

-- if you try to set a *normal* header *before* the request has been created, you
-- also get the same error message as above, which doesn't actually tell you
-- what you did wrong.
req_headers:append("authorization", "Bearer XYZABC6514478")

In this case as well it would also be useful to either loosen the requirements, or if that's not possible then document the requirements or emit an error message explaining what the user actually did wrong.

Thanks! Once I got over these hurdles, I have found this library to be very useful. I'm willing to help make these changes, but I wanted to check first for agreement before making changes.