LUA-HTTP(3)

📦
version 0.3 · 2 versions
, in fedora 43, fedora 44

✨ Introduction ✨

okay so bestie, welcome to lua-http(3) — the manual for lua-http, a performant, capable HTTP and WebSocket library for Lua 5.1, 5.2, 5.3 and LuaJIT. No cap, it's giving networking main character energy. Some of the features of the library include:

  • Support for HTTP versions 1, 1.1 and 2 as specified by RFC 7230 and RFC 7540. Slay.
  • Provides both client and server APIs. Both sides of the convo, we love to see it.
  • Fully asynchronous API that does not block the current thread when executing operations that typically block. Not me blocking the main thread? Never.
  • Support for WebSockets as specified by RFC 6455 including ping/pong, binary data transfer and TLS encryption. Ping/pong is literally self-care.
  • Transport Layer Security (TLS) — lua-http supports HTTPS and WSS via luaossl. TLS? Obsessed.
  • Easy integration into other event-loop or scripts. It just slides in, no drama.

Why lua-http? 💅

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. Say it with me: async and fast.
  • Can be used without forcing the developer to follow a specific pattern. Conversely, the library can be adapted to many common patterns. Your pattern, your rules.
  • Can be used at a very high level without need to understand the transportation of HTTP data (other than connection addresses). High-level bestie era.
  • Provides a rich low level API, if desired, for creating powerful HTTP based tools at the protocol level. And if you wanna go low-level? It ate.

As a result of these design goals, the library is simple and unobtrusive and can accommodate tens of thousands of connections on commodity hardware. Tens of thousands. On commodity hardware. Iconic.

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

Portability 🌍

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

  • cqueues — Posix API library for Lua. The async backbone.
  • luaossl — Lua bindings for TLS/SSL. Security queen.
  • lua-zlib — Optional Lua bindings for zlib. Optional, but cute.

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. Portability? We love her.

Common Use Cases 🎀

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

Retrieving a Document 📄

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. Like, fetch? Slay.

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)

WebSocket Communications 🦋

To request information from a WebSocket server, use the websocket module to create a new WebSocket client. Hello, real-time bestie.

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

Asynchronous Operation ⚡

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. No dead routines in this house.

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. Event-driven? It's giving kernel-level polling royalty.

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 for more information about the cqueues library. Go read, bestie.
  • cqueues examples can be found with the cqueues source code available through git or archives or accessed online here. Source code era.
  • For more information on integrating cqueues with other event loop libraries please see integration with other event loops. Loop integration, iykyk.
  • For other libraries that use cqueues such as asynchronous APIs for Redis and PostgreSQL, please see the cqueues wiki entry here. Redis and PostgreSQL? The crossover event.

Conventions 📜

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

HTTP 🌐

  • 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). Internalize it.
  • Header fields should always be used with lower case keys. Lowercase or it's not invited.

Errors 💀

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

Timeouts ⏳

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". Timeout? We don't ghost, we set boundaries.

Terminology 🧚

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. Two connection types, one vibe.

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. Streams are the moment.

🌈 Interfaces 🌈

ok so bestie, here's the tea ☕ — lua-http keeps HTTP 1 and HTTP 2 in separate modules, but they're giving the same energy underneath, so the library hands you one shared interface for everything that makes sense in both worlds (and whatever future protocol glow-up comes next 💅).

The next few sections are the whole interface menu, no gatekeeping.

💖 connection 💖

A connection is basically a socket wrapped in a lil protocol-specific jacket. It may have streams on it — those are the individual request/response situations happening over the connection. OR you can fully ignore streams and just do low-level protocol stuff straight on the socket. Your call, main character ✨.

Every connection type exposes these fields:

connection.type

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 connection type is used by entities who want to respond to requests

connection.version

The HTTP version number of the connection, as a number. 🔢

connection:pollfd()

connection:events()

connection:timeout()

connection:connect(timeout)

Completes the connection to the remote server using the address specified, the HTTP version and any options you gave in the connection.new constructor. connect 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 — it's a whole journey 🛫.

Returns true on success. On error, returns nil, an error message and an error number.

connection:checktls()

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's no active TLS session. Go peep the luaossl website for more info about the ssl object, iykyk.

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 isn't connected, returns AF_UNSPEC (0). On error, returns nil, an error message and an error number.

connection:peername()

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 isn't 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 by :peername() point to the proxy, not the remote server. Don't get it twisted 🫶

connection:flush(timeout)

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.

connection:shutdown()

Performs an orderly shutdown of the connection by closing all streams and calls :shutdown() on the socket. The connection cannot be re-opened. It's over, it's giving closed-for-business 😭

connection:close()

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

connection:new_stream()

Creates and returns a new stream on the connection. Fresh stream, who dis ✨

