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?
answer
- filled in by the network, not the client
- a non-standard property on Request
- an airport code for the data center
- optional, nullable, read-only
basics
~20 srequest.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 linesexport 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
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.
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.
Handle request.cf defensively in production: default every field, overwrite forwarded headers, and test geography-dependent logic with explicit fixtures.
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.