Support for custom headers

[edubart]

For example can pass custom headers (in this case the Cookie) in the client websocket by doing
wb:connect(uri, {headers = { Cookie = 'mycookie' })

Note that with this option the options origin and protocols could be removed and , then the header generation code simplified, however I did not want to break API compability.

This implements #23

[agentzh]

I think we also need some corresponding test cases for this new feature in the existing test suite.

Need some docs as well.

Thanks!

[agentzh]

It's very bad to use .. in a loop. Lua strings are immutable and this can easily lead to O(n^2) time complexity and O(n^2) space complexity. Better use a globally shared Lua table to collect all these string pieces.

[edubart]

Indeed, however is not like this is a critical code, neither many of custom headers usually will be used and I see no guaranteed performant way to avoid concacenating with ".." while maintaining the API the design.

We could use string.format() in each iteration here, but is not clear if it would perform better. We could also create an auxiliary table and use table.concat(), but again is not clear if creating another table (with strings inside which would also so be collected) to do the task would perform better.

Anyway I have no intention to spend time micro optimazing here as this is not a critical code.

[agentzh]

@edubart This table can be shared by all the function invocations. You do not even need to clear the table actually.

[agentzh]

@edubart In fact, this piece of code is run in a request handler. I'd say code run by every request should be considered "hot code path".

[edubart]

I have no intention to do anything futher, I will leave using my fork as in my case the performance difference is negligible.

[agentzh]

Style: need a space after the comma (,).

[agentzh]

Maybe it's better to use a flat array for this option, as in

{ name1, value1, name2, value2, ...}.

So that we can avoid iterating through a hash table. Additionally, iterating through a hash table is not JIT compiled in LuaJIT.

[edubart]

Although this is not the most performant way it maintains the usual design of other lua libraries APIs, like lua-resty-http does for headers, which I also use in resty projects, and different APIs design across libraries usually is undesired, thus I think using hash table instead of flat arrays is for the better.

[agentzh]

@edubart The lua-resty-http library you referenced is not our work, so we do not really care about being consistent with all the 3rd-party libraries. That's not even possible anyway. The upcoming ngx.req.get_header_list() and ngx.resp.get_header_list() API functions of the OpenResty core will use a similarly structured flat array. OpenResty's core APIs and libraries care more about performance.

[agentzh]

@edubart Maybe it's easier to just add support for a cookie option? That would also be more efficient.

[edubart]

@agentzh Just adding cookie is not sufficient, I also need to use other header options like Authentication, and some custom ones like Api-Key, this way is more flexible, another users may need different headers aswell.

[edubart]

A test and documentation were added.