connection:get_next_incoming_stream(timeout)

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

connection:onidle(new_handler)

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

🌸 stream 🌸

An HTTP stream is an abstraction of a request/response within an HTTP connection. Within a stream there may be a number of "header" blocks, plus data known as the "body" 💌.

All stream types expose the following fields and functions:

stream.connection

The underlying connection object.

stream:checktls()

Convenience wrapper equivalent to stream.connection:checktls()

stream:localname()

Convenience wrapper equivalent to stream.connection:localname()

stream:peername()

Convenience wrapper equivalent to stream.connection:peername()

stream:get_headers(timeout)

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

stream:write_headers(headers, end_stream, timeout)

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.

stream:write_continue(timeout)

Sends a 100-continue header block.

stream:get_next_chunk(timeout)

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.

stream:each_chunk()

Iterator over stream:get_next_chunk()

stream:get_body_as_string(timeout)

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

stream:get_body_chars(n, timeout)

Reads n characters (bytes) of body from the stream and returns 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.

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

Reads in body data from the stream until the lua pattern 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 the 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.

stream:save_body_to_file(file, timeout)

Reads the body from the stream and saves it to the lua file handle file. On error, returns nil, an error message and an error number.

stream:get_body_as_file(timeout)

Reads the body from the stream into a temporary file and returns a lua file handle. On error, returns nil, an error message and an error number.

stream:unget(str)

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. It's giving undo button 🫠

stream:write_chunk(chunk, end_stream, timeout)

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.

stream:write_body_from_string(str, timeout)

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

stream:write_body_from_file(options|file, timeout)

  • 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 make sure it's at the correct offset before calling. On error, returns nil, an error message and an error number.

stream:shutdown()

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

👑 Modules 👑

http.bit

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.

band(a, b)

Bitwise And operation.

bor(a, b)

Bitwise Or operation.

bxor(a, b)

Bitwise XOr operation.

Example

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

http.client

Deals with obtaining a connection to an HTTP server. The plug 🔌.

negotiate(socket, options, timeout)

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

connect(options, timeout)

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. So yeah, it's a whole saga, budget accordingly ⏳.

Example

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. 🍪 (the browser kind, not the snack kind — though honestly, both are iconic)

🍪 bake(name, value, expiry_time, domain, path, secure_only, http_only, same_site)

bestie this one literally just hands you back a string you can slap straight into a Set-Cookie header, built out of every param you passed in. that's it. that's the function. 💅

