Documentation updates #49

RussellHaley · 2016-11-05T08:16:18Z

Updated introduction. Moved Common Use Cases into introduction to keep peoples interest. Updated interface blurbs as per daurnimators notes.

coveralls · 2016-11-05T08:22:11Z

Coverage remained the same at 86.268% when pulling dfe3f90 on RussellHaley:master into fd2a92f on daurnimator:master.

coveralls · 2016-11-06T09:23:50Z

Coverage remained the same at 86.268% when pulling 56b4b35 on RussellHaley:master into fd2a92f on daurnimator:master.

daurnimator

Haven't finished reviewing yet.

daurnimator · 2016-11-06T09:23:40Z

doc/index.md

 # Introduction

-lua-http is an HTTP library for Lua, it supports: both client and server operations, both HTTP 1 and HTTP 2.
+Lua-http is an performant, capable Hyper Text Transfer Protocol (HTTP) and WebSocket (WS) library for Lua 5.1, 5.2, 5.3 and LuaJIT. Lua-http can be run in either a Server (listen) or Client (connect) mode and includes the following features: 


Capitalisation (lua-http vs Lua-http): I'm leaning towards the former.

daurnimator · 2016-11-06T09:27:56Z

doc/index.md

 # Introduction

-lua-http is an HTTP library for Lua, it supports: both client and server operations, both HTTP 1 and HTTP 2.
+Lua-http is an performant, capable Hyper Text Transfer Protocol (HTTP) and WebSocket (WS) library for Lua 5.1, 5.2, 5.3 and LuaJIT. Lua-http can be run in either a Server (listen) or Client (connect) mode and includes the following features: 


"can be run" <== libraries don't get "run", they are "used" or "utilized"

daurnimator · 2016-11-06T09:28:33Z

doc/index.md

 # Introduction

-lua-http is an HTTP library for Lua, it supports: both client and server operations, both HTTP 1 and HTTP 2.
+Lua-http is an performant, capable Hyper Text Transfer Protocol (HTTP) and WebSocket (WS) library for Lua 5.1, 5.2, 5.3 and LuaJIT. Lua-http can be run in either a Server (listen) or Client (connect) mode and includes the following features: 


I don't think I would mention listen vs connect yet.

daurnimator · 2016-11-06T09:28:59Z

doc/index.md

 # Introduction

-lua-http is an HTTP library for Lua, it supports: both client and server operations, both HTTP 1 and HTTP 2.
+Lua-http is an performant, capable Hyper Text Transfer Protocol (HTTP) and WebSocket (WS) library for Lua 5.1, 5.2, 5.3 and LuaJIT. Lua-http can be run in either a Server (listen) or Client (connect) mode and includes the following features: 


need new line before a list.

daurnimator · 2016-11-06T09:29:42Z

doc/index.md


