HTTP¶
The rtype.Http plugin (src/rtype/plugins/http/, library plugin-http) lets a game's scripts send HTTPS requests
and read the responses: to call a web API, such as an AI model's, from gameplay. It requires no other plugin.
Why it looks like this¶
- Nothing waits. A request takes from milliseconds to many seconds (an AI model's answer), and a frame lasts 16 ms.
rtype.http.requestreturns an id at once; the response comes later as anrtype.HttpResponseevent. There is no thread: a curl multi handle is advanced, without waiting, by one system per frame (rtype.Http.Poll, PreUpdate), so systems of Update read a response in the frame it ends. - The server is authoritative, and keeps the secrets. A game lists the plugin on the side that makes the requests,
the server in a networked game (
if not engine.isClient then ... endinproject.luau). An API key is never written in a script: a header names it as{{env:NAME}}, the plugin reads the environment variable when it sends the request, and only the variableshttp.secretslists can be named. The key never passes through Luau. - A game reaches only what it names.
http.allowedHostsis empty by default, so nothing can be reached until the game lists its hosts. URLs arehttps://only, unlesshttp.allowHttp(a local server); no redirect is followed, since it could lead to another host. - Failures are data, mistakes are errors. A request that cannot be sent (a URL that is not one, a host that is not
allowed, a header without
:, an unknown secret, an unknown method, a body on a GET) throws anHttpException, which a script gets as a Luau error naming the cause. A request that was sent and failed (no network, a timeout, a response overhttp.maxResponseBytes) ends with anHttpResponsewhosestatusis 0 and whoseerrorsays why. An error status (404, 500) is a response:statusholds it,okis false. - Long texts. A request's URL, headers and body and a response's body are
std::stringfields: call data and events of any length (Systems). A script reads an event that owns memory as a copy made with its copy hook (Luau bridge).
Parts¶
| File | What |
|---|---|
HttpPlugin |
Inserts the HttpClient, registers the event and the calls, adds rtype.Http.Poll |
HttpSettings |
The http section of project.luau, checked when the plugin is created |
HttpClient |
The resource rtype.HttpClient: send(), cancel(), poll(); at most maxConcurrent in flight, the next ones queued (highest priority first, send order among equals, at most maxQueued) |
detail/CurlClient |
The libcurl transfers. Private: curl reaches no public header |
HttpEvents.hpp |
HttpResponse |
HttpCalls.hpp |
rtype.http.request, rtype.http.cancel, and the engine.http.request helper (HttpForms.luau) |
libcurl is a private package of the plugin: Schannel on Windows, OpenSSL 3 on Linux and macOS (the xmake package
picks it). curl_global_init() is reference-counted by curl and called once per HttpClient.
Settings¶
| Key | Default | Meaning |
|---|---|---|
allowedHosts |
{} |
The hosts a request may go to, exactly, any case: "api.example.com" |
allowHttp |
false |
Also allow http:// (a local server, the tests) |
maxConcurrent |
8 |
Requests in flight at once; the next ones wait their turn |
maxQueued |
256 |
Requests waiting for a slot; one more ends at once with the error queue_full (0: no waiting) |
timeout |
30 |
Seconds a request may take from its send, queue time included; a request may ask for less, never more |
maxResponseBytes |
1048576 |
A longer response body ends the request with an error |
secrets |
{} |
The environment variables a header may name as {{env:NAME}} |
From scripts¶
-- project.luau (server)
engine.settings.plugins = { "rtype.Http" }
engine.settings.http.allowedHosts = { "api.example.com" }
engine.settings.http.secrets = { "EXAMPLE_API_KEY" }
-- a server system
engine.ecs.system("game.Ask", {
phase = "Update",
query = {},
calls = { "rtype.http.request" },
events = { read = { "rtype.HttpResponse" } },
run = function(ctx)
local id = engine.http.request(ctx, {
method = "POST",
url = "https://api.example.com/v1/answer",
headers = { Authorization = "Bearer {{env:EXAMPLE_API_KEY}}", ["Content-Type"] = "application/json" },
body = '{"question":"where to mine?"}',
})
for response in ctx.events.read("rtype.HttpResponse") do
if response.ok then print(response.body) else print(response.status, response.error) end
end
end,
})
| Call | Arguments | Result |
|---|---|---|
rtype.http.request |
method ("GET"), url, headers (Name: value lines), body, timeout (0: the setting), priority (whole number, 0; higher is sent first) |
request, its id |
rtype.http.cancel |
request |
cancelled: false when it already ended |
engine.http.request(ctx, { url, method, headers, body, timeout, priority }) is the same call with headers as a table; ctx is
nil while the script loads. rtype.HttpResponse carries request, status, ok, body and error.
To build a body or read a reply as a table, use the JSON codec: Json.md (engine.json.encode / decode).
Queue and deadline¶
A request over maxConcurrent waits in a queue ordered by priority (higher first; send order among equals). The queue
holds maxQueued requests: the next one is not dropped silently, it ends with an HttpResponse whose error is
queue_full (kQueueFull), in the next poll. The timeout is a deadline set at send(): a request that waits too long
is never sent and ends with the error timeout; one that starts gets only the time left. So an agent's wait is bounded
by timeout, whatever the queue.
Tests¶
tests/plugins/HttpTests.cpp runs every case against LocalHttpServer (tests/plugins/LocalHttpServer.hpp), a plain
HTTP server on 127.0.0.1 built on Asio, so no test reaches the internet. HttpClient.DISABLED_ReachesARealHttpsServer
does (--gtest_also_run_disabled_tests), to check that a build speaks TLS. tests/engine/ScriptHttpTests.cpp sends
requests from scripts.
Later¶
- Streaming responses (an AI model's tokens as they come).
- Hot reload of the
httpsettings.