Log in Start free

All docs

All docs / Build

Writing handlers

Requests and responses, routing, every entry point, the Web APIs you can use, TCP, HTTP/2, caching and limits.

Open in the console

An app is an ES module whose default export holds handler functions. Each handler gets the event (a request, a schedule tick, a batch of queue messages or an email), env (bindings, variables and secrets) and ctx (lets work continue after the response). The runtime is workerd, the same as Cloudflare Workers, so code and libraries written for Workers run as is.

The fetch handler

js

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);

    if (request.method === "GET" && url.pathname === "/") {
      return new Response("Hello from the edge", {
        headers: { "content-type": "text/plain; charset=utf-8" },
      });
    }

    if (request.method === "POST" && url.pathname === "/api/echo") {
      const body = await request.json();          // throws on invalid JSON
      return Response.json({ youSent: body });    // sets content-type for you
    }

    return Response.json({ error: "not found" }, { status: 404 });
  },
};

request is a standard Request: , , , and the body via , , , or the stream (read it once).

method

url

headers

json()

text()

formData()

arrayBuffer()

body

js

const routes = [
  { method: "GET", pattern: new URLPattern({ pathname: "/api/posts" }), handler: listPosts },
  { method: "GET", pattern: new URLPattern({ pathname: "/api/posts/:id" }), handler: getPost },
  { method: "POST", pattern: new URLPattern({ pathname: "/api/posts" }), handler: createPost },
];

export default {
  async fetch(request, env, ctx) {
    for (const r of routes) {
      const match = r.method === request.method && r.pattern.exec(request.url);
      if (match) return r.handler(request, env, ctx, match.pathname.groups);
    }
    return Response.json({ error: "not found" }, { status: 404 });
  },
};

async function getPost(request, env, ctx, { id }) {
  const post = await env.DB.prepare("SELECT * FROM posts WHERE id = ?").bind(id).first();
  return post ? Response.json(post) : Response.json({ error: "no such post" }, { status: 404 });
}

src/
  index.js        entry: routing only
  routes/links.js request handlers for one feature
  lib/db.js       storage access
  lib/http.js     json(), errors, CORS helpers
  assets/page.html
README.md
wrangler.jsonc   so `rr deploy` works too

js

export default {
  async fetch(request, env, ctx) { /* … */ },

  // Cron triggers (console: Triggers, config: triggers.crons)
  async scheduled(controller, env, ctx) {
    // controller.cron is the expression that fired, controller.scheduledTime the time
    ctx.waitUntil(env.DB.prepare("DELETE FROM sessions WHERE expires < ?").bind(Date.now()).run());
  },

  // Messages from a queue this app consumes
  async queue(batch, env, ctx) {
    for (const msg of batch.messages) {
      await handle(msg.body, env);
      msg.ack();
    }
  },

  // Mail routed to this app by Email routing
  async email(message, env, ctx) {
    await message.forward("team@example.com");
  },
};

js

export default {
  async fetch(request, env, ctx) {
    const slug = new URL(request.url).pathname.slice(1);
    const link = await env.DB.prepare("SELECT url FROM links WHERE slug = ?").bind(slug).first();
    if (!link) return new Response("not found", { status: 404 });
    ctx.waitUntil(
      env.DB.prepare("UPDATE links SET clicks = clicks + 1 WHERE slug = ?").bind(slug).run(),
    );
    return Response.redirect(link.url, 302);
  },
};

js

// HMAC-SHA256 signature, hex encoded
async function sign(secret, data) {
  const key = await crypto.subtle.importKey(
    "raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"],
  );
  const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(data));
  return [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("");
}

js

import { connect } from "cloudflare:sockets";

async function whois(server, query) {
  const socket = connect({ hostname: server, port: 43 });
  const writer = socket.writable.getWriter();
  await writer.write(new TextEncoder().encode(query + "\r\n"));
  writer.releaseLock();
  return await new Response(socket.readable).text();   // reads until the server closes
}

export default {
  async fetch(request) {
    const domain = new URL(request.url).searchParams.get("d") ?? "example.cn";
    return new Response(await whois("whois.cnnic.cn", domain));
  },
};

js

import { fetchVia, ping, tcp, udp, dns, regions } from "/_edge/net.js";

export default {
  async fetch(request) {
    // An HTTP/3 request from a random node in us-west.
    const res = await fetchVia("https://cloudflare.com/cdn-cgi/trace", {}, { region: "us-west", httpVersion: "3" });
    const trace = await res.text();

    // Latency to 1.1.1.1 from three regions at once.
    const pings = await Promise.all(
      ["asia-east", "eu-west", "us-west"].map((region) => ping("1.1.1.1", { region, count: 3 })),
    );

    // Is port 443 open, seen from any node? (send/readBytes for a banner)
    const port = await tcp("example.com", 443, { region: "random" });

    // One UDP datagram out, one back: { reply, rttMs, timedOut }.
    // const r = await udp("203.0.113.9", 27015, queryBytes, { region: "eu-west" });

    // A lookup through 8.8.8.8 from a node in asia-east.
    const aaaa = await dns("example.com", { type: "AAAA", server: "8.8.8.8", region: "asia-east" });

    return Response.json({
      node: res.headers.get("x-rf-node"),
      proto: res.headers.get("x-rf-proto"),
      trace,
      pings: pings.map((p) => ({ node: p.node.label, region: p.node.region, avgMs: p.avgMs, loss: p.loss })),
      connectMs: port.connectMs,
      aaaa: aaaa.records,
      regions: await regions(),
    });
  },
};

js

import { fetchHttp2 } from "/_edge/http2.js";

export async function pushToIPhone(env, deviceToken, title, body) {
  const jwt = await apnsJwt(env); // ES256 JWT from your .p8 key, cached ~50 minutes
  const res = await fetchHttp2(`https://api.push.apple.com/3/device/${deviceToken}`, {
    method: "POST",
    headers: {
      authorization: `bearer ${jwt}`,
      "apns-topic": env.APNS_BUNDLE_ID,
      "apns-push-type": "alert",
    },
    body: JSON.stringify({ aps: { alert: { title, body }, sound: "default" } }),
  });
  if (res.status !== 200) throw new Error(`APNs ${res.status}: ${await res.text()}`);
}

js

export default {
  async fetch(request, env, ctx) {
    const cache = caches.default;
    const hit = await cache.match(request);
    if (hit) return hit;
    const upstream = await fetch("https://api.example.com/rates");
    const res = new Response(upstream.body, upstream);
    res.headers.set("cache-control", "public, max-age=300");
    ctx.waitUntil(cache.put(request, res.clone()));
    return res;
  },
};

js

const CORS = {
  "access-control-allow-origin": "https://app.example.com",
  "access-control-allow-methods": "GET, POST, OPTIONS",
  "access-control-allow-headers": "content-type, authorization",
};

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") return new Response(null, { status: 204, headers: CORS });
    const res = await handle(request, env);
    for (const [k, v] of Object.entries(CORS)) res.headers.set(k, v);
    return res;
  },
};

js

export default {
  async fetch(request) {
    if (request.headers.get("upgrade") !== "websocket") {
      return new Response("expected a WebSocket", { status: 426 });
    }
    const [client, server] = Object.values(new WebSocketPair());
    server.accept();
    server.addEventListener("message", (e) => server.send(`echo: ${e.data}`));
    return new Response(null, { status: 101, webSocket: client });
  },
};