https://github.com/serverless-dns/serverless-dns Skip to content Sign up * Product + Features + Mobile + Actions + Codespaces + Copilot + Packages + Security + Code review + Issues + Discussions + Integrations + GitHub Sponsors + Customer stories * Team * Enterprise * Explore + Explore GitHub + Learn and contribute + Topics + Collections + Trending + Skills + GitHub Sponsors + Open source guides + Connect with others + The ReadME Project + Events + Community forum + GitHub Education + GitHub Stars program * Marketplace * Pricing + Plans + Compare plans + Contact Sales + Education [ ] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this organization All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up {{ message }} serverless-dns / serverless-dns Public * * Notifications * Fork 223 * Star 502 The RethinkDNS resolver that deploys to Cloudflare Workers, Deno Deploy, and Fly.io rethinkdns.com/configure License MPL-2.0 license 502 stars 223 forks Star Notifications * Code * Issues 16 * Pull requests 0 * Discussions * Actions * Projects 0 * Wiki * Security * Insights More * Code * Issues * Pull requests * Discussions * Actions * Projects * Wiki * Security * Insights serverless-dns/serverless-dns This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. main Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags 2 branches 11 tags Code Latest commit @georgyo @ignoramous georgyo and ignoramous run: cleanup background jobs on exit ... d736751 Jul 30, 2022 run: cleanup background jobs on exit d736751 Git stats * 602 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time .github Create FUNDING.yml Jul 25, 2022 .husky chore(git): pre-commit hook to lint & fmt Dec 29, 2021 .vscode chore: VSCode extension recommendations; update ignore files. Jan 25, 2022 src cc: support for search cmd Jul 15, 2022 test test(manual): proxy-proto-server Dec 17, 2021 .dockerignore chore: VSCode extension recommendations; update ignore files. Jan 25, 2022 .env.example rm redundant terminate_tls env var Jan 24, 2022 .eslintrc.cjs Event bus to streamline process up (#43) Jan 1, 2022 .gitignore chore: Add .vscode config Jan 9, 2022 .prettierignore chore: VSCode extension recommendations; update ignore files. Jan 25, 2022 .prettierrc.json style: eslint & m. fmt Dec 28, 2021 LICENSE Initial commit Mar 10, 2021 README.md tls-offload to Fly.io edge for DoH and DoT Apr 27, 2022 deno.Dockerfile chore: update deno@1.20.1 Mar 26, 2022 fly.tls.toml blocklist update Jul 27, 2022 fly.toml blocklist update Jul 27, 2022 import_map.json radix-trie-cache: faster find(q, cursor) instead of get(q) Mar 2, 2022 node.Dockerfile Event bus to streamline process up (#43) Jan 1, 2022 package.json node: httpx-server for h2c + h1x on the same port Apr 28, 2022 run run: cleanup background jobs on exit Jul 30, 2022 webpack.config.cjs Fix the broken queueMicrotask polyfill Feb 1, 2022 wrangler.toml blocklist update Jul 27, 2022 View code [ ] It's a bird, it's a plane, it's... a self-hosted, pi-hole esque, DNS resolver The RethinkDNS resolver Self-host Development Setup Code style Env vars Request flow A note about runtimes Cloud Blocklists README.md It's a bird, it's a plane, it's... a self-hosted, pi-hole esque, DNS resolver serverless-dns is a Pi-Hole esque content-blocking, serverless, stub DNS-over-HTTPS (DoH) and DNS-over-TLS (DoT) resolver. Runs out-of-the-box on Cloudflare Workers, Deno Deploy, and Fly.io. Free tiers of all these services should be enough to cover 10 to 20 devices worth of DNS traffic per month. The RethinkDNS resolver RethinkDNS runs serverless-dns in production at these endpoints: Cloud platform Server Protocol Domain Usage locations [?] Cloudflare 200+ (ping) DoH basic.rethinkdns.com configure Workers Deno Deploy 30+ (ping) DoH private beta Fly.io 30+ (ping) DoH and max.rethinkdns.com configure DoT Server-side processing takes from 0 milliseconds (ms) to 2ms (median), and end-to-end latency (varies across regions and networks) is between 10ms to 30ms (median). Self-host Cloudflare Workers is the easiest platform to setup serverless-dns: Deploy to Cloudflare Workers For step-by-step instructions, refer: Platform Difficulty Runtime Doc [?] Cloudflare Easy v8 Isolates Hosting on Cloudflare Workers Deno.com Moderate Deno Isolates Hosting on Deno.com Fly.io Hard Node MicroVM Hosting on Fly.io To setup blocklists, visit https://.tld/configure from your browser (it should load something similar to RethinkDNS' configure page). For help or assistance, feel free to open an issue or submit a patch. --------------------------------------------------------------------- Development Setup Code: # navigate to work dir cd /my/work/dir # clone this repository git clone https://github.com/serverless-dns/serverless-dns.git # navigate to serverless-dns cd ./serverless-dns Node: # install node v16+ via nvm, if required # https://github.com/nvm-sh/nvm#installing-and-updating wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash nvm install --lts # get js dependencies npm i # (optional) update dependencies npm update # run serverless-dns on node ./run n # run a clinicjs.org profiler ./run n [cpu|fn|mem] Deno: # install deno.land v1.18+ # https://github.com/denoland/deno/#install curl -fsSL https://deno.land/install.sh | sh # run serverless-dns on deno ./run d Wrangler: # install Cloudflare Workers (cli) aka Wrangler # https://developers.cloudflare.com/workers/cli-wrangler/install-update npm i @cloudflare/wrangler -g # run serverless-dns on Cloudflare Workers (cli) # Make sure to setup Wrangler first: # https://developers.cloudflare.com/workers/cli-wrangler/authentication ./run w # profile wrangler with Chrome DevTools # blog.cloudflare.com/profiling-your-workers-with-wrangler Code style Commits on this repository enforces the Google JavaScript style guide (ref: .eslintrc.cjs). A git pre-commit hook that runs linter (eslint) and formatter (prettier) on .js files. Use git commit --no-verify to bypass this hook. Pull requests are also checked for code style violations and fixed automatically where possible. Env vars Configure .env (ref) or env.js if you need to tweak the defaults. Values in .env file take precedence over corresponding variables set in env.js. For Cloudflare Workers setup env vars in wrangler.toml, instead. Request flow 1. The request/response flow: client <-> src/server-[node|workers| deno] <-> doh.js <-> plugin.js 2. The plugin.js flow: userOperation.js -> cacheResponse.js -> cc.js -> dnsResolver.js --------------------------------------------------------------------- A note about runtimes Deno Deploy (cloud) and Deno (the runtime) do not expose the same API surface (for example, Deno Deploy only supports HTTP/S server-listeners; whereas, Deno suports raw TCP/UDP/TLS in addition to plain HTTP and HTTP/S). Except on Node, serverless-dns uses DoH upstreams defined by env vars, CF_DNS_RESOLVER_URL / CF_DNS_RESOLVER_URL_2. On Node, the default DNS upstream is 1.1.1.2 (ref). The entrypoint for Node and Deno are src/server-node.js, src/ server-deno.ts respectively, and both listen for TCP-over-TLS, HTTP/S connections; whereas, the entrypoint for Cloudflare Workers, which only listens over HTTP (cli) or over HTTP/S (prod), is src/ server-workers.js. For prod setups on Deno and local (non-prod) setups on Node, the key (private) and cert (public chain) files, by default, are read from paths defined in env vars, TLS_KEY_PATH and TLS_CRT_PATH. Whilst for prod setup on Node (on Fly.io), either TLS_OFFLOAD must be set to true or key and cert must be base64 encoded in env var TLS_CERTKEY (ref), like so: # EITHER: offload tls to fly.io and set tls_offload to true TLS_OFFLOAD="true" # OR: base64 representation of both key (private) and cert (public chain) TLS_CERTKEY="KEY=b64_key_content\nCRT=b64_cert_content" Process bringup is different for each of these runtimes: For Node, src/core/node/config.js governs the bringup; while for Deno, it is src/core/deno/config.ts and for Workers it is src/core/workers/ config.js. src/system.js pub-sub co-ordinates the bringup phase among various modules. On Node and Deno, in-process DNS caching, backed by @serverless-dns/ lfu-cache is used; on Cloudflare Workers, both, Cache Web API and in-process caches are used. To disable caching altogether on all three platfroms, set env var, PROFILE_DNS_RESOLVES=true. Cloud Cloudflare Workers and Deno Deploy are ephemeral, as in, the process that serves client request is not long-lived, and in fact, two back-to-back requests may be served by two different isolates (processes). Resolver on Fly.io, running Node, is backed by persistent VMs and is hence longer-lived, like traditional "serverfull" environments. Cloudflare Workers build-time and runtime configurations are defined in wrangler.toml. Webpack5 bundles the files in an ESM module which is then uploaded to Cloudflare by Wrangler. For Deno Deploy, the code-base is bundled up in a single javascript file with deno bundle and then handed off to Deno.com. For Fly.io, which runs Node, the runtime directives are defined in fly.toml (used by dev and live deployment-types), while deploy directives are in node.Dockerfile. flyctl accordingly sets up serverless-dns on Fly.io's infrastructure. For deploys offloading TLS termination to Fly.io (B1 deployment-type), the runtime directives are instead defined in fly.tls.toml, which sets up HTTP2 Cleartext and HTTP/1.1 on port 443, and DNS over TCP on port 853. Ref: github/workflows. Blocklists 190+ blocklists are compressed in a Succinct Radix Trie (based on Steve Hanov's impl) with modifications to speed up string search ( lookup) at the expense of "succintness". The blocklists are versioned with unix timestamp (env var: CF_LATEST_BLOCKLIST_TIMESTAMP), and generated once every week, but we'd like to generate 'em daily / hourly, if possible see), and hosted on Lightsail Object Store (env var: CF_BLOCKLIST_URL). serverless-dns downloads 3 blocklist files required to setup the radix trie during runtime bringup or, lazily, when serving a DNS request. serverless-dns compiles around ~5M entries (as of Feb 2022) in to a succinct radix trie, from around 190+ blocklists. These are defined in serverless-dns/blocklists repository. About The RethinkDNS resolver that deploys to Cloudflare Workers, Deno Deploy, and Fly.io rethinkdns.com/configure Topics nodejs serverless workers adblock dns-over-https doh pihole dns-over-tls deno cloudflare-workers Resources Readme License MPL-2.0 license Stars 502 stars Watchers 6 watching Forks 223 forks Releases 11 tags Sponsor this project * * https://svc.rethinkdns.com/r/sponsor Learn more about GitHub Sponsors Packages 0 No packages published Contributors 8 * @ignoramous * @amithm7 * @santhosh-ponnusamy * @georgyo * @PeterDaveHello * @neneeen * @harish83a * @shruuub Languages * JavaScript 91.2% * TypeScript 5.0% * Shell 3.2% * Dockerfile 0.6% Footer (c) 2022 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.