Skip to content

Conversation

RussellHaley
Copy link
Contributor

Removed some of the busy-ness and added white space using headers.

doc/index.md Outdated
# 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. The software supports x86, x64 and Arm based systems, as well as GNU/Linux, OSX, FreeBSD and others [1]. lua-http can be utilized as a server or client and includes the following features:
lua-http is an performant, capable HTTP and WebSocket library for Lua. The library supports Lua 5.1 and greater and runs on a wide range of operating systems and platforms. Some of the features of the library include:
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I prefer listing the versions of lua: most people just scan the text looking for the thing they care about

doc/index.md Outdated
lua-http is an performant, capable HTTP and WebSocket library for Lua. The library supports Lua 5.1 and greater and runs on a wide range of operating systems and platforms. Some of the features of the library include:

- 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)
- HTTP version 1, 1.1 and 2 as specified by [RFC 7230](https://tools.ietf.org/html/rfc7230) and [RFC 7540](https://tools.ietf.org/html/rfc7540)
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

version => versions
(plural)

doc/index.md Outdated
lua-http was written to fill a gap in the Lua ecosystem by providing an HTTP and WebSocket library with the following traits:
### Portability

lua-http is pure Lua code with the following external runtime dependancies:
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

external runtime dependancies

Perhaps "non-lua dependencies" or similar?

doc/index.md Outdated

- [cqueues](http://25thandclement.com/~william/projects/cqueues.html) - Posix API library for Lua
- [luaossl](http://25thandclement.com/~william/projects/luaossl.html) - Lua bindings for TLS/SSL
- [openssl](https://www.openssl.org/) - Provides TLS/SSL libraries
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

openssl is depended on transitively: I'm not sure it should be mentioned explicitly?

doc/index.md Outdated
- [cqueues](http://25thandclement.com/~william/projects/cqueues.html) - Posix API library for Lua
- [luaossl](http://25thandclement.com/~william/projects/luaossl.html) - Lua bindings for TLS/SSL
- [openssl](https://www.openssl.org/) - Provides TLS/SSL libraries

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mention the (optional) lua-zlib?

doc/index.md Outdated
# 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. The software supports x86, x64 and Arm based systems, as well as GNU/Linux, OSX, FreeBSD and others [1]. lua-http can be utilized as a server or client and includes the following features:
lua-http is an performant, capable HTTP and WebSocket library for Lua. The library supports Lua 5.1, 5.2, 5.3 and LuaJIT and runs on a wide range of Posix compatible operating systems and platforms. Some of the features of the library include:
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and LuaJIT and

doesn't flow well. It was better with the full stop (.)

runs on a wide range of Posix compatible operating systems

I wouldn't mention environments here: it's not important for the primary audience of this document.

- WebSockets as specified by [RFC 6455](https://tools.ietf.org/html/rfc6455) including ping/pong, binary data transfer and TLS encryption
- Transport Layer Security (TLS) - lua-http supports HTTPS and WSS via [luaossl](https://github.com/wahern/luaossl).
- Fully asynchronous API that does not block the current thread when executing operations that typically block
- Provides both client and server APIs
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move this up the list?
Also how about:

Provides functionality for both clients and servers with a common interface.

I don't love the word "common" in that, can you think of a better word/phrasing?

doc/index.md Outdated
lua-http was written to fill a gap in the Lua ecosystem by providing an HTTP and WebSocket library with the following traits:
### Portability

lua-http is pure Lua code with dependancies on the following external libraries:
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

dependancies => dependencies

doc/index.md Outdated
- [cqueues](http://25thandclement.com/~william/projects/cqueues.html) - Posix API library for Lua
- [luaossl](http://25thandclement.com/~william/projects/luaossl.html) - Lua bindings for TLS/SSL
- [openssl](https://www.openssl.org/) - Provides TLS/SSL libraries required by luaossl
- [lua-zlib](https://github.com/brimworks/lua-zlib) - Lua bindings for zlib
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lua-zlib is an optional dependency

doc/index.md Outdated

- [cqueues](http://25thandclement.com/~william/projects/cqueues.html) - Posix API library for Lua
- [luaossl](http://25thandclement.com/~william/projects/luaossl.html) - Lua bindings for TLS/SSL
- [openssl](https://www.openssl.org/) - Provides TLS/SSL libraries required by luaossl
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I mentioned it before, but I don't like mentioning non-direct dependencies. i.e. dependencies of dependencies.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, that got left in by mistake.

doc/index.md Outdated

### `server:add_socket(socket)` <!-- --> {#http.server:add_socket}

Add a new connection socket to the server for processing. The server will use the current `onstream` request handler and all `options` currently specified through the [*server.listen(options)*](#http.server.listen) function. `add_socket` can be used to process connection sockets obtained from an external source such as:
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/function/constructor/

doc/index.md Outdated
Add a new connection socket to the server for processing. The server will use the current `onstream` request handler and all `options` currently specified through the [*server.listen(options)*](#http.server.listen) function. `add_socket` can be used to process connection sockets obtained from an external source such as:
- Another cqueues thread with some other master socket.
- From inetd for start on demand daemons.
- A Unix socket with scm_rights.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SCM_RIGHTS is a C constant: should be in capitals and between backticks.

doc/index.md Outdated

Implements a subset of the SOCKS proxy protocol.


Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no newline required here

doc/index.md Outdated

- `host` (required) a string to pass to the SOCKS server as the host to connect to. Will be resolved locally if [`.needs_resolve`](#http.socks.needs_resolve) is `true`
- `port` (required) a number to pass to the SOCKS server as the port to connect to
Negotiates a socks conneciton.`host` is a required string passed to the SOCKS server as the host address. The address will be resolved locally if [`.needs_resolve`](#http.socks.needs_resolve) is `true`. `port` is a required number to pass to the SOCKS server as the connection port.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

need space after '.'

doc/index.md Outdated

The function takes a string of uncompressed data and an end of stream flag,
it returns the compressed data as a string.
Returns a function that deflates (compresses) a zlib stream. The returned function takes a string of uncompressed data and an end of stream flag and returns the compressed data as a string. The function will throw an error if the stream is invalid.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need newline after first sentence to match inflate

doc/index.md Outdated
- `false`: allows non-tls connections only
- `.version`: the http version to allow to connect (default: any)
- `.onerror`: Function that will be called when an error occurs (default: do nothing). See [server:onerror()](#http.server:onerror)
- `.onstream`: Callback function for handling a new client request. The function requires parameters for [*server*](#http.server) and [*stream*](#stream) and can throw an error without crashing the server instance.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The function requires parameters for server and stream and can throw

Instead:

The function will receive the server object and a stream as parameters. If your function throws an error it will be reported from :step() (or :loop()).

doc/index.md Outdated
- `.port`: Port to bind to (optional if tls isn't `nil`, in which case defaults to 80 for `.tls == false` or 443 if `.tls == true`)
- `.path`: Path to UNIX socket (required if not `.host`)
- `.v6only`: Allow ipv6 only (no ipv4-mapped-ipv6)
- `.mode`: (optional) fchmod or chmod socket after creating UNIX domain socket
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fchmod and chmod should be in backticks I think?

doc/index.md Outdated
- WebSockets as specified by [RFC 6455](https://tools.ietf.org/html/rfc6455) including ping/pong, binary data transfer and TLS encryption
- Transport Layer Security (TLS) - lua-http supports HTTPS and WSS via [luaossl](https://github.com/wahern/luaossl).
- Fully asynchronous API that does not block the current thread when executing operations that typically block
- Provides both client and server APIs
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you hoisted "fully asynchronous API" instead of "Provides both client and server APIs". I don't mind too much though

doc/index.md Outdated
### `server:pause()` <!-- --> {#http.server:pause}

Cause the server loop to stop processing new clients until [`:resume`](#http.server:resume) is called.
Cause the server loop to stop processing new clients until [`:resume`](#http.server:resume) is called. Existing client connections will run to until closed.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"will run to until" ?

doc/index.md Outdated
# 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. The software supports x86, x64 and Arm based systems, as well as GNU/Linux, OSX, FreeBSD and others [1]. lua-http can be utilized as a server or client and includes the following features:
lua-http is an performant, capable HTTP and WebSocket library for Lua 5.1, 5.2, 5.3 and LuaJIT. Some of the features of the library include:
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You have two spaces before "Some"

doc/index.md Outdated
### `deflate()` <!-- --> {#http.zlib.deflate}

Returns a function that deflates (compresses) a zlib stream.
Returns a function that deflates (compresses) a zlib stream.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

whitespace at end of line

doc/index.md Outdated
lua-http is an performant, capable HTTP and WebSocket library for Lua 5.1, 5.2, 5.3 and LuaJIT. Some of the features of the library include:

- 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)
- HTTP versions 1, 1.1 and 2 as specified by [RFC 7230](https://tools.ietf.org/html/rfc7230) and [RFC 7540](https://tools.ietf.org/html/rfc7540)
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

prefix with "Support for "?

doc/index.md Outdated

Each headers object has an index by field name to efficiently retrieve values by key. Keep in mind that there can be multiple values for a given field name. (e.g. an HTTP server may send two `Set-Cookie` headers).

As noted in the [Conventions](#Conventions) section, HTTP 1 request and status line fields are passed around inside of 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).
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should those strings be inside of backticks?

doc/index.md Outdated

Create a new instance of an HTTP Server by passing in table `options`:

- `.client_timeout`: Timeout (in seconds) to wait for client to send first bytes and/or complete TLS handshake (default: 10)
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think these fields need re-ordering. Possibly from most vital to rarely used.

doc/index.md Outdated
- `.cq` (optional): A cqueues controller to use
- `.ctx`: An `openssl.ssl.context` object to use for tls connections. If `nil` is passed, a self-signed context will be generated
- `.family`: (optional) Protocol family
- `.host`: Address to bind to (required if not `.path`)
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

required if not .path

needs rewording

### `server:add_socket(socket)` <!-- --> {#http.server:add_socket}

Add a new connection socket to the server for processing. The server will use the current `onstream` request handler and all `options` currently specified through the [*server.listen(options)*](#http.server.listen) constructor. `add_socket` can be used to process connection sockets obtained from an external source such as:
- Another cqueues thread with some other master socket.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

need an empty line before a list

doc/index.md Outdated

- `host` (required) a string to pass to the SOCKS server as the host to connect to. Will be resolved locally if [`.needs_resolve`](#http.socks.needs_resolve) is `true`
- `port` (required) a number to pass to the SOCKS server as the port to connect to
Negotiates a socks conneciton. `host` is a required string passed to the SOCKS server as the host address. The address will be resolved locally if [`.needs_resolve`](#http.socks.needs_resolve) is `true`. `port` is a required number to pass to the SOCKS server as the connection port.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

conneciton

doc/index.md Outdated
The function takes a string of compressed data and an end of stream flag,
it returns the uncompressed data as a string.
It will throw an error if the stream is invalid
The returned function takes a string of compressed data and an end of stream flag and returns the uncompressed data as a string. The function will throw an error if the stream is invalid.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sentence runs on for a bit. could you rephrase? (same for deflate)

doc/index.md Outdated
- `socket` should be a cqueues socket object

Returns a *http.socks* object.
Opens a file descrptor on `socket` and returns a *http.socks* object. `socket` should be a cqueues socket object
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

descrptor

doc/index.md Outdated
- `socket` should be a cqueues socket object

Returns a *http.socks* object.
Opens a file descrptor on `socket` and returns a *http.socks* object. `socket` should be a cqueues socket object
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Opens a file descrptor on socket

I dont understand that.

fdopen takes an existing cqueues.socket to use as a basis for a http.socks object.

doc/index.md Outdated
- `.ctx` (*context object*): An `openssl.ssl.context` object to use for tls connections. If `nil` is passed, a self-signed context will be generated.


The list below contains optional items that are required for more specilized services:
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ehhh, I don't really like this separated out like this.

doc/index.md Outdated
- `.ctx` (*context object*): An `openssl.ssl.context` object to use for tls connections. If `nil` is passed, a self-signed context will be generated.


The list below contains optional items that are required for more specilized services:
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also, "specilized"

@daurnimator
Copy link
Owner

@RussellHaley will you get time to work on this today?

doc/index.md Outdated
- `.port` (*number*): IP port for the local socket. Specify 0 for automatic port selection. Ports 1-1024 require the application has root privilege to run. Maximum value is 65535. If `.tls == nil` then this value is required. Othewise, the defaults are:
- `.tls == false`: then the default is 80.
- `.tls == true`: the default is 443.
- `.tls == false`: then the default is 80.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

grammar seems off. How about:

  • 80 if .tls == false
  • 443 if .tls == true

doc/index.md Outdated

- `.client_timeout` (*number*): Timeout (in seconds) to wait for client to send first bytes and/or complete TLS handshake. Default is 10 seconds.
- `.host` (*string*): Local IP address in dot-decimal or IPV6 notation. This value is required if `.path` is not specified.
- `.host` (*string*): Local IP address in dot-decimal or IPV6 notation. This value is required if `.path` is not specified.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/dot-decimal/dotted decimal/

doc/index.md Outdated
Returns a function that inflates (uncompresses) a zlib stream.

The returned function takes a string of compressed data and an end of stream flag and returns the uncompressed data as a string. The function will throw an error if the stream is invalid.
Returns a reference to a function that inflates (uncompresses) a zlib stream.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not a reference to a function, it's a function (infact it's a closure if you want to be more precise).

@coveralls
Copy link

coveralls commented Dec 15, 2016

Coverage Status

Coverage remained the same at 86.518% when pulling bbeb62e on RussellHaley:master into 5be709b on daurnimator:master.

1 similar comment
@coveralls
Copy link

Coverage Status

Coverage remained the same at 86.518% when pulling bbeb62e on RussellHaley:master into 5be709b on daurnimator:master.

@coveralls
Copy link

coveralls commented Dec 15, 2016

Coverage Status

Coverage remained the same at 86.518% when pulling 2cf16e0 on RussellHaley:master into 5be709b on daurnimator:master.

doc/index.md Outdated

Each headers object has an index by field name to efficiently retrieve values by key. Keep in mind that there can be multiple values for a given field name. (e.g. an HTTP server may send two `Set-Cookie` headers).

As noted in the [Conventions](#Conventions) section, HTTP 1 request and status line fields are passed around inside of 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).
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:status should be in quotes and backticks here.

doc/index.md Outdated
## http.server

This interface is **unstable**.
The http.server object is used to listen on sockets and respond to all types of HTTP requests. Each client request is threaded and independent of the other client requests. An `http.server` is instantiated by passing a number of options including an `onstream` response handler that processes the HTTP requests and provides a stream mechanism for response. `onstream` can also be used for testing and upgrading a request, with HTTP 1.1 to WebSockets being the notible example. The server can be made non-blocking when used in conjunction with cqueues.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inconsistent about putting "http.server" in backticks.

Spelling: notible

The server can be made non-blocking when used in conjunction with cqueues.

It is non-blocking already: onstream handlers are run in parallel

doc/index.md Outdated
This interface is **unstable**.
The http.server object is used to listen on sockets and respond to all types of HTTP requests. Each client request is threaded and independent of the other client requests. An `http.server` is instantiated by passing a number of options including an `onstream` response handler that processes the HTTP requests and provides a stream mechanism for response. `onstream` can also be used for testing and upgrading a request, with HTTP 1.1 to WebSockets being the notible example. The server can be made non-blocking when used in conjunction with cqueues.

For examples of how to use the server library, please see the example directory in the source tree.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

directory is called "examples" (plural). perhaps add a link too?

doc/index.md Outdated

Create a new instance of an HTTP Server by passing in table `options`. The following is a list of the most commonly used options:

- `.client_timeout` (*number*): Timeout (in seconds) to wait for client to send first bytes and/or complete TLS handshake. Default is 10 seconds.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move this option down? (it's not an important one)

doc/index.md Outdated
- `80` if `.tls == false`
- `443` if `.tls == true`
- `.path` (*string*): Path to UNIX a socket. This value is required if `.host` is not specified.
- `.onerror` (*function*): Function that will be called when an error occurs (default: do nothing). See [server:onerror()](#http.server:onerror)
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The default behaviour written here is incorrect.

doc/index.md Outdated

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

Returns a number or `nil` that represents a timeout in seconds.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The timeout before :step() should be called.

doc/index.md Outdated

### `server:step()` <!-- --> {#http.server:step}

Initiates a single response/request. This function can be used for fine control over the response processing. However, [*server:loop()*](#http.server:loop) is the recommended way to run the server for most applications. Returns `nil`, an error and an error message on failure.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does not initiate. It services each managed connection at most once.

doc/index.md Outdated
Returns `true` if the master socket and all client connection have been closed, `false` otherwise.


### `server:step()` <!-- --> {#http.server:step}
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:step takes a timeout

Initiates a single response/request. This function can be used for fine control over the response processing. However, [*server:loop()*](#http.server:loop) is the recommended way to run the server for most applications. Returns `nil`, an error and an error message on failure.


### `server:loop()` <!-- --> {#http.server:loop}
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

loop takes a timeout

doc/index.md Outdated
The function takes a string of compressed data and an end of stream flag,
it returns the uncompressed data as a string.
It will throw an error if the stream is invalid
The closure takes a string of compressed data and an end of stream flag (`boolean`) as parameters and returns the inflated output as a string. To improve performance across multiple calls, maintain the reference to the function and send `end_of_stream=false`. The function will throw an error if the input is invalid. See the zlib example a the end of this chapter.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'end_of_stream=false'

This style is unfamiliar.

@coveralls
Copy link

coveralls commented Dec 15, 2016

Coverage Status

Coverage remained the same at 86.518% when pulling 5db1771 on RussellHaley:master into 5be709b on daurnimator:master.

@daurnimator daurnimator merged commit 5db1771 into daurnimator:master Dec 15, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants