lua-http Documentation

The lua-http library provides the following capabilities:

• Asynchronous Support: Optionally supports asynchronous operations, including DNS lookups and TLS.
• Protocol Support: Supports HTTP(S) versions 1.0, 1.1, and 2.
• Dual Role: Provides functionality for both HTTP clients and servers.
• Cookie Management: Built-in support for managing cookies.
• Websockets: Support for Websocket protocols.
• Runtime Compatibility: Compatible with Lua 5.1, 5.2, 5.3, 5.4, and LuaJIT.

The http.h1_stream module implements the standard stream interface. For the following operations, refer to the base stream documentation:

• Connection & Identity: connection, checktls(), localname(), peername()
• Headers: get_headers(timeout), write_headers(headers, end_stream, timeout)
• Body Reading: get_next_chunk(timeout), each_chunk(), get_body_as_string(timeout), get_body_chars(n, timeout), get_body_until(pattern, plain, include_pattern, timeout), save_body_to_file(file, timeout), get_body_as_file(timeout)
• Body Writing: write_chunk(chunk, end_stream, timeout), write_body_from_string(str, timeout), write_body_from_file(options|file, timeout)
• Stream Control: unget(str), shutdown(), set_state(new)

The http.h2_error object is a specialized error type used to encapsulate HTTP/2 specific error information. When handling or inspecting HTTP/2 errors, you can access the following fields on an error object:

• name: A short identifier for the error.
• code: The numeric error code.
• description: A description of the error code.
• message: The specific error message.
• traceback: A traceback captured at the point the error was thrown.
• stream_error: A boolean indicating if the error is at the stream level (true) or the protocol level (false).

The http.headers module manages an ordered list of HTTP header fields. Each field consists of a name, a value, and a never_index boolean flag. The never_index flag indicates if the value contains sensitive data (e.g., credentials) and should not be indexed.

Key characteristics:

• Efficient Retrieval: Headers are indexed by name for fast lookup, but since HTTP allows multiple values for the same name (like Set-Cookie), retrieval methods handle multiple values.
• HTTP/2 Compatibility: HTTP/1 request and status line fields are stored within the headers object using HTTP/2 pseudo-headers: ":authority", ":method", ":path", ":scheme", and ":status". Note that ":status" is always stored as a string.
• Sensitivity Defaults: The never_index flag defaults to true for sensitive fields: authorization, proxy-authorization, cookie, and set-cookie.

lua-http is designed to be fully asynchronous and non-blocking. It achieves this by utilizing cqueues, a Lua/C library that uses kernel-level APIs and Lua yielding.

Key behaviors:

• All operations (DNS lookup, TLS negotiation, read/write) are non-blocking when run inside a cqueue or a cqueue-enabled container.
• While operations are asynchronous, blocking API calls take an optional timeout argument to prevent unresponsive routines.
• The library can be integrated into existing event loops or used as a standalone event-driven application.

The http.socks module implements a subset of the SOCKS proxy protocol. You can initialize a SOCKS object using http.socks.connect(uri) or wrap an existing cqueues.socket using http.socks.fdopen(socket).

-- Using a URI to connect
local socks = http.socks.connect("socks5://proxy-address:port")

-- Or wrapping an existing socket
local socks = http.socks.fdopen(existing_socket)

A connection encapsulates a socket and provides protocol-specific operations. It serves as the transport layer for HTTP communication.

Connections can be used in two ways:

1. With Streams: A connection may have one or more streams which encapsulate individual requests and responses happening over that connection.
2. Low-level: You can ignore streams entirely and use low-level protocol-specific operations to read and write directly to the socket.

All connection types expose fields for type (either "client" or "server") and version (the HTTP version number).

lua-http uses terminology borrowed from HTTP/2 to describe its internal abstractions:

• Connection: An abstraction over an underlying TCP/IP socket. The library provides specific connection types for HTTP/1 and HTTP/2.
• Stream: Represents a request/response on a connection object. There are distinct stream types for HTTP/1 and HTTP/2, but they share a common interface.