본문으로 건너뛰기

스크립트 API 참조

Hodor는 내장 JavaScript 엔진에서 스크립트를 실행합니다. 스크립트 타입에 따라 Hodor는 아래 엔트리 함수 중 하나를 적절한 시점에 호출합니다 — 필요한 로직만 구현하면 됩니다. 아무것도 수정하지 않는다면, 불필요한 호출을 피하기 위해 사용하지 않는 엔트리 함수를 삭제하세요.

사용 가능한 전역 객체와 클래스:

카테고리이름
엔트리 함수onRequest, onResponse, onSessionCompleted, onSchedule, abort()
네이티브 $ 모듈$codec, $hash, $hmac, $crypto, $jwt, $format, $fs, $env, $uuid, $log
웹 표준 APIfetch, 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)​

재작성 스크립트와 Quick Request 전송 전 스크립트를 위한 것입니다. 이 함수는 HTTP 요청이 서버로 전송되기 전에 호출됩니다. (변경된) request를 반환하세요.

파라미터타입설명
contextRewriteContext컨텍스트 객체입니다.
urlstringHTTP 요청의 URL입니다.
requestRequestHTTP 요청 객체입니다.
// 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)​

재작성 스크립트와 Quick Request 응답 후 스크립트를 위한 것입니다. 이 함수는 HTTP 응답이 클라이언트로 전송되기 전에 호출됩니다. (변경된) response를 반환하세요.

파라미터타입설명
contextRewriteContext컨텍스트 객체입니다.
urlstringHTTP 응답의 URL입니다.
responseResponseHTTP 응답 객체입니다.
// 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 스크립트를 위한 것입니다. HTTP 응답이 반환된 후 비동기로 호출되며, 앱과 서버 간 데이터 전송에는 영향을 주지 않습니다. 데이터 수집과 전달에 유용합니다.

파라미터타입설명
contextCompletedContext컨텍스트 객체입니다.
urlstringHTTP 요청의 URL입니다.
requestRequestHTTP 요청 객체입니다.
responseResponseHTTP 응답 객체입니다.
// 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)​

스케줄 스크립트를 위한 것입니다. 예약된 트리거 시각에 호출됩니다(5 또는 6파트 cron 표현식 지원). 스케줄 루프를 멈추려면 abort()를 사용하세요.

파라미터타입설명
contextScheduleContext컨텍스트 객체입니다.
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()를 호출하면 스크립트를 멈추고 현재 실행을 즉시 중단합니다 — Hodor가 보고하는 AbortError를 던집니다.

// ✅ 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)처럼 4번째 파라미터를 선언하지 마세요. 엔트리 함수의 파라미터 개수는 고정입니다 — 4번째 파라미터가 있으면 엔트리가 탐지되지 않습니다.

네이티브 모듈​

$ 접두 모듈은 런타임이 활성화될 때 주입됩니다. 네이티브로 구현되어 동기로 반환하고(별도 표기가 없는 한) 문자열 입력을 UTF-8로 다룹니다.

$codec — 인코딩과 디코딩​

프로토콜 변환과 데이터 전송을 위한 Base64 / Hex / URL 퍼센트 인코딩입니다.

메서드반환값
$codec.base64Encode(str)Base64 문자열입니다.
$codec.base64Decode(str)디코딩된 문자열. 무효한 입력은 ""를 반환합니다 (예외를 던지지 않음).
$codec.hexEncode(str)소문자 hex 문자열입니다.
$codec.hexDecode(str)디코딩된 문자열. 무효한 문자는 건너뜁니다.
$codec.urlEncode(str)퍼센트 인코딩된 문자열입니다.
$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?)평문. 무효한 암호문은 "Error: Invalid ciphertext"를 반환합니다.
$crypto.encryptDES(plaintext, key)DES-ECB + PKCS7, 키는 8바이트로 절단 → Base64.
$crypto.decryptDES(ciphertext, key)평문. 비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 프리티 프린팅과 minify입니다. JSON 키는 출력에서 알파벳순으로 정렬됩니다.

메서드반환값
$format.json(str, indent?)프리티 프린팅된 JSON. indent는 1–8로 고정(기본 2), 무효한 입력은 "Error: Invalid JSON".
$format.minify(str)minify된 JSON (키 정렬, 공백 없음), 무효한 입력은 "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 생성과 검증입니다(요청 ID, 멱등 키).

메서드반환값
$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 문자열을 검증하기 전에 하이픈을 다시 넣으세요.

$log — 구조화 로깅​

