스크립트 API 참조
Hodor는 내장 JavaScript 엔진에서 스크립트를 실행합니다. 스크립트 타입에 따라 Hodor는 아래 엔트리 함수 중 하나를 적절한 시점에 호출합니다 — 필요한 로직만 구현하면 됩니다. 아무것도 수정하지 않는다면, 불필요한 호출을 피하기 위해 사용하지 않는 엔트리 함수를 삭제하세요.
사용 가능한 전역 객체와 클래스:
| 카테고리 | 이름 |
|---|---|
| 엔트리 함수 | onRequest, onResponse, onSessionCompleted, onSchedule, abort() |
네이티브 $ 모듈 | $codec, $hash, $hmac, $crypto, $jwt, $format, $fs, $env, $uuid, $log |
| 웹 표준 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)
재작성 스크립트와 Quick Request 전송 전 스크립트를 위한 것입니다. 이 함수는 HTTP 요청이 서버로 전송되기 전에 호출됩니다. (변경된) request를 반환하세요.
| 파라미터 | 타입 | 설명 |
|---|---|---|
context | RewriteContext | 컨텍스트 객체입니다. |
url | string | HTTP 요청의 URL입니다. |
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)
재작성 스크립트와 Quick Request 응답 후 스크립트를 위한 것입니다. 이 함수는 HTTP 응답이 클라이언트로 전송되기 전에 호출됩니다. (변경된) response를 반환하세요.
| 파라미터 | 타입 | 설명 |
|---|---|---|
context | RewriteContext | 컨텍스트 객체입니다. |
url | string | HTTP 응답의 URL입니다. |
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 스크립트를 위한 것입니다. HTTP 응답이 반환된 후 비동기로 호출되며, 앱과 서버 간 데이터 전송에는 영향을 주지 않습니다. 데이터 수집과 전달에 유용합니다.
| 파라미터 | 타입 | 설명 |
|---|---|---|
context | CompletedContext | 컨텍스트 객체입니다. |
url | string | HTTP 요청의 URL입니다. |
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)
스케줄 스크립트를 위한 것입니다. 예약된 트리거 시각에 호출됩니다(5 또는 6파트 cron 표현식 지원). 스케줄 루프를 멈추려면 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()를 호출하면 스크립트를 멈추고 현재 실행을 즉시 중단합니다 — 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:
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
method | string | "GET" | 대소문자 무시. 모르는 값은 GET으로 폴백됩니다. |
timeoutInterval | number | 30 | 초 단위입니다. |
headers | [[k, v]] 또는 [{k: v}] | [] | 두 형태 모두 받습니다. |
textBody | string | — | 요청 바디 텍스트입니다. |
encoding | string | — | "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 객체(자동 직렬화) 또는 URLSearchParamstimeoutInterval: 초 단위 타임아웃 (기본 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) → string | Base64 인코딩 — UTF-8 대칭 의미론(브라우저와 달리 비Latin1 문자열 허용). |
atob(str) | (string) → string | Base64 디코딩. 무효한 입력은 ""를 반환합니다. |
performance.now() | () → number | 에포크 이후 밀리초입니다(페이지 로드가 아님). |
sleep(ms) | (number) → Promise | ms 후 resolve. await sleep(1000)처럼 사용합니다. |
require(id) | (string) → any | CommonJS 의미론(module.exports)으로 스크립트 라이브러리를 로드합니다. 키는 @libs/<key>이며 스크립트 라이브러리 identifier → 스크립트 라이브러리 이름(유니크 매치) → 내장 라이브러리 순으로 해석됩니다. 없으면 예외를 던집니다. |
TextEncoder | new 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 요청입니다.
| 멤버 | 타입 | 설명 |
|---|---|---|
scheme | string (get / set) | 요청의 scheme, 예: https. |
host | string (get / set) | 요청의 host입니다. |
port | number (get / set) | 요청의 port입니다. |
path | string (get / set) | 요청의 path입니다. |
method | string (get / set) | HTTP 메서드, 예: GET. |
queries | URLSearchParams (get) | 요청의 쿼리 파라미터입니다. |
headers | Headers (get) | 요청의 헤더입니다. |
body | Body (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¶m2=value2',
headers: [
['Content-Type', 'application/json'],
['Authorization', 'Bearer token']
],
textBody: '{"key": "value"}'
});
console.log(request.encode());
Response
Response 클래스는 onResponse / onSessionCompleted에 전달되는 HTTP 응답입니다.
| 멤버 | 타입 | 설명 |
|---|---|---|
statusCode | number (get / set) | 응답의 상태 코드입니다. |
statusPhrase | string (get / set) | 응답의 상태 문구, 예: OK. |
headers | Headers (get) | 응답의 헤더입니다. |
body | Body (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() | string | 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
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)에 전달되는 컨텍스트 객체입니다.
| 멤버 | 타입 | 설명 |
|---|---|---|
isEnableOnRequest | boolean (get) | onRequest 엔트리가 활성화되어 있는지 여부입니다. |
isEnableOnResponse | boolean (get) | onResponse 엔트리가 활성화되어 있는지 여부입니다. |
parameters | object (get / set) | onRequest와 onResponse 사이에서 공유되는 파라미터 사전입니다. |
scriptName | string (get) | 스크립트의 이름입니다. |
CompletedContext
HTTP completed 스크립트에 전달되는 컨텍스트 객체입니다.
| 멤버 | 타입 | 설명 |
|---|---|---|
session | object (get) | completed 스크립트와 연관된 세션 객체입니다. |
scriptName | string (get) | completed 스크립트의 이름입니다. |
ScheduleContext
스케줄 스크립트에 전달되는 컨텍스트 객체입니다.
| 멤버 | 타입 | 설명 |
|---|---|---|
parameters | object (get / set) | 설정하면 다음 runloop로 전달되는 파라미터입니다. |
cron | string (get) | 스케줄의 cron 표현식입니다. |
repeatedCount | number (get) | 스크립트가 반복된 횟수입니다. |
scriptName | string (get) | 스케줄 스크립트의 이름입니다. |
동작 노트
- 미포착 예외는 스크립트를 실패시킵니다. 오류(
abort()의AbortError포함)는 Hodor로 전파되고 실행은 실패로 보고됩니다 — 오류 이전의 부분 재작성은 폐기되므로, 위험한 블록은try / catch로 감싸세요. - 타임아웃 와치독. 각 스크립트 실행에는 시간 예산이 있습니다. 끝나지 않는 스크립트(예: 무한 루프 또는 멈춘
await)는 강제 중단되고 타임아웃으로 보고됩니다. - 반환값으로서의 오류. 일부 API는 절대 예외를 던지지 않습니다:
$codec.base64Decode는"",$crypto는"Error: ..."문자열,$fs.read는"Error: ..."문자열,$fs.info는undefined를 반환합니다.try / catch에 의존하지 말고 이 반환값들을 확인하세요. console.logvs$log. 둘 다 스크립트 로그 뷰에서 볼 수 있습니다.$log는 타임스탬프와 레벨을 추가합니다.- 스크립트 런타임 영속성.
sdk.setVar로 쓴 변수와$fs로 쓴 파일은 같은 스크립트의 이후 실행에서도 사용할 수 있습니다.SharedPreferences는 앱 재시작을 넘어 영속됩니다.