-lua-http is an HTTP library for Lua, it supports: both client and server operations, both HTTP 1 and HTTP 2.
+Lua-http is an performant, capable Hyper Text Transfer Protocol (HTTP) and WebSocket (WS) library for Lua 5.1, 5.2, 5.3 and LuaJIT. Lua-http can be run in either a Server (listen) or Client (connect) mode and includes the following features: 
+- HTTP 1 and HTTP 2 as specified by RFCs [1945](https://tools.ietf.org/html/rfc1945) and [7540 ](https://tools.ietf.org/html/rfc7540)


lists bullets should be prefixed with two spaces i.e. -

daurnimator · 2016-11-06T09:49:59Z

doc/index.md


 ### `connection:localname()` <!-- --> {#connection:localname}

+Provides the uri for the local socket. The return format is: address family, IP address, port. If the connection object is not connected, returns AF_UNSPEC (0). If the error is other than a connection error, returns nil and the state name.


Returns, not Provides.

daurnimator · 2016-11-06T09:50:11Z

doc/index.md


 ### `connection:localname()` <!-- --> {#connection:localname}

+Provides the uri for the local socket. The return format is: address family, IP address, port. If the connection object is not connected, returns AF_UNSPEC (0). If the error is other than a connection error, returns nil and the state name.


This return format is not a uri.

daurnimator · 2016-11-06T09:50:46Z

doc/index.md


 ### `connection:localname()` <!-- --> {#connection:localname}

+Provides the uri for the local socket. The return format is: address family, IP address, port. If the connection object is not connected, returns AF_UNSPEC (0). If the error is other than a connection error, returns nil and the state name.


This will return nil, error_message, errno on failure (which again: shouldn't need to be mentioned).

daurnimator · 2016-11-06T09:52:00Z

doc/index.md


+Provides the uri for the local socket. The return format is: address family, IP address, port. If the connection object is not connected, returns AF_UNSPEC (0). If the error is other than a connection error, returns nil and the state name.
+
+    --example: print(connection:localname())


Please give examples their own heading one level down from the current (so #### here). And an id field so that it can be linked to.

daurnimator · 2016-11-06T09:53:12Z

doc/index.md


 ### `connection:peername()` <!-- --> {#connection:peername}

+Provides the URI for the remote socket *peer* (as in the next hop).  Notably: If the client is using a proxy, the :peername() will be the proxy, not the remote server connection.The return format is: ip address, port. If not connected, returns 0. If the error is other than a connection error, returns nil and the statename.


See comments for :localname().

Missing space after "."

It returns family before address, port.

daurnimator · 2016-11-06T10:17:27Z

doc/index.md

 ### `stream.connection` <!-- --> {#stream.connection}

-The underlying [*connection*](#connection) object
+The underlying [*connection*](#connection) object that contains the socket.


Why is the socket worth calling out over any other property?

daurnimator · 2016-11-06T10:18:50Z

doc/index.md

 ### `connection:new_stream()` <!-- --> {#connection:new_stream}

-Create a new [stream](#stream) on the connection.
+Create a new [stream](#stream) on the connection. Use new_stream to initiate a new http request.


It can be for more than just creating a new request: for HTTP2 you can also create a new stream for use in stream prioritisation, or for a push promise. (though usually for a promise you would usually use the higher level api)

daurnimator · 2016-11-06T10:21:31Z

doc/index.md


-Write the given [`headers`](#http.headers) object to the stream.
-Takes a flag indicating if this is the last chunk in the stream, if `true` the stream will be closed.
+Write the given [`headers`](#http.headers) object to the stream. The function takes a flag indicating if this is the last chunk in the stream, if `true` the stream will be closed. If `timeout` is specified, the socket will be polled untile `timeout` is exceeded.


"will be polled" => not exactly... it's the maximum amount of time to wait for the data to get sent out from the OS. this may include connection completion time (which may include DNS, TLS, etc), or alternatively if the TCP outgoing it will be waiting for it to drain.

daurnimator · 2016-11-06T10:23:02Z

doc/index.md


 ### `stream:get_next_chunk(timeout)` <!-- --> {#stream:get_next_chunk}

+(?) Does it block or poll? will it poll indefinetly or until some time?


"Does it block or poll?" what is the difference? what do you mean "until some time"?
"indefinetly" => "indefinitely"

daurnimator · 2016-11-06T10:23:22Z

doc/index.md


-Write the given [`headers`](#http.headers) object to the stream.
-Takes a flag indicating if this is the last chunk in the stream, if `true` the stream will be closed.
+Write the given [`headers`](#http.headers) object to the stream. The function takes a flag indicating if this is the last chunk in the stream, if `true` the stream will be closed. If `timeout` is specified, the socket will be polled untile `timeout` is exceeded.


daurnimator · 2016-11-06T10:43:11Z

doc/index.md


 ### `h1_connection:read_body_chunk(timeout)` <!-- --> {#http.h1_connection:read_body_chunk}

+Reads the next available line of data from the request and returns the chunk and it's size. This function will yield until complete or `timeout`. Returns nil, and 0 if no data was read. Returns nil, an error and an error message if there was an error reading.


This function attempts to read a http body chunk.
It does not know if it is in a request context, or being used correctly.

Returns nil, and 0 if no data was read.

Huh?

Returns nil, an error and an error message if there was an error reading.

Should be nil, error_message, errno on failure.

Special case: this function returns false on the last chunk.

daurnimator · 2016-11-06T10:44:00Z

doc/index.md


 ### `h1_connection:write_request_line(method, path, httpversion, timeout)` <!-- --> {#http.h1_connection:write_request_line}

+Sends an HTTP request to a remote server. Yields until success or `timeout`. If the write fails, returns nil, an error message and an error number.


It does not send a request, just a request-line (which is the first line sent by a http 1 client)

daurnimator · 2016-11-06T10:44:57Z

doc/index.md


 ### `h1_connection:write_headers_done(timeout)` <!-- --> {#http.h1_connection:write_headers_done}

+Finalizes the http headers in the socket. Yields until success or `timeout`. Returns nil, an error message and an error if the write fails.


'Finalizes' has special meaning in programming.

Better to say: Terminates a header block by sending "\r\n"

daurnimator · 2016-11-06T10:45:25Z

doc/index.md


 ### `h1_connection:write_body_last_chunk(chunk_ext, timeout)` <!-- --> {#http.h1_connection:write_body_last_chunk}

+Finalizes the message body. `chunck_ext` must be nil as chunk extensions are not supported. Will yield until complete or `timeout` is exceeded.


"Finalizes" (see above)

daurnimator · 2016-11-06T10:45:52Z

doc/index.md


-In addition to following the [*stream*](#stream) interface and the methods from [http.stream_common](#http.stream_common),
-an `http.h1_stream` has the following methods:
+The h1_stream represents an HTTP 1.0 or 1.1 request/response. The module follows the [*stream*](#stream) interface and the methods from [http.stream_common](#http.stream_common), as well as the following HTTP 1 specific functions:


"The" => "A"

coveralls · 2016-11-07T07:45:41Z

Coverage decreased (-0.003%) to 86.265% when pulling 67ea725 on RussellHaley:master into fd2a92f on daurnimator:master.

daurnimator · 2016-11-07T11:00:19Z

doc/index.md

 # Introduction

-lua-http is an HTTP library for Lua, it supports: both client and server operations, both HTTP 1 and HTTP 2.
+lua-http is an performant, capable Hyper Text Transfer Protocol (HTTP) and WebSocket (WS) library for Lua 5.1, 5.2, 5.3 and LuaJIT. lua-http can be utilized as a Server or Client and includes the following features: 


why are Server and Client capitalised?

daurnimator · 2016-11-07T11:00:45Z

doc/index.md

+-  Fully asynchronous API that does not block the current thread when executing operations that typically block
+-  Easy integration into other event-loop based application models

+lua-http was written to fill a gap in the Lua ecosystem by providing an asynchrounous HTTP and WebSocket capabilities to Lua applications without forcing the developer to follow a specific pattern, or even know anything about the transportation of HTTP data (other than the connection addresses). The library is simple and un-obtrusive and is designed to accommodate tens of thousands of connections on commodity hardware. This allows other developers to concentrate on line-of-business features when building Internet enabled applications, instead of worrying about the details of connection management. 


asynchrounous => asynchronous

daurnimator · 2016-11-07T11:01:51Z

doc/index.md

+-  Fully asynchronous API that does not block the current thread when executing operations that typically block
+-  Easy integration into other event-loop based application models

+lua-http was written to fill a gap in the Lua ecosystem by providing an asynchrounous HTTP and WebSocket capabilities to Lua applications without forcing the developer to follow a specific pattern, or even know anything about the transportation of HTTP data (other than the connection addresses). The library is simple and un-obtrusive and is designed to accommodate tens of thousands of connections on commodity hardware. This allows other developers to concentrate on line-of-business features when building Internet enabled applications, instead of worrying about the details of connection management. 


I'd like to add something like "unless they want to". lua-http intentionally gives you the capabilities to get down and dirty with the HTTP protocol if you want to.

daurnimator · 2016-11-07T11:02:11Z

doc/index.md

+## Common use cases

-HTTP 1 request and status line fields are passed around inside of [headers](#http.headers) objects under keys `":authority"`, `":method"`, `":path"`, `":scheme"` and `":status"` as defined in HTTP 2. As such, they are all kept in string form (important to remember for the `:status` field).
+The following are a few basic examples of how the lua-http library can be used. 


end in colon?

daurnimator · 2016-11-07T11:02:34Z

doc/index.md

+The following are a few basic examples of how the lua-http library can be used. 

-Header fields should always be used with lower case keys.
+###Retrieving a document


need a space between # and text

daurnimator · 2016-11-07T11:20:03Z

doc/index.md


 ### `connection:close()` <!-- --> {#connection:close}

+Closes all streams and refuses new connections. Can be re-opened using connect()


Should note: "all connection specific operating systems resources are released"

daurnimator · 2016-11-07T11:20:50Z

doc/index.md

 ### `connection:new_stream()` <!-- --> {#connection:new_stream}

-Create a new [stream](#stream) on the connection.
+Create a new [stream](#stream) on the connection. Use new_stream to initiate a new http request. In HTTP2 a new stream can also be used in stream prioritization or to initiate a push promise.


new_stream

Should put in backticks? Possibly with : in front?

daurnimator · 2016-11-07T11:21:45Z

doc/index.md

 ### `connection:new_stream()` <!-- --> {#connection:new_stream}

-Create a new [stream](#stream) on the connection.
+Create a new [stream](#stream) on the connection. Use new_stream to initiate a new http request. In HTTP2 a new stream can also be used in stream prioritization or to initiate a push promise.


"used in stream prioritization" => "used to organise stream priorities"

daurnimator · 2016-11-07T11:22:07Z

doc/index.md

 ### `connection:new_stream()` <!-- --> {#connection:new_stream}

-Create a new [stream](#stream) on the connection.
+Create a new [stream](#stream) on the connection. Use new_stream to initiate a new http request. In HTTP2 a new stream can also be used in stream prioritization or to initiate a push promise.


Try not to use "also" (I'm guilty of this too!)

daurnimator · 2016-11-07T11:23:02Z

doc/index.md

 ### `stream:unget(str)` <!-- --> {#stream:unget}

-Returns nothing
+Prepends str to the request body buffer, allowing it to be returned again on a subsequent get_next_chunck() command ("un-gets" the data). Returns true on success. On failure returns nil, error message and an error number.


"str" should be in backticks.

daurnimator · 2016-11-09T07:26:39Z

doc/index.md

 ### `h1_connection:read_request_line(timeout)` <!-- --> {#http.h1_connection:read_request_line}

-Gets the request method, requested path and HTTP version for an incoming request. On error, returns nil, an error message and an error number.
+Returns information about in incoming request. Returns the `request method`, `requested path` and `HTTP version` for an incoming request. On error, returns nil, an error message and an error number.


Importantly this method reads from the socket (it's not information already cached)

daurnimator · 2016-11-09T07:27:27Z

doc/index.md

 ### `h1_connection:read_request_line(timeout)` <!-- --> {#http.h1_connection:read_request_line}

-Gets the request method, requested path and HTTP version for an incoming request. On error, returns nil, an error message and an error number.
+Returns information about in incoming request. Returns the `request method`, `requested path` and `HTTP version` for an incoming request. On error, returns nil, an error message and an error number.


request method, requested path and HTTP version

Those are not variable or property names: shouldn't be in backticks.

daurnimator · 2016-11-09T07:28:11Z

doc/index.md

 ### `h1_connection:read_header(timeout)` <!-- --> {#http.h1_connection:read_header}

-Returns the HTTP header (?key, val) from an incoming request. If the header could not be read, the function returns nil an error and an error message.
+Returns the HTTP headers from an incoming request as a table of string keys and values. If the header could not be read, the function returns nil an error and an error message.


Returns the HTTP headers from an incoming request as a table of string keys and values.

No it doesn't: it returns 2 values: the field name and the field value.

daurnimator · 2016-11-09T07:28:35Z

doc/index.md

 ### `h1_connection:read_body_by_length(len, timeout)` <!-- --> {#http.h1_connection:read_body_by_length}

-Get the number of bytes from the buffered HTTP request body. Use a negative number for *up to* that number of bytes. Asserts if len is not a number.
+Get `len` number of bytes from the buffered HTTP request body. Use a negative number for *up to* that number of bytes. This function will yield and wait on the socket if length of the buffered body is less than `len`. Asserts if len is not a number.


from the buffered HTTP request body

It's not buffered. This reads from the socket

coveralls · 2016-11-09T07:29:11Z

Coverage decreased (-0.003%) to 86.265% when pulling 4066acb on RussellHaley:master into fd2a92f on daurnimator:master.

daurnimator · 2016-11-09T07:29:13Z

doc/index.md

 ### `h1_connection:read_body_chunk(timeout)` <!-- --> {#http.h1_connection:read_body_chunk}

-Reads the next available line of data from the request and returns the chunk and it's size. This function will yield until complete or `timeout`. Returns nil, and 0 if no data was read. Returns nil, an error and an error message if there was an error reading.
+Reads the next available line of data from the request and returns the chunk and it's size. This function will yield until a complete chunk is received or `timeout`. Returns nil, and 0 if no data was read. Returns nil, an error and an error message if there was an error reading.


This function will yield

Why mention this only here and not for other read_* methods?

daurnimator · 2016-11-09T07:29:45Z

doc/index.md

 ### `h1_connection:read_body_chunk(timeout)` <!-- --> {#http.h1_connection:read_body_chunk}

-Reads the next available line of data from the request and returns the chunk and it's size. This function will yield until complete or `timeout`. Returns nil, and 0 if no data was read. Returns nil, an error and an error message if there was an error reading.
+Reads the next available line of data from the request and returns the chunk and it's size. This function will yield until a complete chunk is received or `timeout`. Returns nil, and 0 if no data was read. Returns nil, an error and an error message if there was an error reading.


Don't forget to mention the false case.

daurnimator · 2016-11-10T08:30:14Z

doc/index.md

 # Introduction

-lua-http is an performant, capable Hyper Text Transfer Protocol (HTTP) and WebSocket (WS) library for Lua 5.1, 5.2, 5.3 and LuaJIT. lua-http can be utilized as a Server or Client and includes the following features: 
+lua-http is an performant, capable Hyper Text Transfer Protocol (HTTP) and WebSocket (WS) library for Lua 5.1, 5.2, 5.3 and LuaJIT. The software supports x86, x64 and Arm based systems, as well as GNU/Linux, OSX, FreeBSD and others. lua-http can be utilized as a server or client and includes the following features: 


The software supports x86, x64 and Arm based systems

lua-http is pure lua code. It has no demands for architecture.

as well as GNU/Linux, OSX, FreeBSD and others

where lua-http can run is mainly limited by where cqueues works (which is BSDs, Linux, OSX, Solaris): if you can port cqueues to it, lua-http should automatically work.

daurnimator · 2016-11-10T08:30:33Z

doc/index.md


-lua-http was written to fill a gap in the Lua ecosystem by providing an asynchrounous HTTP and WebSocket capabilities to Lua applications without forcing the developer to follow a specific pattern, or even know anything about the transportation of HTTP data (other than the connection addresses). The library is simple and un-obtrusive and is designed to accommodate tens of thousands of connections on commodity hardware. This allows other developers to concentrate on line-of-business features when building Internet enabled applications, instead of worrying about the details of connection management. 
+lua-http was written to fill a gap in the Lua ecosystem by providing an HTTP and WebSocket library with the following traits:
+- Asynchronous a performant


a performant

'and performant'?

daurnimator · 2016-11-10T08:32:21Z

doc/index.md

+
+As a result of these design goals, the library is simple and un-obtrusive and can accommodate tens of thousands of connections on commodity hardware. 
+
+lua-http is a flexible HTTP and WebSocket library that allows developers to concentrate on line-of-business features when building Internet enabled applications. If you are looking for a way to streamline development of an internet enabled application, enable HTTP networking in your game, create a new Internet Of Things (IoT) system, or write a performant custom web server for a specific use case, lua-http has the tools you need.


😁 so fluffy

daurnimator · 2016-11-10T08:34:55Z

doc/index.md


 Header fields should always be used with lower case keys.

+- `item_name` - Indicates a value


Prefix with "in this documentation" or such.

Perhaps move this to the top of the Conventions section.

daurnimator · 2016-11-10T08:36:14Z

doc/index.md

 ### `connection:localname()` <!-- --> {#connection:localname}

-Returns the connection information for the local socket. The return format is address family, IP address, port separated by whitespace. `<Address-Family> `<IP-Address>` `<port-number>`. If the connection object is not connected, returns AF_UNSPEC (0). If the error is other than a connection error, returns nil and the state name.
+Returns the connection information for the local socket. Returns address family, IP address, port for an external socket. For unix sockets, the function returns `AF_UNIX` and the path. If the connection object is not connected, returns AF_UNSPEC (0). If the error is other than a connection error, returns `nil` and the state name.


AF_UNIX is in backticks but AF_UNSPEC is not

daurnimator · 2016-11-10T08:36:50Z

doc/index.md

 ### `connection:peername()` <!-- --> {#connection:peername}

-Returns the connection information for the socket *peer* (as in the next hop). The return format is address family, IP address, port separated by whitespace. `<Address-Family> `<IP-Address>` `<port-number>`. If not connected, returns 0. If the error is other than a connection error, returns nil and the statename.
+Returns the connection information for the socket *peer* (as in the next hop). The return format is address family, IP address, port separated by whitespace. `<Address-Family> `<IP-Address>` `<port-number>`. If not connected, returns 0. If the error is other than a connection error, returns `nil` and the statename.


use updated copy from :localname

daurnimator · 2016-11-10T08:38:50Z

doc/index.md

-	  - `version` (nil|1.0|1.1|2): HTTP version to use.
-		  - `nil`: attempts HTTP 2 and falls back to HTTP 1.1
+	  - `version` (`nil`|1.0|1.1|2): HTTP version to use.
+		  - ``nil``: attempts HTTP 2 and falls back to HTTP 1.1


Has double backticks around nil

That's because it's REALLY nil. Or a mistake using replace all.

daurnimator · 2016-11-10T08:40:09Z

doc/index.md

 ### `h1_connection:read_headers_done(timeout)` <!-- --> {#http.h1_connection:read_headers_done}

-Checks if all chunks of the HTTP headers have been fully received. Returns nil, an error and an error message if the socket cannot be read.
+Checks for an empty line ("\r\n"), which indicates the end of the HTTP headers. Returns true if an empty line is received. Any other value is pushed back on the socket receive buffer (unget) and the function returns false. This function will yield waiting for input from the socket or until `timeout` is exceeded. Returns `nil`, an error and an error message if the socket cannot be read.


Put string literals in backticks.

daurnimator · 2016-11-10T08:40:57Z

doc/index.md

 ### `h1_connection:read_body_chunk(timeout)` <!-- --> {#http.h1_connection:read_body_chunk}

-Reads the next available line of data from the request and returns the chunk and it's size. This function will yield until a complete chunk is received or `timeout`. Returns nil, and 0 if no data was read. Returns nil, an error and an error message if there was an error reading.
+Reads the next available line of data from the request and returns the chunk and it's size. This function will yield until a complete chunk is received or `timeout` is exceeded. Returns `nil`, and 0 if no data was read. Returns `nil`, an error and an error message if there was an error reading.


Returns nil, and 0 if no data was read.

No it doesn't?

WTH? I'd claim intoxication but I'd be lying. :(

daurnimator · 2016-11-10T08:41:32Z

doc/index.md

 ### `h1_connection:write_body_chunk(chunk, chunk_ext, timeout)` <!-- --> {#http.h1_connection:write_body_chunk}

-Writes a line of data to the socket. `chunk_ext` must be nil as chunck extensions are not supported. Will yield until complete or `timeout` is exceeded. Returns true on success. Returns nil, an error message and an error number if the write fails. 
+Writes a line of data to the socket. `chunk_ext` must be `nil` as chunck extensions are not supported. Will yield until complete or `timeout` is exceeded. Returns true on success. Returns `nil`, an error message and an error number if the write fails. 


daurnimator · 2016-11-10T08:43:26Z

doc/index.md

 ### `h1_connection:write_body_last_chunk(chunk_ext, timeout)` <!-- --> {#http.h1_connection:write_body_last_chunk}

-Finalizes the message body. `chunck_ext` must be nil as chunk extensions are not supported. Will yield until complete or `timeout` is exceeded. Returns nil, an error message and an error number if the write fails.
+Writes a trailer ("0\r\n") to signal the end of the HTTP body. `chunck_ext` must be `nil` as chunk extensions are not supported. Will yield until complete or `timeout` is exceeded. Returns `nil`, an error message and an error number if the write fails.


The "0\r\n" isn't the trailer (that comes afterwards); it is the separator that signals the end of a chunked body.

daurnimator · 2016-11-10T08:43:45Z

doc/index.md

 If `cond` is truthy, returns `cond, ...`

-If `cond` is falsy (i.e. `false` or `nil`), throws an error with the first element of `...` as the `message`.
+If `cond` is falsy (i.e. `false` or ``nil``), throws an error with the first element of `...` as the `message`.


double backticks.

daurnimator · 2016-11-10T08:45:43Z

doc/index.md

 ### `request.version` <!-- --> {#http.request.version}

-The HTTP version to use; leave as `nil` to auto-select.
+The HTTP version to use; leave as ``nil`` to auto-select.


double backticks.

daurnimator · 2016-11-10T08:45:46Z

doc/index.md


  - If `body` is a string it will be sent as given.
-  - If `body` is a function, it will be called repeatedly like an iterator. It should return chunks of the request body as a string or `nil` if done.
+  - If `body` is a function, it will be called repeatedly like an iterator. It should return chunks of the request body as a string or ``nil`` if done.


double backticks.

daurnimator · 2016-11-10T08:45:53Z

doc/index.md

 ### `socks:take_socket()` <!-- --> {#http.socks:take_socket}

-Take possesion of the socket object managed by the http.socks object. Returns the socket (or `nil` if not available).
+Take possesion of the socket object managed by the http.socks object. Returns the socket (or ``nil`` if not available).


double backticks.

daurnimator · 2016-11-10T08:45:56Z

doc/index.md

  - If `str` is a valid `token`, return it as-is.
  - If `str` would be valid as a `quoted-string`, return the quoted version
-  - Otherwise, returns `nil`
+  - Otherwise, returns ``nil``


double backticks.

daurnimator · 2016-11-10T08:46:01Z

doc/index.md


  - `data` should be a string
-  - `opcode` can be a numeric opcode, `"text"` or `"binary"`. If `nil`, defaults to a text frame
+  - `opcode` can be a numeric opcode, `"text"` or `"binary"`. If ``nil``, defaults to a text frame


double backticks.

daurnimator · 2016-11-14T07:13:03Z

doc/index.md

+  ```
+
+Asserts if `new` is not a valid value.



newline required

daurnimator · 2016-11-14T07:13:52Z

doc/index.md

+-  Easy integration into other event-loop based application models

+lua-http was written to fill a gap in the Lua ecosystem by providing an HTTP and WebSocket library with the following traits:
+- Asynchronous and performant


newline required before start of list

daurnimator · 2016-11-14T07:15:11Z

doc/index.md


-HTTP over TLS (i.e. HTTPS) is fully supported.
+-  HTTP 1 and HTTP 2 as specified by [RFC 7230](https://tools.ietf.org/html/rfc7230) and [RFC 7540](https://tools.ietf.org/html/rfc7540)
+-  WebSockets as specified by [RFC 6455](https://tools.ietf.org/html/rfc6455) and [RFC 7936](https://tools.ietf.org/html/rfc7936) including ping/pong, binary data transfer and TLS encyrption


I don't think I'd bother mentioning RFC 7936

daurnimator · 2016-11-14T07:15:37Z

doc/index.md

-HTTP over TLS (i.e. HTTPS) is fully supported.
+-  HTTP 1 and HTTP 2 as specified by [RFC 7230](https://tools.ietf.org/html/rfc7230) and [RFC 7540](https://tools.ietf.org/html/rfc7540)
+-  WebSockets as specified by [RFC 6455](https://tools.ietf.org/html/rfc6455) and [RFC 7936](https://tools.ietf.org/html/rfc7936) including ping/pong, binary data transfer and TLS encyrption
+-  Transport Layer Security (TLS)- lua-http supports HTTPS and WSS via [luaossl](https://github.com/wahern/luaossl).  


need space between ) and -

daurnimator · 2016-11-14T07:16:07Z

doc/index.md


+lua-http was written to fill a gap in the Lua ecosystem by providing an HTTP and WebSocket library with the following traits:
+- Asynchronous and performant
+- Can be used without forcing the developer to follow a specific pattern. Conversly, the library can be adapted to many common patterns. 


Conversly => Conversely

daurnimator · 2016-11-14T07:22:12Z

doc/index.md


 ### `h1_connection:write_request_line(method, path, httpversion, timeout)` <!-- --> {#http.h1_connection:write_request_line}

+Sends an HTTP 1.x request line to a remote server, initiating an HTTP request. Yields until success or `timeout`. If the write fails, returns `nil`, an error message and an error number.


Perhaps mention which :write function flush the write buffer.
IIRC of the header-related functions only write_headers_done does.

daurnimator · 2016-11-14T07:23:25Z

doc/index.md


 ### `h1_connection:write_body_last_chunk(chunk_ext, timeout)` <!-- --> {#http.h1_connection:write_body_last_chunk}

+Writes the chunked body terminator `"0\r\n"` to signal the end of the HTTP body. `chunck_ext` must be `nil` as chunk extensions are not supported. Will yield until complete or `timeout` is exceeded. Returns `nil`, an error message and an error number if the write fails.


chunk_ext => chunck_ext

daurnimator · 2016-11-14T07:31:04Z

doc/index.md


 ### `h1_connection:write_body_chunk(chunk, chunk_ext, timeout)` <!-- --> {#http.h1_connection:write_body_chunk}
+
+Writes a line of data to the socket. `chunk_ext` must be `nil` as chunk extensions are not supported. Will yield until complete or `timeout` is exceeded. Returns true on success. Returns `nil`, an error message and an error number if the write fails. 


It doesn't write a 'line'. it writes the data in chunk as a single chunk in the HTTP chunked transfer encoding.

daurnimator · 2016-11-14T07:32:51Z

doc/index.md


 ### `h1_stream:set_state(new)` <!-- --> {#http.h1_stream:set_state}

+Sets the h1_stream.state if `new` is one of the following valid states:


Take out 'the'.

I don't know how to feel about mentioning the internal/private .state field here.

If I read the function correctly, it checks for valid values so I thought it best to show them. I first tried a formatted list, but decided Lua was cleaner. Up to you if you want me to remove it.

daurnimator · 2016-11-14T07:33:06Z

doc/index.md

+Sets the h1_stream.state if `new` is one of the following valid states:
+
+```lua
+	valid_states = {


this line shouldn't be indented.

daurnimator · 2016-11-14T07:34:54Z

doc/index.md

+- For more information on integrating cqueues with other event loop libraries please see [integration with other event loops](https://github.com/wahern/cqueues/wiki/Integrations-with-other-main-loops).
+
+- For other libraries that use cqueues such as asynchronous APIs for Redis and PostgreSQL, please see [the cqueues wiki entry here](https://github.com/wahern/cqueues/wiki/Libraries-that-use-cqueues).
+


needs 2nd newline here

I added the second newline, but the github automagic that compares the copies didn't seem to pick it up?

daurnimator · 2016-11-14T07:35:16Z

doc/index.md

+
+_Newline_ - A single carriage return and line feed `"\r\n"`, indicating a blank line
+
+*Note: the section is incomplete*


Why have this note here?

daurnimator · 2016-11-14T07:35:30Z

doc/index.md


-Either `"client"` or `"server"`
+The mode of use for the connection object. Valid values are:
+- `"client"` - Connects to a remote URI


newline required before list

daurnimator · 2016-11-14T07:36:05Z

doc/index.md

 ## connection

-All connection types expose the fields:
+lua-http has separate libraries for both HTTP 1 and HTTP 2 type communications. Future protocols will also be supported and exposed as new modules. As HTTP 2 builds on HTTP 1, the _[connection](#connection)_ and _[stream](#stream)_ modules have been written to contain common interfaces wherever possible. All _[connection](#connection)_ types expose the following fields:


As HTTP 2 builds on HTTP 1

Rephrase?

daurnimator · 2016-11-14T07:36:48Z

doc/index.md


 ### `connection:peername()` <!-- --> {#connection:peername}

+Returns the connection information for the socket *peer* (as in, the next hop). Returns address family, IP address, port for an external socket. For unix sockets, the function returns `AF_UNIX` and the path. If the connection object is not connected, returns `AF_UNSPEC` (0). If the error is other than a connection error, returns `nil` and the state name.


and the state name.

Huh? (you might have found a bug here?)

daurnimator · 2016-11-14T07:39:19Z

doc/index.md

 ### `connect(options, timeout)` <!-- --> {#http.client.connect}

-Creates a new connection to an HTTP server.
+This function returns an open connection to an HTTP server. Once a connection has been opened, a stream can be created to start a request/response exchange. Please see [`h1_stream.new_stream`](h1_stream.new_stream) and [`h2_stream.new_stream`](h2_stream.new_stream) for more information about creating requests.


It's not necessarily "open"; only after calling :connect() on the result is the connection truly "open".

Though, we haven't defined what "open" means...... I assumed it would be the underlying socket, but perhaps not?

daurnimator · 2016-11-14T07:40:12Z

doc/index.md


 ### `h1_connection:read_request_line(timeout)` <!-- --> {#http.h1_connection:read_request_line}

+Reads a request line from the socket. Returns the request method, requested path and HTTP version for an incoming request. `:read_request_line()` yields until a `"\r\n"` terminated chunk is received, or `timeout` is exceeded. If the incoming chunck is not a valid HTTP request line, `nil` is returned. On error, returns `nil`, an error message and an error number.


chunck => chunk

daurnimator · 2016-11-14T07:40:20Z

doc/index.md


 ### `h1_connection:read_status_line(timeout)` <!-- --> {#http.h1_connection:read_status_line}

+Reads a line of input from the socket. If the input is a valid status line, the HTTP version (1 or 1.1), status code and reason description (if applicable) is returned. `:read_status_line()` yields until a "\r\n" terminated chunck is received, or `timeout` is exceeded. If the socket could not be read, returns `nil`, an error message and an error number.


chunck => chunk

daurnimator · 2016-11-14T07:40:45Z

doc/index.md


 ### `h1_connection:flush(...)` <!-- --> {#http.h1_connection:flush}

+Flushes all buffered data on the socket. Returns `true` on success. Returns `false` and the error if the socket fails to flush.


"all buffered data" => "all buffered outgoing data"

daurnimator · 2016-11-14T08:26:05Z

doc/index.md

 -  HTTP 1 and HTTP 2 as specified by [RFC 7230](https://tools.ietf.org/html/rfc7230) and [RFC 7540](https://tools.ietf.org/html/rfc7540)
-  WebSockets as specified by [RFC 6455](https://tools.ietf.org/html/rfc6455) and [RFC 7936](https://tools.ietf.org/html/rfc7936) including ping/pong, binary data transfer and TLS encyrption
-  Transport Layer Security (TLS)- lua-http supports HTTPS and WSS via [luaossl](https://github.com/wahern/luaossl).  
+-  WebSockets as specified by [RFC 6455](https://tools.ietf.org/html/rfc6455) including ping/pong, binary data transfer and TLS encyrption


encyrption => encryption

daurnimator · 2016-11-14T08:41:28Z

doc/index.md

+    local websocket = require "http.websocket"
+    local ws = websocket.new_from_uri("ws://echo.websocket.org")
+    local ws_ok, err, errno = ws:connect()
+    if ws_ok then


Don't bother with this construction for examples, just assert.

daurnimator · 2016-11-14T08:42:30Z

doc/index.md

-	valid_states = {
-	["idle"] = 1; -- initial
+valid_states = {
+  ["idle"] = 1; -- initial


this line has space indentation instead of tab.

daurnimator · 2016-11-15T07:10:24Z

doc/index.md

 ### `connection:localname()` <!-- --> {#connection:localname}

-Returns the connection information for the local socket. Returns address family, IP address and port for an external socket. For Unix domain sockets, the function returns `AF_UNIX` and the path. If the connection object is not connected, returns `AF_UNSPEC` (0). 
+Returns the connection information for the local socket. Returns address family, IP address and port for an external socket. For Unix domain sockets, the function returns `AF_UNIX` and the path. If the connection object is not connected, returns `AF_UNSPEC` (0). If the error is other than a connection error, returns `nil` an error message and an error number.


If the error is other than a connection error

I don't like this phrasing, e.g. what is a "connection error"?

It should be enough to just say "on error, returns ..."

daurnimator · 2016-11-15T07:11:04Z

doc/index.md

 This function returns a new connection to an HTTP server. Once a connection has been opened, a stream can be created to start a request/response exchange. Please see [`h1_stream.new_stream`](h1_stream.new_stream) and [`h2_stream.new_stream`](h2_stream.new_stream) for more information about creating requests.

-  - `options` is a table containing the options to [*http.client.negotiate*](#http.client.negotiate),plus the following:
+  - `options` is a table containing the options to [*http.client.negotiate*](#http.client.negotiate), plus the following:


http.client.negotiate

Should this be in backticks instead of italics?

daurnimator · 2016-11-15T07:11:20Z

doc/index.md

-	["half closed (local)"] = 3; -- have sent whole body
-	["half closed (remote)"] = 3; -- have received whole body
-	["closed"] = 4; -- complete
+  ["open"] = 2; -- have sent or received headers; haven't sent body yet


please use tabs, not spaces.

Sorry, didn't have my editor configured correctly.

daurnimator · 2016-11-15T08:32:59Z

doc/index.md

 To request information from a WebSocket server, use the `websocket` module to create a new WebSocket client.

 ```lua
 do


No need for a do...end here

coveralls · 2016-11-16T07:22:20Z

Coverage remained the same at 86.227% when pulling b6f74ef on RussellHaley:master into cc808f7 on daurnimator:master.

coveralls · 2016-11-16T07:22:20Z

Coverage remained the same at 86.227% when pulling b6f74ef on RussellHaley:master into cc808f7 on daurnimator:master.

daurnimator · 2016-11-16T07:44:46Z

You didn't actually rebase. try: git rebase -i

…ntroduction, much more

coveralls · 2016-11-17T06:54:10Z

Coverage remained the same at 86.227% when pulling f084d7e on RussellHaley:master into cc808f7 on daurnimator:master.

coveralls · 2016-11-17T06:54:10Z

Coverage remained the same at 86.227% when pulling f084d7e on RussellHaley:master into cc808f7 on daurnimator:master.

coveralls · 2016-11-17T07:00:31Z

Coverage decreased (-2.1%) to 84.099% when pulling 48b2f1c on RussellHaley:master into cc808f7 on daurnimator:master.

RyanSquared · 2016-11-17T07:02:46Z

not to be picky but can you remove the trailing whitespace? should just be something like sed "s/ *$//" -i.

daurnimator requested changes Nov 6, 2016

View reviewed changes

daurnimator added the documentation label Nov 7, 2016

daurnimator requested changes Nov 7, 2016

View reviewed changes

daurnimator reviewed Nov 9, 2016

View reviewed changes

daurnimator mentioned this pull request Nov 9, 2016

Start making releases #36

Closed

daurnimator added this to the First release milestone Nov 9, 2016

RussellHaley changed the title ~~Updated introduction, changes as per Duarnimators notes~~ Documentation updates Nov 10, 2016

daurnimator reviewed Nov 10, 2016

View reviewed changes

daurnimator requested changes Nov 14, 2016

View reviewed changes

daurnimator reviewed Nov 14, 2016

View reviewed changes

daurnimator requested changes Nov 14, 2016

View reviewed changes

daurnimator reviewed Nov 15, 2016

View reviewed changes

RussellHaley force-pushed the master branch from b6f74ef to f084d7e Compare November 17, 2016 06:46

doc/index.md: Overhaul of docs: document undocumented function, add i…

48b2f1c

…ntroduction, much more

RussellHaley force-pushed the master branch from f084d7e to 48b2f1c Compare November 17, 2016 06:50

daurnimator merged commit 48b2f1c into daurnimator:master Nov 17, 2016


		### `connection:localname()` <!-- --> {#connection:localname}

		Provides the uri for the local socket. The return format is: address family, IP address, port. If the connection object is not connected, returns AF_UNSPEC (0). If the error is other than a connection error, returns nil and the state name.


		Provides the uri for the local socket. The return format is: address family, IP address, port. If the connection object is not connected, returns AF_UNSPEC (0). If the error is other than a connection error, returns nil and the state name.

		--example: print(connection:localname())


		### `connection:peername()` <!-- --> {#connection:peername}

		Provides the URI for the remote socket peer (as in the next hop). Notably: If the client is using a proxy, the :peername() will be the proxy, not the remote server connection.The return format is: ip address, port. If not connected, returns 0. If the error is other than a connection error, returns nil and the statename.


		### `stream:get_next_chunk(timeout)` <!-- --> {#stream:get_next_chunk}

		(?) Does it block or poll? will it poll indefinetly or until some time?


		### `h1_connection:read_body_chunk(timeout)` <!-- --> {#http.h1_connection:read_body_chunk}

		Reads the next available line of data from the request and returns the chunk and it's size. This function will yield until complete or `timeout`. Returns nil, and 0 if no data was read. Returns nil, an error and an error message if there was an error reading.


		### `h1_connection:write_request_line(method, path, httpversion, timeout)` <!-- --> {#http.h1_connection:write_request_line}

		Sends an HTTP request to a remote server. Yields until success or `timeout`. If the write fails, returns nil, an error message and an error number.


		### `h1_connection:write_headers_done(timeout)` <!-- --> {#http.h1_connection:write_headers_done}

		Finalizes the http headers in the socket. Yields until success or `timeout`. Returns nil, an error message and an error if the write fails.


		### `h1_connection:write_body_last_chunk(chunk_ext, timeout)` <!-- --> {#http.h1_connection:write_body_last_chunk}

		Finalizes the message body. `chunck_ext` must be nil as chunk extensions are not supported. Will yield until complete or `timeout` is exceeded.


		### `connection:close()` <!-- --> {#connection:close}

		Closes all streams and refuses new connections. Can be re-opened using connect()


		As a result of these design goals, the library is simple and un-obtrusive and can accommodate tens of thousands of connections on commodity hardware.

		lua-http is a flexible HTTP and WebSocket library that allows developers to concentrate on line-of-business features when building Internet enabled applications. If you are looking for a way to streamline development of an internet enabled application, enable HTTP networking in your game, create a new Internet Of Things (IoT) system, or write a performant custom web server for a specific use case, lua-http has the tools you need.


		Header fields should always be used with lower case keys.

		- `item_name` - Indicates a value


		### `h1_connection:write_request_line(method, path, httpversion, timeout)` <!-- --> {#http.h1_connection:write_request_line}

		Sends an HTTP 1.x request line to a remote server, initiating an HTTP request. Yields until success or `timeout`. If the write fails, returns `nil`, an error message and an error number.


		### `h1_connection:write_body_last_chunk(chunk_ext, timeout)` <!-- --> {#http.h1_connection:write_body_last_chunk}

		Writes the chunked body terminator `"0\r\n"` to signal the end of the HTTP body. `chunck_ext` must be `nil` as chunk extensions are not supported. Will yield until complete or `timeout` is exceeded. Returns `nil`, an error message and an error number if the write fails.


		### `h1_connection:write_body_chunk(chunk, chunk_ext, timeout)` <!-- --> {#http.h1_connection:write_body_chunk}

		Writes a line of data to the socket. `chunk_ext` must be `nil` as chunk extensions are not supported. Will yield until complete or `timeout` is exceeded. Returns true on success. Returns `nil`, an error message and an error number if the write fails.


		### `h1_stream:set_state(new)` <!-- --> {#http.h1_stream:set_state}

		Sets the h1_stream.state if `new` is one of the following valid states:

		- For more information on integrating cqueues with other event loop libraries please see [integration with other event loops](https://github.com/wahern/cqueues/wiki/Integrations-with-other-main-loops).

		- For other libraries that use cqueues such as asynchronous APIs for Redis and PostgreSQL, please see [the cqueues wiki entry here](https://github.com/wahern/cqueues/wiki/Libraries-that-use-cqueues).


		_Newline_ - A single carriage return and line feed `"\r\n"`, indicating a blank line

		Note: the section is incomplete


		### `connection:peername()` <!-- --> {#connection:peername}

		Returns the connection information for the socket peer (as in, the next hop). Returns address family, IP address, port for an external socket. For unix sockets, the function returns `AF_UNIX` and the path. If the connection object is not connected, returns `AF_UNSPEC` (0). If the error is other than a connection error, returns `nil` and the state name.


		### `h1_connection:read_request_line(timeout)` <!-- --> {#http.h1_connection:read_request_line}

		Reads a request line from the socket. Returns the request method, requested path and HTTP version for an incoming request. `:read_request_line()` yields until a `"\r\n"` terminated chunk is received, or `timeout` is exceeded. If the incoming chunck is not a valid HTTP request line, `nil` is returned. On error, returns `nil`, an error message and an error number.


		### `h1_connection:read_status_line(timeout)` <!-- --> {#http.h1_connection:read_status_line}

		Reads a line of input from the socket. If the input is a valid status line, the HTTP version (1 or 1.1), status code and reason description (if applicable) is returned. `:read_status_line()` yields until a "\r\n" terminated chunck is received, or `timeout` is exceeded. If the socket could not be read, returns `nil`, an error message and an error number.

Uh oh!

Documentation updates #49

Documentation updates #49

Uh oh!

Conversation

RussellHaley commented Nov 5, 2016

Uh oh!

coveralls commented Nov 5, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coveralls commented Nov 6, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

daurnimator left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coveralls commented Nov 7, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

coveralls commented Nov 5, 2016 •

edited

Loading

coveralls commented Nov 6, 2016 •

edited

Loading

coveralls commented Nov 7, 2016 •

edited

Loading

coveralls commented Nov 9, 2016 •

edited

Loading

daurnimator Nov 9, 2016 •

edited

Loading

daurnimator Nov 10, 2016 •

edited

Loading


		### `h1_connection:flush(...)` <!-- --> {#http.h1_connection:flush}

		Flushes all buffered data on the socket. Returns `true` on success. Returns `false` and the error if the socket fails to flush.