Edge Workers 개요 및 빠른 시작

Edge Workers는 CDN 엣지 노드에서 실행되는 JavaScript 함수입니다. 요청이 엣지에 도착하여 보안 검사를 통과하면, 캐시 조회 및 원본 서버로의 요청 전송 전에 경로가 일치하는 Worker가 실행됩니다. Worker는 다음 작업을 수행할 수 있습니다.

• 직접 응답: 원본 서버에 연결하지 않고 사용자 지정 콘텐츠나 리디렉션을 반환합니다.
• 원본 서버 요청 재작성: 요청 헤더를 추가하거나 덮어쓴 후 원본 서버로 전달합니다. 필요에 따라 메서드와 경로도 변경할 수 있습니다.
• 그대로 전달: 아무것도 변경하지 않고 도메인의 일반 설정에 따라 요청을 처리합니다.

프로그래밍 모델은 Cloudflare Workers를 따릅니다. export default { fetch(request, env, ctx) }를 내보내고 Response를 반환합니다. 각 실행은 새로 생성된 격리 샌드박스에서 이루어집니다. 요청 간에 전역 상태를 공유하지 않습니다.

#콘솔 페이지

#빠른 시작

#1단계: Worker 생성

1. CDN → Workers로 이동하고 오른쪽 상단의 Worker 생성을 클릭합니다.
2. 필수 항목인 이름과 선택 항목인 설명을 입력합니다.
3. 템플릿으로 시작 드롭다운에서 예제를 선택하여 편집기에 불러올 수 있습니다. 사용자 지정 응답, 리디렉션, 인증 토큰, 암호화 도구 모음 및 fetch 전달 예제가 제공됩니다. 또는 아래 예제를 붙여 넣습니다.
4. 활성화 스위치가 켜져 있는지 확인한 후 저장을 클릭합니다.

저장하면 편집기에 Worker 상세 페이지가 열리고 상단에 버전 번호가 표시됩니다. 새 코드를 저장할 때마다 버전이 하나씩 증가합니다.

#2단계: 코드 작성

다음 최소 예제는 /hello 요청에 엣지에서 JSON을 반환합니다. 그 외의 모든 경로는 평소처럼 원본 서버로 전달됩니다.

export default {
  async fetch(request, env, ctx) {
    // request.url may be "/hello?x=1" or a full URL, so extract the path
    const path = request.url.replace(/^https?:\/\/[^\/]+/, "").split("?")[0];

    if (path === "/hello") {
      return Response.json({
        message: "Hello from the edge",
        host: request.headers.get("host"),
        method: request.method,
      });
    }

    // Not handled here: pass through to the origin
    return { action: "continue" };
  },
};

#3단계: 도메인에 연결

