serverless-dns: Serverless content-blocking DNS resolver for Cloudflare, Deno, Fastly and Fly.io
serverless-dns delivers a serverless DoH/DoT resolver with content-blocking that runs on Cloudflare, Deno, Fastly and Fly.io—suitable for privacy-focused individuals and small self-hosted deployments; however, evaluate license and community/maintenance maturity before production use.
GitHub serverless-dns/serverless-dns Updated 2025-11-12 Branch main Stars 2.9K Forks 2.1K
DNS-over-HTTPS (DoH) DNS-over-TLS (DoT) Edge computing Self-hosted content-blocking Cloudflare Workers Deno Deploy Fastly Compute@Edge Fly.io Serverless

💡 Deep Analysis

6
What concrete problems does this project solve and how are those goals achieved technically?

Core Analysis

Project Positioning: serverless-dns aims to provide a Pi-hole-like encrypted DNS (DoH/DoT) resolver that runs on edge/serverless platforms, minimizing device maintenance and ongoing operational cost for individuals and small teams.

Technical Features

  • Edge/Serverless Implementation: Supports Cloudflare Workers, Deno, Fastly, Fly.io with a stateless/lightweight design tailored to serverless constraints.
  • Integrated Features: Built-in blocklist management (via /configure), a plugin processing pipeline (user-op.js -> cache-resolver.js -> cc.js -> resolver.js), and HMAC-based access control.
  • Upstream Interaction: Acts as a stub/forwarding resolver that relies on configurable upstream DoH or system resolver for final answers, avoiding full recursive complexity.

Practical Recommendations

  1. Validation Path: Deploy first on Cloudflare Workers (recommended in README) to validate features, then port to other runtimes as needed.
  2. Blocklist & Cache: Use /configure to tune blocklists and enable cache components to reduce upstream requests.
  3. Enable Logging: Configure Logpush -> R2 or equivalent log exports for auditing and false-positive analysis.

Caveats

  • Not a full recursive resolver: It depends on upstream DoH and is not suitable for completely offline or highly customized resolution needs.
  • Runtime differences: Platform network APIs and quotas can change behavior or limit features.

Important Notice: Best suited for privacy-focused, low-ops deployments covering small device counts on free tiers; for high-throughput or enterprise-grade DNS, consider a dedicated recursive resolver or commercial offering.

Summary: Technically, serverless-dns uses a stateless, plugin-driven edge approach to solve self-hosted DoH/DoT and content-blocking pains, but is bound by serverless resource and upstream dependencies.

88.0%
Regarding performance and scalability, for what traffic scale is this serverless DNS suitable? How to use caching and upstream configuration to optimize latency and cost?

Core Analysis

Traffic Fit: Based on README and implementation, serverless-dns suits low-to-moderate traffic (individuals/small teams). Free tiers are said to cover ~10–20 devices/month; server-side processing is 0–2ms with median end-to-end ~10–30ms.

Technical Analysis

  • Caching: The cache-resolver.js plugin can cache frequent answers to cut upstream DoH calls.
  • Upstream Strategy: Configure multiple upstream DoH servers and prefer nearby/low-latency upstreams to reduce latency and failures.
  • Serverless Limits: Concurrency, execution time, and quota limits become bottlenecks at high scale—unsuitable as a high-traffic authoritative resolver.

Practical Recommendations

  1. Enable & Tune Cache: Use cache-resolver, tune TTLs and respect upstream TTLs to avoid staleness.
  2. Multi-Upstream Setup: Maintain a prioritized list of trusted DoH upstreams with regional preferences and fallback logic.
  3. Monitor & Optimize: Export logs (Logpush -> R2) to measure hot queries, cache hit ratio, and false positives and refine blocklists/cache.

Caveats

  • High concurrency can drive up cost on serverless platforms quickly.
  • Large persistent caches require external storage (e.g., R2); edge instances aren’t suitable for big local caches.

Important Notice: Use serverless-dns as an edge filtering/forwarding layer near users; for high-throughput or full recursive needs, use a dedicated recursive DNS server or managed enterprise service.

Summary: Proper caching and upstream design yield low-latency, low-cost self-hosted DoH/DoT for small deployments, but serverless limits constrain large-scale use.

87.0%
Compared to traditional Pi-hole or self-hosted recursive DNS, what are the key differences in suitable scenarios and limitations? When should you prefer this project or revert to traditional solutions?

Core Analysis

Role Comparison: serverless-dns is an edge/stub Pi-hole-like implementation focusing on low-ops encrypted DNS and content blocking. Traditional Pi-hole/self-hosted recursive DNS runs on a persistent host and offers full recursive capabilities and local integration.

Key Differences

  • Operational Model: serverless-dns runs serverless (no hardware maintenance); Pi-hole requires a host/device to run continuously.
  • Resolver Role: serverless-dns is a forwarding/stub resolver relying on upstream DoH; Pi-hole can be a local recursive/cache and integrate with LAN services.
  • Scalability & Limits: edge deployment gives broad node coverage and lower latency but is constrained by serverless execution/quota and persistence limits; Pi-hole supports larger local caches and complex policies.

When to Prefer serverless-dns

  1. You want minimal ops and no persistent hardware while getting encrypted DoH/DoT endpoints.
  2. Your devices are geographically distributed and benefit from edge node proximity.
  3. Traffic is small-scale (personal/small team) and fits free/low-cost tiers.

When to Use Pi-hole / Recursive DNS

  • Need local DHCP/DNS integration, complex custom resolution, or large persistent caches.
  • Require high throughput, enterprise-level SLAs, or on-premises independence.