takes the contents of a Cookie header (that's the cookie argument, okurr) and parses it.

returns a table where the name and value pairs are all sitting pretty as strings. ✨

🎀 parse_cookies(req_headers)

same vibe, but it parses every single Cookie header inside the http.headers object you pass as req_headers.

returns a table with name and value pairs, as strings. no cap. 🫶

🎀 parse_setcookie(setcookie)

parses the contents of a Set-Cookie header, i.e. the setcookie you gave it. gives you back three things — name, value and params, and here's the breakdown:

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

🏪 new_store()

makes you a shiny brand new cookie store. ✨

cookies are unique for a tuple of domain, path and name — but heads up, multiple cookies with the same name can still show up in a single request because of overlapping paths or domains. so don't be gagged when you see dupes. 😭

📜 store.psl

a lua-psl object you use to check stuff against the Public Suffix List. set this field to false if you want to skip checking the suffix list entirely.

defaults to the latest PSL on the system. and if lua-psl isn't installed? then it'll be nil. 🙈

⏰ store.time()

a function the store calls to get the current time for expiries and such.

defaults to a function based on os.time.

the maximum length (in bytes) of cookies in the store. this value also doubles as the default maximum cookie length for :lookup().

decreasing this value only stops new cookies from being added — it will not remove old cookies. fr fr, don't expect it to clean up after itself.

defaults to infinity (aka no maximum size at all). 🦋

🔢 store.max_cookies

the maximum number of cookies allowed in the store.

decreasing this value only prevents new cookies from being added, it will not remove old cookies.

defaults to infinity (any number of cookies is allowed). iconic behavior honestly.

🔢 store.max_cookies_per_domain

the maximum number of cookies allowed in the store per domain.

decreasing this value only prevents new cookies from being added, it will not remove old cookies.

defaults to infinity (any number of cookies is allowed). 💅

💾 store:store(req_domain, req_path, req_is_http, req_is_secure, req_site_for_cookies, name, value, params)

tries to add a cookie to the store. let's go through the cast 👑

  • req_domain is the domain the cookie was obtained from
  • req_path is the path the cookie was obtained from
  • req_is_http is a boolean flag telling you if the cookie came from a “non-HTTP” API
  • req_is_secure is a boolean flag telling you if the cookie came from a “secure” protocol
  • req_site_for_cookies is a string with the host that should be treated as the “site for cookies” (See RFC 6265bis-02 Section 5.2) — can be nil if you don't know it
  • name is a string with the cookie name
  • value is a string with the cookie value
  • params is a table where the keys are cookie attribute names and the values are cookie attribute values

returns a boolean telling you whether a cookie actually got stored. 🎀

💾 store:store_from_request(req_headers, resp_headers, req_host, req_site_for_cookies)

tries to store any cookies it finds in the response headers.

  • req_headers is the http.headers object for the outgoing request
  • resp_headers is the http.headers object you got back in response
  • req_host is the host your query was pointed at (only used if req_headers is missing a Host header)
  • req_site_for_cookies is a string with the host that should be considered the “site for cookies” (See RFC 6265bis-02 Section 5.2) — can be nil if unknown

🔍 store:get(domain, path, name)

returns the cookie value for the cookie stored under the domain, path and name you passed in.

🗑️ store:remove(domain, path, name)

deletes the cookie stored for the domain, path and name you passed.

  • if name is nil or you just didn't pass it, then all cookies for that domain and path get removed
  • if path is nil or not passed (on top of name), then all cookies for that domain get removed

so like... leave args off and it goes full cleanup mode. 💀

finds the cookies that are visible and suitable for passing along to an entity.

  • domain is the domain that'll be sent the cookie
  • path is the path that'll 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 with the host that should be considered the “site for cookies” (See RFC 6265bis-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)
  • max_cookie_length is the maximum cookie length to allow (See also store.max_cookie_length)

returns a string ready to drop into 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 your query was pointed at (only used if headers is missing a Host header)
  • site_for_cookies is a string with the host that should be considered the “site for cookies” (See RFC 6265bis-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)
  • max_cookie_length is the maximum cookie length to allow (See also store.max_cookie_length)

returns a string ready to drop into a Cookie header. 🫶

⏳ store:clean_due()

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

🧹 store:clean()

removes all the expired cookies from the store. spring cleaning bestie 🌸

📂 store:load_from_file(file)

loads cookie data from the file object file into the store. the file needs to be in the Netscape Cookiejar format. any invalid lines in the file just get ignored, no drama.

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

📂 store:save_to_file(file)

writes the cookie data from the store into the file object file, in the Netscape Cookiejar format. note that file is not seek-ed or truncated before writing — keep that in mind 👀

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

🌈 http.h1_connection

the h1_connection module adheres to the connection interface</> and provides HTTP 1 and 1.1 specific operations.

🔌 new(socket, conn_type, version)

constructor for a brand 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. slay 💅

📌 h1_connection.version

specifies the HTTP version used for the connection handshake. valid values are:

  • 1.0
  • 1.1

See connection.version

📌 h1_connection:pollfd()

See connection:pollfd()

📌 h1_connection:events()

See connection:events()

📌 h1_connection:timeout()

See connection:timeout()

📌 h1_connection:connect(timeout)

See connection:connect(timeout)

📌 h1_connection:checktls()

See connection:checktls()

📌 h1_connection:localname()

See connection:localname()

📌 h1_connection:peername()

See connection:peername()

📌 h1_connection:flush(timeout)

See connection:flush(timeout)

🚪 h1_connection:shutdown(dir)

shut down is as graceful as it can possibly be: pipelined streams get shut down first, then the underlying socket gets shut down in the appropriate direction(s). so polite. 🎀

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

See connection:shutdown()

🚪 h1_connection:close()

See connection:close()

🌱 h1_connection:new_stream()

in HTTP 1, only a client may initiate new streams with this function. server besties, sit this one out 🙈

See connection:new_stream() for more information.

📥 h1_connection:get_next_incoming_stream(timeout)

See connection:get_next_incoming_stream(timeout)

😴 h1_connection:onidle(new_handler)

See connection:onidle(new_handler)

📏 h1_connection:setmaxline(read_length)

sets the maximum read buffer size (in bytes) to read_length. i.e. it sets the maximum length of lines (like headers, yk).

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

🧽 h1_connection:clearerr(...)

clears errors so you can do further read or write operations on the connection. returns the error number of existing errors. this function is what you use to recover from known errors. 🫶

🧽 h1_connection:error(...)

returns the error number of existing errors.

🤝 h1_connection:take_socket()

used to hand the reference of the connection socket over to another object. resets the socket to defaults and returns the single existing reference of the socket to the calling routine. you'd use this for connection upgrades, like upgrading from HTTP 1 to a WebSocket. ✨

📖 h1_connection:read_request_line(timeout)

reads a request line from the socket. returns the request method, the requested path and the HTTP version for an incoming request.

:read_request_line() yields until a "\r\n" terminated chunk is received, or until timeout is exceeded. if the incoming chunk is not a valid HTTP request line, nil is returned. on error, it returns nil, an error message, and an error number.

📖 h1_connection:read_status_line(timeout)

reads a line of input from the socket. if the input is a valid status line, you get back the HTTP version (1 or 1.1), the status code, and the reason description (if applicable).

:read_status_line() yields until a "\r\n" terminated chunk is received, or until timeout is exceeded. if the socket could not be read, it returns nil, an error message, and an error number.

📖 h1_connection:read_header(timeout)

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

h1_connection:read_headers_done(timeout) 💖

okay so bestie this one checks for an empty line, which is the signal that the HTTP headers are done. It returns true if an empty line shows up. Any other value gets 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. If the socket cannot be read, it returns nil, an error and an error message.

h1_connection:read_body_by_length(len, timeout) ✨

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 the length of the buffered body is less than len. Asserts if len is not a number.

h1_connection:read_body_till_close(timeout) 🎀

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.

h1_connection:read_body_chunk(timeout) 🦋

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 the chunk header or the socket.

h1_connection:write_request_line(method, path, httpversion, timeout) 🌸

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.

h1_connection:write_status_line(httpversion, status_code, reason_phrase, timeout) 💅

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.

h1_connection:write_header(k, v, timeout) 🫶

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.

h1_connection:write_headers_done(timeout) 😭

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.

h1_connection:write_body_chunk(chunk, chunk_ext, timeout) 🔥

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.

h1_connection:write_body_last_chunk(chunk_ext, timeout) 👑

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.

h1_connection:write_body_plain(body, timeout) 🌈

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.

http.h1_reason_phrases ⭐

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

Example:

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

http.h1_stream 💀

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

The gzip transfer encoding is supported transparently.

h1_stream.connection 🎀

See stream.connection

h1_stream.max_header_lines 🌸

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

h1_stream:checktls() 💅

See stream:checktls()

h1_stream:localname() 🫶

See stream:localname()

h1_stream:peername() 😭

See stream:peername()

h1_stream:get_headers(timeout) 🔥

See stream:get_headers(timeout)

h1_stream:write_headers(headers, end_stream, timeout) 👑

See stream:write_headers(headers, end_stream, timeout)

h1_stream:write_continue(timeout) 🌈

See stream:write_continue(timeout)

h1_stream:get_next_chunk(timeout) ⭐

See stream:get_next_chunk(timeout)

h1_stream:each_chunk() 💀

See stream:each_chunk()

h1_stream:get_body_as_string(timeout) 🙈

See stream:get_body_as_string(timeout)

h1_stream:get_body_chars(n, timeout) 🍓

See stream:get_body_chars(n, timeout)

h1_stream:get_body_until(pattern, plain, include_pattern, timeout) 🧚

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

h1_stream:save_body_to_file(file, timeout) 💜

See stream:save_body_to_file(file, timeout)

h1_stream:get_body_as_file(timeout) ✨

See stream:get_body_as_file(timeout)

h1_stream:unget(str) 🌟

See stream:unget(str)

h1_stream:write_chunk(chunk, end_stream, timeout) 💖

See stream:write_chunk(chunk, end_stream, timeout)

h1_stream:write_body_from_string(str, timeout) 🎀

See stream:write_body_from_string(str, timeout)

h1_stream:write_body_from_file(options|file, timeout) 🌸

See stream:write_body_from_file(options|file, timeout)

h1_stream:shutdown() 💅

See stream:shutdown()

h1_stream:set_state(new) 🫶

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.

h1_stream:read_headers(timeout) 😭

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

http.h2_connection 👑

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.

new(socket, conn_type, settings) 🌈

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.

h2_connection.version ⭐

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

See connection.version.

h2_connection:pollfd() 💀

See connection:pollfd()

h2_connection:events() 🙈

See connection:events()

h2_connection:timeout() 🍓

See connection:timeout()

h2_connection:empty() 🧚

h2_connection:step(timeout) 💜

h2_connection:loop(timeout) ✨

h2_connection:connect(timeout) 🌟

See connection:connect(timeout)

h2_connection:checktls() 💖

See connection:checktls()

h2_connection:localname() 🎀

See connection:localname()

h2_connection:peername() 🌸

See connection:peername()

h2_connection:flush(timeout) 💅

See connection:flush(timeout)

h2_connection:shutdown() 🫶

See connection:shutdown()

h2_connection:close() 😭

See connection:close()

h2_connection:new_stream(id) 🔥

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.

h2_connection:get_next_incoming_stream(timeout) 👑

See connection:get_next_incoming_stream(timeout)

h2_connection:onidle(new_handler) 🌈

See connection:onidle(new_handler)

h2_connection:read_http2_frame(timeout) ⭐

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

h2_connection:ping(timeout) 🙈

h2_connection:write_window_update(inc, timeout) 🍓

h2_connection:write_goaway_frame(last_stream_id, err_code, debug_msg, timeout) 🧚

h2_connection:set_peer_settings(peer_settings) 💜

h2_connection:ack_settings() ✨

h2_connection:settings(tbl, timeout) 🌟

http.h2_error 💖

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

errors 🎀

A table containing errors as defined by the HTTP 2 specification. It can be indexed by error name (e.g. errors.PROTOCOL_ERROR) or numeric code (e.g. errors[0x1]).

is(ob) 🌸

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

h2_error:new(ob) 💅

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.

h2_error:new_traceback(message, stream_error, lvl) 🫶

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

h2_error:error(message, stream_error, lvl) 😭

Creates and throws a new error.

h2_error:assert(cond, ...) 🔥

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.

http.h2_stream 👑

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

h2_stream.connection 🌈

See stream.connection

h2_stream:checktls() ⭐

See stream:checktls()

h2_stream:localname() 💀

See stream:localname()

h2_stream:peername() 🙈

See stream:peername()

h2_stream:get_headers(timeout) 🍓

See stream:get_headers(timeout)

h2_stream:write_headers(headers, end_stream, timeout) 🧚

See stream:write_headers(headers, end_stream, timeout)

h2_stream:write_continue(timeout) 💜

See stream:write_continue(timeout)

h2_stream:get_next_chunk(timeout)

bestie this one is a rerun 💖 she's literally stream:get_next_chunk(timeout) in a different outfit. Go read that one.

h2_stream:each_chunk()

same deal — it's stream:each_chunk(). periodt.

h2_stream:get_body_as_string(timeout)

yep, stream:get_body_as_string(timeout). copy paste behaviour, no cap.

h2_stream:get_body_chars(n, timeout)

that's stream:get_body_chars(n, timeout) 💅

h2_stream:get_body_until(pattern, plain, include_pattern, timeout)

yup: stream:get_body_until(pattern, plain, include_pattern, timeout).

h2_stream:save_body_to_file(file, timeout)

stream:save_body_to_file(file, timeout) — go look it up queen 🌸

h2_stream:get_body_as_file(timeout)

stream:get_body_as_file(timeout). iconic, moving on.

h2_stream:unget(str)

stream:unget(str). that's the whole thing.

h2_stream:write_chunk(chunk, end_stream, timeout)

stream:write_chunk(chunk, end_stream, timeout) ✨

h2_stream:write_body_from_string(str, timeout)

stream:write_body_from_string(str, timeout).

h2_stream:write_body_from_file(options|file, timeout)

stream:write_body_from_file(options|file, timeout).

h2_stream:shutdown()

stream:shutdown(). same energy, same everything.

okay so the next little cluster? the docs just list these with zero explanation. no notes, no description, nothing. she's mysterious, and honestly? respect 💅

  • h2_stream:pick_id(id) — picks an id. that's all we're given, fr fr.
  • h2_stream:set_state(new) — sets the state. that's it, that's the tweet.
  • h2_stream:reprioritise(child, exclusive) — reprioritises child with exclusive in the mix. again: no elaboration. it's giving enigma.

h2_stream:write_http2_frame(typ, flags, payload, timeout, flush)

writes a frame with h2_stream's stream id 🦋

and then: go see h2_connection:write_http2_frame(typ, flags, streamid, payload, timeout, flush).

and here come the rest of the frame-writing girlies — again, listed bare, no commentary in the source, so I'm not gonna invent any:

  • h2_stream:write_data_frame(payload, end_stream, padded, timeout, flush)
  • h2_stream:write_headers_frame(payload, end_stream, end_headers, padded, exclusive, stream_dep, weight, timeout, flush)
  • h2_stream:write_priority_frame(exclusive, stream_dep, weight, timeout, flush)
  • h2_stream:write_rst_stream_frame(err_code, timeout, flush)
  • h2_stream:rst_stream(err, timeout)
  • h2_stream:write_settings_frame(ACK, settings, timeout, flush)
  • h2_stream:write_push_promise_frame(promised_stream_id, payload, end_headers, padded, timeout, flush)

h2_stream:push_promise(headers, timeout)

pushes a new promise to the client 🫶

returns the new stream as a h2_stream.

  • h2_stream:write_ping_frame(ACK, payload, timeout, flush)
  • h2_stream:write_goaway_frame(last_streamid, err_code, debug_msg, timeout, flush)
  • h2_stream:write_window_update_frame(inc, timeout, flush)
  • h2_stream:write_window_update(inc, timeout)
  • h2_stream:write_continuation_frame(payload, end_headers, timeout, flush)

🎀 http.headers

an ordered list of header fields, bestie. every field has a name, a value and a never_index flag — and that flag is the one that says "hey this is potentially sensitive data, don't index it" 🙈

every headers object also keeps an index by field name so you can grab values by key fast. but heads up: there can totally be multiple values for a given field name — like an HTTP server sending two Set-Cookie headers. so don't act surprised 👑

and like we said back in the Conventions section: HTTP 1 request and status line fields get passed around inside headers objects under the keys ":authority", ":method", ":path", ":scheme" and ":status", exactly as defined in HTTP 2. which means they're all kept in string form. important to remember for ":status", okay? it's a string. not a number. a string. 💅

new()

creates and returns a brand new headers object. slay.

headers:len()

returns the number of headers.

also available as #headers in Lua 5.2+. 🌈

headers:clone()

creates and returns a clone of the headers object. twin behaviour.

headers:append(name, value, never_index)

append a header, bestie.

  • 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 either. (yes, really. no gatekeeping here.)
  • never_index is an optional boolean that says whether the value should be considered secret. it defaults to true for these header fields: authorization, proxy-authorization, cookie and set-cookie.

headers:each()

an iterator over all the headers that emits name, value, never_index.

Example

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
]]

