Difference between revisions of "lua-https"

m
m
Line 16: Line 16:
 
{{param|string|url|HTTP or HTTPS URL to access.}}
 
{{param|string|url|HTTP or HTTPS URL to access.}}
 
{{param|table|options|Optional options for advanced mode.}}
 
{{param|table|options|Optional options for advanced mode.}}
{{subparam|string|data|Additional data to send as application/x-www-form-urlencoded.}}
+
{{subparam|string|data|Additional data to send as application/x-www-form-urlencoded (unless specified otherwise in Content-Type header).}}
 
{{subparam|string|method|HTTP method. If absent, it's either "GET" or "POST" depending on the data field above.}}
 
{{subparam|string|method|HTTP method. If absent, it's either "GET" or "POST" depending on the data field above.}}
 
{{subparam|table|headers|Additional headers to add to the request as key-value pairs.}}
 
{{subparam|table|headers|Additional headers to add to the request as key-value pairs.}}
Line 23: Line 23:
 
{{param|string|body|HTTP response body or nil on failure.}}
 
{{param|string|body|HTTP response body or nil on failure.}}
 
{{param|table|headers|HTTP response headers as key-value pairs or nil on failure or option parameter above is nil.}}
 
{{param|table|headers|HTTP response headers as key-value pairs or nil on failure or option parameter above is nil.}}
 +
=== Notes ===
 +
To urlencode a Lua table suitable for application/x-www-form-urlencoded data, use a LuaSocket function.
 +
<source lang="lua">
 +
local url = require("socket.url")
 +
 +
function urlencode(list)
 +
-- Since order of pairs is undefined, the key-value order is also undefined.
 +
local result = {}
 +
for k, v in pairs(list) do
 +
result[#result + 1] = url.escape(k).."="..url.escape(v)
 +
end
 +
return table.concat(result, "&")
 +
end
 +
 +
-- Usage
 +
code, body, headers = https.request("https://example.com", {data = urlencode({key = "value", foo = "bar"})
 +
</source>
  
 
== Compile From Source ==
 
== Compile From Source ==

Revision as of 14:00, 3 November 2022

Available since LÖVE 12.0
Users can compile from source for earlier versions of LÖVE.


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.

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

Reference

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

The https table expose single function: https.request

Synopsis

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

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.

Returns

number code
HTTP status code, or 0 on failure.
string body
HTTP response body or nil on failure.
table headers
HTTP response headers as key-value pairs or nil on failure or option parameter above is nil.

Notes

To urlencode a Lua table suitable for application/x-www-form-urlencoded data, use a LuaSocket function.

local url = require("socket.url")

function urlencode(list)
	-- Since order of pairs is undefined, the key-value order is also undefined.
	local result = {}
	for k, v in pairs(list) do
		result[#result + 1] = url.escape(k).."="..url.escape(v)
	end
	return table.concat(result, "&")
end

-- Usage
code, body, headers = https.request("https://example.com", {data = urlencode({key = "value", foo = "bar"})

Compile From Source

While lua-https will be 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. Grab the source code at https://github.com/love2d/lua-https. All compilation requires Lua 5.1 (or LuaJIT) headers and libraries available.

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.

Linux

Compilation is done using CMake. Ensure you have OpenSSL and cURL development libraries installed to enable all supported Linux backends.

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.

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.

See Also




Other Languages