Skip to content
bucker

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.

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)

// 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

// 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

// 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

// 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

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.