headers:has(name)

returns a boolean saying whether the headers object has a field with the given name. vibe check, but for headers.

headers:delete(name)

removes all occurrences of a field name from the headers object. every single one. gone. 💀

headers:geti(i)

return the i-th header as name, value, never_index.

headers:get_as_sequence(name)

returns all headers with the given name in a table. that table will contain a field .n holding the number of elements. ✨

Example

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"}
]]

headers:get(name)

returns all headers with the given name as multiple return values. yes, plural. she's generous.

headers:get_comma_separated(name)

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

headers:modifyi(i, value, never_index)

change the i-th's header to a new value and never_index. glow-up for one specific header.

headers:upsert(name, value, 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. 🚫 so don't try it, she will not cooperate.

headers:sort()

sorts the list of headers by their field name, ordering the ones starting with : first. if names are equal, then it sorts by value, then by never_index. so organised. so main character.

headers:dump(file, prefix)

prints the headers list to the given file, one per line. if file isn't given, it prints to stderr instead. prefix gets prefixed to each line. 🌸

🌈 http.hpack

okay this whole section is just a big list of signatures with no explanations attached. so I'm handing them to you exactly as they are, no invented lore, no extra claims:

  • new(SETTINGS_HEADER_TABLE_SIZE)
  • hpack_context:append_data(val)
  • hpack_context:render_data()
  • hpack_context:clear_data()
  • hpack_context:evict_from_dynamic_table()
  • hpack_context:dynamic_table_tostring()
  • hpack_context:set_max_dynamic_table_size(SETTINGS_HEADER_TABLE_SIZE)
  • hpack_context:encode_max_size(val)
  • hpack_context:resize_dynamic_table(new_size)
  • hpack_context:add_to_dynamic_table(name, value, k)
  • hpack_context:dynamic_table_id_to_index(id)
  • hpack_context:lookup_pair_index(k)
  • hpack_context:lookup_name_index(name)
  • hpack_context:lookup_index(index)
  • hpack_context:add_header_indexed(name, value, huffman)
  • hpack_context:add_header_never_indexed(name, value, huffman)
  • hpack_context:encode_headers(headers)
  • hpack_context:decode_headers(payload, header_list, pos)

that's the whole list, bestie. every single one. no skipping 💜

👑 http.hsts

data structures useful for HSTS (HTTP Strict Transport Security). the security girlies are gonna eat this up.

new_store()

creates and returns a new HSTS store. fresh out the box ✨

hsts_store.max_items

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. so don't think lowering it cleans anything up for you, it doesn't 😭

defaults to infinity (meaning any number of items is allowed).

hsts_store:clone()

creates and returns a copy of a store.

hsts_store:store(host, directives)

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

returns a boolean indicating if the item was accepted. 🫶

hsts_store:remove(host)

removes the entry for host from the store (if it exists). if it doesn't exist, whatever, nothing happens.

hsts_store:check(host)

returns a boolean indicating if the given host is a known HSTS host. 👀

hsts_store:clean_due()

returns the number of seconds until the next item in the store expires. tick tock ⏳

hsts_store:clean()

removes expired entries from the store. self-care.

🦋 http.proxies

new()

returns an empty proxies object. a blank canvas, bestie.

proxies:update(getenv)

getenv defaults to os.getenv.

reads environmental variables that are used to control if requests go through a proxy:

  • http_proxy (or CGI_HTTP_PROXY if you're 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 the other options though.
  • no_proxy or NO_PROXY: a list of hosts to not use a proxy for.

returns proxies. 💅

proxies:choose(scheme, host)

returns the proxy to use for the given scheme and host as a URI. picks your fighter for you.

💖 http.request

the http.request module encapsulates all the functionality required to retrieve an HTTP document from a server. this is the whole point of the operation, honestly.

new_from_uri(uri)

creates a new http.request object from the given uri.

new_connect(uri, connect_authority)

creates a new http.request object from the given uri that will perform a CONNECT request. fancy.

request.host

the host this request should be sent to.

request.port

the port this request should be sent to.

request.bind

the local outgoing address and optionally port to bind, in the form of "address[:port]". default is to let the kernel choose an address+port. let the kernel cook 🍳

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.

request.tls

a boolean indicating if TLS should be used.

request.ctx

an alternative SSL_CTX* to use. if it's not specified, it uses the default TLS settings (see http.tls for information).

request.sendname

the TLS SNI host name used.

request.version

the HTTP version to use; leave it as nil to auto-select. she'll pick for you, trust her.

request.proxy

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

request.headers

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

request.hsts

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.

request.proxies

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.

request.is_top_level

a boolean flag indicating if this request is a "top level" request (See RFC 6265bis-02 Section 5.2).

defaults to true.

request.site_for_cookies

a string containing the host that should be considered as the "site for cookies" (See RFC 6265bis-02 Section 5.2). can be nil if it's unknown. 🎀

  • Defaults to nil. 💤 (yeah this one's just chillin' with no value set, bestie)

request.follow_redirects 🌀

Boolean that says whether :go() should chase down redirects like it's stalking an ex's finsta. Defaults to true.

request.expect_100_timeout ⏳

The number of seconds to wait for a 100 Continue response before just going ahead and sending the request body anyway. Defaults to 1.

request.max_redirects 🔁

The max number of redirects to follow before giving up on life. Defaults to 5. Set it to math.huge if you're built different and refuse to ever give up.

request.post301 📮

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, like, everywhere in web browsers and servers just assume it. Modern HTTP endpoints send status code 308 to say "hey, don't change my method." Defaults to false.

request.post302 📮

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

request:clone() 🧬

Creates and returns a clone of the request. Yes, it's giving identical twin energy.

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.

request:handle_redirect(headers) 🚦

Process a redirect.

headers should be response headers for a redirect.

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

request:to_uri(with_userinfo) 🪪

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.

request:set_body(body) 📦

Lets you set 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 to the start, then sent as a body. Any errors encountered during file operations will be thrown.

request:go(timeout) 🚀

Performs the request. The moment we've all been waiting for, fr fr.

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 💖

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 in the source tree.

new(options) ✨

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. ♾️

listen(options) 🎧

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.

server:onerror(new_handler) 🚨

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.

server:listen(timeout) 👂

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.

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

server:pause() ⏸️

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

server:resume() ▶️

Resumes a paused server and processes new client requests. Welcome back bestie 🫶

server:close() 🔒

Shutdown the server and close the socket. A closed server cannot be reused. That's it, it's over, no coming back from this one 💀

server:pollfd() 🔍

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

server:events() 🎟️

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

server: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().

server:empty() 🫙

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

server:step(timeout) 👣

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.

server:loop(timeout) 🔄

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. Just vibing in the loop forever, honestly.

server:add_socket(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) 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.

server:add_stream(stream) 🌊

Add an existing stream to the server for processing.

🧦 http.socks 🧦

Implements a subset of the SOCKS proxy protocol.

connect(uri) 🔗

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.

fdopen(socket) 🪟

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

socks.needs_resolve 🌐

Specifies if the destination host should be resolved locally.

socks:clone() 🧬

Make a clone of a given socks object.

socks:add_username_password_auth(username, password) 🔐

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

socks:negotiate(host, port, timeout) 🤝

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.

socks:close() 🚪

socks:take_socket() 🫴

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

🌈 http.tls 🌈

has_alpn 🎀

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

  • has_hostname_validation — a boolean that tells you whether hostname validation is available in the environment you're running in right now. It might be switched off if your OpenSSL is an old version. 😭
  • modern_cipher_list — the Mozilla “Modern” cipher list, all strung together as a colon separated list, ready to be passed straight to OpenSSL. 💅
  • intermediate_cipher_list — same energy, but the Mozilla “Intermediate” cipher list: colon separated, OpenSSL-ready, no notes.
  • old_cipher_list — and the Mozilla “Old” cipher list, also colon separated, also ready to pass to OpenSSL. (the vintage collection fr 🫶)
  • banned_ciphers — a set (a table with string keys and values of true) holding the ciphers that are banned in HTTP 2, where the keys are OpenSSL cipher names. Ciphers OpenSSL doesn't know about are just… not in the set. 🙈
  • new_client_context() — creates and returns a brand new luaossl SSL context, and it's genuinely useful for HTTP client connections. main character energy.
  • new_server_context() — creates and returns a fresh luaossl SSL context, this one useful for HTTP server connections. 💜

🧰 http.util 🧰

  • encodeURI(str), encodeURIComponent(str), decodeURI(str), decodeURIComponent(str) — all four of these are listed completely bare in the source, with zero description attached, so I'm not about to invent one for you. The signatures are the whole story here. 😌
  • query_args(str) — hands you back an iterator over the pairs inside str.

Example:

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"
]]
  • dict_to_query(dict) — takes a dictionary (a table with string keys) whose values are strings, and converts it into an encoded query string. ✨

