Summary

Classes

API Reference

Classes

HttpConnection

A persistent HTTP connection to a single host and port.

Supports both HTTP and HTTPS. Multiple requests can be sent over the same connection when the server supports keep-alive.

local conn = http.HttpConnection.new("example.com", 443, nil, "https")
conn:request("GET", "/")
local resp = conn:getResponse()
print(resp.status, resp.body)
conn:close()

Properties

host: string

port: number

_timeouts: TimeoutOptions

_scheme: string

_verifySsl: boolean

_sock: any?

_leftover: string

_lastRequestMethod: string?

_prefetchedResponse: HttpResponseInternal?

_activeResponseStream: HttpResponseStream?

_appliedTimeout: number?

HttpConnection.new

Creates a new HttpConnection to the given host.

The connection is not established until the first request is sent (or HttpConnection.connect is called explicitly).

HttpConnection.new(host: string, port: number?, timeout: (number | TimeoutOptions)?, scheme: string?, verifySsl: boolean?) → HttpConnection

Parameters

host: string

The remote hostname or IP address.

port: number?

The remote port number. Defaults to 80 for HTTP, 443 for HTTPS.

timeout: (number | TimeoutOptions)?

Either one timeout in seconds for every phase, or a table with connect, read, and write timeouts.

scheme: string?

"http" (default) or "https".

verifySsl: boolean?

Whether to verify the server's TLS certificate. Defaults to true.

Returns

HttpConnection

A new connection object.

HttpConnection:_applyTimeout

HttpConnection:_applyTimeout(phase: "connect" | "read" | "write") → ()

HttpConnection:setTimeouts

Updates the per-phase timeouts used by this connection.

You may pass a single number to apply the same timeout to connect, read, and write phases, or a table with explicit connect, read, and write values. Passing nil clears the timeout configuration.

HttpConnection:setTimeouts(timeout: (number | TimeoutOptions)?) → ()

Parameters

timeout: (number | TimeoutOptions)?

New timeout settings in seconds.

HttpConnection:connect

Opens the underlying TCP (and optionally TLS) connection.

This is called automatically on the first request, so you rarely need to call it directly.

HttpConnection:connect() → ()

HttpConnection:close

Closes the connection and releases associated resources.

It is safe to call close multiple times.

HttpConnection:close() → ()

HttpConnection:request

Sends an HTTP request over this connection.

Automatically connects if not already connected. Sets Host and Content-Length headers when not explicitly provided.

HttpConnection:request(method: string, path: string, headers: { [string]: string }?, body: string?, expectContinue: boolean?, bodyStream: UploadBodyStream?, bodyLength: number?) → ()

Parameters

method: string

The HTTP method (e.g. "GET", "POST").

path: string

The request path (e.g. "/api/users").

headers: { [string]: string }?

Optional table of request headers.

body: string?

Optional request body string.

expectContinue: boolean?

When true, waits for 100 Continue before sending a non-empty request body.

bodyStream: UploadBodyStream?

Optional incremental request-body reader.

bodyLength: number?

Optional exact byte size for bodyStream.

HttpConnection:_recvUntil

read from socket, respecting leftover from previous over-reads

HttpConnection:_recvUntil(delim: string) → (string, string)

HttpConnection:_recvExact

read exactly n bytes, respecting leftover

HttpConnection:_recvExact(n: number) → string

HttpConnection:_recvAll

read until connection closes, respecting leftover

HttpConnection:_recvAll() → string

HttpConnection:_recvSome

read up to n bytes, respecting leftover

HttpConnection:_recvSome(n: number) → string

HttpConnection:_recvChunked

read chunked transfer-encoding body

HttpConnection:_recvChunked() → (string, { [string]: string })

HttpConnection:_openResponse

HttpConnection:_openResponse(skipInformational: boolean) → HttpResponseStream

HttpConnection:_readResponse

HttpConnection:_readResponse(skipInformational: boolean) → HttpResponseInternal

HttpConnection:getResponse

HttpConnection:getResponse() → HttpResponse

HttpConnection:getResponseStream

HttpConnection:getResponseStream() → HttpResponseStream

HttpResponseStream

Properties

status: number

reason: string

headers: { [string]: string }

trailers: { [string]: string }

httpVersion: string

_connection: HttpConnection?

_closed: boolean

_mode: "buffer" | "length" | "chunked" | "close"

_keepAlive: boolean

_closeConnectionOnFinish: boolean

_remaining: number

_chunkRemaining: number

_buffer: string

_bufferOffset: number

HttpResponseStream:_finalize

HttpResponseStream:_finalize() → ()

HttpResponseStream:_readChunkHeader

HttpResponseStream:_readChunkHeader() → ()

HttpResponseStream:read

HttpResponseStream:read(count: number?) → string?

HttpResponseStream:readAll

HttpResponseStream:readAll() → string

HttpResponseStream:close

HttpResponseStream:close() → ()

UploadBodyStream

Properties

close: (((self: UploadBodyStream) → ()))?

UploadBodyStream:read

UploadBodyStream:read(size: number?) → string?

Types

HttpResponse

A completed HTTP response returned by HttpConnection.getResponse and the convenience request functions.

When a chunked response includes trailer headers, they are exposed on trailers after the body has been fully consumed.

status: number

reason: string

headers: { [string]: string }

trailers: { [string]: string }

body: string

httpVersion: string

TimeoutOptions

Per-phase timeout settings for an HttpConnection.

Use this when you want different limits for establishing the connection, sending request bytes, and waiting for response bytes.

connect: number?

read: number?

write: number?