Tài liệu tham khảo API Script
Hodor chạy script của bạn trong một engine JavaScript tích hợp sẵn. Tùy loại script, Hodor gọi một trong các hàm điểm vào dưới đây vào đúng thời điểm — bạn chỉ cần cài đặt logic bạn cần. Nếu không thay đổi gì, hãy xóa hàm điểm vào không dùng để tránh các lệnh gọi không cần thiết.
Các đối tượng toàn cục và lớp khả dụng:
| Danh mục | Tên |
|---|---|
| Hàm điểm vào | onRequest, onResponse, onSessionCompleted, onSchedule, abort() |
Mô-đun $ gốc | $codec, $hash, $hmac, $crypto, $jwt, $format, $fs, $env, $uuid, $log |
| API chuẩn web | fetch, HTTPClient, setTimeout / setInterval, btoa / atob / sleep / require / TextEncoder / crypto, console |
| Lớp HTTP | Request, Response, Body, Headers, URLSearchParams |
| Lưu trữ | SharedPreferences, biến sdk |
| Ngữ cảnh | RewriteContext, CompletedContext, ScheduleContext |
Dùng console.log(...) ở bất kỳ đâu trong script để xem giá trị — kết quả hiển thị trong chế độ xem log của script.
Hàm Điểm Vào
Script được phát hiện bằng cách quét các khai báo async function — số tham số của mỗi hàm điểm vào là cố định (onRequest/onResponse nhận 3, onSessionCompleted nhận 4, onSchedule nhận 1). Các phép gán hàm mũi tên (let onRequest = async (...) => {}) không được phát hiện. Tên tham số tự do.
onRequest(context, url, request)
Thiết kế cho Rewrite Script và script trước khi gửi của Quick Request. Hàm này được gọi trước khi yêu cầu HTTP được gửi đến máy chủ. Hãy trả về request (có thể đã sửa).
| Tham số | Kiểu | Mô tả |
|---|---|---|
context | RewriteContext | Đối tượng ngữ cảnh. |
url | string | URL của yêu cầu HTTP. |
request | Request | Đối tượng yêu cầu 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)
Thiết kế cho Rewrite Script và script sau phản hồi của Quick Request. Hàm này được gọi trước khi phản hồi HTTP được gửi về máy khách. Hãy trả về response (có thể đã sửa).
| Tham số | Kiểu | Mô tả |
|---|---|---|
context | RewriteContext | Đối tượng ngữ c ảnh. |
url | string | URL của phản hồi HTTP. |
response | Response | Đối tượng phản hồi 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)
Thiết kế cho HTTP Completed Script. Được gọi không đồng bộ sau khi phản hồi HTTP được trả về, không ảnh hưởng đến việc truyền dữ liệu giữa ứng dụng và máy chủ. Hữu ích cho việc thu thập và chuyển tiếp dữ liệu.
| Tham số | Kiểu | Mô tả |
|---|---|---|
context | CompletedContext | Đối tượng ngữ cảnh. |
url | string | URL của yêu cầu HTTP. |
request | Request | Đối tượng yêu cầu HTTP. |
response | Response | Đối tượng phản hồi 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)
Thiết kế cho Schedule Script. Được gọi vào thời điểm kích hoạt định kỳ (hỗ trợ biểu thức cron 5 hoặc 6 phần). Dùng abort() để dừng vòng lặp định kỳ.
| Tham số | Kiểu | Mô tả |
|---|---|---|
context | ScheduleContext | Đối tượng ngữ cảnh. |
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()
Bên trong các script kênh (onRequest / onResponse / onSchedule), gọi abort() để dừng script và hủy ngay thực thi hiện tại — nó ném ra một AbortError mà Hodor báo lại cho bạn.
// ✅ correct — abort() is injected into the script scope
async function onRequest(context, url, request) {
if (url.includes("/tracking")) abort();
return request;
}
Tuyệt đối không khai báo onRequest(context, url, request, aborter) với tham số thứ 4. Số tham số của hàm điểm vào là cố định — tham số thứ 4 khiến điểm vào không thể được phát hiện.
Mô-đun Gốc
Tất cả mô-đun tiền tố $ được chèn vào khi runtime kích hoạt. Chúng được cài đặt gốc, trả về đồng bộ (trừ khi có ghi chú) và coi đầu vào chuỗi là UTF-8.
$codec — Mã hóa & Giải mã
Base64 / Hex / mã hóa phần trăm URL cho chuyển đổi giao thức và truyền dữ liệu.
| Phương thức | Trả về |
|---|---|
$codec.base64Encode(str) | Chuỗi Base64. |
$codec.base64Decode(str) | Chuỗi đã giải mã; đầu vào không hợp lệ trả về "" (không ném ngoại lệ). |
$codec.hexEncode(str) | Chuỗi hex chữ thường. |
$codec.hexDecode(str) | Chuỗi đã giải mã; ký tự không hợp lệ bị bỏ qua. |
$codec.urlEncode(str) | Chuỗi mã hóa phần trăm. |
$codec.urlDecode(str) | Chuỗi đã giải mã; chuỗi không hợp lệ được trả về nguyên trạng. |
$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 — Băm
Tính toán hàm băm cho kiểm tra toàn vẹn, đánh địa chỉ nội dung và ẩn danh hóa. Trả về hex chữ thường.
| Phương thức | Độ dài đầu ra |
|---|---|
$hash.md5(str) | 32 ký tự hex |
$hash.sha1(str) | 40 ký tự hex |
$hash.sha256(str) | 64 ký tự hex |
$hash.sha384(str) | 96 ký tự hex |
$hash.sha512(str) | 128 ký tự hex |
$hash.md5("hello"); // "5d41402abc4b2a76b9719d911017c592"
$hash.sha256("hello"); // "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
// integrity check
const checksum = $hash.sha256(JSON.stringify({user: "admin"}));
$hmac — Mã xác thực thông điệp
Băm có khóa để ký API và phát hiện can thiệp. Cả (data, key) đều được mã hóa UTF-8; trả về hex chữ thường.
| Phương thức | Thuật toán |
|---|---|
$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 — Mã hóa đối xứng
Mã hóa xác thực AES-GCM (khuyến nghị) và DES (tương thích cũ).
| Phương thức | Trả về |
|---|---|
$crypto.encryptAES(plaintext, password, options?) | Bản mã Base64; khi thất bại trả về chuỗi "Error: <reason>". |
$crypto.decryptAES(ciphertext, password, options?) | Văn bản rõ; ciphertext không hợp lệ trả về "Error: Invalid ciphertext". |
$crypto.encryptDES(plaintext, key) | DES-ECB + PKCS7, khóa bị cắt còn 8 byte → Base64. |
$crypto.decryptDES(ciphertext, key) | Văn bản rõ; đầu vào không phải Base64 trả về "". |
options: { keySize: 128 \| 192 \| 256 } (mặc định 256). Định dạng bản mã AES là base64(nonce[12] + ciphertext + tag[16]) — ghép cặp với decryptAES; khi tương tác với ngôn ngữ khác bạn phải tự tách định d ạng này.
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
Tạo, phân tích và xác minh chữ ký JWT (họ HMAC) cho các script luồng xác thực.
| Phương thức | Trả về |
|---|---|
$jwt.sign(payload, secret, algorithm?) | Chuỗi JWT; mặc định HS256. |
$jwt.decode(token) | Đối tượng {header, payload} (chữ ký không được xác minh); trả về null với token lỗi định dạng. |
$jwt.verify(token, secret, algorithm?) | boolean — kết quả xác minh chữ ký. |
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 — Định dạng dữ liệu
In đẹp và thu gọn JSON/XML phục vụ ghi log và gỡ lỗi. Các khóa JSON được sắp theo bảng chữ cái trong đầu ra.
| Phương thức | Trả về |
|---|---|
$format.json(str, indent?) | JSON in đẹp; thụt lề bị chặn trong khoảng 1–8 (mặc định 2); đầu vào không hợp lệ trả về "Error: Invalid JSON". |
$format.minify(str) | JSON thu gọn (khóa đã sắp, không khoảng trắng); đầu vào không hợp lệ trả về "Error: Invalid JSON". |
$format.xml(str) | XML thụt lề đơn giản. |
$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 — Hệ thống tệp
Đọc/ghi tệp nhẹ bên trong script (cấu hình, bộ nhớ đệm, xuất dữ liệu). Đường dẫn hỗ trợ mở rộng ~; write tự tạo các thư mục cha còn thiếu.
| Phương thức | Trả về |
|---|---|
$fs.read(path) | Nội dung UTF-8; thất bại trả về "Error: Cannot read file at <path>". |
$fs.readBinary(path) | Các byte dạng Base64; thất bại trả về "". |
$fs.write(path, content) | boolean — thành công. |
$fs.exists(path) | boolean. |
$fs.delete(path) | boolean; tệp không tồn tại trả về false. |
$fs.list(path) | string[] các mục thư mục; thất bại trả về []. |
$fs.info(path) | Chuỗi JSON {size, modified, isDirectory, path}; đường dẫn không tồn tại trả về 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
Hình dạng thất bại khác nhau theo từng phương thức: read trả về chuỗi "Error: ...", readBinary trả về "", list trả về [] và info trả về undefined — hãy xử lý từng trường hợp tương ứng.
$env — Biến môi trường
Biến môi trường tiến trình và đường dẫn hệ thống. Lưu ý: $env là môi trường tiến trình (chia sẻ giữa các lần thực thi, sống cùng tiến trình). Để lưu biến hướng người dùng một cách bền vững, hãy dùng sdk.setEnvVar hoặc SharedPreferences thay thế.
| Phương thức | Trả về |
|---|---|
$env.get(key) | Giá trị; khóa không tồn tại trả về "". |
$env.set(key, value) | boolean — kết quả setenv. |
$env.all() | Chuỗi JSON của tất cả biến môi trường. |
$env.cwd() | Thư mục làm việc hiện tại. |
$env.tmpDir() | Thư mục tạm. |
$env.homeDir() | Thư mục home của người dùng. |
$env.set("APP_VERSION", "1.0.0");
$env.get("APP_VERSION"); // "1.0.0"
const all = JSON.parse($env.all());
$uuid — UUID
Tạo và xác thực UUID (ID yêu cầu, khóa idempotency).
| Phương thức | Trả về |
|---|---|
$uuid.v4() | UUID v4 chuẩn (chữ hoa, có gạch nối), ví dụ "550e8400-E29B-41D4-A716-446655440000". |
$uuid.compact() | Dạng không gạch nối, chữ thường. |
$uuid.validate(str) | Chuỗi có phải UUID hợp lệ hay không. |
const id = $uuid.v4();
$uuid.compact(); // "550e8400e29b41d4a716446655440000"
$uuid.validate($uuid.v4()); // true
$uuid.validate("not-uuid"); // false
validate chỉ chấp nhận định dạng có gạch nối — validate($uuid.compact()) trả về false. Hãy chèn lại gạch nối trước khi xác thực một chuỗi dạng compact.
$log — Ghi log có cấu trúc
Các dòng log có dấu thời gian, có cấp độ, được định tuyến qua hệ thống console của engine (được thu vào chế độ xem log của script).
| Phương thức | Trả về |
|---|---|
$log.log(level, message, tag?) | Dòng log đã định dạng (cũng được in ra). |
$log.debug / info / warn / error(message) | Các phương thức cấp độ tiện lợi, chỉ xuất ra. |
Định dạng dòng log: [yyyy-MM-dd'T'HH:mm:ss.SSSZ] [LEVEL] [tag] message (phần [tag] bị bỏ qua khi không có tag).
$log.info("Server started on port 8080");
// [2025-07-24T01:11:45.548+0800] [INFO] Server started on port 8080
$log.log("info", "Request processed", "API");
// [2025-07-24T01:11:45.548+0800] [INFO] [API] Request processed
API Web
fetch
Gửi các yêu cầu HTTP thật từ script — kênh chính cho các quy trình kiểu Postman.
fetch(url: string, options?: object) → Promise<response>
options:
| Trường | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
method | string | "GET" | Không phân biệt hoa/thường; giá trị lạ rơi về GET. |
timeoutInterval | number | 30 | Tính bằng giây. |
headers | [[k, v]] hoặc [{k: v}] | [] | Cả hai dạng đều được chấp nhận. |
textBody | string | — | Nội dung body yêu cầu. |
encoding | string | — | "hex" nghĩa là textBody là một chuỗi hex. |
Giá trị đã phân giải là một đối tượng thuần: statusCode (số), headers (mảng các đối tượng một khóa, giữ lại khóa trùng) và textBody() — một hàm trả về {text, encoding} với tự động phát hiện bộ ký tự (body không giải mã được rơi về {text: <hex>, encoding: "hex"}). Giá trị bị từ chối là một chuỗi thông báo lỗi.
// GET
const rsp = await fetch("https://httpbin.org/get");
if (rsp.statusCode === 200) {
const body = rsp.textBody(); // {text: "...", encoding: "utf-8"}
const json = JSON.parse(body.text);
}
// POST JSON
const rsp2 = await fetch("https://httpbin.org/post", {
method: "POST",
headers: [["Content-Type", "application/json"]],
textBody: JSON.stringify({a: 1}),
timeoutInterval: 10,
});
HTTPClient
Lớp HTTPClient gửi các yêu cầu HTTP từ bất kỳ script nào (cài đặt trên nền fetch). Tất cả phương thức đều là async và trả về một đối tượng phản hồi có statusCode, headers và textBody().
| Phương thức | Mô tả |
|---|---|
HTTPClient.get(url, params?) | Gửi yêu cầu GET. |
HTTPClient.post(url, params?) | Gửi yêu cầu POST. |
HTTPClient.put(url, params?) | Gửi yêu cầu PUT. |
HTTPClient.update(url, params?) | Gửi yêu cầu UPDATE. |
HTTPClient.delete(url, params?) | Gửi yêu cầu DELETE. |
HTTPClient.request(url, method, params?) | Gửi yêu cầu với phương thức tùy chỉnh. |
params là một đối tượng tùy chọn gồm:
headers: đối tượng header yêu cầu, ví dụ{"key1": "value1"}body: body yêu cầu — một chuỗi, đối tượng JSON (tự được serialize) hoặc URLSearchParamstimeoutInterval: thời gian chờ tính bằng giây (mặc định 60)
try {
var params = {
"headers": {"key1": "value1"},
"body": {"a": "a1", "b": "b1"},
};
const response = await HTTPClient.post("https://dummyjson.com/products/1", params);
console.log(response.textBody().text);
} catch(error) {
console.log(error);
}
Bộ hẹn giờ
setTimeout / setInterval / clearTimeout / clearInterval hoạt động như trong trình duyệt. Các callback được điều phối trên một hàng đợi engine tuần tự, nên bộ hẹn giờ kích hoạt tin cậy bất kể luồng chủ.
| Hàm | Trả về |
|---|---|
setTimeout(callback, ms) | ID bộ hẹn giờ (chuỗi), kích hoạt một lần. |
setInterval(callback, ms) | ID bộ hẹn giờ, kích hoạt lặp lại. |
clearTimeout(id) / clearInterval(id) | Hủy (idempotent, ID lạ bị bỏ qua). |
await new Promise(resolve => setTimeout(resolve, 500)); // wait 0.5s
const timer = setInterval(() => console.log("tick"), 1000);
setTimeout(() => clearInterval(timer), 3500);
Hàm toàn cục
| Tên | Chữ ký | Mô tả |
|---|---|---|
btoa(str) | (string) → string | Mã hóa Base64 — ngữ nghĩa đối xứng UTF-8 (cho phép chuỗi ngoài Latin1, khác với trình duyệt). |
atob(str) | (string) → string | Giải mã Base64; đầu vào không hợp lệ trả về "". |
performance.now() | () → number | Số mili giây kể từ epoch (không phải thời điểm tải trang). |
sleep(ms) | (number) → Promise | Được resolve sau ms; dùng await sleep(1000). |
require(id) | (string) → any | Tải một thư viện script theo ngữ nghĩa CommonJS (module.exports); khóa là @libs/<key>, được phân giải theo thứ tự định danh thư viện script → tên thư viện script (duy nhất) → thư viện tích hợp sẵn; ném ngoại lệ khi không tìm thấy. |
TextEncoder | new TextEncoder().encode(str) | Mã hóa UTF-8 vào một Uint8Array (encoding luôn là "utf-8"). |
crypto.getRandomValues(n) | (Array) → number[] | Điền n giá trị UInt32 ngẫu nhiên. |
crypto.randomUUID() | () → string | UUID ngẫu nhiên (chữ hoa, có gạch nối). |
btoa("Hello"); // "SGVsbG8="
atob("SGVsbG8="); // "Hello"
btoa("中文"); // works — UTF-8 bytes are encoded
performance.now(); // 1760000000000.123
await sleep(100);
const { encode } = require("@libs/base64"); // built-in lib
const { sign } = require("@libs/sign-lib"); // your script library
new TextEncoder().encode("hi"); // Uint8Array [104, 105]
Thư viện được quản lý trong trình quản lý mô-đun script. Khóa require luôn là @libs/<key>: thư viện script của bạn được phân giải theo định danh trước (ổn định khi đổi tên), sau đó theo tên (khớp duy nhất), rồi đến các thư viện tích hợp sẵn @libs/base64 / @libs/hex. Thư viện xuất qua module.exports, có thể require thư viện khác, và khóa không tồn tại sẽ ném ngoại lệ (thất bại trước khi gửi sẽ hủy yêu cầu, thất bại sau phản hồi giữ nguyên phản hồi gốc). Xem hướng dẫn đầy đủ tại scripting Quick Request, Tải thư viện script bằng require().