Справочник API скриптов
Hodor выполняет ваши скрипты во встроенном JavaScript-движке. В зависимости от типа скрипта Hodor вызывает одну из функций входа ниже в нужный момент — вы реализуете только нужную логику. Если вы ничего не изменяете, удалите неиспользуемую функцию входа, чтобы избежать лишних вызовов.
Доступные глобальные объекты и классы:
| Категория | Имена |
|---|---|
| Функции входа | onRequest, onResponse, onSessionCompleted, onSchedule, abort() |
Нативные $-модули | $codec, $hash, $hmac, $crypto, $jwt, $format, $fs, $env, $uuid, $log |
| Стандартные Web API | fetch, HTTPClient, setTimeout / setInterval, btoa / atob / sleep / require / TextEncoder / crypto, console |
| HTTP-классы | Request, Response, Body, Headers, URLSearchParams |
| Хранилище | SharedPreferences, sdk-переменные |
| Контексты | RewriteContext, CompletedContext, ScheduleContext |
Используйте console.log(...) в любом месте скрипта, чтобы посмотреть значения — вывод отображается в журнале скрипта.
Функции входа
Скрипты обнаруживаются сканированием объявлений async function — количество параметров каждой функции входа фиксировано (onRequest/onResponse принимают 3, onSessionCompleted — 4, onSchedule — 1). Присваивания стрелочных функций (let onRequest = async (...) => {}) не обнаруживаются. Имена параметров свободные.
onRequest(context, url, request)
Предназначена для Rewrite Script и скриптов перед запросом Quick Request. Вызывается перед отправкой HTTP-зап роса на сервер. Верните (возможно измененный) request.
| Параметр | Тип | Описание |
|---|---|---|
context | RewriteContext | Объект контекста. |
url | string | URL HTTP-запроса. |
request | Request | Объект HTTP-запроса. |
// modify request body
async function onRequest(context, url, request) {
// parse to Text
var text = request.body.parseText()
console.log(text)
request.body = "this is a replaced request text"
// parse to JSON
var json = request.body.parseJSON()
json["script_json"] = "JSONValue"
request.body = json
// parse to URLSearchParams
var urlencoded = request.body.parseURLSearchParams()
urlencoded.append("script", "parseURLSearchParams")
request.body = urlencoded
// Done
return request;
}
// redirect, modify path / queries / headers
async function onRequest(context, url, request) {
console.log(url);
// set a parameter, you can get it in onResponse
context.parameters["custom"] = "custom parameter on request"
// redirect
request.scheme = "http"
request.path = "/upload/json"
request.host = "192.168.3.30"
request.port = 6000
// change method
request.method = "POST"
// queries operation
request.queries.append("name", "value1") // add query
request.queries.set("name", "value2") // replace or add query
request.queries.get("name") // get query by name
request.queries.delete("name") // delete query by name
// headers operation
request.headers.delete("accept") // delete header by name
request.headers.append("hodor", "custom value") // add name-value pair
request.headers.forEach((value, name) => {
console.log(name + ":" + value)
});
// Done
return request;
}
onResponse(context, url, response)
Предназначена для Rewrite Script и скриптов после ответа Quick Request. Вызывается перед отправкой HTTP-ответа клиенту. Верните (возможно измененный) response.
| Параметр | Тип | Описание |
|---|---|---|
context | RewriteContext | Объект контекста. |
url | string | URL HTTP-ответа. |
response | Response | Объект HTTP-ответа. |
// response body
async function onResponse(context, url, response) {
// parse to Text
var text = response.body.parseText()
console.log(text)
response.body = "this is a replaced response text"
// parse to JSON
var json = response.body.parseJSON()
json["script_json"] = "JSONValue"
response.body = json
// parse to URLSearchParams
var urlencoded = response.body.parseURLSearchParams()
urlencoded.append("script", "parseURLSearchParams")
response.body = urlencoded
// Done
return response;
}
// change status code and headers
async function onResponse(context, url, response) {
// get parameters set in onRequest
console.log(context.parameters["custom"]) // Output "custom parameter on request"
response.statusCode = 200 // change status code
response.statusPhrase = "OK" // change status phrase
response.headers.delete("accept")
response.headers.append("hodor", "custom value")
response.headers.forEach((value, name) => {
console.log(name + ":" + value)
});
// Done
return response
}
onSessionCompleted(context, url, request, response)
Предназначена для HTTP Completed Script. Вызывается асинхронно после возврата HTTP-ответа, не влияя на передачу данных между приложением и сервером. Полезна для сбора и пересылки данных.
| Параметр | Тип | Описание |
|---|---|---|
context | CompletedContext | Объект контекста. |
url | string | URL HTTP-запроса. |
request | Request | Объект HTTP-запроса. |
response | Response | Объект HTTP-ответа. |
// sample: pass session data to your own server
async function onSessionCompleted(context, url, request, response) {
try {
var reqText = request.body.parseText();
var rspText = response.body.parseText()
var params = {
"body": { // HTTPClient post body data
"url": url, // request url
"reqHeader": request.headers.encode(), // request headers
"reqText": reqText, // request body
"rspHeader": response.headers.encode(), // response headers
"rspText": rspText, // response body
},
"headers": { // HTTPClient headers
"from": "onSessionCompleted"
},
}
const rsp = await HTTPClient.post("http://192.168.3.30:8000/upload", params)
let text = rsp.body.parseText()
console.log(text)
} catch(error) {
console.log(error)
}
}
onSchedule(context)
Предназначена для Schedule Script. Вызывается в назначенное время срабатывания (поддерживаются cron-выражения из 5 или 6 частей). Используйте abort(), чтобы остановить цикл расписания.
| Параметр | Тип | Описание |
|---|---|---|
context | ScheduleContext | Объект контекста. |
async function onSchedule(context) {
// set custom parameters for next runloop
context.parameters["custom"] = "custom parameters for next runloop";
// repeated count
console.log(`repeatedCount ${context.repeatedCount}`);
// if repeatedCount is 2, abort schedule
if (context.repeatedCount == 2) {
abort()
}
// you can also use HTTPClient to send requests
const rsp = await HTTPClient.get("https://www.apple.com")
let text = rsp.body.parseText()
console.log(text)
}
abort()
Внутри канальных скриптов (onRequest / onResponse / onSchedule) вызовите abort(), чтобы остановить скрипт и немедленно прервать текущее выполнение — бросается AbortError, о котором Hodor сообщает вам.
// ✅ correct — abort() is injected into the script scope
async function onRequest(context, url, request) {
if (url.includes("/tracking")) abort();
return request;
}
Не объявляйте onRequest(context, url, request, aborter) с четвертым параметром. Количество параметров функций входа фиксировано — четвертый параметр делает точку входа необнаружимой.
Нативные модули
Все модули с префиксом $ внедряются при активации рантайма. Они реализованы нативно, возвращают синхронно (если не указано иное) и трактуют строковые входы как UTF-8.
$codec — Кодирование и декодирование
Base64 / Hex / URL percent-кодирование для преобразования протоколов и передачи данных.
| Метод | Возвращает |
|---|---|
$codec.base64Encode(str) | Строку Base64. |
$codec.base64Decode(str) | Декодированную строку; неверный вход возвращает "" (не бросает). |
$codec.hexEncode(str) | Строку строчного hex. |
$codec.hexDecode(str) | Декодированную строку; неверные символы пропускаются. |
$codec.urlEncode(str) | Percent-кодированную строку. |
$codec.urlDecode(str) | Декодированную строку; неверные последовательности возвращаются как есть. |
$codec.base64Encode("Hello, World!"); // "SGVsbG8sIFdvcmxkIQ=="
$codec.base64Decode("SGVsbG8sIFdvcmxkIQ=="); // "Hello, World!"
$codec.hexEncode("ABC"); // "414243"
$codec.hexDecode("414243"); // "ABC"
$codec.urlEncode("hello world&foo=bar"); // "hello%20world%26foo%3Dbar"
$hash — Хеширование
Вычисление дайджестов для проверок целостности, адресации контента и анонимизации. Возвращает строчный hex.
| Метод | Длина вывода |
|---|---|
$hash.md5(str) | 32 hex-символа |
$hash.sha1(str) | 40 hex-символов |
$hash.sha256(str) | 64 hex-символа |
$hash.sha384(str) | 96 hex-символов |
$hash.sha512(str) | 128 hex-символов |
$hash.md5("hello"); // "5d41402abc4b2a76b9719d911017c592"
$hash.sha256("hello"); // "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
// integrity check
const checksum = $hash.sha256(JSON.stringify({user: "admin"}));
$hmac — Код аутентификации сообщений
Хеширование с ключом для подписи API и обнаружения подмены. Оба (data, key) кодируются в UTF-8; возвращает строчный hex.
| Метод | Алгоритм |
|---|---|
$hmac.md5(data, key) | HMAC-MD5 |
$hmac.sha1(data, key) | HMAC-SHA1 |
$hmac.sha256(data, key) | HMAC-SHA256 |
$hmac.sha384(data, key) | HMAC-SHA384 |
$hmac.sha512(data, key) | HMAC-SHA512 |
const signature = $hmac.sha256("important data", "my-secret-key");
const isValid = (signature === $hmac.sha256("important data", "my-secret-key")); // true
$crypto — Симметричное шифрование
Аутентифицированное шифрование AES-GCM (рекомендуется) и DES (наследуемая совместимость).
| Метод | Возвращает |
|---|---|
$crypto.encryptAES(plaintext, password, options?) | Шифротекст Base64; сбои возвращают строку "Error: <reason>". |
$crypto.decryptAES(ciphertext, password, options?) | Plaintext; неверный шифротекст возвращает "Error: Invalid ciphertext". |
$crypto.encryptDES(plaintext, key) | DES-ECB + PKCS7, ключ усекается до 8 байт → Base64. |
$crypto.decryptDES(ciphertext, key) | Plaintext; не-Base64 вход возвращает "". |
options: { keySize: 128 \| 192 \| 256 } (по умолчанию 256). Формат AES-шифротекста — base64(nonce[12] + ciphertext + tag[16]) — парный к decryptAES; при взаимодействии с другими языками распаковать этот формат нужно самостоятельно.
const encrypted = $crypto.encryptAES("sensitive data", "my-password");
$crypto.decryptAES(encrypted, "my-password"); // "sensitive data"
// 128-bit key
const e128 = $crypto.encryptAES("data", "pass", { keySize: 128 });
// errors are returned as strings, not thrown — check the prefix
const out = $crypto.decryptAES("not-base64!!", "p");
if (out.startsWith("Error:")) { /* handle error */ }
$jwt — JSON Web Token
Создание, разбор и проверка подписи JWT (семейство HMAC) для скриптов аутентификационных потоков.
| Метод | Возвращает |
|---|---|
$jwt.sign(payload, secret, algorithm?) | Строку JWT; по умолчанию HS256. |
$jwt.decode(token) | Объект {header, payload} (подпись не проверяется); на некорректных токенах возвращает null. |
$jwt.verify(token, secret, algorithm?) | boolean — результат проверки подписи. |
algorithm: "HS256" | "HS384" | "HS512".
// sign
const payload = JSON.stringify({ sub: "user123", exp: Math.floor(Date.now() / 1000) + 3600 });
const token = $jwt.sign(payload, "my-secret", "HS256");
// decode — returns an object directly, no JSON.parse needed
const decoded = $jwt.decode(token);
decoded.header.alg; // "HS256"
decoded.payload.sub; // "user123"
// verify
$jwt.verify(token, "my-secret", "HS256"); // true
$jwt.verify(token, "wrong-secret", "HS256"); // false
// expiry check
const exp = $jwt.decode(token).payload.exp;
const expired = exp * 1000 < Date.now();
$format — Форматирование данных
Красивая печать и минификация JSON/XML для логирования и отладки. Ключи JSON сортируются по алфавиту в выводе.
| Метод | Возвращает |
|---|---|
$format.json(str, indent?) | Отформатированный JSON; indent ограничен 1–8 (по умолчанию 2); неверный вход возвращает "Error: Invalid JSON". |
$format.minify(str) | Минифицированный JSON (отсортированные ключи, без whitespace); неверный вход возвращает "Error: Invalid JSON". |
$format.xml(str) | Простой XML с отступами. |
$format.json('{"b":1,"a":2}');
// {
// "a": 2,
// "b": 1
// }
$format.json('{"a":2}', 4); // 4-space indent
$format.minify('{ "a": 2 }'); // '{"a":2}'
$format.xml('<root><child>t</child></root>');
// <root>
// <child>t</child>
// </root>
$fs — Файловая система
Легкое чтение/запись файлов внутри скриптов (конфигурация, кэш, экспорт). Пути поддерживают раскрытие ~; write автоматически создает недостающие родительские каталоги.
| Метод | Возвращает |
|---|---|
$fs.read(path) | UTF-8 контент; сбой возвращает "Error: Cannot read file at <path>". |
$fs.readBinary(path) | Байты как Base64; сбой возвращает "". |
$fs.write(path, content) | boolean — успех. |
$fs.exists(path) | boolean. |
$fs.delete(path) | boolean; отсутствующие файлы возвращают false. |
$fs.list(path) | string[] записей каталога; сбой возвращает []. |
$fs.info(path) | JSON-строку {size, modified, isDirectory, path}; отсутствующие пути возвращают undefined. |
const file = $env.tmpDir() + "/hodor-test.txt";
$fs.write(file, "Hello from Hodor!");
$fs.read(file); // "Hello from Hodor!"
$fs.exists(file); // true
$fs.list($env.tmpDir()); // ["hodor-test.txt", ...]
const info = JSON.parse($fs.info(file));
info.size; // byte count
info.isDirectory; // false
$fs.delete(file); // true
Формы сбоев различаются по методам: read возвращает строку "Error: ...", readBinary возвращает "", list возвращает [], а info возвращает undefined — обрабатывайте каждый соответствующим образом.
$env — Переменные окружения
Переменные окружения процесса и системные пути. Примечание: $env — это окружение процесса (общее между выполнениями, живет вместе с процессом). Для сохранения пользовательских переменных используйте sdk.setEnvVar или SharedPreferences.
| Метод | Возвращает |
|---|---|
$env.get(key) | Значение; отсутствующие ключи возвращают "". |
$env.set(key, value) | boolean — результат setenv. |
$env.all() | JSON-строку всех переменных окружения. |
$env.cwd() | Текущий рабочий каталог. |
$env.tmpDir() | Временный каталог. |
$env.homeDir() | Дома шний каталог пользователя. |
$env.set("APP_VERSION", "1.0.0");
$env.get("APP_VERSION"); // "1.0.0"
const all = JSON.parse($env.all());
$uuid — UUID
Генерация и валидация UUID (идентификаторы запросов, ключи идемпотентности).
| Метод | Возвращает |
|---|---|
$uuid.v4() | Стандартный v4 UUID (заглавные, с дефисами), например "550e8400-E29B-41D4-A716-446655440000". |
$uuid.compact() | Форму без дефисов, строчными. |
$uuid.validate(str) | Является ли строка валидным UUID. |
const id = $uuid.v4();
$uuid.compact(); // "550e8400e29b41d4a716446655440000"
$uuid.validate($uuid.v4()); // true
$uuid.validate("not-uuid"); // false
validate принимает только формат с дефисами — validate($uuid.compact()) возвращает false. Перед валидацией compact-строки вставьте дефисы обратно.