RequestRemote

requestRemote

Queues a bounded asynchronous HTTP or HTTPS request from a server-side resource.

Syntax

number|false requestRemote(string url [, table options], function callback [, table callbackArguments])

Parameters

Name	Type	Required	Description
url	string	yes	The absolute public http:// or https:// URL to request, up to 2048 bytes.
options	table	no	Optional request settings: method, postData or body, headers, username, password, connectionAttempts, connectTimeout, timeout, and maxRedirects.
callback	function	yes	Called as callback(responseBody, responseInfo, ...callbackArguments) on the resource's server tick.
callbackArguments	table	no	Optional one-based array whose values are appended to the callback arguments.

Returns

Returns a numeric request identifier when queued, or false when validation, service availability, or resource limits reject the request.

Examples

Example 1

Read and decode a JSON response:

local requestId = requestRemote("https://api.example.com/status", {
    headers = { Accept = "application/json" },
    connectTimeout = 3000,
    timeout = 10000
}, function(body, info, label)
    if not info.success then
        outputDebugString(label .. " failed: " .. (info.error or "unknown error"))
        return
    end

    local data, errorMessage = fromJSON(body)
    if data == false then
        outputDebugString(errorMessage)
        return
    end
    outputDebugString(label .. " returned HTTP " .. info.statusCode)
end, {"status service"})

Example 2

Send a JSON POST request:

local payload = assert(toJSON({ event = "player_join", playerId = playerId }))

requestRemote("https://api.example.com/events", {
    method = "POST",
    body = payload,
    headers = { ["Content-Type"] = "application/json" }
}, function(body, info)
    if not info.success then
        outputDebugString(info.error or "Remote request failed")
    end
end)

Notes

• Available only in server-side resource scripts.
• The callback information table contains requestId, success, statusCode, headers, effectiveUrl, bytesReceived, durationMs, attempts, aborted, and error.
• Only HTTP and HTTPS are accepted. Loopback, private, link-local, reserved, documentation, and mixed public/private DNS results are rejected. Every redirect target is resolved and validated again.
• DNS answers are pinned for each transfer to prevent rebinding between validation and connection. TLS certificate and hostname verification remain enabled.
• Hard limits are 4 MiB request bodies, 8 MiB response bodies, 128 request headers, 256 response headers, 64 KiB aggregate header bytes, 3 attempts, 10 seconds to connect, 30 seconds total and 3 redirects. Compiled service defaults: 8 workers, 256 queued work items and 32 pending requests per resource.
• If a body is supplied without an explicit method, the method defaults to POST.
• Credentials remain server-side, but resources should still avoid placing secrets in URLs or logs.
• Expanded limits apply from update 0.1.3 BUILD81. See Scripting limits; earlier 0.1.3 binaries retain their old limits.