타임스탬프와 레벨이 붙은 로그 라인을 엔진의 콘솔 시스템으로 보냅니다(스크립트의 로그 뷰에 수집됨).

메서드반환값
$log.log(level, message, tag?)포맷된 로그 라인 (출력도 됩니다).
$log.debug / info / warn / error(message)편의 레벨 메서드, 출력 전용입니다.

로그 라인 형식: [yyyy-MM-dd'T'HH:mm:ss.SSSZ] [LEVEL] [tag] message (tag가 없으면 [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​

fetch​

스크립트에서 실제 HTTP 요청을 보냅니다 — Postman 스타일 워크플로의 주 채널입니다.

fetch(url: string, options?: object) → Promise<response>

options:

필드타입기본값설명
methodstring"GET"대소문자 무시. 모르는 값은 GET으로 폴백됩니다.
timeoutIntervalnumber30초 단위입니다.
headers[[k, v]] 또는 [{k: v}][]두 형태 모두 받습니다.
textBodystring—요청 바디 텍스트입니다.
encodingstring—"hex"는 textBody가 hex 문자열임을 뜻합니다.

해석된 값은 일반 객체입니다: statusCode (number), headers (단일 키 객체의 배열, 중복 키 보존), 그리고 textBody() — 문자 집합을 자동 감지하는 {text, encoding}을 반환하는 함수입니다(디코딩 불가능한 바디는 {text: <hex>, encoding: "hex"}로 폴백). reject된 값은 오류 메시지 문자열입니다.

// 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​

HTTPClient 클래스는 어떤 스크립트에서든 HTTP 요청을 보냅니다(fetch 위에 구현). 모든 메서드는 async이며 statusCode, headers, textBody()를 가진 응답 객체를 반환합니다.

메서드설명
HTTPClient.get(url, params?)GET 요청을 보냅니다.
HTTPClient.post(url, params?)POST 요청을 보냅니다.
HTTPClient.put(url, params?)PUT 요청을 보냅니다.
HTTPClient.update(url, params?)UPDATE 요청을 보냅니다.
HTTPClient.delete(url, params?)DELETE 요청을 보냅니다.
HTTPClient.request(url, method, params?)커스텀 메서드로 요청을 보냅니다.

params는 다음을 가진 선택적 객체입니다:

  • headers: 요청 헤더 객체, 예: {"key1": "value1"}
  • body: 요청 바디 — 문자열, JSON 객체(자동 직렬화) 또는 URLSearchParams
  • timeoutInterval: 초 단위 타임아웃 (기본 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);
}

타이머​

setTimeout / setInterval / clearTimeout / clearInterval은 브라우저와 같이 동작합니다. 콜백은 직렬 엔진 큐에 디스패치되므로, 호스트 스레드와 무관하게 타이머가 확실하게 발화합니다.

함수반환값
setTimeout(callback, ms)타이머 id (string), 한 번 발화합니다.
setInterval(callback, ms)타이머 id, 반복 발화합니다.
clearTimeout(id) / clearInterval(id)취소합니다(멱등, 모르는 id는 무시).
await new Promise(resolve => setTimeout(resolve, 500)); // wait 0.5s
const timer = setInterval(() => console.log("tick"), 1000);
setTimeout(() => clearInterval(timer), 3500);

전역 함수​

이름시그니처설명
btoa(str)(string) → stringBase64 인코딩 — UTF-8 대칭 의미론(브라우저와 달리 비Latin1 문자열 허용).
atob(str)(string) → stringBase64 디코딩. 무효한 입력은 ""를 반환합니다.
performance.now()() → number에포크 이후 밀리초입니다(페이지 로드가 아님).
sleep(ms)(number) → Promisems 후 resolve. await sleep(1000)처럼 사용합니다.
require(id)(string) → anyCommonJS 의미론(module.exports)으로 스크립트 라이브러리를 로드합니다. 키는 @libs/<key>이며 스크립트 라이브러리 identifier → 스크립트 라이브러리 이름(유니크 매치) → 내장 라이브러리 순으로 해석됩니다. 없으면 예외를 던집니다.
TextEncodernew TextEncoder().encode(str)Uint8Array로 UTF-8 인코딩합니다(encoding은 항상 "utf-8").
crypto.getRandomValues(n)(Array) → number[]n개의 랜덤 UInt32 값으로 채웁니다.
crypto.randomUUID()() → string랜덤 UUID (대문자, 하이픈 포함).
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]

