Reference

Architecture

How xdns.wtf routes traffic, manages state, and stays secure.

Overview

xdns.wtf uses a single Cloudflare Worker to handle all traffic for the xdns.wtf zone. A wildcard DNS record (*.xdns.wtf) routes all subdomains through Cloudflare's edge network to the Worker, which then looks up the tenant and proxies traffic to the configured origin.

No per-tenant DNS records are created. Provisioning is purely a database write — which means new subdomains are live instantly, and deletions take effect immediately.

Request flow

1.  Browser hits https://myapp.xdns.wtf/path?q=1

2.  DNS: *.xdns.wtf → Cloudflare (proxied)
        Cloudflare terminates TLS at the nearest PoP

3.  Worker receives request
        URL:  https://myapp.xdns.wtf/path?q=1
        Host: myapp.xdns.wtf

4.  Worker extracts slug from Host header
        "myapp.xdns.wtf" → slug = "myapp"

5.  D1 lookup:
        SELECT slug, target_origin, subnet_id, status
        FROM tenants WHERE slug = 'myapp'

6.  If not found or status != 'active' → 404

7.  Build upstream URL:
        https://myapp.vercel.app/path?q=1
        (target_origin + original path + query string)

8.  Forward request:
        - Same HTTP method
        - Same request body (streamed)
        - Set X-XDNS-Tenant: myapp
        - Set X-XDNS-Subnet: <subnet_id>  (if configured)
        - redirect: "manual"  (pass-through redirects)

9.  Stream upstream response back to browser

Stack

Layer	Technology	Purpose
DNS	Cloudflare zone — xdns.wtf	Wildcard *.xdns.wtf → Worker. No per-tenant records.
Edge compute	Cloudflare Workers (V8 isolates)	Hostname router + admin API. Runs at 300+ PoPs, no cold start.
Database	Cloudflare D1 (SQLite at edge)	Tenant slug → target mapping. Sub-ms reads at edge.
Web	Next.js on Vercel	Landing page and docs (this site). Apex xdns.wtf proxied here.
CI/CD	GitHub Actions + Wrangler	git push to main → auto-deploy Worker.

Data model

A single tenants table in Cloudflare D1:

Column	Type	Constraints	Description
`slug`	TEXT	PRIMARY KEY	Subdomain slug (e.g. myapp)
`target_origin`	TEXT	NOT NULL	Origin URL (e.g. https://myapp.vercel.app)
`subnet_id`	TEXT	nullable	Optional subnet/group identifier
`status`	TEXT	NOT NULL	'active' or 'suspended'
`created_at`	INTEGER	NOT NULL	Unix epoch timestamp

-- Index on status for efficient filtering
CREATE INDEX idx_tenants_status ON tenants(status);

Security

SSRF protection

Target origins pointing to private IP ranges are rejected at validation time with a 400 private_origin_blocked error. Blocked ranges: 10.x, 172.16-31.x, 192.168.x, 127.x, localhost, 0.0.0.0, [::1].

Admin token auth

All /api/* routes require a valid Bearer token. The token is stored as a Wrangler secret (never in code or config files).

Abuse kill switch

Set status = 'suspended' on a tenant record to instantly block routing. The Worker returns 404 for any suspended tenant without reaching the upstream origin.

Redirect pass-through

Upstream redirects are passed through to the client using redirect: "manual". The Worker does not follow redirects on behalf of the client.

Reserved slugs

The following slugs cannot be provisioned:

wwwapiadminmailcdnftpsmtpimappopns1ns2ns3ns4mxdevstagingteststatusdashboardappdocshelpsupportbilling

Apex routing

Requests to xdns.wtf (no subdomain) are proxied by the Worker to the Next.js site on Vercel at the URL configured in the SITE_ORIGIN Wrangler variable. Path and query string are preserved.

Deployment

WorkerPush to main → GitHub Actions runs Wrangler deploy. Or run just deploy manually.

WebPush to main → Vercel auto-deploys the Next.js site. Root directory: web/.

D1Run just migrate to apply migrations to the remote D1 database.