# Proxy mode

Proxy mode puts UsherStats in front of your site without any code: you point a hostname at us, and every request to it
gets analytics and bot protection and is then forwarded to your server (the origin). Use it when your site is not on
Cloudflare Workers, or you would rather not change it.

## Setting it up

1. In the dashboard (or the API), add the hostname to your site in proxy mode and give the **origin**: where your site
   really lives, such as `origin.example.com` or `https://example-app.pages.dev`.
2. Create the DNS records it shows you. The CNAME is what sends traffic to us; the TXT records are optional, and let
   the hostname go live before you move the CNAME, with no gap:

```json records
[
  { "type": "CNAME", "name": "shop.customer.example", "value": "proxy.usherstats.com", "purpose": "routing" },
  { "type": "TXT", "name": "_cf-custom-hostname.shop.customer.example", "value": "5cc07c04-ea62-4a5a-95f0-419334a875a4", "purpose": "ownership" },
  { "type": "TXT", "name": "_acme-challenge.shop.customer.example", "value": "810b7d5f01154524b961ba0cd578acc2", "purpose": "certificate" }
]
```

3. Wait for the status to become **active**. A certificate is issued for your hostname automatically once the CNAME is
   in place, usually within minutes; until then the status shows what is still missing (for example, a CAA record that
   does not allow the certificate authority).

Each plan includes a number of proxy-mode hostnames (Free 1, Starter 3, Growth 10, Business 50); beyond that, $1 per
hostname per month, up to 500 per workspace on any plan (write to support@usherstats.com for more). Proxy hostnames
can be added or removed 30 times an hour per workspace.

A proxied hostname belongs to one site. It goes live once Cloudflare has validated it (the CNAME, or the TXT
records the answer lists); one still not validated after 72 hours is released: another site may then add it, and a
daily job removes it.

## The origin

The origin is a hostname, optionally with `https://` or `http://` and a port. It cannot be the proxied hostname itself
(that would loop), a `usherstats.com` hostname, or a bare IP address, and the port must be one Cloudflare can reach
(80, 8080, 8880, 2052, 2082, 2086, 2095 for http; 443, 2053, 2083, 2087, 2096, 8443 for https).

## What your origin receives

- The request as the visitor sent it: method, path, query string, body and headers.
- `X-Forwarded-Host` (your hostname), `X-Forwarded-Proto`, and the visitor's address appended to `X-Forwarded-For`.
- The `Host` header is the origin's own hostname. If your server picks the site by host name, configure it to answer
  for the origin hostname, or read `X-Forwarded-Host`.
- Not the `us_pass` cookie (the bot protection pass), and not the headers that only describe the connection to us.

## What visitors receive

Your origin's response, streamed as it was sent: status, headers, cookies and body. HTML pages also get the analytics
script. Nothing is cached beyond what your origin's own `Cache-Control` allows. Redirects are passed on rather than
followed, and a redirect to your origin's hostname is rewritten to your public hostname, so visitors never see the
origin's name.

## Analytics and bot protection

Proxied requests are recorded and protected exactly as with the Worker SDK (see [Bot protection](bot-protection.md)):
the same modes, rules and check. In proxy mode the analytics script is served from your hostname and sends its page
reports straight to `collect.usherstats.com`, so pageviews carry the visitor's own country and network. If your
origin cannot be reached, visitors get a short `502` page from us, and the failed request is recorded.

## Limits

- WebSocket connections are not proxied.
- Request records count toward the plan's server requests, as with the Worker SDK.