라이브러리는 스크립트 모듈 매니저에서 관리됩니다. require 키는 항상 @libs/<key>입니다: 자신의 스크립트 라이브러리는 identifier(리네임에도 안정적) 우선, 다음 이름(유니크 매치), 마지막으로 내장 라이브러리 @libs/base64 / @libs/hex 순으로 해석됩니다. 라이브러리는 module.exports로 export하고 다른 라이브러리를 require할 수 있으며, 없는 키는 예외를 던집니다(전송 전 실패는 요청을 중단, 응답 후 실패는 원래 응답 유지). 전체 가이드는 Quick Request 스크립트, 스크립트 라이브러리 require를 참조하세요.

console​

console.log / info / warn / error는 값을 스크립트의 로그 뷰에 출력합니다. 여러 인자가 직렬화되므로 객체와 배열을 바로 로그로 남길 수 있습니다:

console.log("headers", {Accept: "application/json"}, [1, 2, 3]);

$log는 구조화된 레벨 출력을 제공합니다($log 참조) — 두 채널 모두 Hodor의 스크립트 로그 뷰에서 볼 수 있습니다.

HTTP 클래스​

Request​

Request 클래스는 onRequest / onSessionCompleted에 전달되는 패키지된 HTTP 요청입니다.

멤버타입설명
schemestring (get / set)요청의 scheme, 예: https.
hoststring (get / set)요청의 host입니다.
portnumber (get / set)요청의 port입니다.
pathstring (get / set)요청의 path입니다.
methodstring (get / set)HTTP 메서드, 예: GET.
queriesURLSearchParams (get)요청의 쿼리 파라미터입니다.
headersHeaders (get)요청의 헤더입니다.
bodyBody (get) / string | Map | Array | URLSearchParams (set)요청의 바디입니다.
노트

헤더는 .set() / .append()로 수정해야 합니다 — 인덱스 대입(예: headers["X-Key"] = v)은 무시됩니다.

요청을 직접 생성할 수도 있습니다:

const request = new Request({
scheme: 'https',
host: 'example.com',
port: 8080,
path: '/api',
method: 'GET',
queries: 'param1=value1&param2=value2',
headers: [
['Content-Type', 'application/json'],
['Authorization', 'Bearer token']
],
textBody: '{"key": "value"}'
});
console.log(request.encode());

Response​

Response 클래스는 onResponse / onSessionCompleted에 전달되는 HTTP 응답입니다.

멤버타입설명
statusCodenumber (get / set)응답의 상태 코드입니다.
statusPhrasestring (get / set)응답의 상태 문구, 예: OK.
headersHeaders (get)응답의 헤더입니다.
bodyBody (get) / string | Map | Array | URLSearchParams (set)응답의 바디입니다.
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​

Body 클래스는 HTTP 요청이나 응답의 바디입니다. request.body / response.body에 새 값을 대입하면 바디 전체가 교체됩니다.

메서드반환값설명
parseText()string | null바디를 텍스트로 파싱합니다.
parseJSON()object | null바디를 JSON으로 파싱합니다.
parseURLSearchParams()URLSearchParams | null바디를 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​

Headers 클래스는 HTTP 헤더입니다.

메서드반환값설명
append(name, value)void지정한 헤더에 값을 덧붙입니다.
set(name, value)void지정한 헤더의 값을 설정(교체)합니다.
get(name)string | null지정한 헤더의 값을 얻습니다.
has(name)boolean지정한 헤더가 존재하는지 확인합니다.
delete(name)void지정한 헤더를 삭제합니다.
forEach(callback, thisArg?)void각 헤더에 함수를 호출합니다.
entries() / keys() / values()Iterator항목 / 키 / 값을 순회합니다.
encode()Array헤더를 직렬화 가능한 형태로 인코딩합니다.
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​

URLSearchParams 클래스는 URL 쿼리(또는 urlencoded 바디) 파라미터입니다.

메서드반환값설명
append(name, value)void지정한 파라미터에 값을 덧붙입니다.
set(name, value)void지정한 파라미터의 값을 설정(교체)합니다.
get(name)string | null지정한 파라미터의 값을 얻습니다.
has(name)boolean지정한 파라미터가 존재하는지 확인합니다.
delete(name)void지정한 파라미터를 삭제합니다.
forEach(callback, thisArg?)void각 파라미터에 함수를 호출합니다.
entries() / keys() / values()Iterator항목 / 키 / 값을 순회합니다.
sort()void파라미터를 정렬합니다.
toString()stringurlencoded 문자열로 직렬화합니다.
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​

