QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

2026-09-12T11:51:42Z

Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

← Older revision		Revision as of 11:51, 12 September 2026
Line 1:		Line 1:
	~~<!-- This page is generated automatically from the function definition: requestRemote. -->~~
	= requestRemote =		= requestRemote =
	Queues a bounded asynchronous HTTP or HTTPS request from a server-side resource.		Queues a bounded asynchronous HTTP or HTTPS request from a server-side resource.
Line 67:		Line 66:
	* 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.		* 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.		* DNS answers are pinned for each transfer to prevent rebinding between validation and connection. TLS certificate and hostname verification remain enabled.
	* ~~Default hard~~ limits are 1 MiB request bodies, 2 MiB response bodies, 32 request headers, ~~16 KiB~~ response headers, 3 attempts, 10 seconds to connect, 30 seconds total, 3 redirects, and 4 pending requests per resource.		* 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 <code>POST</code>.		* If a body is supplied without an explicit method, the method defaults to <code>POST</code>.
	* Credentials remain server-side, but resources should still avoid placing secrets in URLs or logs.		* 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.

	[[Category:Lua Functions]]		[[Category:Lua Functions]]

QCherry: Document asynchronous server-side HTTP API

2026-08-24T12:48:53Z

Document asynchronous server-side HTTP API

New page

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

== Syntax ==
<syntaxhighlight lang="lua">
number|false requestRemote(string url [, table options], function callback [, table callbackArguments])
</syntaxhighlight>

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

== Returns ==
Returns a numeric request identifier when queued, or <code>false</code> when validation, service availability, or resource limits reject the request.

== Examples ==
=== Example 1 ===
Read and decode a JSON response:
<syntaxhighlight lang="lua" line>
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"})
</syntaxhighlight>
=== Example 2 ===
Send a JSON POST request:
<syntaxhighlight lang="lua" line>
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)
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The callback information table contains <code>requestId</code>, <code>success</code>, <code>statusCode</code>, <code>headers</code>, <code>effectiveUrl</code>, <code>bytesReceived</code>, <code>durationMs</code>, <code>attempts</code>, <code>aborted</code>, and <code>error</code>.
* 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.
* Default hard limits are 1 MiB request bodies, 2 MiB response bodies, 32 request headers, 16 KiB response headers, 3 attempts, 10 seconds to connect, 30 seconds total, 3 redirects, and 4 pending requests per resource.
* If a body is supplied without an explicit method, the method defaults to <code>POST</code>.
* Credentials remain server-side, but resources should still avoid placing secrets in URLs or logs.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:Utility Functions]]
[[Category:HTTP Functions]]

RequestRemote - Revision history

QCherry: Document expanded scripting capacities and complete audited limits for 0.1.3 BUILD81

QCherry: Document asynchronous server-side HTTP API