lua-http - Man Page

The lua-http library 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. Conversely, the library can be adapted to many common patterns.
• Can be used at a very high level without need to understand the transportation of HTTP data (other than connection addresses).
• Provides a rich low level API, if desired, for creating powerful HTTP based tools at the protocol level.

As a result of these design goals, the library is simple and unobtrusive 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.

lua-http is pure Lua code with dependencies on the following external libraries:

• 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
• lua-zlib (https://github.com/brimworks/lua-zlib) - Optional Lua bindings for zlib

lua-http can run on any operating system supported by cqueues and openssl, which at the time of writing is GNU/Linux, FreeBSD, NetBSD, OpenBSD, OSX and Solaris.

The following are two simple demonstrations of how the lua-http library can be used:

The highest level interface for clients is http.request. By constructing a request object from a URI using new_from_uri and immediately evaluating it, you can easily fetch an HTTP resource.

local http_request = require "http.request"
local headers, stream = assert(http_request.new_from_uri("http://example.com"):go())
local body = assert(stream:get_body_as_string())
if headers:get ":status" ~= "200" then
    error(body)
end
print(body)

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

local websocket = require "http.websocket"
local ws = websocket.new_from_uri("wss://echo.websocket.org")
assert(ws:connect())
assert(ws:send("koo-eee!"))
local data = assert(ws:receive())
assert(data == "koo-eee!")
assert(ws:close())

lua-http has been written to perform asynchronously so that it can be used in your application, server or game without blocking your main loop. Asynchronous operations are achieved by utilizing cqueues, a Lua/C library that incorporates Lua yielding and kernel level APIs to reduce CPU usage. All lua-http operations including DNS lookup, TLS negotiation and read/write operations will not block the main application thread when run from inside a cqueue or cqueue enabled “container”. While sometimes it is necessary to block a routine (yield) and wait for external data, any blocking API calls take an optional timeout to ensure good behaviour of networked applications and avoid unresponsive or “dead” routines.

Asynchronous operations are one of the most powerful features of lua-http and require no effort on the developers part. For instance, an HTTP server can be instantiated within any Lua main loop and run alongside application code without adversely affecting the main application process. If other cqueue enabled components are integrated within a cqueue loop, the application is entirely event driven through kernel level polling APIs.

cqueues can be used in conjunction with lua-http to integrate other features into your lua application and create powerful, performant, web enabled applications. Some of the examples in this guide will use cqueues for simple demonstrations. For more resources about cqueues, please see:

• The cqueues website (http://25thandclement.com/~william/projects/cqueues.html) for more information about the cqueues library.
• cqueues examples can be found with the cqueues source code available through git or archives (http://www.25thandclement.com/~william/projects/cqueues.html#download) or accessed online here (https://github.com/wahern/cqueues/tree/master/examples).
• 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).

The following is a list of API conventions and general reference:

• 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).
• Header fields should always be used with lower case keys.

• Invalid function parameters will throw a lua error (if validated).
• Errors are returned as nil, error, errno unless noted otherwise.
• Some HTTP 2 operations return/throw special http 2 error objects.

All operations that may block the current thread take a timeout argument. This argument is always the number of seconds to allow before returning nil, err_msg, ETIMEDOUT where err_msg is a localised error message such as "connection timed out".

Much lua-http terminology is borrowed from HTTP 2.

Connection - An abstraction over an underlying TCP/IP socket. lua-http currently has two connection types: one for HTTP 1, one for HTTP 2.

Stream - A request/response on a connection object. lua-http has two stream types: one for HTTP 1 streams, and one for HTTP 2 streams. The common interfaces is described in stream.

A connection encapsulates a socket and provides protocol specific operations. A connection may have streams which encapsulate the requests/responses happening over a conenction. Alternatively, you can ignore streams entirely and use low level protocol specific operations to read and write to the socket.

All connection types expose the following fields:

The mode of use for the connection object. Valid values are:

• "client": Acts as a client; this connection type is used by entities who want to make requests
• "server": Acts as a server; this conenction type is used by entities who want to respond to requests

The HTTP version number of the connection as a number.

Completes the connection to the remote server using the address specified, HTTP version and any options specified in the connection.new constructor. The connect function will yield until the connection attempt finishes (success or failure) or until timeout is exceeded. Connecting may include DNS lookups, TLS negotiation and HTTP2 settings exchange. Returns true on success. On error, returns nil, an error message and an error number.

Checks the socket for a valid Transport Layer Security connection. Returns the luaossl ssl object if the connection is secured. Returns nil and an error message if there is no active TLS session. Please see the luaossl website (http://25thandclement.com/~william/projects/luaossl.html) for more information about the ssl object.

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). On error, returns nil, an error message and an error number.

Returns the connection information for the socket peer (as in, the next hop). Returns address family, IP address and 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). On error, returns nil, an error message and an error number.

Note: If the client is using a proxy, the values returned :peername() point to the proxy, not the remote server.

Flushes buffered outgoing data on the socket to the operating system. Returns true on success. On error, returns nil, an error message and an error number.

Performs an orderly shutdown of the connection by closing all streams and calls :shutdown() on the socket. The connection cannot be re-opened.

Closes a connection and releases operating systems resources. Note that :close() performs a connection:shutdown() prior to releasing resources.