SharedPreferences 클래스는 스크립트 실행과 앱 재시작을 넘어 유지되는 로컬 영속 키-값 스토리지를 제공합니다(시스템 user defaults 기반).

메서드반환값설명
SharedPreferences.write(key, value)void값을 씁니다 (string / number / boolean / object / array). null을 쓰면 키가 삭제됩니다.
SharedPreferences.read(key)any키에 연결된 값을 읽거나, 없으면 null을 반환합니다.
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 — Quick Request 스크립트​

sdk (별칭 pm)는 Quick Request 전/후 스크립트에서만 주입됩니다. 앱의 변수 스토리지(환경, 전역, 런타임 변수)와 연결되고 어설션을 수집하며, Postman과 비슷한 API 형태를 갖습니다.

멤버설명
sdk.env.get(key)앱에서 정의한 환경 변수를 읽습니다.
sdk.env.set(key, value)환경 변수를 설정합니다(sdk.setEnvVar와 같음).
sdk.setEnvVar(key, value)env 변수를 씁니다 — 수집되어 앱에 영속화됩니다.
sdk.setVar(key, value)런타임(로컬) 변수를 씁니다.
sdk.setGlobalVar(key, value)전역 변수를 씁니다.
sdk.getVar(key)런타임 변수를 읽습니다.
sdk.test(name, fn)이름 붙은 어설션 블록을 실행합니다. 실패는 수집되어 앱에 보고됩니다.
sdk.expect(value)어설션 프리미티브: toBe, toEqual, toBeTruthy.
sdk.jsonPath(object, path)닷 경로 조회, 예: "$.data.list[0].id".
sdk.utils.uuid()crypto.randomUUID()와 같습니다.
sdk.utils.base64Encode(s) / base64Decode(s)btoa / atob와 같습니다.
sdk.utils.md5(s)$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;
}
노트

어설션 결과는 전송 전 스크립트에서 보고됩니다. 응답 후 스크립트에서는 어설션이 실행되지만 결과는 수집되지 않습니다.

컨텍스트​

RewriteContext​

재작성 스크립트(onRequest / onResponse)에 전달되는 컨텍스트 객체입니다.

멤버타입설명
isEnableOnRequestboolean (get)onRequest 엔트리가 활성화되어 있는지 여부입니다.
isEnableOnResponseboolean (get)onResponse 엔트리가 활성화되어 있는지 여부입니다.
parametersobject (get / set)onRequest와 onResponse 사이에서 공유되는 파라미터 사전입니다.
scriptNamestring (get)스크립트의 이름입니다.

CompletedContext​

HTTP completed 스크립트에 전달되는 컨텍스트 객체입니다.

멤버타입설명
sessionobject (get)completed 스크립트와 연관된 세션 객체입니다.
scriptNamestring (get)completed 스크립트의 이름입니다.

ScheduleContext​

스케줄 스크립트에 전달되는 컨텍스트 객체입니다.

멤버타입설명
parametersobject (get / set)설정하면 다음 runloop로 전달되는 파라미터입니다.
cronstring (get)스케줄의 cron 표현식입니다.
repeatedCountnumber (get)스크립트가 반복된 횟수입니다.
scriptNamestring (get)스케줄 스크립트의 이름입니다.

동작 노트​

  • 미포착 예외는 스크립트를 실패시킵니다. 오류(abort()의 AbortError 포함)는 Hodor로 전파되고 실행은 실패로 보고됩니다 — 오류 이전의 부분 재작성은 폐기되므로, 위험한 블록은 try / catch로 감싸세요.
  • 타임아웃 와치독. 각 스크립트 실행에는 시간 예산이 있습니다. 끝나지 않는 스크립트(예: 무한 루프 또는 멈춘 await)는 강제 중단되고 타임아웃으로 보고됩니다.
  • 반환값으로서의 오류. 일부 API는 절대 예외를 던지지 않습니다: $codec.base64Decode는 "", $crypto는 "Error: ..." 문자열, $fs.read는 "Error: ..." 문자열, $fs.info는 undefined를 반환합니다. try / catch에 의존하지 말고 이 반환값들을 확인하세요.
  • console.log vs $log. 둘 다 스크립트 로그 뷰에서 볼 수 있습니다. $log는 타임스탬프와 레벨을 추가합니다.
  • 스크립트 런타임 영속성. sdk.setVar로 쓴 변수와 $fs로 쓴 파일은 같은 스크립트의 이후 실행에서도 사용할 수 있습니다. SharedPreferences는 앱 재시작을 넘어 영속됩니다.