lua-https

lua-https is a simple Lua HTTPS module using native platform backends specifically written for LÖVE 12.0 and supports Windows, Linux, macOS, iOS, and Android.

Reference

To use lua-https, load it with require like local https = require("https"). lua-https does not create global variables!

The https module exposes a single function: https.request.

Synopsis

Basic form:

code, body = https.request( url )

Advanced form:

code, body, headers = https.request( url, options )

Callback form (streaming):

ok, err = https.request( url, options, callback, context )

Arguments

• string url: HTTP or HTTPS URL to access.
• table options: Optional options for advanced mode.
  • string data: Additional data to send as application/x-www-form-urlencoded (unless specified otherwise in Content-Type header).
  • string method: HTTP method. If absent, it's either "GET" or "POST" depending on the data field above.
  • table headers: Additional headers to add to the request as key-value pairs.
• table or userdata callback: Optional callback target for streaming.
  • response(context, status, headers): Called once when status and headers are available.
  • body(context, chunk): Called one or more times as body chunks arrive. Return false, "message" to abort.
  • complete(context, err): Called once at the end. err is nil on success.
• any context: Optional user value passed as first argument to all callback functions.

Return values

Basic/advanced mode:

• number code: HTTP status code.
• string body: HTTP response body.
• table headers: HTTP response headers as key-value pairs in advanced mode only.

On failure in basic/advanced mode:

• nil, string err

Callback mode:

• boolean ok: true on success.
• string err: non-nil on failure, otherwise nil.

Migration

Old basic usage:

local code, body = https.request("https://example.com")
if not code then
	error(body)
end

New callback usage:

local state = { chunks = {} }
local ok, err = https.request("https://example.com", {}, {
	body = function(context, chunk)
		context.chunks[#context.chunks + 1] = chunk
		return true
	end,
	complete = function(context, completeErr)
		context.err = completeErr
	end
}, state)

if not ok then
	error(err)
end

local body = table.concat(state.chunks)

Old advanced usage:

local code, body, headers = https.request("https://example.com", {
	method = "GET",
	headers = { ["Accept"] = "application/json" }
})

New callback usage with response metadata:

local state = {}
local ok, err = https.request("https://example.com", {
	method = "GET",
	headers = { ["Accept"] = "application/json" }
}, {
	response = function(context, status, headers)
		context.status = status
		context.headers = headers
	end,
	body = function(context, chunk)
		context.body = (context.body or "") .. chunk
		return true
	end
}, state)

assert(ok, err)
print(state.status, state.headers["content-type"])

Callback Notes

• Header keys passed to response are lowercase.
• If body is not provided, callback mode still works.
• If complete is not provided, callback mode still works.
• Callback lookup supports metatable-based class/object style (__index).
• Callback mode only works on backends that support streaming callbacks.
• Callback mode is currently supported on Apple backends (macOS and iOS), WinINet on Windows, and the shared connection-based backends.
• Android does not yet support true streaming callbacks.

Platform Support

• macOS / iOS: Supported through the Apple NSURL backend.
• Windows: Supported through WinINet and the shared connection-based backends.
• Linux: Supported through the shared connection-based backends and cURL when available.
• Android: Basic and advanced request modes work, but true streaming callback mode is not implemented yet.

Examples

Basic:

local https = require("https")
local code, body = https.request("https://example.com")
assert(code == 200, body)

Advanced:

local https = require("https")
local code, body, headers = https.request("https://example.com", {
	method = "GET",
	headers = {
		["User-Agent"] = "lua-https"
	}
})
assert(code == 200, body)
print(headers["content-type"] or headers["Content-Type"])

Streaming with progress:

local https = require("https")

local state = { received = 0, total = 0 }
local ok, err = https.request("https://example.com/file", {}, {
	response = function(context, status, headers)
		print("status", status)
		context.total = tonumber(headers["content-length"]) or 0
	end,
	body = function(context, chunk)
		context.received = context.received + #chunk
		if context.total > 0 then
			print(string.format("%.2f%%", context.received * 100 / context.total))
		end
		return true
	end,
	complete = function(context, completeErr)
		if completeErr then
			print("failed:", completeErr)
		else
			print("done")
		end
	end
}, state)

assert(ok, err)

Class/object style callbacks:

local https = require("https")

local Downloader = {}
Downloader.__index = Downloader

function Downloader:response(status, headers)
	self.status = status
	self.total = tonumber(headers["content-length"]) or 0
	self.received = 0
end

function Downloader:body(chunk)
	self.received = self.received + #chunk
	return true
end

function Downloader:complete(err)
	self.error = err
end

local instance = setmetatable({}, Downloader)
local ok, err = https.request("https://example.com", {}, Downloader, instance)
assert(ok, err)

Compile From Source

While lua-https is bundled in LÖVE 12.0 by default, it's possible to compile the module from source and use it on earlier version of LÖVE or Lua. All compilation requires Lua 5.1 (or LuaJIT) headers and libraries.

Linux

Ensure you have CMake as well as the OpenSSL and cURL development libraries installed.

cmake -Bbuild -S. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$PWD/install
cmake --build build --target install

https.so can be found in the install folder.

Windows

Compilation is done using CMake. This assume MSVC toolchain is used. Change "x64" to "Win32" to compile for x86 32-bit platform or "ARM64" for ARM64 platform.

cmake -Bbuild -S. -A x64 -DCMAKE_INSTALL_PREFIX=%CD%\install
cmake --build build --config Release --target install

https.dll can be found in the install folder.

Android

Available since LÖVE 11.4 Proper 3rd-party C module support requires this LÖVE version.

Compilation is done by placing lua-https source code in <love-android>/love/src/jni/lua-modules. The structure will look like this:

<love-android>/love/src/jni/lua-modules/lua-https

• example
• src
• Android.mk
• CMakeLists.txt
• java.txt
• license.txt

Afterwards compile love-android as usual. The modules will be automatically embedded to the APK. This can be verified by checking the APK with Zip viewer application and inspecting files in lib/arm64-v8a and lib/armeabi-v7a.

Copyright

Copyright © 2019-2025 LOVE Development Team

lua-https is licensed under zLib license, same as LÖVE.