Example:

local http_util = require "http.util"
print(http_util.dict_to_query({foo = "bar"; baz = "qux"})) --> "baz=qux&foo=bar"
  • resolve_relative_path(orig_path, relative_path) — listed with no blurb in the source, bestie. Signature only, that's all she wrote. 🎀
  • is_safe_method(method) — returns a boolean telling you whether the string method you passed in is a “safe” method. Peep RFC 7231 section 4.2.1 for more. 🌸
  • is_ip(str) — returns a boolean telling you whether the string str is a valid IP.
  • scheme_to_port — a map from schemes (as strings) to default ports (as integers).
  • split_authority(authority, scheme) — splits an authority into its host and port components. If the authority doesn't have a port component, it'll attempt to use the default for the scheme. 💫

Example:

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
  • to_authority(host, port, scheme) — joins the host and port together to make a valid authority component. It omits the port if that port is the default for the scheme.
  • imf_date(time) — returns the time in HTTP's preferred date format (see RFC 7231 section 7.1.1.1). time defaults to the current time. 🕰️
  • maybe_quote(str) — the little decision tree, and it goes like this:
    • 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.

🌈 http.version 🌈

  • name — "lua-http". That's it. That's the name. 💖
  • version — the current version of lua-http, as a string.

🕸️ http.websocket 🕸️

  • new_from_uri(uri, protocols) — creates a new http.websocket object of type "client" from the URI you give it.
    • protocols (optional) should be a lua table containing a sequence of protocols to send to the server. 💌
  • new_from_stream(stream, headers) — 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 has no side effects, which is exactly why it's okay to use it tentatively. 👑
  • websocket.close_timeout — the amount of time (in seconds) to wait between sending a close frame and actually closing the connection. Defaults to 3 seconds.
  • websocket:accept(options, timeout) — 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.
  • websocket:connect(timeout) — connect to a websocket server. Usually called after a successful new_from_uri. 🔌
  • websocket:receive(timeout) — reads and returns the next data frame plus its opcode. Any ping frames that show up while it's reading get responded to automatically. 🏓
    • The opcode 0x1 will be returned as "text" and 0x2 will be returned as "binary".
  • websocket:each() — an iterator over websocket:receive().
  • websocket:send_frame(frame, timeout) — the low level function for sending a raw frame.
  • websocket:send(data, opcode, timeout) — sends the given data as a data frame.
    • data should be a string.
    • opcode can be a numeric opcode, "text" or "binary". If it's nil, it defaults to a text frame. Heads up: this opcode is the websocket frame opcode, not an application specific opcode. It should be one from the IANA registry.
  • websocket:send_ping(data, timeout) — sends a ping frame.
    • data is optional.
  • websocket:send_pong(data, timeout) — sends a pong frame. Works as a unidirectional keep-alive.
    • data is optional.
  • websocket:close(code, reason, timeout) — closes the websocket connection.
    • code defaults to 1000.
    • reason is an optional string.