Important Notice: The approaches aren’t mutually exclusive—use serverless-dns as an edge filtering/encryption layer while keeping Pi-hole/local resolvers for LAN-level needs.

Summary: Choose serverless-dns for low-ops, distributed encrypted DNS; choose Pi-hole or recursive servers for heavy-duty, local, or enterprise-grade DNS needs.

87.0%
What is the deployment and onboarding user experience? What common pitfalls exist and what best practices reduce failure risk?

Core Analysis

Onboarding Experience: The project supplies run scripts and config templates for multiple platforms. Cloudflare Workers offers the smoothest onboarding; Deno, Fastly, and Fly require stronger DevOps knowledge (env vars, TLS, Logpush).

Technical Analysis (Data-backed)

  • Automation: ./run w|n|d|f scripts and wrangler.toml/fastly.toml templates reduce initial manual steps.
  • Key Pitfalls: DoT SNI hostname length limits affect where to place auth keys; runtime network API and quota differences cause behavior variance; logging might need extra work on Fly/Deno.

Practical Recommendations

  1. Validate on Workers: Start with Cloudflare Workers to validate blocklist and basic flow.
  2. Migrate Gradually: After validation, migrate to target runtimes and test network calls, certs, and timeouts.
  3. Enable Logs Early: Configure Logpush -> R2 (or equivalent) immediately for troubleshooting data.
  4. DoT Auth: Ensure msg-key and hostname lengths conform to SNI constraints when using DoT.

Caveats

  • Execution & Quota Limits: Free tiers are cited for ~10–20 devices/month; scale beyond requires cost assessment.
  • TLS & Domain Management: Misconfigured TLS or DNS will break DoH/DoT endpoints.

Important Notice: Staged deployment (Workers validation → logs → migration) reduces failure risk significantly.

Summary: Scripts and docs lower initial barrier; production stability requires medium-level operations skills and platform-aware configuration.

86.0%
How to ensure observability and log auditing for serverless-dns? What are recommended logging and analytics practices in a stateless edge environment?

Core Analysis

Observability Challenge: Stateless edge instances are not suitable for long-term storage of detailed logs, and platform logging support varies (README notes Fly/Deno may lack native log collection), so audit/analytics must be centralized.

Technical Analysis

  • Built-in Capabilities: The project includes an analytics API and logging options and recommends Cloudflare Logpush -> R2 for native integration.
  • Edge Constraints: Persisting every request locally increases latency and cost; external storage is needed for durable auditing.

Practical Recommendations

  1. Asynchronous Batch Export: Perform lightweight sampling/aggregation at edge (by domain/response type) and asynchronously upload batches to R2 or another object store.
  2. Use Logpush: Prefer Cloudflare Logpush -> R2 when on Workers for stable, low-ops collection.
  3. Platform Adapters: Build custom exporters for Fly/Deno if native logpush is absent, or use a small proxy for log shipping.
  4. Analytics Pipeline: After export, run batch/stream ETL to compute cache hit rates, false-positive metrics, and top queries.

Caveats

  • DNS logs are sensitive—consider anonymization or encrypted storage before export.
  • Sampling rate must balance observability with cost: too low loses fidelity; too high is expensive.

Important Notice: Don’t attempt per-request persistent logging at edge; use sampling, aggregation, async batch export, and centralized storage for efficient and compliant auditing.

Summary: Centralize logs (Logpush -> R2 or equivalent) and do sampling/aggregation at the edge to achieve scalable observability in a stateless environment.

86.0%
How does the project's authentication work? What special constraints and configuration points apply when using DoT?

Core Analysis

Auth Core: serverless-dns uses an HMAC-based lightweight access key mechanism: the server stores HMAC outputs in ACCESS_KEYS, and clients generate a token using msg-key and the fixed message sdns-public-auth-info, placing it in requests (DoH blockstamp or DoT hostname).

Technical Analysis

  • Flow: hex(hmac-sha256(msg-key|domain.tld), msg) is appended to ACCESS_KEYS for server-side verification.
  • DoT Constraint: DoT commonly uses SNI or hostname embedding for auth; SNI/hostname length limits (protocol/implementation) can truncate long tokens or cause connection failures.

Practical Recommendations

  1. Prefer DoH for Auth: Use DoH with blockstamp tokens to avoid SNI length issues when possible.
  2. Shorten msg-key: Use shorter msg-key or token encodings for DoT to fit hostname limits.
  3. Alternative Auth: For stronger auth, use TLS client certificates or an API gateway-level auth on the edge.

Caveats

  • Hostname length limits vary by runtime—test DoT connectivity on your target platform.
  • msg is fixed as sdns-public-auth-info per README; changing it requires adjusting server-side ACCESS_KEYS generation.

Important Notice: Embedding long HMAC tokens in DoT hostnames is risky—prefer shorter tokens or switch to DoH/certificate-based auth.

Summary: HMAC works well for DoH but requires careful handling for DoT due to SNI length constraints; plan accordingly.

84.0%

✨ Highlights

  • Native deployment across Cloudflare, Deno, Fastly and Fly.io
  • Low latency: end-to-end median ~10–30 ms
  • Documentation exists but community/activity metrics are inconsistent
  • Repository license is unspecified — potential legal/compliance risk

🔧 Engineering

  • Feature: Serverless DoH/DoT resolver with content-blocking
  • Technical: Edge-first design, runs across multiple FaaS providers

⚠️ Risks

  • Maintenance and contributor data are unclear; community activity unknown
  • No declared license or releases — exercise caution for commercial/production use

👥 For who?

  • Target users: individuals or ops teams familiar with DNS and edge deployment
  • Use cases: self-hosted privacy DNS and small-scale edge resolver deployments