Creates and returns a new stream on the connection.

Returns the next peer initiated stream on the connection. This function can be used to yield and “listen” for incoming HTTP streams.

Provide a callback to get called when the connection becomes idle i.e. when there is no request in progress and no pipelined streams waiting. When called it will receive the connection as the first argument. Returns the previous handler.

An HTTP stream is an abstraction of a request/response within a HTTP connection. Within a stream there may be a number of “header” blocks as well as data known as the “body”.

All stream types expose the following fields and functions:

The underlying connection object.

Convenience wrapper equivalent to stream.connection:checktls()

Convenience wrapper equivalent to stream.connection:localname()

Convenience wrapper equivalent to stream.connection:peername()

Retrieves the next complete headers object (i.e. a block of headers or trailers) from the stream.

Write the given 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 stream will wait for the send to complete until timeout is exceeded.

Sends a 100-continue header block.

Returns the next chunk of the http body from the socket, potentially yielding for up to timeout seconds. On error, returns nil, an error message and an error number.

Iterator over stream:get_next_chunk()

Reads the entire body from the stream and return it as a string. On error, returns nil, an error message and an error number.

Reads n characters (bytes) of body from the stream and return them as a string. If the stream ends before n characters are read then returns the partial result. On error, returns nil, an error message and an error number.

