gateway-workers

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.

Thêm skills từ cloudflare

add-autogate
cloudflare
Hướng dẫn từng bước để thêm autogate mới vào workerd nhằm triển khai dần các thay đổi rủi ro, bao gồm đăng ký enum, ánh xạ chuỗi, mẫu sử dụng, và…
add-autogate
cloudflare
Hướng dẫn từng bước để thêm autogate mới vào workerd nhằm triển khai dần các thay đổi rủi ro, bao gồm đăng ký enum, ánh xạ chuỗi, mẫu sử dụng, và…
add-compat-flag
cloudflare
Hướng dẫn từng bước để thêm một cờ tương thích mới vào workerd, bao gồm lược đồ capnp, cách sử dụng C++, kiểm thử và các yêu cầu về tài liệu.
add-compat-flag
cloudflare
Hướng dẫn từng bước để thêm cờ tương thích mới vào workerd, bao gồm lược đồ capnp, cách sử dụng trong C++, kiểm thử và các yêu cầu về tài liệu.
agents-sdk
cloudflare
Xây dựng AI agent trên Cloudflare Workers bằng Agents SDK. Tải khi tạo agent có trạng thái, quy trình làm việc bền vững, ứng dụng WebSocket thời gian thực, tác vụ theo lịch trình,…
architecture
cloudflare
Sử dụng khi lần đầu điều hướng cơ sở mã, thêm một phương thức client mới, thêm một trình xử lý/dịch vụ container mới, hoặc hiểu cách một yêu cầu luân chuyển…
basin
cloudflare
Xây dựng và khắc phục sự cố các quy trình phân tích Cloudflare Basin bằng Basin Pipelines, Basin Catalog và Basin SQL. Sử dụng để truyền dữ liệu vào các bảng R2 Iceberg, quản lý danh mục hoặc truy vấn các bảng đó; cũng sử dụng cho các yêu cầu dùng tên cũ Data Platform, Pipelines, R2 Data Catalog hoặc R2 SQL.
data-analysisawsdatabase
bazel-test-hygiene
cloudflare
Các quy tắc bắt buộc khi chạy kiểm thử bazel trong quá trình phát triển. Tải kỹ năng này trước khi chạy bất kỳ lệnh kiểm thử bazel nào, đặc biệt là khi xác thực các bản sửa lỗi hoặc…