skip to content

In Cloudflare Workers, what is request.cf, what do properties such as country, colo and asn tell you, and how far can you trust them?

level: juniorimportance: should knowfreq 30%

answer

  1. filled in by the network, not the client
  2. a non-standard property on Request
  3. an airport code for the data center
  4. optional, nullable, read-only

basics

~20 s

request.cf is a read-only, Workers-only object that Cloudflare's network attaches to an incoming request: country, colo (the data center's IATA code), asn, tlsVersion and more. Clients cannot set it, but values are IP-derived estimates that may be null or absent.

solid answer

~40 s

`request.cf` is a non-standard property that Cloudflare's network fills in on incoming requests before your Worker runs. It describes the connection: `country` (a two-letter code, a special code such as `T1`, or null), `city`, `region`, `timezone`, `latitude` and `longitude`, `asn` and `asOrganization`, `colo` (the IATA code of the data center that took the request), and `httpProtocol`, `tlsVersion` and `tlsCipher`. A client cannot write it, unlike a header it sends, and the object is read-only to your code too. Two limits apply: location fields come from the client IP, so VPNs and proxies move them, and fields can be null or missing, so code must handle `undefined`. In local `wrangler dev`, the object is a cached sample of the developer's own connection, not the visitor's.

code

javascript · 19 lines
javascript
export default {
  async fetch(request) {
    const cf = request.cf ?? {};
    const url = new URL(request.url);

    const headers = new Headers(request.headers);
    // set() overwrites any value the client sent under the same name.
    headers.set("X-Visitor-Country", cf.country ?? "unknown");
    headers.set("X-Edge-Colo", cf.colo ?? "unknown");
    headers.set("X-Visitor-ASN", String(cf.asn ?? 0));
    headers.set("X-Client-TLS", cf.tlsVersion ?? "unknown");

    return fetch(`https://legacy.example.com${url.pathname}${url.search}`, {
      method: request.method,
      headers,
      body: request.body,
    });
  },
};

go deeper

for a junior

Name the common request.cf fields, especially country, colo, asn and tlsVersion, and know that Cloudflare fills them in while client headers can be forged.

for a middle

Explain why the object may be missing or null, why it is read-only, and how local dev supplies one cached sample instead of the visitor's data.

for a senior

Handle request.cf defensively in production: default every field, overwrite forwarded headers, and test geography-dependent logic with explicit fixtures.

for a principal

Decide which business rules may rest on IP-derived location and which need stronger signals, and document that line for every team that reads request.cf.

## What it is Every request that reaches a Worker through Cloudflare's network carries a `cf` property that the Fetch standard does not have. The network computes it from the client connection and attaches it before the `fetch` handler runs, so the Worker can make decisions about **where** and **how** the client connected without calling any lookup service. In the Workers TypeScript types the property is optional (`cf?`), which is a reminder that code must cope with its absence. ## The fields teams use most | Property | Meaning | Example | |---|---|---| | `country` | Two-letter country code, a special code such as `T1`, or null | `"US"` | | `colo` | IATA airport code of the data center that received the request | `"DFW"` | | `asn`, `asOrganization` | Autonomous system of the client's network | `395747` | | `city`, `region`, `postalCode`, `timezone` | Approximate location from the IP | `"Austin"` | | `httpProtocol` | Protocol the client used | `"HTTP/2"` | | `tlsVersion`, `tlsCipher` | TLS details of the client connection | `"TLSv1.3"` | | `isEUCountry` | `"1"` when the country is in the EU | `"1"` | | `clientTcpRtt` | Smoothed round-trip time in milliseconds, for TCP clients | `22` | `country` is the same value that the `CF-IPCountry` header carries. That header is removed from requests a Worker makes to an origin that is not proxied behind Cloudflare, so a Worker that wants a legacy origin to know the visitor's country forwards `request.cf.country` in a header of its own. ## How far to trust it - **Not client-controlled.** A client can send any header it likes, including a fake country header, but it cannot write `request.cf`. When forwarding these values, use `headers.set()` on a header set you built, so a client-sent header of the same name is overwritten rather than passed along. - **Read-only.** Assigning `request.cf.country = "DE"` throws a `TypeError` in module code. To send different `cf` options on a subrequest you pass a new `cf` object in the request init, which controls how Cloudflare handles that subrequest rather than describing the client. - **Estimates, not identity.** Location fields come from IP geolocation. VPNs, corporate proxies and mobile carriers move them, so they suit defaults (language, nearest region, analytics) better than hard security decisions. - **Nullable and optional.** `country`, `city` and other fields can be null, and some fields are filled only in specific setups, such as `botManagement`, set only with Bot Management, and `hostMetadata`, set only for custom hostnames that carry metadata. ## Where it is missing or fake 1. The dashboard and Playground preview editors do not provide `request.cf` at all. 2. Local `wrangler dev` provides an object that Miniflare downloads once, describing the developer's own connection, and caches for up to 30 days, with a built-in fallback (Austin, `DFW`) when it cannot fetch one. Every local request sees the same values. 3. A `Request` your own code constructs from a URL has no incoming metadata. So write `const cf = request.cf ?? {}` and give each field a default, and test country-dependent logic with explicit fixtures instead of relying on the developer's location. ## Typical uses Forwarding the visitor's country, data center and ASN to a legacy origin for its logs, choosing a default locale, recording `colo` and `httpProtocol` in analytics to see where traffic lands, and noticing old TLS versions in logs. Enforcing a minimum TLS version belongs in the zone's TLS settings, not in Worker code. ## Reading the example The Worker below reads `request.cf` once with a fallback to an empty object, copies the incoming headers into a new `Headers` object, and sets four headers of its own from `country`, `colo`, `asn` and `tlsVersion`, each with a default for the case where the field is missing. Because it uses `set()`, a client that sends its own `X-Visitor-Country` cannot smuggle a value through. The legacy origin then logs or acts on headers it can rely on, as long as it accepts traffic only from the Worker.

  • Why not just read the CF-IPCountry header at the origin?
    Cloudflare removes `CF-IPCountry` from requests a Worker sends to an origin that is not proxied behind Cloudflare, and a header can be forged by anyone who reaches the origin directly. Forwarding `request.cf.country` under your own header, set with `headers.set()`, gives the origin the value every time; the origin should still accept traffic only from the Worker.
  • A test of country-specific pricing passes locally but fails in production. What is the likely gap?
    Locally, `request.cf` is a cached sample of the developer's own connection, identical for every request, so the test only ever exercised one country. Inject `cf` values explicitly in tests, handle null and `T1` countries, and keep a default branch for a missing `cf`.

  • A client can set request.cf.country by sending a CF-IPCountry header.
  • request.cf.colo is the visitor's city.
  • request.cf is always present, so request.cf.country needs no null check.
  • Assigning request.cf.country changes what the origin sees.
  • Geolocation from request.cf is reliable enough to enforce legal access controls alone.