Dokumentacja API skryptów
Hodor uruchamia Twoje skrypty we wbudowanym silniku JavaScript. W zależności od typu skryptu Hodor wywołuje w odpowiednim momencie jedną z poniższych funkcji wejściowych — implementujesz tylko potrzebną logikę. Jeśli czegoś nie modyfikujesz, usuń nieużywaną funkcję wejściową, aby uniknąć zbędnych wywołań.
Dostępne globalne obiekty i klasy:
| Kategoria | Nazwy |
|---|---|
| Funkcje wejściowe | onRequest, onResponse, onSessionCompleted, onSchedule, abort() |
Natywne moduły $ | $codec, $hash, $hmac, $crypto, $jwt, $format, $fs, $env, $uuid, $log |
| Standardowe API webowe | fetch, HTTPClient, setTimeout / setInterval, btoa / atob / sleep / require / TextEncoder / crypto, console |
| Klasy HTTP | Request, Response, Body, Headers, URLSearchParams |
| Przechowywanie | SharedPreferences, zmienne sdk |
| Konteksty | RewriteContext, CompletedContext, ScheduleContext |
Użyj console.log(...) w dowolnym miejscu skryptu, aby podejrzeć wartości — wyjście pokazuje się w widoku logów skryptu.
Funkcje wejściowe
Skrypty są wykrywane przez skanowanie w poszukiwaniu deklaracji async function — liczba parametrów każdej funkcji wejściowej jest stała (onRequest/onResponse przyjmują 3, onSessionCompleted przyjmuje 4, onSchedule przyjmuje 1). Przypisania funkcji strzałkowych (let onRequest = async (...) => {}) nie są wykrywane. Nazwy parametrów są dowolne.
onRequest(context, url, request)
Przeznaczona dla Rewrite Script i skryptów przed wysłaniem Quick Request. Funkcja wywoływana przed wysłaniem żądania HTTP do serwera. Zwróć (ewentualnie zmodyfikowane) request.
| Parametr | Typ | Opis |
|---|---|---|
context | RewriteContext | Obiekt kontekstu. |
url | string | URL żądania HTTP. |
request | Request | Obiekt żądania 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)
Przeznaczona dla Rewrite Script i skryptów po odpowiedzi Quick Request. Funkcja wywoływana przed odesłaniem odpowiedzi HTTP do klienta. Zwróć (ewentualnie zmodyfikowaną) response.
| Parametr | Typ | Opis |
|---|---|---|
context | RewriteContext | Obiekt kontekstu. |
url | string | URL odpowiedzi HTTP. |
response | Response | Obiekt odpowiedzi 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)
Przeznaczona dla HTTP Completed Script. Wywoływana asynchronicznie po zwróceniu odpowiedzi HTTP, bez wpływu na transmisj ę danych między aplikacją a serwerem. Przydatna do zbierania i przekazywania danych.
| Parametr | Typ | Opis |
|---|---|---|
context | CompletedContext | Obiekt kontekstu. |
url | string | URL żądania HTTP. |
request | Request | Obiekt żądania HTTP. |
response | Response | Obiekt odpowiedzi 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)
Przeznaczona dla Schedule Script. Wywoływana w zaplanowanym momencie wyzwalania (obsługiwane są wyrażenia cron 5- lub 6-częściowe). Użyj abort(), aby zatrzymać pętlę harmonogramu.
| Parametr | Typ | Opis |
|---|---|---|
context | ScheduleContext | Obiekt kontekstu. |
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()
Wewnątrz skryptów kanału (onRequest / onResponse / onSchedule) wywołaj abort(), aby zatrzymać skrypt i natychmiast przerwać bieżące wykonanie — rzuca AbortError, który Hodor raportuje z powrotem do Ciebie.
// ✅ correct — abort() is injected into the script scope
async function onRequest(context, url, request) {
if (url.includes("/tracking")) abort();
return request;
}
Nie deklaruj onRequest(context, url, request, aborter) z czwartym parametrem. Liczba parametrów funkcji wejściowych jest stała — czwarty parametr sprawia, że punkt wejścia staje się niewykrywalny.
Moduły natywne
Wszystkie moduły z prefiksem $ są wstrzykiwane przy aktywacji środowiska wykonawczego. Są zaimplementowane natywnie, zwracają synchronicznie (chyba że zaznaczono) i traktują wejściowe ciągi jako UTF-8.
$codec — Kodowanie i dekodowanie
Base64 / Hex / kodowanie procentowe URL do konwersji protokołów i transferu danych.
| Metoda | Zwraca |
|---|---|
$codec.base64Encode(str) | Ciąg Base64. |
$codec.base64Decode(str) | Zdekodowany ciąg; niepoprawne wejście zwraca "" (nie rzuca wyjątku). |
$codec.hexEncode(str) | Ciąg hex małymi literami. |
$codec.hexDecode(str) | Zdekodowany ciąg; niepoprawne znaki są pomijane. |
$codec.urlEncode(str) | Ciąg zakodowany procentowo. |
$codec.urlDecode(str) | Zdekodowany ciąg; niepoprawne sekwencje zwracane są w oryginalnej postaci. |
$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 — Funkcje skrótu
Obliczanie skrótów dla kontroli integralności, adresowania treści i anonimizacji. Zwraca hex małymi literami.
| Metoda | Długość wyjścia |
|---|---|
$hash.md5(str) | 32 znaki hex |
$hash.sha1(str) | 40 znaków hex |
$hash.sha256(str) | 64 znaki hex |
$hash.sha384(str) | 96 znaków hex |
$hash.sha512(str) | 128 znaków hex |
$hash.md5("hello"); // "5d41402abc4b2a76b9719d911017c592"
$hash.sha256("hello"); // "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
// integrity check
const checksum = $hash.sha256(JSON.stringify({user: "admin"}));
$hmac — Kod uwierzytelniania wiadomości
Haszowanie z kluczem do podpisywania API i wykrywania manipulacji. Zarówno (data, key) są kodowane UTF-8; zwraca hex małymi literami.
| Metoda | Algorytm |
|---|---|
$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 — Szyfrowanie symetryczne
Uwierzytelnione szyfrowanie AES-GCM (zalecane) oraz DES (dla zgodności ze starszymi systemami).
| Metoda | Zwraca |
|---|---|
$crypto.encryptAES(plaintext, password, options?) | Szyfrogram Base64; niepowodzenia zwracają ciąg "Error: <reason>". |
$crypto.decryptAES(ciphertext, password, options?) | Tekst jawny; niepoprawny szyfrogram zwraca "Error: Invalid ciphertext". |
$crypto.encryptDES(plaintext, key) | DES-ECB + PKCS7, klucz skracany do 8 bajtów → Base64. |
$crypto.decryptDES(ciphertext, key) | Tekst jawny; wejście spoza Base64 zwraca "". |
options: { keySize: 128 \| 192 \| 256 } (domyślnie 256). Format szyfrogramu AES to base64(nonce[12] + ciphertext + tag[16]) — używaj go w parze z decryptAES; przy interoperacyjności z innymi językami musisz sam rozpakować ten format.
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
Tworzenie, parsowanie i weryfikacja podpisu JWT (rodzina HMAC) dla skryptów przepływów uwierzytelniania.
| Metoda | Zwraca |
|---|---|
$jwt.sign(payload, secret, algorithm?) | Ciąg JWT; domyślnie HS256. |
$jwt.decode(token) | Obiekt {header, payload} (podpis nie jest weryfikowany); dla zniekształconych tokenów zwraca null. |
$jwt.verify(token, secret, algorithm?) | boolean — wynik weryfikacji podpisu. |
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 — Formatowanie danych
Formatowanie JSON/XML (pretty-print) i minifikacja do logowania i debugowania. Klucze JSON w wyjściu są sortowane alfabetycznie.
| Metoda | Zwraca |
|---|---|
$format.json(str, indent?) | Sformatowany JSON; wcięcie ograniczone do 1–8 (domyślnie 2); niepoprawne wejście zwraca "Error: Invalid JSON". |
$format.minify(str) | Zminifikowany JSON (posortowane klucze, bez białych znaków); niepoprawne wejście zwraca "Error: Invalid JSON". |
$format.xml(str) | Prosty XML z wcięciami. |
$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 — System plików
Lekkie odczytywanie/zapisywanie plików wewnątrz skryptów (konfiguracja, cache, eksport). Ścieżki obsługują rozwijanie ~; write automatycznie tworzy brakujące katalogi nadrzędne.
| Metoda | Zwraca |
|---|---|
$fs.read(path) | Treść UTF-8; niepowodzenie zwraca "Error: Cannot read file at <path>". |
$fs.readBinary(path) | Bajty jako Base64; niepowodzenie zwraca "". |
$fs.write(path, content) | boolean — sukces. |
$fs.exists(path) | boolean. |
$fs.delete(path) | boolean; brakujące pliki zwracają false. |
$fs.list(path) | string[] wpisów katalogu; niepowodzenie zwraca []. |
$fs.info(path) | Ciąg JSON {size, modified, isDirectory, path}; brakujące ścieżki zwracają 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
Kształty niepowodzeń różnią się zależnie od metody: read zwraca ciąg "Error: ...", readBinary zwraca "", list zwraca [], a info zwraca undefined — obsługuj każde odpowiednio.
$env — Zmienne środowiskowe
Zmienne środowiskowe procesu i ścieżki systemowe. Uwaga: $env to środowisko procesu (współdzielone między wykonaniami, żyje z procesem). Aby utrwalać zmienne widoczne dla użytkownika, użyj zamiast tego sdk.setEnvVar albo SharedPreferences.
| Metoda | Zwraca |
|---|---|
$env.get(key) | Wartość; brakujące klucze zwracają "". |
$env.set(key, value) | boolean — wynik setenv. |
$env.all() | Ciąg JSON wszystkich zmiennych środowiskowych. |
$env.cwd() | Bieżący katalog roboczy. |
$env.tmpDir() | Katalog tymczasowy. |
$env.homeDir() | Katalog domowy użytkownika. |
$env.set("APP_VERSION", "1.0.0");
$env.get("APP_VERSION"); // "1.0.0"
const all = JSON.parse($env.all());
$uuid — UUID
Generowanie i walidacja UUID (identyfikatory żądań, klucze idempotencji).
| Metoda | Zwraca |
|---|---|
$uuid.v4() | Standardowy UUID v4 (wielkie litery, z myślnikami), np. "550e8400-E29B-41D4-A716-446655440000". |
$uuid.compact() | Forma bez myślników, małymi literami. |
$uuid.validate(str) | Czy ciąg jest poprawnym UUID. |
const id = $uuid.v4();
$uuid.compact(); // "550e8400e29b41d4a716446655440000"
$uuid.validate($uuid.v4()); // true
$uuid.validate("not-uuid"); // false
validate akceptuje wyłącznie format z myślnikami — validate($uuid.compact()) zwraca false. Przed walidacją ciągu compact wstaw ponownie myślniki.
$log — Logowanie strukturalne
Linie logu ze znacznikiem czasu i poziomem, routowane przez system konsoli silnika (zbierane do widoku logów skryptu).
| Metoda | Zwraca |
|---|---|
$log.log(level, message, tag?) | Sformatowana linia logu (także wypisywana). |
$log.debug / info / warn / error(message) | Metody pomocnicze dla poziomów, tylko wyjście. |
Format linii logu: [yyyy-MM-dd'T'HH:mm:ss.SSSZ] [LEVEL] [tag] message (segment [tag] jest pomijany, gdy tag nie jest podany).
$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 webowe
fetch
Wysyłaj prawdziwe żądania HTTP ze skryptów — główny kanał dla przepływów w stylu Postman.
fetch(url: string, options?: object) → Promise<response>
options:
| Pole | Typ | Domyślnie | Opis |
|---|---|---|---|
method | string | "GET" | Niewrażliwe na wielkość liter; nieznane wartości wracają do GET. |
timeoutInterval | number | 30 | Sekundy. |
headers | [[k, v]] albo [{k: v}] | [] | Akceptowane są obie formy. |
textBody | string | — | Treść ciała żądania. |
encoding | string | — | "hex" oznacza, że textBody jest ciągiem hex. |
Wartością wynikową jest zwykły obiekt: statusCode (number), headers (tablica obiektów o jednym kluczu, z zachowaniem duplikatów) oraz textBody() — funkcja zwracająca {text, encoding} z automatycznym wykrywaniem zestawu znaków (nieodkodowywalne treści wracają jako {text: <hex>, encoding: "hex"}). Wartością odrzucenia jest ciąg z komunikatem błędu.
// 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
Klasa HTTPClient wysyła żądania HTTP z dowolnego skryptu (zaimplementowana na bazie fetch). Wszystkie metody są async i zwracają obiekt odpowiedzi z statusCode, headers i textBody().
| Metoda | Opis |
|---|---|
HTTPClient.get(url, params?) | Wyślij żądanie GET. |
HTTPClient.post(url, params?) | Wyślij żądanie POST. |
HTTPClient.put(url, params?) | Wyślij żądanie PUT. |
HTTPClient.update(url, params?) | Wyślij żądanie UPDATE. |
HTTPClient.delete(url, params?) | Wyślij żądanie DELETE. |
HTTPClient.request(url, method, params?) | Wyślij żądanie z niestandardową metodą. |
params to opcjonalny obiekt z polami:
headers: obiekt nagłówków żądania, np.{"key1": "value1"}body: ciało żądania — ciąg znaków, obiekt JSON (serializowany automatycznie) albo URLSearchParamstimeoutInterval: limit czasu w sekundach (domyślnie 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);
}
Timery
setTimeout / setInterval / clearTimeout / clearInterval działają jak w przeglądarkach. Wywołania zwrotne są dysponowane na szeregowej kolejce silnika, więc timery odpalają niezawodnie niezależnie od wątku gospodarza.
| Funkcja | Zwraca |
|---|---|
setTimeout(callback, ms) | Identyfikator timera (string), odpala się raz. |
setInterval(callback, ms) | Identyfikator timera, odpala się wielokrotnie. |
clearTimeout(id) / clearInterval(id) | Anuluj (idempotentne, nieznane identyfikatory są ignorowane). |
await new Promise(resolve => setTimeout(resolve, 500)); // wait 0.5s
const timer = setInterval(() => console.log("tick"), 1000);
setTimeout(() => clearInterval(timer), 3500);
Funkcje globalne
| Nazwa | Sygnatura | Opis |
|---|---|---|
btoa(str) | (string) → string | Kodowanie Base64 — symetryczna semantyka UTF-8 (ciągi spoza Latin1 są dozwolone, w przeciwieństwie do przeglądarek). |
atob(str) | (string) → string | Dekodowanie Base64; niepoprawne wejście zwraca "". |
performance.now() | () → number | Milisekundy od epoki (nie od załadowania strony). |
sleep(ms) | (number) → Promise | Rozwiązuje się po ms; użyj await sleep(1000). |
require(id) | (string) → any | Ładuje bibliotekę skryptów według semantyki CommonJS (module.exports); klucz to @libs/<key>, rozwiązywany jako identyfikator biblioteki → nazwa biblioteki (unikalna) → biblioteki wbudowane; rzuca wyjątek, gdy nie znaleziono. |
TextEncoder | new TextEncoder().encode(str) | Koduje UTF-8 do Uint8Array (encoding to zawsze "utf-8"). |
crypto.getRandomValues(n) | (Array) → number[] | Wypełnia n losowymi wartościami UInt32. |
crypto.randomUUID() | () → string | Losowy UUID (wielkie litery, z myślnikami). |
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]
Bibliotekami zarządza się w menedżerze modułów skryptów. Klucz require to zawsze @libs/<key>: Twoje biblioteki skryptów są rozwiązywane najpierw po identyfikatorze (stabilnym mimo zmian nazwy), potem po nazwie (unikalne dopasowanie), a na końcu wbudowane biblioteki @libs/base64 / @libs/hex. Biblioteki eksportują przez module.exports, mogą require-ować inne biblioteki, a brakujący klucz rzuca wyjątek (niepowodzenie przed wysłaniem przerywa żądanie, niepowodzenie po odpowiedzi zachowuje oryginalną odpowiedź). Pełny przewodnik: Quick Request scripting, Ładowanie bibliotek skryptów przez require().
console
console.log / info / warn / error wypisuje wartości do widoku logów skryptu. Wiele argumentów jest serializowanych, więc możesz logować obiekty i tablice bezpośrednio:
console.log("headers", {Accept: "application/json"}, [1, 2, 3]);
$log oferuje ustrukturyzowane wyjście z poziomami (zobacz $log) — oba kanały są widoczne w widoku logów skryptu Hodor.
Klasy HTTP
Request
Klasa Request to spakowane żądanie HTTP przekazywane do onRequest / onSessionCompleted.
| Składowa | Typ | Opis |
|---|---|---|
scheme | string (get / set) | Schemat żądania, np. https. |
host | string (get / set) | Host żądania. |
port | number (get / set) | Port żądania. |
path | string (get / set) | Ścieżka żądania. |
method | string (get / set) | Metoda HTTP, np. GET. |
queries | URLSearchParams (get) | Parametry zapytania żądania. |
headers | Headers (get) | Nagłówki żądania. |
body | Body (get) / string | Map | Array | URLSearchParams (set) | Ciało żądania. |
Nagłówki muszą być modyfikowane przez .set() / .append() — przypisanie indeksowe (np. headers["X-Key"] = v) jest ignorowane.
Możesz też skonstruować żądanie samodzielnie:
const request = new Request({
scheme: 'https',
host: 'example.com',
port: 8080,
path: '/api',
method: 'GET',
queries: 'param1=value1¶m2=value2',
headers: [
['Content-Type', 'application/json'],
['Authorization', 'Bearer token']
],
textBody: '{"key": "value"}'
});
console.log(request.encode());
Response
Klasa Response reprezentuje odpowiedź HTTP przekazywaną do onResponse / onSessionCompleted.
| Składowa | Typ | Opis |
|---|---|---|
statusCode | number (get / set) | Kod statusu odpowiedzi. |
statusPhrase | string (get / set) | Fraza statusu odpowiedzi, np. OK. |
headers | Headers (get) | Nagłówki odpowiedzi. |
body | Body (get) / string | Map | Array | URLSearchParams (set) | Ciało odpowiedzi. |
const response = new Response({
statusCode: 404,
statusPhrase: 'Not Found',
headers: {
'Content-Type': 'application/json',
'Cache-Control': 'no-cache'
},
textBody: '{"error": "Resource not found"}'
});
console.log(response.encode());
Body
Klasa Body reprezentuje ciało żądania lub odpowiedzi HTTP. Przypisanie nowej wartości do request.body / response.body zastępuje całe ciało.
| Metoda | Zwraca | Opis |
|---|---|---|
parseText() | string | null | Parsuje ciało jako tekst. |
parseJSON() | object | null | Parsuje ciało jako JSON. |
parseURLSearchParams() | URLSearchParams | null | Parsuje ciało jako parametry zakodowane w URL. |
const bodyInstance = new Body('{"user": "alice"}');
const json = bodyInstance.parseJSON();
if (json) {
console.log('User:' + json.user);
} else {
console.error('Failed to parse JSON');
}
Headers
Klasa Headers reprezentuje nagłówki HTTP.
| Metoda | Zwraca | Opis |
|---|---|---|
append(name, value) | void | Dokleja wartość do wskazanego nagłówka. |
set(name, value) | void | Ustawia (zastępuje) wartość wskazanego nagłówka. |
get(name) | string | null | Zwraca wartość wskazanego nagłówka. |
has(name) | boolean | Sprawdza, czy wskazany nagłówek istnieje. |
delete(name) | void | Usuwa wskazany nagłówek. |
forEach(callback, thisArg?) | void | Wywołuje funkcję dla każdego nagłówka. |
entries() / keys() / values() | Iterator | Iteruje po wpisach / kluczach / wartościach. |
encode() | Array | Koduje nagłówki do postaci serializowalnej. |
const headers = new Headers();
headers.append('Content-Type', 'application/json');
headers.set('Content-Length', '1024');
console.log(headers.get('Content-Type')); // 'application/json'
console.log(headers.has('Authorization')); // false
headers.forEach((value, name) => {
console.log(name + ' ' + value);
});
URLSearchParams
Klasa URLSearchParams reprezentuje parametry zapytania URL (albo ciała urlencoded).
| Metoda | Zwraca | Opis |
|---|---|---|
append(name, value) | void | Dokleja wartość do wskazanego parametru. |
set(name, value) | void | Ustawia (zastępuje) wartość wskazanego parametru. |
get(name) | string | null | Zwraca wartość wskazanego parametru. |
has(name) | boolean | Sprawdza, czy wskazany parametr istnieje. |
delete(name) | void | Usuwa wskazany parametr. |
forEach(callback, thisArg?) | void | Wywołuje funkcję dla każdego parametru. |
entries() / keys() / values() | Iterator | Iteruje po wpisach / kluczach / wartościach. |
sort() | void | Sortuje parametry. |
toString() | string | Serializuje do ciągu urlencoded. |
const params = new URLSearchParams({ key1: 'value1', key2: 'value2' });
console.log(params.get('key1')); // 'value1'
console.log(params.get('key3')); // null
params.forEach((value, key) => console.log(key + ' ' + value));
SharedPreferences
Klasa SharedPreferences zapewnia lokalny trwały magazyn klucz-wartość, który przeżywa wykonania skryptów i restarty aplikacji (oparty na systemowych user defaults).
| Metoda | Zwraca | Opis |
|---|---|---|
SharedPreferences.write(key, value) | void | Zapisuje wartość (string / number / boolean / obiekt / tablica). Zapis null usuwa klucz. |
SharedPreferences.read(key) | any | Zwraca wartość powiązaną z kluczem albo null, jeśli nie istnieje. |
SharedPreferences.write("test_key", "test_value");
const value = SharedPreferences.read("test_key");
console.log(value);
SharedPreferences.write("cfg", {a: 1}); // objects are stored directly
SharedPreferences.write("cfg", null); // deletes "cfg"
sdk — skrypty Quick Request
sdk (alias pm) jest wstrzykiwany wyłącznie w skryptach przed/po Quick Request. Stanowi pomost do magazynu zmiennych aplikacji (środowiska, zmienne globalne i uruchomieniowe) i zbiera asercje, z kształtem API w stylu Postman.
| Składowa | Opis |
|---|---|
sdk.env.get(key) | Odczytuje zmienną środowiskową zdefiniowaną w aplikacji. |
sdk.env.set(key, value) | Ustawia zmienną środowiskową (to samo co sdk.setEnvVar). |
sdk.setEnvVar(key, value) | Zapisuje zmienną środowiskową — zbierana i zapisywana z powrotem do aplikacji. |
sdk.setVar(key, value) | Zapisuje zmienną uruchomieniową (lokalną). |
sdk.setGlobalVar(key, value) | Zapisuje zmienną globalną. |
sdk.getVar(key) | Odczytuje zmienną uruchomieniową. |
sdk.test(name, fn) | Uruchamia nazwany blok asercji; porażki są zbierane i raportowane w aplikacji. |
sdk.expect(value) | Prymitywy asercji: toBe, toEqual, toBeTruthy. |
sdk.jsonPath(object, path) | Wyszukiwanie po ścieżce kropkowej, np. "$.data.list[0].id". |
sdk.utils.uuid() | To samo co crypto.randomUUID(). |
sdk.utils.base64Encode(s) / base64Decode(s) | To samo co btoa / atob. |
sdk.utils.md5(s) | To samo co $hash.md5. |
// Quick Request pre-request script: sign the request
async function onRequest(context, url, request) {
// read variables defined in the app's environment
const secret = sdk.env.get("secret") || "test-key";
sdk.expect(secret).toBeTruthy();
const ts = String(Date.now());
const bodyText = request.body && request.body.text ? request.body.text : '';
const sig = $hmac.sha256(ts + bodyText, secret);
// headers must be set via .set / .append
request.headers.set("X-Signature", sig);
request.headers.set("X-Timestamp", ts);
// persist variables back to the app
sdk.setEnvVar("lastTs", ts);
sdk.test("signature is 64 hex", () => {
sdk.expect(sig.length).toBe(64);
});
console.log("signed request for", url);
return request;
}
Wyniki asercji są raportowane dla skryptów przed wysłaniem. W skryptach po odpowiedzi asercje się wykonują, ale wyniki nie są zbierane.
Konteksty
RewriteContext
Obiekt kontekstu przekazywany do skryptów rewrite (onRequest / onResponse).
| Składowa | Typ | Opis |
|---|---|---|
isEnableOnRequest | boolean (get) | Czy punkt wejścia onRequest jest włączony. |
isEnableOnResponse | boolean (get) | Czy punkt wejścia onResponse jest włączony. |
parameters | object (get / set) | Słownik parametrów współdzielony między onRequest i onResponse. |
scriptName | string (get) | Nazwa skryptu. |
CompletedContext
Obiekt kontekstu przekazywany do skryptów HTTP completed.
| Składowa | Typ | Opis |
|---|---|---|
session | object (get) | Obiekt sesji powiązany z ukończonym skryptem. |
scriptName | string (get) | Nazwa skryptu completed. |
ScheduleContext
Obiekt kontekstu przekazywany do skryptów harmonogramu.
| Składowa | Typ | Opis |
|---|---|---|
parameters | object (get / set) | Parametry przekazywane do następnej pętli, gdy ustawione. |
cron | string (get) | Wyrażenie cron harmonogramu. |
repeatedCount | number (get) | Ile razy skrypt został powtórzony. |
scriptName | string (get) | Nazwa skryptu harmonogramu. |
Uwagi o zachowaniu
- Nieprzechwycone wyjątki zawodzą skrypt. Błędy (w tym
AbortErrorzabort()) propagują do Hodor, a wykonanie jest raportowane jako nieudane — częściowe przepisania wykonane przed błędem są odrzucane, więc zabezpiecz ryzykowne bloki przeztry / catch. - Strażnik limitu czasu. Każde wykonanie skryptu ma budżet czasowy; skrypt, który nigdy się nie kończy (np. nieskończona pętla albo zawieszony
await), zostaje przerwany i raportowany jako timeout. - Błędy jako wartości zwrotne. Niektóre API nigdy nie rzucają:
$codec.base64Decodezwraca"",$cryptozwraca ciągi"Error: ...",$fs.readzwraca ciągi"Error: ...", a$fs.infozwracaundefined. Sprawdzaj te wartości zwrotne zamiast polegać natry / catch. console.logvs$log. Oba są widoczne w widoku logów skryptu;$logdodaje znaczniki czasu i poziomy.- Trwałość środowiska skryptu. Zmienne zapisane przez
sdk.setVari pliki zapisane przez$fspozostają dostępne dla kolejnych wykonań tego samego skryptu;SharedPreferencesprzetrwa restarty aplikacji.