🗜️ http.zlib 🗜️

An abstraction layer sitting over the various lua zlib libraries. 🧚

  • engine — currently either "lua-zlib" or "lzlib".
  • inflate() — returns a closure that inflates (uncompresses) a zlib stream.
    • That closure takes a string of compressed data and an end of stream flag (boolean) as parameters, and returns the inflated output as a string. It will throw an error if the input isn't a valid zlib stream. ⚠️
  • deflate() — returns a closure that deflates (compresses) a zlib stream.
    • That closure takes a string of uncompressed data and an end of stream flag (boolean) as parameters, and returns the deflated output as a string.

Example:

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)

🎀 http.compat.prosody 🎀

Gives you usage that's similar to prosody's net.http.

  • request(url, ex, callback) — a few key differences from the prosody net.http.request:
    • it 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

Example:

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

🍓 http.compat.socket 🍓

Gives you compatibility with luasocket's http.request module.

Differences:

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

Example — 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
  • Github
  • Issue tracker

🌟 AUTHORS 🌟

  • Daurnimator quae@daurnimator.com

and that's a wrap on the whole thing, bestie 🫶 the footer down there reads lua-http() — source and version, baby — with the date stamped right beside it on the left, so go peek at your own copy for the exact stamp. you ate this entire page. periodt. 💅✨

📦 where this page comes from