Reads in body data from the stream until the lua pattern (http://www.lua.org/manual/5.3/manual.html#6.4.1) pattern is found and returns the data as a string. plain is a boolean that indicates that pattern matching facilities should be turned off so that function does a plain “find substring” operation, with no characters in pattern being considered magic. include_patterns specifies if the pattern itself should be included in the returned string. On error, returns nil, an error message and an error number.

Reads the body from the stream and saves it to the lua file handle (http://www.lua.org/manual/5.3/manual.html#6.8) file. On error, returns nil, an error message and an error number.

Reads the body from the stream into a temporary file and returns a lua file handle (http://www.lua.org/manual/5.3/manual.html#6.8). On error, returns nil, an error message and an error number.

Places str back on the incoming data buffer, allowing it to be returned again on a subsequent command (“un-gets” the data). Returns true on success. On error, returns nil, an error message and an error number.

Writes the string chunk to the stream. If end_stream is true, the body will be finalized and the stream will be closed. write_chunk yields indefinitely, or until timeout is exceeded. On error, returns nil, an error message and an error number.

Writes the string str to the stream and ends the stream. On error, returns nil, an error message and an error number.

• options is a table containing:

  • .file (file)
  • .count (positive integer): number of bytes of file to write

  defaults to infinity (the whole file will be written)

Writes the contents of file file to the stream and ends the stream. file will not be automatically seeked, so ensure it is at the correct offset before calling. On error, returns nil, an error message and an error number.

Closes the stream. The resources are released and the stream can no longer be used.

An abstraction layer over the various lua bit libraries.

Results are only consistent between underlying implementations when parameters and results are in the range of 0 to 0x7fffffff.

Bitwise And operation.

Bitwise Or operation.

Bitwise XOr operation.

local bit = require "http.bit"
print(bit.band(1, 3)) --> 1

Deals with obtaining a connection to an HTTP server.

Negotiates the HTTP settings with the remote server. If TLS has been specified, this function instantiates the encryption tunnel. Parameters are as follows:

• socket is a cqueues socket object

• options is a table containing:

  • .tls (boolean, optional): Should TLS be used?

  defaults to false

  • .ctx (userdata, optional): the SSL_CTX* to use if .tls is true.

  If .ctx is nil then a default context will be used.

  • .sendname (string|boolean, optional): the TLS SNI (https://en.wikipedia.org/wiki/Server_Name_Indication) host to send.

  defaults to true

  • true indicates to copy the .host field as long as it is not an IP
  • false disables SNI

  • .version (nil|1.0|1.1|2): HTTP version to use.

    • nil: attempts HTTP 2 and falls back to HTTP 1.1
    • 1.0
    • 1.1
    • 2
  • .h2_settings (table, optional): HTTP 2 settings to use. See http.h2_connection for details

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 and h2_stream.new_stream for more information about creating streams.

• options is a table containing the options to http.client.negotiate, plus the following:

  • family (integer, optional): socket family to use.

  defaults to AF_INET

  • host (string): host to connect to.

  may be either a hostname or an IP address

  • port (string|integer): port to connect to in numeric form

  e.g. "80" or 80

  • path (string): path to connect to (UNIX sockets)
  • v6only (boolean, optional): if the IPV6_V6ONLY flag should be set on the underlying socket.
  • bind (string, optional): the local outgoing address and optionally port to bind in the form of "address[:port]", IPv6 addresses may be specified via square bracket notation. e.g. "127.0.0.1", "127.0.0.1:50000", "[::1]:30000".
• timeout (optional) is the maximum amount of time (in seconds) to allow for connection to be established.

This includes time for DNS lookup, connection, TLS negotiation (if TLS enabled) and in the case of HTTP 2: settings exchange.

Connect to a local HTTP server running on port 8000

local http_client = require "http.client"
local myconnection = http_client.connect {
    host = "localhost";
    port = 8000;
    tls = false;
}

A module for working with cookies.

Returns a string suitable for use in a Set-Cookie header with the passed parameters.

Parses the Cookie header contents cookie.

Returns a table containing name and value pairs as strings.

Parses all Cookie headers in the http.headers object req_headers.

Returns a table containing name and value pairs as strings.

Parses the Set-Cookie header contents setcookie.

Returns name, value and params where:

• name is a string containing the cookie name
• value is a string containing the cookie value
• params is the a table where the keys are cookie attribute names and values are cookie attribute values

Creates a new cookie store.

Cookies are unique for a tuple of domain, path and name; although multiple cookies with the same name may exist in a request due to overlapping paths or domains.

A lua-psl (https://github.com/daurnimator/lua-psl) object to use for checking against the Public Suffix List. Set the field to false to skip checking the suffix list.

Defaults to the latest (https://rockdaboot.github.io/libpsl/libpsl-Public-Suffix-List-functions.html#psl-latest) PSL on the system. If lua-psl is not installed then it will be nil.

A function used by the store to get the current time for expiries and such.

Defaults to a function based on os.time (https://www.lua.org/manual/5.3/manual.html#pdf-os.time).

The maximum length (in bytes) of cookies in the store; this value is also used as default maximum cookie length for :lookup(). Decreasing this value will only prevent new cookies from being added, it will not remove old cookies.

Defaults to infinity (no maximum size).

The maximum number of cookies allowed in the store. Decreasing this value will only prevent new cookies from being added, it will not remove old cookies.

Defaults to infinity (any number of cookies is allowed).

The maximum number of cookies allowed in the store per domain. Decreasing this value will only prevent new cookies from being added, it will not remove old cookies.

Defaults to infinity (any number of cookies is allowed).

Attempts to add a cookie to the store.

• req_domain is the domain that the cookie was obtained from
• req_path is the path that the cookie was obtained from
• req_is_http is a boolean flag indicating if the cookie was obtained from a “non-HTTP” API
• req_is_secure is a boolean flag indicating if the cookie was obtained from a “secure” protocol
• req_site_for_cookies is a string containing the host that should be considered as the “site for cookies” (See RFC 6265bis-02 Section 5.2 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#section-5.2)), can be nil if unknown.
• name is a string containing the cookie name
• value is a string containing the cookie value
• params is the a table where the keys are cookie attribute names and values are cookie attribute values

Returns a boolean indicating if a cookie was stored.

Attempt to store any cookies found in the response headers.

• req_headers is the http.headers object for the outgoing request
• resp_headers is the http.headers object received in response
• req_host is the host that your query was directed at (only used if req_headers is missing a Host header)
• req_site_for_cookies is a string containing the host that should be considered as the “site for cookies” (See RFC 6265bis-02 Section 5.2 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#section-5.2)), can be nil if unknown.

Returns the cookie value for the cookie stored for the passed domain, path and name.

Deletes the cookie stored for the passed domain, path and name.

If name is nil or not passed then all cookies for the domain and path are removed.

If path is nil or not passed (in addition to name) then all cookies for the domain are removed.

Finds cookies visible to suitable for passing to an entity.

• domain is the domain that will be sent the cookie
• path is the path that will be sent the cookie
• is_http is a boolean flag indicating if the destination is a “non-HTTP” API
• is_secure is a boolean flag indicating if the destination will be communicated with over a “secure” protocol
• is_safe_method is a boolean flag indicating if the cookie will be sent via a safe HTTP method (See also http.util.is_safe_method)
• site_for_cookies is a string containing the host that should be considered as the “site for cookies” (See RFC 6265bis-02 Section 5.2 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#section-5.2)), can be nil if unknown.
• is_top_level is a boolean flag indicating if this request is a “top level” request (See RFC 6265bis-02 Section 5.2 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#section-5.2))
• max_cookie_length is the maximum cookie length to allow (See also store.max_cookie_length)

Returns a string suitable for use in a Cookie header.

Finds cookies suitable for adding to a request.

• headers is the http.headers object for the outgoing request
• host is the host that your query was directed at (only used if headers is missing a Host header)
• site_for_cookies is a string containing the host that should be considered as the “site for cookies” (See RFC 6265bis-02 Section 5.2 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#section-5.2)), can be nil if unknown.
• is_top_level is a boolean flag indicating if this request is a “top level” request (See RFC 6265bis-02 Section 5.2 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#section-5.2))
• max_cookie_length is the maximum cookie length to allow (See also store.max_cookie_length)

Returns a string suitable for use in a Cookie header.

Returns the number of seconds until the next cookie in the store expires.

Remove all expired cookies from the store.

Loads cookie data from the file object file into store. The file should be in the Netscape Cookiejar format. Invalid lines in the file are ignored.

Returns true on success or passes along nil, err, errno if a :read call fails.

Writes the cookie data from store into the file object file in the Netscape Cookiejar format. file is not seek-ed or truncated before writing.

Returns true on success or passes along nil, err, errno if a :write call fails.

The h1_connection module adheres to the connection interface and provides HTTP 1 and 1.1 specific operations.

Constructor for a new connection. Takes a cqueues socket object, a connection type string and a numeric HTTP version number. Valid values for the connection type are "client" and "server". Valid values for the version number are 1 and 1.1. Returns the newly initialized connection object.

Specifies the HTTP version used for the connection handshake. Valid values are:

• 1.0
• 1.1

See connection.version

See connection:pollfd()

See connection:events()

See connection:timeout()

See connection:connect(timeout)

See connection:checktls()

See connection:localname()

See connection:peername()

See connection:flush(timeout)

Shut down is as graceful as possible: pipelined streams are shutdown, then the underlying socket is shut down in the appropriate direction(s).

dir is a string representing the direction of communication to shut down communication in. If it contains "r" it will shut down reading, if it contains "w" it will shut down writing. The default is "rw", i.e. to shutdown communication in both directions.

See connection:shutdown()

See connection:close()

In HTTP 1, only a client may initiate new streams with this function.

See connection:new_stream() for more information.

See connection:get_next_incoming_stream(timeout)

See connection:onidle(new_handler)

Sets the maximum read buffer size (in bytes) to read_length. i.e. sets the maximum length lines (such as headers).

The default comes from the underlying socket, which gets the (changable) cqueues default at time of construction. The default cqueues default is 4096 bytes.

Clears errors to allow for further read or write operations on the connection. Returns the error number of existing errors. This function is used to recover from known errors.

Returns the error number of existing errors.

Used to hand the reference of the connection socket to another object. Resets the socket to defaults and returns the single existing reference of the socket to the calling routine. This function can be used for connection upgrades such as upgrading from HTTP 1 to a WebSocket.

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 chunk is not a valid HTTP request line, nil is returned. On error, returns nil, an error message and an error number.

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 chunk is received, or timeout is exceeded. If the socket could not be read, returns nil, an error message and an error number.

Reads a CRLF terminated HTTP header from the socket and returns the header key and value. This function will yield until a MIME compliant header item is received or until timeout is exceeded. If the header could not be read, the function returns nil an error and an error message.

Checks for an empty line, 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.

Get len number of bytes from the socket. 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.

Reads the entire request body. This function will yield until the body is complete or timeout is expired. If the read fails the function returns nil, an error message and an error number.

Reads the next available line of data from the request and returns the chunk and any chunk extensions. This function will yield until chunk size is received or timeout is exceeded. If the chunk size is indicated as 0 then false and any chunk extensions are returned. Returns nil, an error message and an error number if there was an error reading reading the chunk header or the socket.

Writes the opening HTTP 1.x request line for a new request to the socket buffer. Yields until success or timeout. If the write fails, returns nil, an error message and an error number.

Note the request line will not be flushed to the remote server until write_headers_done is called.

Writes an HTTP status line to the socket buffer. Yields until success or timeout. If the write fails, the function returns nil, an error message and an error number.

Note the status line will not be flushed to the remote server until write_headers_done is called.

Writes a header item to the socket buffer as a key:value string. Yields until success or timeout. Returns nil, an error message and an error if the write fails.

Note the header item will not be flushed to the remote server until write_headers_done is called.

Terminates a header block by writing a blank line ("\r\n") to the socket. This function will flush all outstanding data in the socket output buffer. Yields until success or timeout. Returns nil, an error message and an error if the write fails.

Writes a chunk 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.

Writes the chunked body terminator "0\r\n" to the socket. chunk_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.

Note that the connection will not be immediately flushed to the remote server; normally this will occur when trailers are written.

Writes the contents of body to the socket and flushes the socket output buffer immediately. Yields until success or timeout is exceeded. Returns nil, an error message and an error number if the write fails.

A table mapping from status codes (as strings) to reason phrases for HTTP 1. Any unknown status codes return "Unassigned"

local reason_phrases = require "http.h1_reason_phrases"
print(reason_phrases["200"]) --> "OK"
print(reason_phrases["342"]) --> "Unassigned"

The h1_stream module adheres to the stream interface and provides HTTP 1.x specific operations.

The gzip transfer encoding is supported transparently.

See stream.connection

The maximum number of header lines to read. Default is 100.

See stream:checktls()

See stream:localname()

See stream:peername()

See stream:get_headers(timeout)

See stream:write_headers(headers, end_stream, timeout)

See stream:write_continue(timeout)

See stream:get_next_chunk(timeout)

See stream:each_chunk()

See stream:get_body_as_string(timeout)

See stream:get_body_chars(n, timeout)

See stream:get_body_until(pattern, plain, include_pattern, timeout)

See stream:save_body_to_file(file, timeout)

See stream:get_body_as_file(timeout)

See stream:unget(str)

See stream:write_chunk(chunk, end_stream, timeout)

See stream:write_body_from_string(str, timeout)

See stream:write_body_from_file(options|file, timeout)

See stream:shutdown()

Sets the state of the stream to new. new must be one of the following valid states:

• "open": have sent or received headers; haven’t sent body yet
• "half closed (local)": have sent whole body
• "half closed (remote)": have received whole body
• "closed": complete

Not all state transitions are allowed.

Reads and returns a header block from the underlying connection. Does not take into account buffered header blocks. On error, returns nil, an error message and an error number.

This function should rarely be used, you’re probably looking for :get_headers().

Reads and returns the next chunk as a string from the underlying connection. Does not take into account buffered chunks. On error, returns nil, an error message and an error number.

This function should rarely be used, you’re probably looking for :get_next_chunk().

The h2_connection module adheres to the connection interface and provides HTTP 2 specific operations. An HTTP 2 connection can have multiple streams actively transmitting data at once, hence an http.h2_connection acts much like a scheduler.

Constructor for a new connection. Takes a cqueues socket object, a connection type string and an optional table of HTTP 2 settings. Returns the newly initialized connection object in a non-connected state.

Contains the HTTP connection version. Currently this will always be 2.

See connection.version

See connection:pollfd()

See connection:events()

See connection:timeout()

See connection:connect(timeout)

See connection:checktls()

See connection:localname()

See connection:peername()

See connection:flush(timeout)

See connection:shutdown()

See connection:close()

Create and return a new h2_stream. id (optional) is the stream id to assign the new stream, if not specified for client initiated streams this will be the next free odd numbered stream, for server initiated streams this will be the next free even numbered stream.

See connection:new_stream() for more information.

See connection:get_next_incoming_stream(timeout)

See connection:onidle(new_handler)

A type of error object that encapsulates HTTP 2 error information. An http.h2_error object has fields:

• name: The error name: a short identifier for this error
• code: The error code
• description: The description of the error code
• message: An error message
• traceback: A traceback taken at the point the error was thrown
• stream_error: A boolean that indicates if this is a stream level or protocol level error

A table containing errors as defined by the HTTP 2 specification (https://http2.github.io/http2-spec/#iana-errors). It can be indexed by error name (e.g. errors.PROTOCOL_ERROR) or numeric code (e.g. errors[0x1]).

Returns a boolean indicating if the object ob is an http.h2_error object

Creates a new error object from the passed table. The table should have the form of an error object i.e. with fields name, code, message, traceback, etc.

Fields name, code and description are inherited from the parent h2_error object if not specified.

stream_error defaults to false.

Creates a new error object, recording a traceback from the current thread.

Creates and throws a new error.

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.

An h2_stream represents an HTTP 2 stream. The module follows the stream interface as well as HTTP 2 specific functions.

See stream.connection

See stream:checktls()

See stream:localname()

See stream:peername()

See stream:get_headers(timeout)

See stream:write_headers(headers, end_stream, timeout)

See stream:write_continue(timeout)

See stream:get_next_chunk(timeout)

See stream:each_chunk()

See stream:get_body_as_string(timeout)

See stream:get_body_chars(n, timeout)

See stream:get_body_until(pattern, plain, include_pattern, timeout)

See stream:save_body_to_file(file, timeout)

See stream:get_body_as_file(timeout)

See stream:unget(str)

See stream:write_chunk(chunk, end_stream, timeout)

See stream:write_body_from_string(str, timeout)

See stream:write_body_from_file(options|file, timeout)

See stream:shutdown()

Writes a frame with h2_stream’s stream id.

See h2_connection:write_http2_frame(typ, flags, streamid, payload, timeout, flush)

Pushes a new promise to the client.

Returns the new stream as a h2_stream.

An ordered list of header fields. Each field has a name, a value and a never_index flag that indicates if the header field is potentially sensitive data.

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 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).

Creates and returns a new headers object.

Returns the number of headers.

Also available as #headers in Lua 5.2+.

Creates and returns a clone of the headers object.

Append a header.

• name is the header field name. Lower case is the convention. It will not be validated at this time.
• value is the header field value. It will not be validated at this time.
• never_index is an optional boolean that indicates if the value should be considered secret. Defaults to true for header fields: authorization, proxy-authorization, cookie and set-cookie.

An iterator over all headers that emits name, value, never_index.

local http_headers = require "http.headers"
local myheaders = http_headers.new()
myheaders:append(":status", "200")
myheaders:append("set-cookie", "foo=bar")
myheaders:append("connection", "close")
myheaders:append("set-cookie", "baz=qux")
for name, value, never_index in myheaders:each() do
    print(name, value, never_index)
end
--[[ prints:
":status", "200", false
"set-cookie", "foo=bar", true
"connection", "close", false
"set-cookie", "baz=qux", true
]]

Returns a boolean indicating if the headers object has a field with the given name.

Removes all occurrences of a field name from the headers object.

Return the i-th header as name, value, never_index

Returns all headers with the given name in a table. The table will contain a field .n with the number of elements.

local http_headers = require "http.headers"
local myheaders = http_headers.new()
myheaders:append(":status", "200")
myheaders:append("set-cookie", "foo=bar")
myheaders:append("connection", "close")
myheaders:append("set-cookie", "baz=qux")
local mysequence = myheaders:get_as_sequence("set-cookie")
--[[ mysequence will be:
{n = 2; "foo=bar"; "baz=qux"}
]]

Returns all headers with the given name as multiple return values.

Returns all headers with the given name as items in a comma separated string.

Change the i-th’s header to a new value and never_index.

If a header with the given name already exists, replace it. If not, append it to the list of headers.

Cannot be used when a header name already has multiple values.

Sort the list of headers by their field name, ordering those starting with : first. If names are equal then sort by value, then by never_index.

Print the headers list to the given file, one per line. If file is not given, then print to stderr. prefix is prefixed to each line.

Data structures useful for HSTS (HTTP Strict Transport Security)

Creates and returns a new HSTS store.

The maximum number of items allowed in the store. Decreasing this value will only prevent new items from being added, it will not remove old items.

Defaults to infinity (any number of items is allowed).

Creates and returns a copy of a store.

Add new directives to the store about the given host. directives should be a table of directives, which must include the key "max-age".

Returns a boolean indicating if the item was accepted.

Removes the entry for host from the store (if it exists).

Returns a boolean indicating if the given host is a known HSTS host.

Returns the number of seconds until the next item in the store expires.

Removes expired entries from the store.

Returns an empty `proxies' object

getenv defaults to os.getenv (http://www.lua.org/manual/5.3/manual.html#pdf-os.getenv)

Reads environmental variables that are used to control if requests go through a proxy.

• http_proxy (or CGI_HTTP_PROXY if running in a program with GATEWAY_INTERFACE set): the proxy to use for normal HTTP connections
• https_proxy or HTTPS_PROXY: the proxy to use for HTTPS connections
• all_proxy or ALL_PROXY: the proxy to use for all connections, overridden by other options
• no_proxy or NO_PROXY: a list of hosts to not use a proxy for

Returns proxies.

Returns the proxy to use for the given scheme and host as a URI.

The http.request module encapsulates all the functionality required to retrieve an HTTP document from a server.

Creates a new http.request object from the given URI.

Creates a new http.request object from the given URI that will perform a CONNECT request.

The host this request should be sent to.

The port this request should be sent to.

The local outgoing address and optionally port to bind in the form of "address[:port]". Default is to allow the kernel to choose an address+port.

IPv6 addresses may be specified via square bracket notation. e.g. "127.0.0.1", "127.0.0.1:50000", "[::1]:30000".

This option is rarely needed. Supplying an address can be used to manually select the network interface to make the request from, while supplying a port is only really used to interoperate with firewalls or devices that demand use of a certain port.

A boolean indicating if TLS should be used.

An alternative SSL_CTX* to use. If not specified, uses the default TLS settings (see http.tls for information).

The TLS SNI host name used.

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

Specifies the a proxy that the request will be made through. The value should be a URI or false to turn off proxying for the request.

A http.headers object of headers that will be sent in the request.

The http.hsts store that will be used to enforce HTTP strict transport security. An attempt will be made to add strict transport headers from a response to the store.

Defaults to a shared store.

The http.proxies object used to select a proxy for the request. Only consulted if request.proxy is nil.

The http.cookie.store that will be used to find cookies for the request. An attempt will be made to add cookies from a response to the store.

Defaults to a shared store.

A boolean flag indicating if this request is a “top level” request (See RFC 6265bis-02 Section 5.2 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#section-5.2))

Defaults to true

A string containing the host that should be considered as the “site for cookies” (See RFC 6265bis-02 Section 5.2 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#section-5.2)), can be nil if unknown.

Defaults to nil.

Boolean indicating if :go() should follow redirects. Defaults to true.

Number of seconds to wait for a 100 Continue response before proceeding to send a request body. Defaults to 1.

Maximum number of redirects to follow before giving up. Defaults to 5. Set to math.huge to not give up.

Respect RFC 2616 Section 10.3.2 and don’t convert POST requests into body-less GET requests when following a 301 redirect. The non-RFC behaviour is ubiquitous in web browsers and assumed by servers. Modern HTTP endpoints send status code 308 to indicate that they don’t want the method to be changed. Defaults to false.

Respect RFC 2616 Section 10.3.3 and don’t convert POST requests into body-less GET requests when following a 302 redirect. The non-RFC behaviour is ubiquitous in web browsers and assumed by servers. Modern HTTP endpoints send status code 307 to indicate that they don’t want the method to be changed. Defaults to false.

Creates and returns a clone of the request.

The clone has its own deep copies of the .headers and .h2_settings fields.

The .tls and .body fields are shallow copied from the original request.

Process a redirect.

headers should be response headers for a redirect.

Returns a new request object that will fetch from new location.

Returns a URI for the request.

If with_userinfo is true and the request has an authorization header (or proxy-authorization for a CONNECT request), the returned URI will contain a userinfo component.

Allows setting a request body. body may be a string, function or lua file object.

• 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 lua file object, it will be :seek’d (http://www.lua.org/manual/5.3/manual.html#pdf-file:seek) to the start, then sent as a body. Any errors encountered during file operations will be thrown.

Performs the request.

The request object is not invalidated; and can be reused for a new request. On success, returns the response headers and a stream.

http.server objects are used to encapsulate the accept() and dispatch of http clients. Each new client request will invoke the onstream callback in a new cqueues managed coroutine. In addition to constructing and returning a HTTP response, an onstream handler may decide to take ownership of the connection for other purposes, e.g. upgrade from a HTTP 1.1 connection to a WebSocket connection.

For examples of how to use the server library, please see the examples directory (https://github.com/daurnimator/lua-http/tree/master/examples) in the source tree.

Creates a new instance of an HTTP server listening on the given socket.

• .socket (cqueues.socket): the socket that accept() will be called on
• .onerror (function): Function that will be called when an error occurs (default handler throws an error). See server:onerror()
• .onstream (function): Callback function for handling a new client request. The function receives the server and the new stream as parameters. If the callback throws an error it will be reported from :step() or :loop()

• .tls (boolean): Specifies if the system should use Transport Layer Security. Values are:

  • nil: Allow both tls and non-tls connections
  • true: Allows tls connections only
  • false: Allows non-tls connections only
• .ctx (context object): An openssl.ssl.context object to use for tls connections. If nil is passed, a self-signed context will be generated.
• .connection_setup_timeout (number): Timeout (in seconds) to wait for client to send first bytes and/or complete TLS handshake. Default is 10 seconds.
• .intra_stream_timeout (number): Timeout (in seconds) to wait for a new stream on an idle connection before giving up and closing the connection
• .version (number): The http version to allow to connect (default: any)
• .cq (cqueue): A cqueues controller to use as a main loop. The default is a new controller for the server.
• .max_concurrent (number): Maximum number of connections to allow live at a time. Default is infinity.

Creates a new socket and returns an HTTP server that will accept() from it. Parameters are the same as new(options) except instead of .socket you provide the following:

• .host (string): Local IP address in dotted decimal or IPV6 notation. This value is required if .path is not specified.

• .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. Otherwise, the defaults are:

  • 80 if .tls == false
  • 443 if .tls == true
• .path (string): Path to UNIX a socket. This value is required if .host is not specified.
• .family (string): Protocol family. Default is "AF_INET"
• .v6only (boolean): Specify true to limit all connections to ipv6 only (no ipv4-mapped-ipv6). Default is false.
• .mode (string): fchmod or chmod socket after creating UNIX domain socket.
• .mask (boolean): Set and restore umask when binding UNIX domain socket.
• .unlink (boolean): true means unlink socket path before binding.
• .reuseaddr (boolean): Turn on SO_REUSEADDR flag.
• .reuseport (boolean): Turn on SO_REUSEPORT flag.

If called with parameters, the function replaces the current error handler function with new_handler and returns a reference to the old function. Calling the function with no parameters returns the current error handler. The default handler throws an error. The onerror function for the server can be set during instantiation through the options table passed to the server.listen(options) function.

Initializes the server socket and if required, resolves DNS. server:listen() is required if localname is called before step or loop. On error, returns nil, an error message and an error number.

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). On error, returns nil, an error message and an error number.

Cause the server loop to stop processing new clients until resume is called. Existing client connections will run until closed.

Resumes a paused server and processes new client requests.

Shutdown the server and close the socket. A closed server cannot be reused.

Returns a file descriptor (as an integer) or nil.

The file descriptor can be passed to a system API like select or kqueue to wait on anything this server object wants to do. This method is used for integrating with other main loops, and should be used in combination with :events() and :timeout().

Returns a string indicating the type of events the object is waiting on: the string will contain "r" if it wants to be steped when the file descriptor returned by pollfd() has had POLLIN indicated; "w" for POLLOUT or "p" for POLLPRI.

This method is used for integrating with other main loops, and should be used in combination with :pollfd() and :timeout().

The maximum time (in seconds) to wait before calling server:step().

This method is used for integrating with other main loops, and should be used in combination with :pollfd() and :events().

Returns true if the master socket and all client connection have been closed, false otherwise.

Step once through server’s main loop: any waiting clients will be accept()-ed, any pending streams will start getting processed, and each onstream handler will get be run at most once. This method will block for up to timeout seconds. On error, returns nil, an error message and an error number.

This can be used for integration with external main loops.

Run the server as a blocking loop for up to timeout seconds. The server will continue to listen and accept client requests until either :pause() or :close() is called, or an error is experienced.

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) 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.
• From inetd for start on demand daemons.
• A Unix socket with SCM_RIGHTS.

Add an existing stream to the server for processing.

Implements a subset of the SOCKS proxy protocol.

uri is a string with the address of the SOCKS server. A scheme of "socks5" will resolve hosts locally, a scheme of "socks5h" will resolve hosts on the SOCKS server. If the URI has a userinfo component it will be sent to the SOCKS server as a username and password.

Returns a http.socks object.

This function takes an existing cqueues.socket as a parameter and returns a http.socks object with socket as its base.

Specifies if the destination host should be resolved locally.

Make a clone of a given socks object.

Add username + password authorisation to the set of allowed authorisation methods with the given credentials.

Complete the SOCKS connection.

Negotiates a socks connection. host is a required string passed to the SOCKS server as the host address. The address will be resolved locally if .needs_resolve is true. port is a required number to pass to the SOCKS server as the connection port. On error, returns nil, an error message and an error number.

Take possession of the socket object managed by the http.socks object. Returns the socket (or nil if not available).

Boolean indicating if ALPN is available in the current environment.

It may be disabled if OpenSSL was compiled without ALPN support, or is an old version.

Boolean indicating if hostname validation (https://wiki.openssl.org/index.php/Hostname_validation) is available in the current environment.

It may be disabled if OpenSSL is an old version.

The Mozilla “Modern” cipher list (https://wiki.mozilla.org/Security/Server_Side_TLS#Modern_compatibility) as a colon separated list, ready to pass to OpenSSL

The Mozilla “Intermediate” cipher list (https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28default.29) as a colon separated list, ready to pass to OpenSSL

The Mozilla “Old” cipher list (https://wiki.mozilla.org/Security/Server_Side_TLS#Old_backward_compatibility) as a colon separated list, ready to pass to OpenSSL

A set (table with string keys and values of true) of the ciphers banned in HTTP 2 (https://http2.github.io/http2-spec/#BadCipherSuites) where the keys are OpenSSL cipher names.

Ciphers not known by OpenSSL are missing from the set.

Create and return a new luaossl SSL context useful for HTTP client connections.

Create and return a new luaossl SSL context useful for HTTP server connections.

Returns an iterator over the pairs in str

local http_util = require "http.util"
for name, value in http_util.query_args("foo=bar&baz=qux") do
    print(name, value)
end
--[[ prints:
"foo", "bar"
"baz", "qux"
]]

Converts a dictionary (table with string keys) with string values to an encoded query string.

local http_util = require "http.util"
print(http_util.dict_to_query({foo = "bar"; baz = "qux"})) --> "baz=qux&foo=bar"

Returns a boolean indicating if the passed string method is a “safe” method. See RFC 7231 section 4.2.1 (https://tools.ietf.org/html/rfc7231#section-4.2.1) for more information.

Returns a boolean indicating if the passed string str is a valid IP.

Map from schemes (as strings) to default ports (as integers).

Splits an authority into host and port components. If the authority has no port component, will attempt to use the default for the scheme.

local http_util = require "http.util"
print(http_util.split_authority("localhost:8000", "http")) --> "localhost", 8000
print(http_util.split_authority("example.com", "https")) --> "localhost", 443

Joins the host and port to create a valid authority component. Omits the port if it is the default for the scheme.

Returns the time in HTTP preferred date format (See RFC 7231 section 7.1.1.1 (https://tools.ietf.org/html/rfc7231#section-7.1.1.1))

time defaults to the current time

• 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

"lua-http"

Current version of lua-http as a string.

Creates a new http.websocket object of type "client" from the given URI.

• protocols (optional) should be a lua table containing a sequence of protocols to send to the server

Attempts to create a new http.websocket object of type "server" from the given request headers and stream.

• stream should be a live HTTP 1 stream of the "server" type.
• headers should be headers of a suspected websocket upgrade request from an HTTP 1 client.

This function does not have side effects, and is hence okay to use tentatively.

Amount of time (in seconds) to wait between sending a close frame and actually closing the connection. Defaults to 3 seconds.

Completes negotiation with a websocket client.

• options is a table containing:

  • headers (optional) a headers object to use as a prototype for the response headers
  • protocols (optional) should be a lua table containing a sequence of protocols to allow from the client

Usually called after a successful new_from_stream

Connect to a websocket server.

Usually called after a successful new_from_uri

Reads and returns the next data frame plus its opcode. Any ping frames received while reading will be responded to.

The opcode 0x1 will be returned as "text" and 0x2 will be returned as "binary".

Iterator over websocket:receive().

Low level function to send a raw frame.

Send the given data as a data frame.

• data should be a string
• opcode can be a numeric opcode, "text" or "binary". If nil, defaults to a text frame. Note this opcode is the websocket frame opcode, not an application specific opcode. The opcode should be one from the IANA registry (https://www.iana.org/assignments/websocket/websocket.xhtml#opcode).

Sends a ping frame.

• data is optional

Sends a pong frame. Works as a unidirectional keep-alive.

• data is optional

Closes the websocket connection.

• code defaults to 1000
• reason is an optional string

An abstraction layer over the various lua zlib libraries.

Currently either "lua-zlib" (https://github.com/brimworks/lua-zlib) or "lzlib" (https://github.com/LuaDist/lzlib)

Returns a closure that inflates (uncompresses) a zlib stream.

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. The function will throw an error if the input is not a valid zlib stream.

Returns a closure that deflates (compresses) a zlib stream.

The closure takes a string of uncompressed data and an end of stream flag (boolean) as parameters and returns the deflated output as a string.

local zlib = require "http.zlib"
local original = "the racecar raced around the racecar track"
local deflater = zlib.deflate()
local compressed = deflater(original, true)
print(#original, #compressed) -- compressed should be smaller
local inflater = zlib.inflate()
local uncompressed = inflater(compressed, true)
assert(original == uncompressed)

Provides usage similar to prosody’s net.http (https://prosody.im/doc/developers/net/http)

A few key differences to the prosody net.http.request:

• must be called from within a running cqueue
• The callback may be called from a different thread in the cqueue

• The returned object will be a http.request object

  • This object is passed to the callback on errors and as the fourth argument on success
• The default user-agent will be from lua-http (rather than "Prosody XMPP Server")
• lua-http features (such as HTTP2) will be used where possible

local prosody_http = require "http.compat.prosody"
local cqueues = require "cqueues"
local cq = cqueues.new()
cq:wrap(function()
    prosody_http.request("http://httpbin.org/ip", {}, function(b, c, r)
        print(c) --> 200
        print(b) --> {"origin": "123.123.123.123"}
    end)
end)
assert(cq:loop())

Provides compatibility with luasocket’s http.request module (http://w3.impa.br/~diego/software/luasocket/http.html).

Differences:

• Will automatically be non-blocking when run inside a cqueues managed coroutine
• lua-http features (such as HTTP2) will be used where possible

Using the `simple' interface as part of a normal script:

local socket_http = require "http.compat.socket"
local body, code = assert(socket_http.request("http://lua.org"))
print(code, #body) --> 200, 2514