EasyUniversal / DocsДокументация · SDK 0.3Подписка Universal ↗
Easy Universal / Справочник SDK

Асинхронный HTTP

AngelScript · native runtime · локальная сборка

HTTP SDK — API 0.1, GET и ограниченный POST

Асинхронный для скрипта, ограниченный GET/POST-клиент. Язык — AngelScript.
Это источник разрешённых данных для SDK, а не обход защиты игр и не WebSocket.
Сеть выключена по умолчанию. Запускайте только доверенные пакеты.

Разрешения

В manifest нужны permission http и от одного до четырёх точных origins:

"permissions": ["render", "http"],
"http_origins": ["https://example.com"]

Origin — схема и хост без пути, query, порта или завершающего /.
HTTPS: только lowercase ASCII hostname, стандартный порт 443; Unicode/IPv6
и явно записанный :443 не поддерживаются. Для разрешённой локальной телеметрии
допускается http://127.0.0.1:PORT, где PORT — 1–65535 без ведущих нулей.
Обычный HTTP к другим хостам запрещён. Дубли и неизвестные разрешения отклоняются.

В клиенте сначала прочитайте адреса в Details, затем Load script. GET включается
автоматически только для этих точных origins. Пакеты с http_post требуют
отдельного Allow HTTP POST uploads для отправки POST; GET работает и без
него. POST-согласие сбрасывается при смене fingerprint пакета. Во время сеанса
адреса и разрешение заморожены.

CLI: сначала inspect, затем preview PACKAGE --allow-http. Флаг разрешает
все origins из проверенного manifest; без флага запросы запрещены.
В running session нельзя менять ID, permissions, adapter или http_origins через
Reload — остановите пакет, Refresh, прочитайте новые адреса и разрешите снова.
Это не защита от конкурентной подмены локальных файлов другим процессом.

API

bool http::enabled();
uint http::get(const string &in url);
uint http::post(const string &in url, const string &in body);
string http::state(uint id);
uint http::status(uint id);
string http::body(uint id);
string http::error(uint id);
bool http::release(uint id);

enabled можно вызывать без разрешения. Остальные функции без разрешения
вызывают script exception. get проверяет URL и ставит запрос в очередь,
не ждёт DNS/соединения/ответа; возвращает ID. Неверный URL и исчерпанные slots
вызывают exception. Все callbacks остаются последовательными.

  • pending: результат ещё не готов, status=0, body/error пустые.
  • complete: HTTP-транспорт завершён, доступны status и raw body.

Это не обязательно 200: 404/401 тоже complete, проверьте status сами.

  • error: транспорт/таймаут/лимит/редирект; body пустой, error содержит причину.

Status может быть 0 либо уже полученным HTTP-кодом.

  • unknown: ID отсутствует/освобождён; status=0, body/error пустые.

release удаляет результат или отменяет публикацию pending-запроса;
возвращает false для неизвестного ID. Активный сетевой вызов не прерывается
мгновенно: остановка проверяется между native-операциями. Новый запрос может
подождать освобождения transport thread. После Reload/Stop старые результаты
очищаются; ID не переиспользуются внутри сессии. Ответ хранится до release.

POST: отдельное разрешение

post требует permissions ["http", "http_post"], объявленных http_origins и
явного сетевого согласия. http_post без http отклоняется. Старые GET-пакеты
не могут отправлять POST даже при сетевом согласии. Details показывает GET +
POST uploads для такого пакета; перечитайте исходник перед разрешением.

Тело копируется, максимум 8192 байта, включая NUL/binary; фиксированный
Content-Type: application/octet-stream. JSON можно передать как байты, но
endpoint должен принимать этот media type. Произвольные заголовки и методы
не предоставлены. API/очередь/таймауты/release/Reload такие же, как у GET.
Отмена публикации результата не отменяет уже совершённое действие на сервере.
Не повторяйте POST автоматически после timeout: сервер мог обработать запрос.

Пример

uint request = 0;
void on_load() {
    if (http::enabled()) request = http::get("https://example.com/data.json");
}
void on_frame() {
    if (request == 0 || http::state(request) == "pending") return;
    if (http::state(request) == "complete" && http::status(request) == 200) {
        string bytes = http::body(request);
        // Validate format, bounds and freshness before using data.
    } else runtime::log(http::error(request));
    http::release(request); request = 0;
}

/data.json здесь условный endpoint, не обещание существующего API.
Bundled HTTP demo · explicit consent использует реальный /, но отправляет
запрос только после нажатия кнопки в собственном preview. Автоматических
запросов при запуске/Reload нет. Не передавайте секреты в URL или журнал.

Ограничения и безопасность

  • GET/POST только к exact origin: example.com.evil не совпадает с example.com.

Путь обязан начинаться с /; URL до 2048 ASCII bytes. Нужен percent encoding
для Unicode; control bytes/их escapes, spaces, fragments и \ запрещены.

  • До четырёх незавершённых/сохранённых запросов вместе; один transport thread.

Между завершением предыдущего и началом следующего — не менее 250 ms.
Ответ до 64 KiB, headers до 16 KiB. Нет автоматических повторов.

  • Отдельные WinHTTP timeouts по 500 ms; общий transfer deadline 3 s проверяется

между native-вызовами, не включает ожидание в очереди и не является жёсткой
гарантией времени отдельного OS-вызова. Watchdog supervisor остаётся последним
ограничением при зависшем teardown. UI/script callbacks сеть не ожидают.

  • Не следуем редиректам (300–399 = error), не используем proxy, cookies,

automatic authentication, referrer или script headers. POST требует http_post;
нет потокового upload, PUT/PATCH/DELETE и автоматических повторов.
HTTPS использует обычную проверку сертификата Windows; она не отключается.
TLS 1.2 (и 1.3, если поддержан собранными headers/Windows); старые протоколы
не включаются. Особенности phase/header timeouts описаны в
[WinHTTP option flags](https://learn.microsoft.com/en-us/windows/win32/winhttp/o…).

  • Grant — доверие к указанному сервису, не IP-песочница: DNS не закреплён,

разрешённый HTTPS-хост может разрешиться в локальный/private адрес. Не выдавайте
доступ непроверенному домену или локальному сервису. Job — не OS sandbox.

  • Body — bytes, без автоматического JSON parsing, decoding, HTML rendering,

decompression или disk writes. NUL/binary допустимы; существующие JSON helpers
принимают максимум 8 KiB. Проверяйте размер и формат отдельно.

  • Нет WebSocket, HTTP adapter entity source, произвольных script threads или

сетевой совместимости API Ech0. Не добавляется автоматическая поддержка игр.

tests/http.ps1 проверяет owned loopback server, реальные SDK bindings, consent,
quotas, redirects, binary/size, timeout/deadline, lifecycle и изменение origins.
Публичные HTTPS-сервисы и длительная работа на реальной сети требуют отдельной
проверки; offline/loopback тест не доказывает совместимость внешнего API.

Easy Universal — отдельный проект. Easy External не изменён.