1. CDN → CDN 도메인으로 이동하여 도메인을 열고 Worker 탭으로 전환합니다.
2. 연결 추가를 클릭합니다. 대화 상자에서 다음을 설정합니다.
   • Worker 선택: 방금 생성한 Worker를 선택합니다. 활성화된 Workers만 표시됩니다.
   • 라우트 패턴: 예를 들어 /hello를 입력하거나 모든 경로에 적용하려면 /*를 입력합니다. 규칙은 아래에서 설명합니다.
   • 우선순위: 0–999. 숫자가 클수록 우선합니다.
   • 활성화: 켜진 상태로 둡니다.
3. 저장을 클릭합니다. 설정은 엣지로 자동 전송되며 일반적으로 잠시 후 적용됩니다.

#4단계: 테스트

curl -i https://www.example.com/hello

위 JSON과 함께 200이 반환되면 Worker가 정상적으로 동작하는 것입니다. 다른 경로는 연결을 추가하기 전과 동일하게 동작해야 합니다.

#프로그래밍 인터페이스

#진입점

권장 형식은 export default { fetch(request, env, ctx) { ... } }입니다. fetch는 일반 함수 또는 async 함수로 작성할 수 있습니다. 플랫폼은 export default function (request) {}와 전역 function handler(request) {}도 지원합니다.

#요청 객체

#반환 값

예를 들어 다음 Worker는 원본 서버 요청에 A/B 버킷 정보를 추가합니다.

export default {
  fetch(request) {
    const cookie = request.headers.get("cookie") || "";
    const m = /ab_bucket=(A|B)/.exec(cookie);
    const bucket = m ? m[1] : (Math.random() < 0.5 ? "A" : "B");
    return { action: "rewrite", headers: { "x-ab-bucket": bucket } };
  },
};

#사용 가능한 전역 API

• fetch(url, init): 공개 HTTP/HTTPS 주소로 하위 요청을 보내고 status, ok, headers, text(), json()을 제공하는 Promise<Response>를 반환합니다. return fetch(url)을 사용하여 결과를 클라이언트에 바로 전송할 수 있습니다.
• Headers, Request, Response, TextEncoder / TextDecoder, btoa / atob.
• crypto.subtle.digest, crypto.subtle.importKey / sign / verify (HMAC), crypto.getRandomValues, crypto.randomUUID 및 16진수 문자열을 반환하는 도우미 함수 crypto.md5(), crypto.sha1(), crypto.sha256(), crypto.hmac().

하위 요청 제한은 다음과 같습니다.

• 80 및 443 포트의 http/https만 허용합니다.
• 사설, 루프백 및 링크 로컬 주소는 항상 거부합니다.
• 리디렉션은 최대 3회까지 따릅니다. 각 하위 요청은 10초 후 시간 초과되며 응답 본문은 8 MiB로 제한됩니다.

#경로 패턴

경로 패턴은 호스트 이름과 쿼리 문자열을 제외한 요청 경로에만 대조됩니다. 전체 경로와 일치해야 합니다.

• *는 /를 포함한 임의의 문자열과 일치하므로 여러 디렉터리 수준에 걸쳐 적용됩니다. **도 *와 동일하게 동작합니다.
• ?는 문자 하나와 일치합니다.
• 빈 패턴, * 또는 /*는 모든 경로와 일치합니다.

요청당 최대 하나의 Worker만 실행됩니다. 여러 연결이 일치하면 우선순위가 가장 높은 연결 하나만 실행됩니다. 겹치는 연결에는 서로 다른 우선순위를 지정하십시오.

#리소스 한도

#오류 및 디버깅

Worker에서 예외, 구문 오류, 시간 초과 또는 한도 초과가 발생하면 플랫폼은 요청을 계속 통과시킵니다(fail-open). Worker가 연결되지 않은 것처럼 요청을 원본 서버로 전달하며 오류 페이지는 표시하지 않습니다. 예상한 결과가 나오지 않으면 먼저 코드가 올바르게 실행되는지 확인하십시오.

#활성화, 비활성화 및 삭제

• Workers 목록에서 Worker를 비활성화하면 모든 도메인에서 실행이 중지됩니다. 도메인의 Worker 탭에서 개별 연결만 비활성화할 수도 있습니다.
• Worker를 삭제하면 연결된 모든 도메인에서 실행이 중지됩니다.
• 새 코드를 저장하면 해당 Worker에 연결된 모든 도메인에 자동으로 반영됩니다.

#요금제 및 할당량

도메인당 Worker 경로(연결) 수는 해당 도메인에 연결된 CDN 요금제에 따라 다릅니다. 작성 시점에 CDN Starter, Professional 및 Enterprise 요금제는 각각 도메인당 5개를 허용합니다. 최신 값은 요금제 페이지를 참조하십시오. 한도에 도달하면 콘솔에 "Worker 경로 한도에 도달했습니다"라는 안내가 표시됩니다. 더 추가하려면 요금제를 업그레이드하거나 기존 연결을 삭제하십시오.

#API로 Workers 관리

콘솔의 모든 작업은 사용자 API 호출에 대응합니다. Authorization: Bearer <token> 헤더에 로그인 토큰을 전달하여 인증합니다.

# Create a Worker (include an "id" field to update an existing one)
curl -X POST https://api.yeap.cloud/api/user/cdn/workers/save \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"name":"hello","code":"export default { fetch(){ return new Response(\"hi\"); } };","enabled":true}'

# Bind it to a domain
curl -X POST https://api.yeap.cloud/api/user/cdn/domains/www.example.com/workers/save \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"worker_id":123,"route_pattern":"/hello","priority":10,"enabled":true}'

기타 엔드포인트는 다음과 같습니다.

• Workers: GET /api/user/cdn/workers (목록), GET /api/user/cdn/workers/detail?id= (코드를 포함한 상세 정보), POST /api/user/cdn/workers/toggle, DELETE /api/user/cdn/workers/delete (JSON 본문 {"id":...}).
• 도메인 연결: GET /api/user/cdn/domains/<domain>/workers, POST .../workers/toggle, DELETE .../workers/delete.

#현재 지원하지 않는 기능

• 요청 본문 읽기.
• 콘솔에서 Worker의 환경 변수 또는 KV 설정(env는 빈 객체입니다).
• 원본 서버가 반환한 응답 수정. 현재 "응답 헤더 재작성" 템플릿은 적용되지 않습니다. 응답 헤더를 추가하려면 도메인의 규칙 기능을 사용하십시오.
• 응답 전송 후 실행이 보장되지 않는 ctx.waitUntil()을 통한 백그라운드 작업.
• 실행 로그 및 온라인 디버깅.