gateway-workers

작성자: cloudflare

Build, debug, or review Cloudflare Workers invoked by the Forward action in Gateway HTTP policies, including the GatewayMiddleware entrypoint, Gateway types, context, and continuation.

npx skills add https://github.com/cloudflare/skills --skill gateway-workers

Gateway Workers

Read the current Forward guide before implementing a Worker. It defines how Gateway invokes Workers on permitted HTTP traffic. Retrieve the relevant page below rather than copying setup, API payloads, or limits into the project from memory.

Workflow

  1. Inspect the existing Worker and choose a Worker template for the required transformation, synthetic response, or background task.
  2. Export a named GatewayMiddleware class extending WorkerEntrypoint from cloudflare:workers. Implement handle(request, context, next) and return a Response. Gateway calls this method through RPC. A default fetch() handler alone does not implement the Forward contract.
  3. For TypeScript, follow the chosen template's current package installation and type-import instructions.
  4. Use the second argument for Gateway context. It describes the original request and stays unchanged when the Worker modifies the request. Keep it distinct from this.ctx (Workers execution context) and this.env (bindings).
  5. Continue the user's request with next(request) at most once, or return a synthetic response without calling it. next() always targets the original destination. Changes to the destination URL or host are ignored, and it cannot redirect, retry, or fan out. Use fetch() to send a request to a different destination. It creates an independent subrequest that does not inherit the user's Gateway policies or egress configuration.

Context

Use the published types and context reference for field names and availability. Treat a falsy identity (!identity) as anonymous and guard optional posture values. Call await context.identity() or await context.devicePosture() only when needed. Both getters can reject. Catch lookup failures separately from missing values and decide how to handle each when the Worker depends on them. Use Gateway-provided identity rather than client-supplied identity headers.

Gateway behavior

  • Only the first matching Forward policy invokes a Worker. Worker invocation does not confirm successful body inspection. Follow the Forward guide's inspection order.
  • Gateway inspects the final response, including synthetic responses. Modified request bytes are not inspected again before reaching the origin.
  • Review the Forward guide's limitations before choosing traffic: HTTPS requires decryption, WebSockets bypass the Worker, and matching Workers VPC traffic is dropped. Worker invocation failures fail closed.

Validation

Type-check against the installed Gateway types and test the named RPC entrypoint, including zero or one continuation call and the context values the Worker uses. Then test a permitted request through a scoped Gateway Forward policy. A direct request to a default fetch() handler does not validate the Gateway path. Follow the chosen template's test procedure and the Forward guide's troubleshooting steps.

Check the response and streaming rules: return a final status from 200 to 599, return no body for HEAD requests or statuses 204, 205, and 304, and stream bodies rather than buffering them.

Related skills

  • cloudflare-one: Gateway policy design, traffic paths, identity, TLS, and rollout.
  • workers-best-practices: streaming, bindings, generated environment types, background work, observability, and runtime tests.
  • CLI selection: choose the existing cf-cli or wrangler skill for project setup and deployment.

Skill feedback

If the user reports that this skill gave incorrect or outdated guidance, or is missing information, read references/skill-feedback.md.

cloudflare의 다른 스킬

add-autogate
cloudflare
위험한 변경 사항을 점진적으로 롤아웃하기 위해 workerd에 새 자동 게이트를 추가하는 단계별 가이드(열거형 등록, 문자열 매핑, 사용 패턴 및 … 포함)
add-autogate
cloudflare
위험한 변경 사항의 점진적 배포를 위해 workerd에 새 autogate를 추가하는 단계별 가이드로, enum 등록, 문자열 매핑, 사용 패턴 등을 포함…
add-compat-flag
cloudflare
workerd에 새로운 호환성 플래그를 추가하기 위한 단계별 가이드로, capnp 스키마, C++ 사용법, 테스트 및 문서 요구 사항을 포함합니다.
add-compat-flag
cloudflare
workerd에 새로운 호환성 플래그를 추가하기 위한 단계별 가이드로, capnp 스키마, C++ 사용법, 테스트 및 문서 요구 사항을 포함합니다.
agents-sdk
cloudflare
Cloudflare Workers에서 Agents SDK를 사용하여 AI 에이전트를 구축하세요. 상태 저장 에이전트, 지속 가능한 워크플로우, 실시간 WebSocket 앱, 예약된 작업 등을 생성할 때 로드하세요.
architecture
cloudflare
코드베이스를 처음 탐색할 때, 새 클라이언트 메서드를 추가할 때, 새 컨테이너 핸들러/서비스를 추가할 때, 또는 요청 흐름을 이해할 때 사용합니다.
basin
cloudflare
Basin Pipelines, Basin Catalog, Basin SQL을 사용해 Cloudflare Basin 분석 워크플로를 구축하고 문제를 해결합니다. 데이터를 R2 Iceberg 테이블로 스트리밍하거나, 카탈로그를 관리하거나, 해당 테이블을 쿼리할 때 사용하세요. 이전 이름인 Data Platform, Pipelines, R2 Data Catalog 또는 R2 SQL을 사용하는 요청에도 사용하세요.
data-analysisawsdatabase
bazel-test-hygiene
cloudflare
개발 중 bazel 테스트 실행을 위한 필수 규칙입니다. 특히 수정 사항을 검증할 때 bazel 테스트 명령을 실행하기 전에 이 스킬을 로드하세요.