사용법 가이드

1. 배포 방법

IronJSON은 Cloudflare Workers에 최적화된 Rust + WebAssembly 기반 엔진입니다.

필수 도구

• Rust (stable)
• Wrangler CLI v4+
• wasm32-unknown-unknown 타겟: rustup target add wasm32-unknown-unknown

빌드 & 배포

# 빌드
cargo build --release --target wasm32-unknown-unknown

# 또는 build.sh 실행
bash build.sh

# wrangler로 배포
npx wrangler deploy

2. 환경 변수 설정

Wrangler 대시보드 또는 wrangler.toml에서 다음 변수를 설정합니다.

비밀키 설정 (권장)

# Secret으로 안전하게 저장
npx wrangler secret put IRONJSON_API_KEY

3. API 인증

IRONJSON_API_KEY가 설정된 경우, 모든 POST /process 요청은 다음 헤더를 포함해야 합니다:

x-ironjson-key: your-secret-api-key

키가 일치하지 않으면 401 Unauthorized를 반환합니다.

4. POST /process 요청

JSON 본문을 전송하면 설정된 규칙에 따라 처리 후 결과를 반환합니다.

기본 요청

POST /process
Content-Type: application/json
x-ironjson-key: your-api-key

// 본문
{
  "email": "user@example.com",
  "password": "secret123",
  "age": 30
}

성공 응답

{
  "success": true,
  "data": {
    "email": "user@example.com",
    "age": 30
  }
}

응답 헤더에는 처리 시간(x-ironjson-duration-ms)이 포함됩니다.

5. 요청 헤더 레퍼런스

6. 규칙(Rule) 작성법

규칙은 IRONJSON_RULES 환경 변수에 JSON 배열로 정의합니다.

기본 구조

{
  "rules": [
    {
      "path": "/api/users",
      "methods": ["POST", "PUT"],
      "direction": "request",
      "validate": { ... },
      "remove_fields": ["password"],
      "include_fields": ["name", "email"],
      "mask_fields": ["token"],
      "rename": { "old_key": "new_key" },
      "value_map": { "status": { "active": 1 } }
    }
  ]
}

경로 매칭

path는 Glob 패턴을 지원합니다:

규칙 우선순위

여러 규칙이 매칭되면 경로 세그먼트 수가 많은 규칙이 우선 적용됩니다. 모든 매칭 규칙은 병합(merge)되어 한 번에 처리됩니다.

7. 스키마 검증 정의

validate 필드에 JSON Schema 스타일 정의를 작성합니다.

검증 예제

{
  "type": "object",
  "required": ["email", "name"],
  "properties": {
    "email": { "type": "string", "format": "email" },
    "name":  { "type": "string", "min_length": 1 },
    "age":   { "type": "integer", "min": 0, "max": 150 },
    "tags":  { "type": "array", "items": { "type": "string" }, "unique_items": true }
  },
  "additional_properties": false
}

8. 필드 변환 및 값 매핑

remove_fields — 필드 제거

지정된 필드를 JSON에서 완전히 제거합니다. .으로 중첩 경로를 지정할 수 있습니다.

"remove_fields": ["password", "secret", "user.internal_id"]

include_fields — 화이트리스트

지정된 필드만 남기고 나머지는 제거합니다. (최상위 객체에만 적용)

"include_fields": ["name", "email"]

mask_fields — 민감 정보 마스킹

문자열은 *로 대체, 숫자·불리언은 "***"로 대체합니다. 전체 마스킹이며 최대 256자입니다.

"mask_fields": ["token", "api_key", "credit_card"]

rename — 키 이름 변경

old_key → new_key 형식. .으로 중첩 경로 지원.

"rename": {
  "old_name": "new_name",
  "user.contact.email": "email_address"
}

value_map — 값 변환

문자열 필드의 값을 다른 값으로 매핑합니다.

"value_map": {
  "status": {
    "active": 1,
    "inactive": 0,
    "banned": -1
  }
}

9. 스키마 추론

샘플 JSON을 전송하면 자동으로 JSON Schema를 생성합니다.

POST /infer-schema
Content-Type: application/json
x-ironjson-key: your-api-key

{
  "name": "John",
  "age": 30,
  "email": "john@test.com",
  "tags": ["rust", "wasm"]
}

응답으로 추론된 스키마가 반환됩니다. email 형식은 자동으로 format: "email"로 감지됩니다.

10. 에러 응답

검증 에러 응답 예시

{
  "success": false,
  "error": {
    "type": "validation",
    "message": "Validation failed",
    "details": [
      {
        "path": "$.email",
        "message": "Required field 'email' is missing",
        "expected": "present",
        "found": "missing"
      }
    ]
  }
}

11. 통합 예제

{
  "rules": [{
    "path": "/api/register",
    "methods": ["POST"],
    "direction": "request",
    "validate": {
      "type": "object",
      "required": ["email", "password"],
      "properties": {
        "email": { "type": "string", "format": "email" },
        "password": { "type": "string", "min_length": 8 }
      }
    },
    "remove_fields": ["password"]
  }]
}

{
  "rules": [{
    "path": "/api/users/*",
    "methods": ["GET"],
    "direction": "response",
    "remove_fields": ["password_hash", "internal_notes"],
    "mask_fields": ["email", "phone"],
    "rename": { "user_id": "id" },
    "value_map": {
      "role": { "admin": "관리자", "user": "사용자" }
    }
  }]
}

{
  "rules": [{
    "path": "/api/**",
    "direction": "both",
    "mask_fields": ["token", "secret", "api_key", "authorization"],
    "remove_fields": ["password", "credit_card"]
  }]
}