http

The built-in http module sends HTTP and HTTPS requests from a script. Requests are asynchronous: the response arrives in a callback, the game does not wait for the network.

The module is loaded with require and, like ffi, must be listed in the script dependencies on the website. Otherwise require returns the error module 'http' needs to be stated in the 'requirements' section of the script. A module from the dependencies is also available right away as the global variable http.

-- http is listed in the script dependencies on the website
local http = require("http")
print(type(http.get))   --> function

• Only http:// and https:// addresses are supported.
• There is no synchronous variant: the result arrives only in the callback.
• The callback runs on the game thread, at most one HTTP callback per frame. Several requests can be sent at once; their responses arrive one by one in the following frames.
• An error inside the callback is printed to the console, the script keeps running.
• When the script is turned off, its unfinished requests are cancelled and the callback does not arrive. The game does not freeze.
• The Windows system proxy is used automatically.
• Response headers are not passed to the script: only the status code and the body are available.

http.get(url: string, options: table | nil, callback: function)#

Sends a GET request.

• The callback is always the third argument. Without options pass nil: http.get(url, nil, cb). Calling http.get(url, cb) gives the error bad argument #3 ... (function expected, got nil).
• url is not a string — error bad argument #1 ... (string expected, got ...).

Returns: nothing.

local http = require("http")

http.get("https://httpbin.org/get", nil, function(r)
    if r.error then
        print("network error: ", r.error)
        return
    end
    print("status ", r.status, ", length ", #r.body)
end)

Other methods#

http.head, http.post, http.put, http.delete, http.patch take the same arguments as http.get and send a request with the corresponding method.

post, put and patch without json and params send an empty body with Content-Type: application/x-www-form-urlencoded.

Returns: nothing.

local http = require("http")

http.put("https://httpbin.org/put", { json = '{"p":1}' }, function(r) print("PUT ", r.status) end)
http.patch("https://httpbin.org/patch", { params = { q = "w" } }, function(r) print("PATCH ", r.status) end)
http.delete("https://httpbin.org/delete", { params = { id = "1" } }, function(r) print("DELETE ", r.status) end)
http.head("https://httpbin.org/get", nil, function(r) print("HEAD ", r.status, " ", #r.body) end)   --> HEAD 200 0

Request options#

The options table. All keys are optional, unknown keys are skipped. A key must be a string and a value must have the listed type, otherwise the error is bad argument ... (<type> expected, got ...).

params are not encoded: encode spaces, &, =, non-Latin characters and other special characters in values yourself as %XX. A space or a control character in the address gives the error invalid_url. Non-Latin characters in the address are also better encoded by yourself.

local http = require("http")

http.get("https://httpbin.org/get", {
    timeout = 10,
    headers = { ["X-Key"] = "secret" },
    params  = { page = "2", sort = "name" },   -- sent as ?page=2&sort=name (order is not guaranteed)
}, function(r)
    print(r.status)
end)

http.get("https://httpbin.org/basic-auth/user1/pass1", {
    authorization = { username = "user1", password = "pass1" },
}, function(r)
    print(r.status)   --> 200; with a wrong password — 401
end)

Response#

The callback receives one table:

• 4xx and 5xx codes are a normal response: status and body are filled, there is no error.
• Redirects are followed automatically, up to 50 hops. status and body are those of the last response. On 301, 302, 303 a POST request is repeated as GET without a body.
• The body arrives in full, including binary data: it is a Lua string with any bytes, zero bytes included.

local http = require("http")

http.get("https://httpbin.org/status/404", nil, function(r)
    if r.error then
        print("network: ", r.error)
    elseif r.status ~= 200 then
        print("server answered ", r.status)   --> server answered 404
    else
        print(r.body)
    end
end)

Network errors#

On a network error status = 0, body = "", and error is a string of the form <kind> or <kind> (<code>), where the code is a Windows system error code. Check the kind by the start of the string, for example r.error:find("^dns").

local http = require("http")

http.get("https://httpbin.org/delay/5", { timeout = 2 }, function(r)
    if r.error == "timeout" then
        print("the server did not answer within 2 seconds")
    elseif r.error then
        print("network: ", r.error)
    else
        print(r.status)
    end
end)

http.cookies()#

Creates an empty cookies object. Pass it in the cookie option so that requests send and keep cookies, like a browser.

• The object accumulates cookies from responses (including intermediate responses during redirects). A cookie with the same name, domain and path replaces the previous one, there are no duplicates. Cookies deleted by the server are removed.
• Cookies are stored in the object before the callback is called, and only if the request finished without a network error.
• The script cannot read the contents of the object: it only carries cookies between requests. tostring(obj) returns "cookies".
• Without the cookie option a request sends no cookies.

Returns: cookies — a new object.

local http = require("http")
local jar  = http.cookies()

-- The server sets the cookie srv=abc and redirects to /cookies
http.get("https://httpbin.org/cookies/set?srv=abc", { cookie = jar }, function(r)
    -- The next request with the same object sends srv=abc
    http.get("https://httpbin.org/cookies", { cookie = jar }, function(r2)
        print(r2.body)   --> { "cookies": { "srv": "abc" } }
    end)
end)

cookies:set(fields: table)#

Adds a cookie to the object manually. Another call with the same name, host and path replaces the value.

All fields are optional, unknown fields are skipped. A field of the wrong type gives the error bad argument ... (<type> expected, got ...). If the argument is not a table — table expected.

Returns: nothing.

local http = require("http")
local jar  = http.cookies()

jar:set({ host = "httpbin.org", name = "session", value = "1" })
jar:set({ host = "httpbin.org", name = "session", value = "2" })   -- replaces the previous one

http.get("https://httpbin.org/cookies", { cookie = jar }, function(r)
    print(r.body)   --> { "cookies": { "session": "2" } }
end)

Example: POST with JSON#

local http = require("http")

local body = json.encode({ name = "player", score = 10 })

http.post("https://httpbin.org/post", { json = body, timeout = 10 }, function(r)
    if r.error then
        print("network: ", r.error)
        return
    end
    if r.status ~= 200 then
        print("server answered ", r.status)
        return
    end
    local answer = json.decode(r.body)
    print(answer.json.name)   --> player
end)