# The first-party tunnel

Ad blockers match ingest hostnames, and a blocked ingest is the one drop class Bucker cannot count:
nothing arrives, so nothing is recorded. The tunnel moves the browser's envelopes to a path on
**your** origin, where your server forwards them. This page is the server half: what the handler
guarantees, a recipe per platform, and why Bucker does not run a CNAME for you.

The browser half is `init({ dsn, tunnel: '/your-path' })`; see
[Sending through your own origin](sdk-browser.md#sending-through-your-own-origin-tunnel).

## What the handler does

`tunnelRoute()` (from `@bucker/node/nextjs`, or `@bucker/node/tunnel` for any `Request` -> `Response`
runtime) does four things before it forwards:

1. **Only your DSNs.** It reads the project id from the envelope header and forwards to the DSN you
   listed, with that DSN's host and key. Any other project is a `403`.
2. **Consent, checked before forwarding.** A revoked (or pending) consent header, or a visitor
   `Sec-GPC: 1`, removes every identity-bearing item (product events, survey answers, feedback,
   replay) and the person from errors and sessions. Nothing refused is sent upstream; the browser is
   told item by item in `X-Bucker-Results`. Set `requireConsent: true` when your posture needs a
   stated consent: an envelope with **no** consent header is then refused the same way, while a
   `granted` one is forwarded.
3. **A country, never an address.** The visitor's country is read from your platform's header and
   forwarded as `X-Bucker-Client-Country`. The outbound request is built from nothing, so no inbound
   header (`X-Forwarded-For`, `X-Real-IP`, cookies) reaches Bucker. The ingest edge prefers this
   country over its own lookup for tunnelled envelopes, because its own lookup sees your server.
4. **`transport: "tunnel"`** is stamped on the envelope header, so Bucker can count tunnelled
   traffic and see browsers that arrive direct.

### Where the country comes from

| Platform | Header read |
|---|---|
| Vercel | `x-vercel-ip-country` |
| Cloudflare (Workers, Pages, proxy) | `cf-ipcountry` |
| Fly.io | `fly-region`, mapped to the country the region is in (the region that served the request, so a last resort) |
| Anything else | `country: { lookup: (ip) => 'DE' }`, a local GeoIP lookup you supply; the address goes into your function and no further |

`country: { headers: ['x-my-edge-country'] }` replaces the list; `country: false` turns the country
off. List only headers **your platform sets itself**: a host that does not overwrite
`x-vercel-ip-country` lets a visitor choose it.

### The country header can only tighten

`X-Bucker-Client-Country` is client-supplied, so the ingest never lets it loosen anything. A
direct (non-tunnel) envelope carrying it is treated as if it had none, and so is one whose request
carries a browser's own `Origin` or `Sec-Fetch-*` headers: the handler's outbound request never
does, so an envelope that claims `transport: "tunnel"` from a browser came straight from the page.
(A page cannot set the header on a direct request anyway: the ingest's CORS policy does not allow it.) For a tunnelled one, if the
header and the edge's own lookup disagree and exactly one of them is in the EU, EEA or UK, the
stricter region applies. Consent, residency and EU/UK-hint decisions read that stricter answer.

## Recipes

Every recipe is the same two lines: one handler, one path. Choose a path that is yours (`/bucker` is
as blockable as a hostname if everyone uses it) and put the same path in `init({ tunnel })`.

### Next.js (App Router)

```ts
// app/<your-path>/route.ts
import { tunnelRoute } from '@bucker/node/nextjs'

export const POST = tunnelRoute({ dsns: [process.env.NEXT_PUBLIC_BUCKER_DSN] })
```

### Remix / React Router

```ts
// app/routes/<your-path>.ts
import { tunnelRoute } from '@bucker/node/tunnel'

const tunnel = tunnelRoute({ dsns: [process.env.BUCKER_DSN] })
export const action = ({ request }: { request: Request }) => tunnel(request)
```

### SvelteKit

```ts
// src/routes/<your-path>/+server.ts
import { tunnelRoute } from '@bucker/node/tunnel'
import { env } from '$env/dynamic/private'

const tunnel = tunnelRoute({ dsns: [env.BUCKER_DSN] })
export const POST = ({ request }) => tunnel(request)
```

### Nuxt

```ts
// server/routes/<your-path>.post.ts
import { tunnelRoute } from '@bucker/node/tunnel'
import { toWebRequest } from 'h3'

const tunnel = tunnelRoute({ dsns: [process.env.BUCKER_DSN] })
export default defineEventHandler((event) => tunnel(toWebRequest(event)))
```

### Cloudflare Workers

```ts
import { tunnelRoute } from '@bucker/node/tunnel'

export default {
  fetch(request: Request, env: { BUCKER_DSN: string }) {
    if (new URL(request.url).pathname !== '/your-path') return new Response('Not found', { status: 404 })
    return tunnelRoute({ dsns: [env.BUCKER_DSN] })(request) // cf-ipcountry is set for you
  },
}
```

### A reverse proxy (nginx, Caddy, a load balancer)

A proxy cannot check consent, strip the address or stamp the transport, so it is the weakest option
and the one to use only when you cannot run the handler. Pass the body through unchanged to
`https://<your ingest host>/api/<project id>/envelope/?sentry_key=<public key>&sentry_version=7`
and **do not** forward `X-Forwarded-For` or `X-Real-IP`. Without the stamped transport this traffic
is counted as direct, and a direct envelope's `X-Bucker-Client-Country` is ignored, so there is no
point adding one: the country is the ingest's own lookup of your proxy's address.

## What it costs

Every browser event becomes a request to your host (an invocation on a serverless platform), and
you pay for it. Pair the tunnel with `sampleRate` and `ignoreErrors`.

## Why there is no Bucker-run CNAME

Some vendors offer a managed reverse proxy: point `ingest.yourdomain.com` at them and the blocklists
never see their name. Bucker does not, on purpose. A vendor-run CNAME makes the vendor an
ad-block bypass service, which is a position Bucker will not take for you or against the sites
whose blocklists you are routing around, and it adds a sub-processor that sees every visitor's
address before any consent decision. The tunnel above keeps both on your side of the line: your
server forwards, applies your visitor's consent, and sends Bucker a country.

## Checking that it works

The `tunnel_bypass` instrumentation check reports browser envelopes that reach Bucker directly
while the project's tunnel is in use. It stays `unknown` for a project with no tunnelled traffic:
Bucker cannot tell a project that never set a tunnel up from one whose tunnel is down.
