diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..721082e
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,7 @@
+.pre-commit-config.yaml linguist-generated
+.github/workflows/build.yml linguist-generated
+.github/workflows/check-pre-commit-hooks.yml linguist-generated
+.github/workflows/tests.yml linguist-generated
+.gitattributes linguist-generated
+treefmt.toml linguist-generated
+rustfmt.toml linguist-generated
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
new file mode 100644
index 0000000..4bda464
--- /dev/null
+++ b/.github/workflows/build.yml
@@ -0,0 +1,128 @@
+# This file is automatically generated from Nix configuration. Do not edit directly.
+
+concurrency:
+ cancel-in-progress: true
+ group: ${{ github.workflow }}-${{ github.ref }}
+jobs:
+ build:
+ runs-on: ${{ matrix.runner }}
+ steps:
+ - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10
+ - uses: cachix/install-nix-action@8aa03977d8d733052d78f4e008a241fd1dbf36b3
+ - name: Build static binary
+ run: |
+ nix build .#dows --print-build-logs -o result-dows
+ - name: Build Docker image
+ run: nix build .#docker-image --print-build-logs
+ - name: Upload static binary as artifact
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+ with:
+ if-no-files-found: error
+ name: dows-linux-${{ matrix.arch }}
+ path: result-dows/bin/dows
+ - name: Upload Docker image as artifact
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+ with:
+ if-no-files-found: error
+ name: docker-image-${{ matrix.arch }}
+ path: result
+ strategy:
+ matrix:
+ include:
+ - arch: x86_64
+ runner: ubuntu-26.04
+ - arch: aarch64
+ runner: ubuntu-26.04-arm
+ docker:
+ if: github.event_name == 'push' || github.event_name == 'pull_request'
+ needs:
+ - build
+ runs-on: ubuntu-26.04-arm
+ steps:
+ - name: Download Docker images
+ uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c
+ with:
+ path: artifacts
+ pattern: docker-image-*
+ - env:
+ REGISTRY_PASSWORD: ${{ secrets.registry_password || secrets.GITHUB_TOKEN }}
+ REGISTRY_USER: ${{ vars.REGISTRY_USER }}
+ TAG: ${{ github.head_ref || github.ref_name || 'latest' }}
+ name: Push multi-arch Docker manifest to registry
+ run: |
+ if [[ "$GITHUB_REF_NAME" =~ v[0-9]+\.[0-9]+\.[0-9]+ ]]; then
+ registry=registry.famedly.net/docker-oss
+ else
+ registry=registry.famedly.net/docker-nightly
+ fi
+
+ echo "$REGISTRY_PASSWORD" \
+ | podman login registry.famedly.net -u "$REGISTRY_USER" --password-stdin
+
+ image="$registry/dows"
+ # Branch names may contain slashes, which are not valid in
+ # Docker tags.
+ tag="${TAG//\//-}"
+
+ # Combine the per-arch images into a multi-arch manifest.
+ # Every `podman load` overwrites `dows:latest`, so retag
+ # each image with an arch suffix before loading the next.
+ podman manifest create dows-multiarch
+ for arch in x86_64 aarch64; do
+ podman load < "artifacts/docker-image-$arch/result"
+ podman tag dows:latest "dows:$arch"
+ podman manifest add dows-multiarch "containers-storage:localhost/dows:$arch"
+ done
+
+ # `--all` pushes the per-arch images along with the
+ # manifest (by digest only, so no arch-specific tags show
+ # up in the registry). Publish under both the branch/tag
+ # name and the commit SHA.
+ podman manifest push --all dows-multiarch "docker://$image:$tag"
+ podman manifest push --all dows-multiarch "docker://$image:$GITHUB_SHA"
+ release:
+ if: startsWith(github.ref, 'refs/tags/')
+ needs:
+ - build
+ runs-on: ubuntu-latest
+ steps:
+ - name: Download static binaries
+ uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c
+ with:
+ path: artifacts
+ pattern: dows-linux-*
+ - env:
+ GH_REPO: ${{ github.repository }}
+ GH_TOKEN: ${{ github.token }}
+ name: Create GitHub release
+ run: |
+ tag="${GITHUB_REF#refs/tags/}"
+
+ # The file inside each artifact is just called `dows`;
+ # rename it to the artifact's arch-suffixed name for the
+ # release assets.
+ for dir in artifacts/dows-linux-*; do
+ install -m755 "$dir/dows" "$(basename "$dir")"
+ done
+
+ gh release create "$tag" \
+ --verify-tag \
+ dows-linux-*
+name: Build
+"on":
+ merge_group: {}
+ pull_request:
+ branches:
+ - '**'
+ types:
+ - opened
+ - reopened
+ - synchronize
+ - ready_for_review
+ push:
+ branches:
+ - main
+ tags:
+ - v*
+permissions:
+ contents: write
diff --git a/.github/workflows/check-pre-commit-hooks.yml b/.github/workflows/check-pre-commit-hooks.yml
new file mode 100644
index 0000000..6d5141f
--- /dev/null
+++ b/.github/workflows/check-pre-commit-hooks.yml
@@ -0,0 +1,27 @@
+# This file is automatically generated from Nix configuration. Do not edit directly.
+
+concurrency:
+ cancel-in-progress: true
+ group: ${{ github.workflow }}-${{ github.ref }}
+jobs:
+ prek:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10
+ - uses: cachix/install-nix-action@8aa03977d8d733052d78f4e008a241fd1dbf36b3
+ - env:
+ TREEFMT_NO_CACHE: "1"
+ name: Run pre-commit hooks
+ run: prek --all-files --show-diff-on-failure
+ shell: nix develop .#standards --command bash {0}
+name: Make sure all pre-commit hooks pass
+"on":
+ merge_group: {}
+ pull_request:
+ branches:
+ - '**'
+ types:
+ - opened
+ - reopened
+ - synchronize
+ - ready_for_review
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
new file mode 100644
index 0000000..c4d1951
--- /dev/null
+++ b/.github/workflows/tests.yml
@@ -0,0 +1,25 @@
+# This file is automatically generated from Nix configuration. Do not edit directly.
+
+concurrency:
+ cancel-in-progress: true
+ group: ${{ github.workflow }}-${{ github.ref }}
+jobs:
+ nextest:
+ runs-on: ubuntu-26.04-arm
+ steps:
+ - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10
+ - uses: cachix/install-nix-action@8aa03977d8d733052d78f4e008a241fd1dbf36b3
+ - name: Run tests
+ run: cargo nextest run --all-targets --all-features
+ shell: nix develop .#rust --command bash {0}
+name: Run tests
+"on":
+ merge_group: {}
+ pull_request:
+ branches:
+ - '**'
+ types:
+ - opened
+ - reopened
+ - synchronize
+ - ready_for_review
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..5792167
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+/target/
+result
+result-*
+.devenv/
+.direnv/
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 0000000..5200449
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,66 @@
+repos:
+- hooks:
+ - id: check-added-large-files
+ - id: check-case-conflict
+ - id: check-illegal-windows-names
+ - id: end-of-file-fixer
+ - id: fix-byte-order-marker
+ - id: check-json
+ - id: check-json5
+ - id: check-toml
+ - id: check-vcs-permalinks
+ - id: check-xml
+ - args:
+ - --fix=lf
+ id: mixed-line-ending
+ - id: check-symlinks
+ - id: destroyed-symlinks
+ - id: check-merge-conflict
+ - id: detect-private-key
+ - id: check-shebang-scripts-are-executable
+ - id: check-executables-have-shebangs
+ repo: builtin
+- hooks:
+ - args:
+ - --write-changes
+ - --force-exclude
+ description: Check the repository for spelling mistakes
+ entry: typos
+ id: typos
+ language: system
+ name: typos
+ types:
+ - text
+ - description: Ensure that files set up with the filegen module are up-to-date
+ entry: filegen-apply-script
+ id: filegen
+ language: system
+ name: filegen
+ pass_filenames: false
+ - description: Format *all* files
+ entry: treefmt
+ id: treefmt
+ language: system
+ name: treefmt
+ require_serial: true
+ repo: local
+- hooks:
+ - args:
+ - follow
+ description: Ensure that flake inputs are recursively de-duplicated
+ entry: flake-edit
+ files:
+ glob: '{flake.nix,flake.lock}'
+ id: flake-follows
+ language: system
+ name: flake-follows
+ pass_filenames: false
+ repo: local
+- hooks:
+ - description: Check licensing info for REUSE compliance
+ entry: reuse lint
+ id: reuse
+ language: system
+ name: reuse
+ pass_filenames: false
+ repo: local
diff --git a/Cargo.lock b/Cargo.lock
new file mode 100644
index 0000000..7142048
--- /dev/null
+++ b/Cargo.lock
@@ -0,0 +1,583 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "anyhow"
+version = "1.0.104"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
+
+[[package]]
+name = "base64ct"
+version = "1.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
+[[package]]
+name = "block-buffer"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d2f6c7dbe95a6ed67ad9f18e57daf93a2f034c524b99fd2b76d18fdfeb6660aa"
+dependencies = [
+ "hybrid-array",
+]
+
+[[package]]
+name = "bytes"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "cfg_aliases"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
+
+[[package]]
+name = "const-oid"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6ef517f0926dd24a1582492c791b6a4818a4d94e789a334894aa15b0d12f55c"
+
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "cpufeatures"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
+[[package]]
+name = "crypto-common"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453"
+dependencies = [
+ "hybrid-array",
+]
+
+[[package]]
+name = "data-encoding"
+version = "2.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4ae5f15dda3c708c0ade84bfee31ccab44a3da4f88015ed22f63732abe300c8"
+
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer 0.10.4",
+ "crypto-common 0.1.7",
+]
+
+[[package]]
+name = "digest"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2"
+dependencies = [
+ "block-buffer 0.12.1",
+ "const-oid",
+ "crypto-common 0.2.2",
+]
+
+[[package]]
+name = "dows"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "base64ct",
+ "futures-util",
+ "httparse",
+ "nix",
+ "percent-encoding",
+ "sha1 0.11.0",
+ "tokio",
+ "tokio-tungstenite",
+]
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
+
+[[package]]
+name = "futures-core"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7"
+
+[[package]]
+name = "futures-macro"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d6d3cde68c518367be28956066ddfef33813991b77a55005a69dae04bf3b10b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "futures-sink"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e34418ac499d6305c2fb5ad0ed2f6ac998c5f8ca209b4510f7f94242c647e307"
+
+[[package]]
+name = "futures-task"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109"
+
+[[package]]
+name = "futures-util"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa"
+dependencies = [
+ "futures-core",
+ "futures-macro",
+ "futures-sink",
+ "futures-task",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi",
+ "wasip2",
+]
+
+[[package]]
+name = "http"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6970f50e31d6fc17d3fa27329444bfa74e196cf62e95052a3f6fee181dba6425"
+dependencies = [
+ "bytes",
+ "itoa",
+]
+
+[[package]]
+name = "httparse"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
+
+[[package]]
+name = "hybrid-array"
+version = "0.4.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "818356c5132c1fede50f837ca96afbe78ff42413047f4abb886217845e1b6c8c"
+dependencies = [
+ "typenum",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "log"
+version = "0.4.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
+
+[[package]]
+name = "mio"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "30d65c71f1ce40ab09135ce117d742b9f8a19ff91a41a8b57ed50bc2de59c427"
+dependencies = [
+ "libc",
+ "wasi",
+ "windows-sys",
+]
+
+[[package]]
+name = "nix"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "74523f3a35e05aba87a1d978330aef40f67b0304ac79c1c00b294c9830543db6"
+dependencies = [
+ "bitflags",
+ "cfg-if",
+ "cfg_aliases",
+ "libc",
+]
+
+[[package]]
+name = "percent-encoding"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
+[[package]]
+name = "rand"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41"
+dependencies = [
+ "rand_chacha",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
+dependencies = [
+ "ppv-lite86",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
+dependencies = [
+ "getrandom",
+]
+
+[[package]]
+name = "sha1"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a978451301f4db1d02937a4ab3ccce137717b81826e79b7d49ffe3244a13c3b8"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "digest 0.10.7",
+]
+
+[[package]]
+name = "sha1"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aacc4cc499359472b4abe1bf11d0b12e688af9a805fa5e3016f9a386dc2d0214"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.3.0",
+ "digest 0.11.3",
+]
+
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
+dependencies = [
+ "errno",
+ "libc",
+]
+
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
+[[package]]
+name = "socket2"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09a43598840e33d5b0331f38c5e30d13bb11c11210a4b58f0d9b18a5a5eefcd9"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43cbfe0cf76104d42a574802844187e84a305e531ed54455f11fbde0f10541cd"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "tokio"
+version = "1.53.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d988bcd52dbe076d3d46903332f58c912b87a2c49b1428419a5845154762ffee"
+dependencies = [
+ "bytes",
+ "libc",
+ "mio",
+ "pin-project-lite",
+ "signal-hook-registry",
+ "socket2",
+ "tokio-macros",
+ "windows-sys",
+]
+
+[[package]]
+name = "tokio-macros"
+version = "2.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6328af13490e73a9b4694030fafd93f8c8c6a9dede33e821c3fc63eddf8042ba"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "tokio-tungstenite"
+version = "0.26.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7a9daff607c6d2bf6c16fd681ccb7eecc83e4e2cdc1ca067ffaadfca5de7f084"
+dependencies = [
+ "futures-util",
+ "log",
+ "tokio",
+ "tungstenite",
+]
+
+[[package]]
+name = "tungstenite"
+version = "0.26.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4793cb5e56680ecbb1d843515b23b6de9a75eb04b66643e256a396d43be33c13"
+dependencies = [
+ "bytes",
+ "data-encoding",
+ "http",
+ "httparse",
+ "log",
+ "rand",
+ "sha1 0.10.7",
+ "thiserror",
+ "utf-8",
+]
+
+[[package]]
+name = "typenum"
+version = "1.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "utf-8"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "wasip2"
+version = "1.0.4+wasi-0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
+dependencies = [
+ "wit-bindgen",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
+[[package]]
+name = "zerocopy"
+version = "0.8.55"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b5a105cd7b140f6eeec8acff2ea38135d3cab283ada58540f629fe51e46696eb"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.55"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fe976fb70c78cd64cccfe3a6fc142244e8a77b70959b30faf9d0ac37ee228eb"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
diff --git a/Cargo.toml b/Cargo.toml
new file mode 100644
index 0000000..d4471b2
--- /dev/null
+++ b/Cargo.toml
@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: 2026 Famedly GmbH (info@famedly.com)
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+[package]
+name = "dows"
+version = "0.1.0"
+edition = "2024"
+license = "AGPL-3.0-or-later"
+repository = "https://github.com/famedly/dows"
+
+[dependencies]
+anyhow = "1.0.104"
+base64ct = { version = "1.8.0", features = ["alloc"] }
+httparse = "1.10.1"
+percent-encoding = "2.3.2"
+sha1 = "0.11.0"
+tokio = { version = "1.53.0", features = ["rt-multi-thread", "macros", "net", "io-util", "sync", "signal"] }
+
+[dev-dependencies]
+futures-util = "0.3"
+nix = { version = "0.30", features = ["signal"] }
+tokio-tungstenite = "0.26"
diff --git a/LICENSES/AGPL-3.0-or-later.txt b/LICENSES/AGPL-3.0-or-later.txt
new file mode 100644
index 0000000..be3f7b2
--- /dev/null
+++ b/LICENSES/AGPL-3.0-or-later.txt
@@ -0,0 +1,661 @@
+ GNU AFFERO GENERAL PUBLIC LICENSE
+ Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc.
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ Preamble
+
+ The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+ The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works. By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+ When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+ Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+ A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate. Many developers of free software are heartened and
+encouraged by the resulting cooperation. However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+ The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community. It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server. Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+ An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals. This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+ TERMS AND CONDITIONS
+
+ 0. Definitions.
+
+ "This License" refers to version 3 of the GNU Affero General Public License.
+
+ "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+ "The Program" refers to any copyrightable work licensed under this
+License. Each licensee is addressed as "you". "Licensees" and
+"recipients" may be individuals or organizations.
+
+ To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy. The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+ A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+ To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy. Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+ To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies. Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+ An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License. If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+ 1. Source Code.
+
+ The "source code" for a work means the preferred form of the work
+for making modifications to it. "Object code" means any non-source
+form of a work.
+
+ A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+ The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form. A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+ The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities. However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work. For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+ The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+ The Corresponding Source for a work in source code form is that
+same work.
+
+ 2. Basic Permissions.
+
+ All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met. This License explicitly affirms your unlimited
+permission to run the unmodified Program. The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work. This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+ You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force. You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright. Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+ Conveying under any other circumstances is permitted solely under
+the conditions stated below. Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+ 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+ No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+ When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+ 4. Conveying Verbatim Copies.
+
+ You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+ You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+ 5. Conveying Modified Source Versions.
+
+ You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+ a) The work must carry prominent notices stating that you modified
+ it, and giving a relevant date.
+
+ b) The work must carry prominent notices stating that it is
+ released under this License and any conditions added under section
+ 7. This requirement modifies the requirement in section 4 to
+ "keep intact all notices".
+
+ c) You must license the entire work, as a whole, under this
+ License to anyone who comes into possession of a copy. This
+ License will therefore apply, along with any applicable section 7
+ additional terms, to the whole of the work, and all its parts,
+ regardless of how they are packaged. This License gives no
+ permission to license the work in any other way, but it does not
+ invalidate such permission if you have separately received it.
+
+ d) If the work has interactive user interfaces, each must display
+ Appropriate Legal Notices; however, if the Program has interactive
+ interfaces that do not display Appropriate Legal Notices, your
+ work need not make them do so.
+
+ A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit. Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+ 6. Conveying Non-Source Forms.
+
+ You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+ a) Convey the object code in, or embodied in, a physical product
+ (including a physical distribution medium), accompanied by the
+ Corresponding Source fixed on a durable physical medium
+ customarily used for software interchange.
+
+ b) Convey the object code in, or embodied in, a physical product
+ (including a physical distribution medium), accompanied by a
+ written offer, valid for at least three years and valid for as
+ long as you offer spare parts or customer support for that product
+ model, to give anyone who possesses the object code either (1) a
+ copy of the Corresponding Source for all the software in the
+ product that is covered by this License, on a durable physical
+ medium customarily used for software interchange, for a price no
+ more than your reasonable cost of physically performing this
+ conveying of source, or (2) access to copy the
+ Corresponding Source from a network server at no charge.
+
+ c) Convey individual copies of the object code with a copy of the
+ written offer to provide the Corresponding Source. This
+ alternative is allowed only occasionally and noncommercially, and
+ only if you received the object code with such an offer, in accord
+ with subsection 6b.
+
+ d) Convey the object code by offering access from a designated
+ place (gratis or for a charge), and offer equivalent access to the
+ Corresponding Source in the same way through the same place at no
+ further charge. You need not require recipients to copy the
+ Corresponding Source along with the object code. If the place to
+ copy the object code is a network server, the Corresponding Source
+ may be on a different server (operated by you or a third party)
+ that supports equivalent copying facilities, provided you maintain
+ clear directions next to the object code saying where to find the
+ Corresponding Source. Regardless of what server hosts the
+ Corresponding Source, you remain obligated to ensure that it is
+ available for as long as needed to satisfy these requirements.
+
+ e) Convey the object code using peer-to-peer transmission, provided
+ you inform other peers where the object code and Corresponding
+ Source of the work are being offered to the general public at no
+ charge under subsection 6d.
+
+ A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+ A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling. In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage. For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product. A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+ "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source. The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+ If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information. But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+ The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed. Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+ Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+ 7. Additional Terms.
+
+ "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law. If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+ When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it. (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.) You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+ Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+ a) Disclaiming warranty or limiting liability differently from the
+ terms of sections 15 and 16 of this License; or
+
+ b) Requiring preservation of specified reasonable legal notices or
+ author attributions in that material or in the Appropriate Legal
+ Notices displayed by works containing it; or
+
+ c) Prohibiting misrepresentation of the origin of that material, or
+ requiring that modified versions of such material be marked in
+ reasonable ways as different from the original version; or
+
+ d) Limiting the use for publicity purposes of names of licensors or
+ authors of the material; or
+
+ e) Declining to grant rights under trademark law for use of some
+ trade names, trademarks, or service marks; or
+
+ f) Requiring indemnification of licensors and authors of that
+ material by anyone who conveys the material (or modified versions of
+ it) with contractual assumptions of liability to the recipient, for
+ any liability that these contractual assumptions directly impose on
+ those licensors and authors.
+
+ All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10. If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term. If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+ If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+ Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+ 8. Termination.
+
+ You may not propagate or modify a covered work except as expressly
+provided under this License. Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+ However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+ Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+ Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+ 9. Acceptance Not Required for Having Copies.
+
+ You are not required to accept this License in order to receive or
+run a copy of the Program. Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance. However,
+nothing other than this License grants you permission to propagate or
+modify any covered work. These actions infringe copyright if you do
+not accept this License. Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+ 10. Automatic Licensing of Downstream Recipients.
+
+ Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License. You are not responsible
+for enforcing compliance by third parties with this License.
+
+ An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations. If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+ You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License. For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+ 11. Patents.
+
+ A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based. The
+work thus licensed is called the contributor's "contributor version".
+
+ A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version. For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+ Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+ In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement). To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+ If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients. "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+ If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+ A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License. You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+ Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+ 12. No Surrender of Others' Freedom.
+
+ If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all. For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+ 13. Remote Network Interaction; Use with the GNU General Public License.
+
+ Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software. This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+ Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work. The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+ 14. Revised Versions of this License.
+
+ The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time. Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+ Each version is given a distinguishing version number. If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation. If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+ If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+ Later license versions may give you additional or different
+permissions. However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+ 15. Disclaimer of Warranty.
+
+ THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+ 16. Limitation of Liability.
+
+ IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+ 17. Interpretation of Sections 15 and 16.
+
+ If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+ END OF TERMS AND CONDITIONS
+
+ How to Apply These Terms to Your New Programs
+
+ If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+
+ Copyright (C)
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program. If not, see .
+
+Also add information on how to contact you by electronic and paper mail.
+
+ If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source. For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code. There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+ You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+.
diff --git a/README.md b/README.md
index 39718e0..cc6cb18 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,26 @@
+
+
# dows (DNS over WebSocket proxy)
+
+dows accepts DNS over WebSocket connections and proxies them to DNS servers over
+TCP.
+
+## Protocol
+
+DNS over WebSocket is a transport for DNS messages. The proxy uses the last
+segment (as in RFC 3986) of the WebSocket path as the target endpoint. The
+target endpoint is encoded like an authority without userinfo (as in RFC 3986,
+Section 3). Each DNS message (as in RFC 1035, Section 4.1) is the payload of a
+WebSocket binary data message (as in RFC 6455).
+
+## Usage
+
+The only command line argument is the optional listener address. To restrict the
+allowed upstreams and origins, `DOWS_ALLOWED_UPSTREAMS` and
+`DOWS_ALLOWED_ORIGINS` must be set to comma-separated lists of allowed values.
+Alternatively, both of these variables can be set exactly to `*` (allow any),
+which disables the specific check.
diff --git a/REUSE.toml b/REUSE.toml
new file mode 100644
index 0000000..de216bd
--- /dev/null
+++ b/REUSE.toml
@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: 2026 Famedly GmbH (info@famedly.com)
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+version = 1
+
+# Generated files
+[[annotations]]
+path = [
+ "Cargo.lock",
+ "flake.lock",
+ ".gitignore",
+ ".gitattributes",
+ ".pre-commit-config.yaml",
+ ".github/workflows/*.yml",
+ "treefmt.toml",
+ "rustfmt.toml",
+]
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2026 Famedly GmbH (info@famedly.com)"
+SPDX-License-Identifier = "AGPL-3.0-or-later"
diff --git a/_typos.toml b/_typos.toml
new file mode 100644
index 0000000..14d4151
--- /dev/null
+++ b/_typos.toml
@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2026 Famedly GmbH (info@famedly.com)
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+[default.extend-words]
+dows = "dows" # DNS over WebSocket
diff --git a/build.rs b/build.rs
new file mode 100644
index 0000000..60814fd
--- /dev/null
+++ b/build.rs
@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: 2026 Famedly GmbH (info@famedly.com)
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+use std::process::Command;
+
+fn main() {
+ println!("cargo:rerun-if-env-changed=GIT_COMMIT_HASH");
+ if std::env::var("GIT_COMMIT_HASH").is_ok() {
+ return;
+ }
+
+ let git_dir = git(&["rev-parse", "--absolute-git-dir"]).expect("git should output git-dir");
+ let head_ref = git(&["symbolic-ref", "--quiet", "HEAD"]);
+ let hash =
+ git(&["rev-parse", head_ref.as_deref().unwrap_or("HEAD")]).expect("git should output rev");
+ println!("cargo:rustc-env=GIT_COMMIT_HASH={hash}");
+ println!("cargo:rerun-if-changed={git_dir}/HEAD");
+ if let Some(head_ref) = head_ref {
+ println!("cargo:rerun-if-changed={git_dir}/{head_ref}");
+ }
+}
+
+fn git(args: &[&str]) -> Option {
+ let mut output = Command::new("git").args(args).output().expect("git command should run");
+ output.status.success().then(|| {
+ output.stdout.pop_if(|&mut b| b == b'\n');
+ String::from_utf8(output.stdout).expect("git output should be UTF-8")
+ })
+}
diff --git a/flake.lock b/flake.lock
new file mode 100644
index 0000000..5d9fa77
--- /dev/null
+++ b/flake.lock
@@ -0,0 +1,198 @@
+{
+ "nodes": {
+ "devshell": {
+ "inputs": {
+ "nixpkgs": [
+ "famedly-engineering-standards",
+ "nixpkgs"
+ ]
+ },
+ "locked": {
+ "lastModified": 1768818222,
+ "narHash": "sha256-460jc0+CZfyaO8+w8JNtlClB2n4ui1RbHfPTLkpwhU8=",
+ "owner": "numtide",
+ "repo": "devshell",
+ "rev": "255a2b1725a20d060f566e4755dbf571bbbb5f76",
+ "type": "github"
+ },
+ "original": {
+ "owner": "numtide",
+ "repo": "devshell",
+ "type": "github"
+ }
+ },
+ "famedly-engineering-standards": {
+ "inputs": {
+ "devshell": "devshell",
+ "flake-parts": "flake-parts",
+ "github-actions-nix": "github-actions-nix",
+ "nixpkgs": "nixpkgs",
+ "rust-overlay": "rust-overlay",
+ "treefmt": "treefmt",
+ "wrappers": "wrappers"
+ },
+ "locked": {
+ "lastModified": 1784628414,
+ "narHash": "sha256-JRCYkrZG8CyHJfde9zqHfdWQQWY5Y6AXcUHixREZXt8=",
+ "owner": "famedly",
+ "repo": "engineering-standards",
+ "rev": "26b385aba416cad9e85927899276d050e700b5cb",
+ "type": "github"
+ },
+ "original": {
+ "owner": "famedly",
+ "repo": "engineering-standards",
+ "type": "github"
+ }
+ },
+ "flake-parts": {
+ "inputs": {
+ "nixpkgs-lib": "nixpkgs-lib"
+ },
+ "locked": {
+ "lastModified": 1778716662,
+ "narHash": "sha256-m1Yf0wZ8j1OHjTc2UwHwyQRSnNeSgLJOd7q5Y45hzi4=",
+ "owner": "hercules-ci",
+ "repo": "flake-parts",
+ "rev": "f7c1a2d347e4c52d5fb8d10cb4d94b5884e546fb",
+ "type": "github"
+ },
+ "original": {
+ "owner": "hercules-ci",
+ "repo": "flake-parts",
+ "type": "github"
+ }
+ },
+ "github-actions-nix": {
+ "inputs": {
+ "flake-parts": [
+ "famedly-engineering-standards",
+ "flake-parts"
+ ],
+ "nixpkgs": [
+ "famedly-engineering-standards",
+ "nixpkgs"
+ ]
+ },
+ "locked": {
+ "lastModified": 1773808042,
+ "narHash": "sha256-97K9g40SdtDVWslJG8ytpiC3+qgeQzftsZheGQ8qoGY=",
+ "owner": "synapdeck",
+ "repo": "github-actions-nix",
+ "rev": "805a4f69856e0f3d0bcd8ae916f1625f22b0578c",
+ "type": "github"
+ },
+ "original": {
+ "owner": "synapdeck",
+ "repo": "github-actions-nix",
+ "type": "github"
+ }
+ },
+ "nixpkgs": {
+ "locked": {
+ "lastModified": 1779622335,
+ "narHash": "sha256-6lZN0CPBbeK9UVgFQ8EV4t2qSVQPhhlerFBGZRiz73Y=",
+ "rev": "705e9929918b43bd7b715dc0a878ac870449bb03",
+ "type": "tarball",
+ "url": "https://releases.nixos.org/nixos/26.05/nixos-26.05beta1.705e9929918b/nixexprs.tar.xz?lastModified=1779622335&rev=705e9929918b43bd7b715dc0a878ac870449bb03"
+ },
+ "original": {
+ "type": "tarball",
+ "url": "https://channels.nixos.org/nixos-26.05/nixexprs.tar.xz"
+ }
+ },
+ "nixpkgs-lib": {
+ "locked": {
+ "lastModified": 1777168982,
+ "narHash": "sha256-GOkGPcboWE9BmGCRMLX3worL4EMnsnG8MyKmXNeYuhQ=",
+ "owner": "nix-community",
+ "repo": "nixpkgs.lib",
+ "rev": "f5901329dade4a6ea039af1433fb087bd9c1fe14",
+ "type": "github"
+ },
+ "original": {
+ "owner": "nix-community",
+ "repo": "nixpkgs.lib",
+ "type": "github"
+ }
+ },
+ "root": {
+ "inputs": {
+ "famedly-engineering-standards": "famedly-engineering-standards",
+ "flake-parts": [
+ "famedly-engineering-standards",
+ "flake-parts"
+ ],
+ "nixpkgs": [
+ "famedly-engineering-standards",
+ "nixpkgs"
+ ]
+ }
+ },
+ "rust-overlay": {
+ "inputs": {
+ "nixpkgs": [
+ "famedly-engineering-standards",
+ "nixpkgs"
+ ]
+ },
+ "locked": {
+ "lastModified": 1779851998,
+ "narHash": "sha256-UkkMh3bX9QW4Luqkm98nUaOqKWrU6i65mUnph3WeSSw=",
+ "owner": "oxalica",
+ "repo": "rust-overlay",
+ "rev": "6cddd512fa2bf7231f098d3a2f92f6e4cff71e0a",
+ "type": "github"
+ },
+ "original": {
+ "owner": "oxalica",
+ "repo": "rust-overlay",
+ "type": "github"
+ }
+ },
+ "treefmt": {
+ "inputs": {
+ "nixpkgs": [
+ "famedly-engineering-standards",
+ "nixpkgs"
+ ]
+ },
+ "locked": {
+ "lastModified": 1780220602,
+ "narHash": "sha256-eynAfOmbmxJnkp7YewvCEbShNnnYJ9gLLqkzsYtBPeM=",
+ "owner": "numtide",
+ "repo": "treefmt-nix",
+ "rev": "db947814a175b7ca6ded66e21383d938df01c227",
+ "type": "github"
+ },
+ "original": {
+ "owner": "numtide",
+ "repo": "treefmt-nix",
+ "type": "github"
+ }
+ },
+ "wrappers": {
+ "inputs": {
+ "nixpkgs": [
+ "famedly-engineering-standards",
+ "nixpkgs"
+ ]
+ },
+ "locked": {
+ "lastModified": 1780661205,
+ "narHash": "sha256-3F5DixT3Gk91lBI9E+TGMm0ko5HrRbDiL23di16TJGA=",
+ "owner": "BirdeeHub",
+ "repo": "nix-wrapper-modules",
+ "rev": "8dd304c3582ddd339217e1cc5fb53f50acb63c2d",
+ "type": "github"
+ },
+ "original": {
+ "owner": "BirdeeHub",
+ "repo": "nix-wrapper-modules",
+ "type": "github"
+ }
+ }
+ },
+ "root": "root",
+ "version": 7
+}
diff --git a/flake.nix b/flake.nix
new file mode 100644
index 0000000..dbac5de
--- /dev/null
+++ b/flake.nix
@@ -0,0 +1,80 @@
+# SPDX-FileCopyrightText: 2026 Famedly GmbH (info@famedly.com)
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+{
+ description = "DNS over WebSocket proxy";
+
+ inputs = {
+ famedly-engineering-standards.url = "github:famedly/engineering-standards";
+
+ nixpkgs.follows = "famedly-engineering-standards/nixpkgs";
+ flake-parts.follows = "famedly-engineering-standards/flake-parts";
+ };
+
+ outputs =
+ { famedly-engineering-standards, flake-parts, ... }@inputs:
+ flake-parts.lib.mkFlake { inherit inputs; } {
+ imports = [
+ famedly-engineering-standards.flakeModules.default
+
+ ./nix/package.nix
+ ./nix/workflows/build.nix
+ ./nix/workflows/tests.nix
+ ];
+
+ systems = famedly-engineering-standards.lib.famedlySystems;
+
+ perSystem =
+ { config, pkgs, ... }:
+ {
+ # This is a Rust project, so default to the Rust devshell.
+ devShells.default = config.devShells.rust;
+
+ famedly.standards = {
+ rust.projects."." = { };
+ nix.projects."." = { };
+ };
+
+ # Hard-wrap markdown prose at 80 columns, like most major Rust
+ # projects (and matching rustfmt's comment_width). mdformat
+ # runs through the treefmt pre-commit hook, so violations are
+ # fixed automatically.
+ treefmt = {
+ programs.mdformat = {
+ enable = true;
+ settings.wrap = 80;
+ };
+
+ # Refer to the binary by name so that the generated
+ # treefmt.toml does not contain nix store paths. The package
+ # is put on PATH through the prek wrapper and the devshell.
+ settings.formatter.mdformat.command = "mdformat";
+ };
+
+ # Check licensing information (SPDX headers and REUSE.toml)
+ # against the REUSE specification. This runs in CI through
+ # the check-pre-commit-hooks workflow.
+ prek-pre-commit = {
+ package.runtimePkgs = [ pkgs.reuse ];
+
+ workspaces.".".repos = [
+ {
+ repo = "local";
+ hooks = [
+ {
+ id = "reuse";
+ name = "reuse";
+ description = "Check licensing info for REUSE compliance";
+ pass_filenames = false;
+
+ entry = "reuse lint";
+ language = "system";
+ }
+ ];
+ }
+ ];
+ };
+ };
+ };
+}
diff --git a/nix/package.nix b/nix/package.nix
new file mode 100644
index 0000000..1419070
--- /dev/null
+++ b/nix/package.nix
@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: 2026 Famedly GmbH (info@famedly.com)
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+{ inputs, ... }:
+{
+ perSystem =
+ { config, pkgs, ... }:
+ let
+ mkDows =
+ rustPlatform:
+ rustPlatform.buildRustPackage {
+ pname = "dows";
+ version = (pkgs.lib.importTOML ../Cargo.toml).package.version;
+
+ src = pkgs.lib.fileset.toSource {
+ root = ../.;
+ fileset = pkgs.lib.fileset.unions [
+ ../Cargo.toml
+ ../Cargo.lock
+ ../build.rs
+ ../src
+ ];
+ };
+
+ cargoLock.lockFile = ../Cargo.lock;
+
+ # ensure that the flake is always built from a clean tree, so
+ # the binary contains the correct commit hash to fulfill AGPL requirements
+ env.GIT_COMMIT_HASH = inputs.self.rev;
+
+ meta = {
+ description = "DNS over WebSocket proxy";
+ mainProgram = "dows";
+ };
+ };
+ in
+ {
+ packages = {
+ dows = mkDows pkgs.pkgsStatic.rustPlatform;
+ default = config.packages.dows;
+
+ docker-image = pkgs.dockerTools.buildLayeredImage {
+ name = "dows";
+ tag = "latest";
+
+ config = {
+ Entrypoint = [ (pkgs.lib.getExe config.packages.dows) ];
+ ExposedPorts."8080/tcp" = { };
+ };
+ };
+ };
+ };
+}
diff --git a/nix/workflows/build.nix b/nix/workflows/build.nix
new file mode 100644
index 0000000..33c6449
--- /dev/null
+++ b/nix/workflows/build.nix
@@ -0,0 +1,207 @@
+# SPDX-FileCopyrightText: 2026 Famedly GmbH (info@famedly.com)
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+{ config, ... }:
+let
+ allowed-actions = config.famedly.standards.allowed-action-versions;
+
+ # Not (yet) part of the engineering standards' allow-list
+ # (`standards/allowed-github-actions.toml`), so we pin them here the
+ # same way: by full commit SHA.
+ #
+ # rev = "v7.0.1"
+ upload-artifact = "actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a";
+ # rev = "v8.0.1"
+ download-artifact = "actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c";
+in
+{
+ perSystem.githubActions.workflows.build = {
+ name = "Build";
+
+ on.pullRequest = {
+ branches = [ "**" ];
+ types = [
+ "opened"
+ "reopened"
+ "synchronize"
+ "ready_for_review"
+ ];
+ };
+ on.mergeGroup = { };
+ on.push = {
+ branches = [ "main" ];
+ tags = [ "v*" ];
+ };
+
+ concurrency = {
+ group = "\${{ github.workflow }}-\${{ github.ref }}";
+ cancelInProgress = true;
+ };
+
+ permissions = {
+ # `write` is required to create releases for tag builds.
+ contents = "write";
+ };
+
+ # Build the static binary and the Docker image natively on each
+ # architecture and hand both to the jobs below as artifacts. The
+ # artifact names carry the architecture so that the per-arch
+ # results do not collide.
+ jobs.build = {
+ strategy.matrix.include = [
+ {
+ arch = "x86_64";
+ runner = "ubuntu-26.04";
+ }
+ {
+ arch = "aarch64";
+ runner = "ubuntu-26.04-arm";
+ }
+ ];
+
+ runsOn = "\${{ matrix.runner }}";
+
+ steps = [
+ { uses = allowed-actions."actions/checkout".uses; }
+ { uses = allowed-actions."cachix/install-nix-action".uses; }
+
+ {
+ name = "Build static binary";
+ run = ''
+ nix build .#dows --print-build-logs -o result-dows
+ '';
+ }
+
+ {
+ name = "Build Docker image";
+ run = "nix build .#docker-image --print-build-logs";
+ }
+
+ {
+ name = "Upload static binary as artifact";
+ uses = upload-artifact;
+ with_ = {
+ name = "dows-linux-\${{ matrix.arch }}";
+ path = "result-dows/bin/dows";
+ if-no-files-found = "error";
+ };
+ }
+
+ {
+ name = "Upload Docker image as artifact";
+ uses = upload-artifact;
+ with_ = {
+ name = "docker-image-\${{ matrix.arch }}";
+ path = "result";
+ if-no-files-found = "error";
+ };
+ }
+ ];
+ };
+
+ # Push images for all builds: version tags go to the release
+ # registry (docker-oss), everything else (PRs, main) goes to the
+ # nightly registry (docker-nightly). The per-architecture images
+ # are combined into a single multi-arch manifest.
+ jobs.docker = {
+ runsOn = "ubuntu-26.04-arm";
+ if_ = "github.event_name == 'push' || github.event_name == 'pull_request'";
+ needs = [ "build" ];
+
+ steps = [
+ {
+ name = "Download Docker images";
+ uses = download-artifact;
+ with_ = {
+ pattern = "docker-image-*";
+ path = "artifacts";
+ };
+ }
+
+ {
+ name = "Push multi-arch Docker manifest to registry";
+ env = {
+ REGISTRY_USER = "\${{ vars.REGISTRY_USER }}";
+ REGISTRY_PASSWORD = "\${{ secrets.registry_password || secrets.GITHUB_TOKEN }}";
+ TAG = "\${{ github.head_ref || github.ref_name || 'latest' }}";
+ };
+ run = ''
+ if [[ "$GITHUB_REF_NAME" =~ v[0-9]+\.[0-9]+\.[0-9]+ ]]; then
+ registry=registry.famedly.net/docker-oss
+ else
+ registry=registry.famedly.net/docker-nightly
+ fi
+
+ echo "$REGISTRY_PASSWORD" \
+ | podman login registry.famedly.net -u "$REGISTRY_USER" --password-stdin
+
+ image="$registry/dows"
+ # Branch names may contain slashes, which are not valid in
+ # Docker tags.
+ tag="''${TAG//\//-}"
+
+ # Combine the per-arch images into a multi-arch manifest.
+ # Every `podman load` overwrites `dows:latest`, so retag
+ # each image with an arch suffix before loading the next.
+ podman manifest create dows-multiarch
+ for arch in x86_64 aarch64; do
+ podman load < "artifacts/docker-image-$arch/result"
+ podman tag dows:latest "dows:$arch"
+ podman manifest add dows-multiarch "containers-storage:localhost/dows:$arch"
+ done
+
+ # `--all` pushes the per-arch images along with the
+ # manifest (by digest only, so no arch-specific tags show
+ # up in the registry). Publish under both the branch/tag
+ # name and the commit SHA.
+ podman manifest push --all dows-multiarch "docker://$image:$tag"
+ podman manifest push --all dows-multiarch "docker://$image:$GITHUB_SHA"
+ '';
+ }
+ ];
+ };
+
+ # For version tags, publish a single GitHub release with the static
+ # binaries of both architectures attached.
+ jobs.release = {
+ runsOn = "ubuntu-latest";
+ if_ = "startsWith(github.ref, 'refs/tags/')";
+ needs = [ "build" ];
+
+ steps = [
+ {
+ name = "Download static binaries";
+ uses = download-artifact;
+ with_ = {
+ pattern = "dows-linux-*";
+ path = "artifacts";
+ };
+ }
+
+ {
+ # `gh` is preinstalled on GitHub runners.
+ name = "Create GitHub release";
+ env = {
+ GH_TOKEN = "\${{ github.token }}";
+ GH_REPO = "\${{ github.repository }}";
+ };
+ run = ''
+ tag="''${GITHUB_REF#refs/tags/}"
+
+ # The file inside each artifact is just called `dows`;
+ # rename it to the artifact's arch-suffixed name for the
+ # release assets.
+ for dir in artifacts/dows-linux-*; do
+ install -m755 "$dir/dows" "$(basename "$dir")"
+ done
+
+ gh release create "$tag" \
+ --verify-tag \
+ dows-linux-*
+ '';
+ }
+ ];
+ };
+ };
+}
diff --git a/nix/workflows/tests.nix b/nix/workflows/tests.nix
new file mode 100644
index 0000000..b3dcba1
--- /dev/null
+++ b/nix/workflows/tests.nix
@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: 2026 Famedly GmbH (info@famedly.com)
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+{ config, ... }:
+let
+ allowed-actions = config.famedly.standards.allowed-action-versions;
+in
+{
+ perSystem.githubActions.workflows.tests = {
+ name = "Run tests";
+
+ on.pullRequest = {
+ branches = [ "**" ];
+ types = [
+ "opened"
+ "reopened"
+ "synchronize"
+ "ready_for_review"
+ ];
+ };
+ on.mergeGroup = { };
+
+ concurrency = {
+ group = "\${{ github.workflow }}-\${{ github.ref }}";
+ cancelInProgress = true;
+ };
+
+ jobs.nextest = {
+ runsOn = "ubuntu-26.04-arm";
+
+ steps = [
+ { uses = allowed-actions."actions/checkout".uses; }
+ { uses = allowed-actions."cachix/install-nix-action".uses; }
+
+ {
+ name = "Run tests";
+ shell = "nix develop .#rust --command bash {0}";
+ run = "cargo nextest run --all-targets --all-features";
+ }
+ ];
+ };
+ };
+}
diff --git a/rustfmt.toml b/rustfmt.toml
new file mode 100644
index 0000000..ad0e701
--- /dev/null
+++ b/rustfmt.toml
@@ -0,0 +1,11 @@
+comment_width = 80
+doc_comment_code_block_width = 80
+edition = "2024"
+format_code_in_doc_comments = true
+group_imports = "StdExternalCrate"
+hard_tabs = true
+imports_granularity = "Crate"
+max_width = 100
+style_edition = "2024"
+use_small_heuristics = "Max"
+wrap_comments = true
diff --git a/src/main.rs b/src/main.rs
new file mode 100644
index 0000000..ed78299
--- /dev/null
+++ b/src/main.rs
@@ -0,0 +1,319 @@
+// SPDX-FileCopyrightText: 2026 Famedly GmbH (info@famedly.com)
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! DNS over WebSocket (DoWS) proxy.
+
+mod translate;
+use std::{io, sync::Arc};
+
+use base64ct::{Base64, Encoding};
+use httparse::Status;
+use percent_encoding::percent_decode_str;
+use sha1::{Digest, Sha1};
+use tokio::{
+ io::{AsyncReadExt, AsyncWriteExt},
+ net::{
+ TcpListener, TcpStream,
+ tcp::{ReadHalf, WriteHalf},
+ },
+ signal::unix::{SignalKind, signal},
+ sync::Mutex,
+};
+use translate::{close_frame, dns_to_ws, ws_to_dns};
+
+const INFO: &str = concat!(
+ env!("CARGO_PKG_NAME"),
+ " ",
+ env!("CARGO_PKG_VERSION"),
+ "\r\n",
+ "Source code at ",
+ env!("CARGO_PKG_REPOSITORY"),
+ "/commit/",
+ env!("GIT_COMMIT_HASH"),
+ "\r\n"
+);
+
+/// Policies that are passed to the connection handler
+struct Policy {
+ /// Allowed origins
+ allowed_origins: Option,
+ /// Allowed upstreams
+ allowed_upstreams: Option,
+}
+
+/// The listener accepts any number of connections concurrently, each on
+/// its own tokio task.
+///
+/// SIGTERM (as sent by e.g. `docker stop` or the integration tests) makes
+/// the process exit cleanly instead of being killed by the default signal
+/// disposition. A clean exit runs the exit hooks, which coverage
+/// instrumentation needs to write its profile data. In-flight connections
+/// are dropped.
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+ let policy = Arc::new(Policy {
+ allowed_upstreams: Some(std::env::var("DOWS_ALLOWED_UPSTREAMS")?).filter(|x| x != "*"),
+ allowed_origins: Some(std::env::var("DOWS_ALLOWED_ORIGINS")?).filter(|x| x != "*"),
+ });
+ let listen_arg = std::env::args().nth(1);
+ let listen_str = listen_arg.as_deref().unwrap_or("[::]:8080");
+ let listener = TcpListener::bind(listen_str).await?;
+ println!("listening on {}", listener.local_addr()?);
+ let mut sigterm = signal(SignalKind::terminate())?;
+ let mut sigint = signal(SignalKind::interrupt())?;
+ loop {
+ tokio::select! {
+ accepted = listener.accept() => {
+ let (sock, _addr) = accepted?;
+ tokio::spawn(handle_connection(sock, policy.clone()));
+ }
+ _ = sigterm.recv() => return Ok(()),
+ _ = sigint.recv() => return Ok(()),
+ }
+ }
+}
+
+/// Handles a single client connection end-to-end: performs the WebSocket
+/// handshake, connects to the requested upstream DNS server, then
+/// forwards traffic in both directions concurrently until either side
+/// closes the connection.
+async fn handle_connection(mut sock: TcpStream, policy: Arc) -> io::Result<()> {
+ let mut buf = [0; 65536];
+ let mut data_len = 0;
+ let (mut headers, mut request);
+ let request_len = loop {
+ let size @ 1.. = sock.read(&mut buf[data_len..]).await? else {
+ return Err(io::ErrorKind::UnexpectedEof.into());
+ };
+ data_len += size;
+ headers = [httparse::EMPTY_HEADER; 64];
+ request = httparse::Request::new(&mut headers);
+ match request.parse(&buf[..data_len]) {
+ Err(e) => return Err(io::Error::new(io::ErrorKind::InvalidData, e)),
+ Ok(Status::Complete(len)) => break len,
+ _ => {}
+ }
+ };
+
+ for h in request.headers.iter() {
+ if h.name.eq_ignore_ascii_case("origin") {
+ if policy
+ .allowed_origins
+ .as_ref()
+ .is_some_and(|x| !x.split(",").any(|x| x.as_bytes() == h.value))
+ {
+ let resp = "HTTP/1.1 403 Forbidden\r\n\
+ Connection: close\r\n\
+ Content-Type: text/plain\r\n\r\n";
+ sock.write_all(resp.as_bytes()).await?;
+ return Ok(());
+ }
+ }
+ }
+
+ if request.path == Some("/") {
+ let resp = "HTTP/1.1 200 OK\r\n\
+ Connection: close\r\n\
+ Content-Type: text/plain\r\n\r\n";
+ sock.write_all(resp.as_bytes()).await?;
+ sock.write_all(INFO.as_bytes()).await?;
+ return Ok(());
+ }
+ let Some(key_header) = websocket_key(&request) else {
+ let resp = "HTTP/1.1 426 Upgrade Required\r\n\
+ Upgrade: websocket\r\n\
+ Connection: upgrade, close\r\n\
+ Content-Type: text/plain\r\n\r\n";
+ sock.write_all(resp.as_bytes()).await?;
+ sock.write_all(INFO.as_bytes()).await?;
+ return Ok(());
+ };
+ if request_len != data_len {
+ let resp = "HTTP/1.1 400 Bad Request\r\n\
+ Connection: close\r\n\
+ Content-Type: text/plain\r\n\r\n";
+ sock.write_all(resp.as_bytes()).await?;
+ return Ok(());
+ }
+ let accept = compute_accept_key(key_header);
+ let response = format!(
+ "HTTP/1.1 101 Switching Protocols\r\n\
+ Upgrade: websocket\r\n\
+ Connection: upgrade\r\n\
+ Sec-WebSocket-Accept: {accept}\r\n\r\n"
+ );
+ sock.write_all(response.as_bytes()).await?;
+
+ let path = request.path.unwrap();
+ let (path, _query) = path.split_once("?").unwrap_or((path, ""));
+ let final_segment = path.rsplit_once("/").map(|(_, end)| end).unwrap_or(path);
+ let upstream_addr = parse_upstream_addr(&percent_decode_str(final_segment).decode_utf8_lossy());
+ if policy.allowed_upstreams.as_ref().is_some_and(|x| {
+ !x.split(",").map(str::trim).any(|x| parse_upstream_addr(x) == upstream_addr)
+ }) {
+ let mut buf = [0u8; _];
+ const MESSAGE: &str = "upstream prohibited by proxy configuration";
+ sock.write_all(close_frame(&mut buf, 1000, MESSAGE)).await?;
+ return Ok(());
+ }
+ let mut upstream = match TcpStream::connect(upstream_addr).await {
+ Ok(upstream) => upstream,
+ Err(e) => {
+ let mut buf = [0u8; _];
+ sock.write_all(close_frame(&mut buf, 1000, e)).await?;
+ return Ok(());
+ }
+ };
+
+ let (mut sock_r, sock_w) = sock.split();
+ let (mut up_r, mut up_w) = upstream.split();
+ let sock_w = Mutex::new(Some(sock_w));
+
+ let _ = tokio::try_join!(
+ forward_responses(&mut up_r, &sock_w),
+ forward_requests(&mut sock_r, &sock_w, &mut up_w)
+ );
+
+ Ok(())
+}
+
+/// Forward traffic from an upstream DNS server to a WebSocket client.
+async fn forward_responses(
+ up_r: &mut ReadHalf<'_>,
+ sock_w: &Mutex>>,
+) -> io::Result<()> {
+ /// Size of the upstream-to-client working buffer: a maximum-size DNS
+ /// message with its 2-byte length prefix (65537 bytes) plus the prefix
+ /// area required by `dns_to_ws` (2 bytes per 128 bytes of input).
+ const BUF_SIZE: usize = 65536 / 128 * 130 + 1;
+
+ // Reserve the prefix area as required by `dns_to_ws`.
+ let offset = BUF_SIZE / 130 * 2;
+ let mut dns_buf = [0u8; BUF_SIZE];
+ let mut dns_fill = offset;
+
+ let close_msg = loop {
+ let size = match up_r.read(&mut dns_buf[dns_fill..]).await {
+ Ok(0) => break close_frame(dns_buf.first_chunk_mut().unwrap(), 1000, ""),
+ Err(e) => break close_frame(dns_buf.first_chunk_mut().unwrap(), 1000, e),
+ Ok(size) => size,
+ };
+ dns_fill += size;
+ let (ws_len, end) = dns_to_ws(&mut dns_buf[..dns_fill], offset);
+ if ws_len > 0
+ && let Some(sock_w) = sock_w.lock().await.as_mut()
+ {
+ sock_w.write_all(&dns_buf[..ws_len]).await?;
+ }
+ let trailer_len = dns_fill - end;
+ dns_buf.copy_within(end..dns_fill, offset);
+ dns_fill = offset + trailer_len;
+ };
+
+ if let Some(mut sock_w) = sock_w.lock().await.take() {
+ sock_w.write_all(close_msg).await?;
+ }
+
+ Ok(())
+}
+
+/// Forward traffic from a WebSocket client to an upstream DNS server.
+async fn forward_requests(
+ sock_r: &mut ReadHalf<'_>,
+ sock_w: &Mutex>>,
+ up_w: &mut WriteHalf<'_>,
+) -> io::Result<()> {
+ // fits maximum sized message, 2 header bytes, 2 extended length bytes, and
+ // 4 mask bytes
+ let mut ws_buf = [0u8; 65535 + 8];
+ let mut ws_fill = 0usize;
+
+ // fits maximum sized message with 2 header bytes
+ let mut dns_buf = [0u8; 65535 + 2];
+ let mut dns_pos = 0;
+
+ // When ws_to_dns stops because the output buffer `dns_buf` is full,
+ // the next iteration needs to rerun ws_to_dns with more space in
+ // the output buffer without reading new data.
+ let mut read = true;
+
+ let code = loop {
+ if read {
+ let size @ 1.. = sock_r.read(&mut ws_buf[ws_fill..]).await? else {
+ break 1000;
+ };
+ ws_fill += size;
+ }
+ let (dns_complete, dns_end, pong, ws_pos) =
+ match ws_to_dns(&mut ws_buf[..ws_fill], &mut dns_buf, dns_pos) {
+ Ok(state) => state,
+ Err(code) => break code,
+ };
+ if dns_complete > 0 {
+ if up_w.write_all(&dns_buf[..dns_complete]).await.is_err() {
+ break 1000;
+ }
+ }
+ if pong > 0
+ && let Some(sock_w) = sock_w.lock().await.as_mut()
+ {
+ sock_w.write_all(&ws_buf[..pong]).await?;
+ }
+ dns_buf.copy_within(dns_complete..dns_end, 0);
+ dns_pos = dns_end - dns_complete;
+ ws_buf.copy_within(ws_pos..ws_fill, 0);
+ ws_fill -= ws_pos;
+ read = ws_fill == 0 || dns_complete == 0;
+ };
+
+ if let Some(mut sock_w) = sock_w.lock().await.take() {
+ let close_msg = close_frame(dns_buf.first_chunk_mut().unwrap(), code, "");
+ sock_w.write_all(close_msg).await?;
+ }
+
+ Err(io::ErrorKind::UnexpectedEof.into())
+}
+
+/// Normalizes the final path segment into a `host:port` string suitable for
+/// `TcpStream::connect`, defaulting the port to 53 if the argument doesn't
+/// already specify one.
+fn parse_upstream_addr(s: &str) -> String {
+ if !s.contains(':') || s.ends_with(']') { format!("{s}:53") } else { s.into() }
+}
+
+/// Checks if a value is contained in a multi-valued HTTP header.
+fn contains_val(value: &[u8], needle: &[u8]) -> bool {
+ value.split(|&c| c == b',').any(|v| v.trim_ascii().eq_ignore_ascii_case(needle))
+}
+
+/// Returns the `Sec-WebSocket-Key` header value if the parsed request is
+/// a valid HTTP/1.1 WebSocket upgrade request (RFC 6455 section 4.2.1),
+/// or `None` otherwise.
+fn websocket_key<'a>(req: &'a httparse::Request) -> Option<&'a str> {
+ let (mut upgrade, mut connection, mut version) = (false, false, false);
+ let mut key = None;
+
+ for h in req.headers.iter() {
+ if h.name.eq_ignore_ascii_case("upgrade") {
+ upgrade |= contains_val(h.value, b"websocket");
+ } else if h.name.eq_ignore_ascii_case("connection") {
+ connection |= contains_val(h.value, b"upgrade");
+ } else if h.name.eq_ignore_ascii_case("sec-websocket-version") {
+ version = h.value.trim_ascii().eq_ignore_ascii_case(b"13");
+ } else if h.name.eq_ignore_ascii_case("sec-websocket-key") {
+ key = std::str::from_utf8(h.value).ok();
+ }
+ }
+
+ key.filter(|_| upgrade && connection && version)
+}
+
+/// Computes the `Sec-WebSocket-Accept` header value for a given
+/// `Sec-WebSocket-Key`, per RFC 6455 section 1.3.
+fn compute_accept_key(key: &str) -> String {
+ let mut hasher = Sha1::new();
+ hasher.update(key.as_bytes());
+ hasher.update(b"258EAFA5-E914-47DA-95CA-C5AB0DC85B11");
+ Base64::encode_string(&hasher.finalize())
+}
diff --git a/src/translate.rs b/src/translate.rs
new file mode 100644
index 0000000..b56d52d
--- /dev/null
+++ b/src/translate.rs
@@ -0,0 +1,186 @@
+// SPDX-FileCopyrightText: 2026 Famedly GmbH (info@famedly.com)
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+#[cfg(test)]
+mod tests;
+
+use std::{
+ fmt::Display,
+ io::{Cursor, Write},
+};
+
+const BINARY_DATA: u8 = 0x2;
+const CLOSE: u8 = 0x8;
+const PING: u8 = 0x9;
+const PONG: u8 = 0xA;
+const TYPE_MASK: u8 = 0xF;
+
+/// The last frame of a message.
+const FIN: u8 = 0x80;
+
+const MASKED: u8 = 0x80;
+
+/// The actual len is encoded in the next 2 bytes.
+const EXTENDED_LEN_2: u8 = 126;
+
+/// The actual len is encoded in the next 8 bytes (never occurs in DoWS).
+const EXTENDED_LEN_8: u8 = 127;
+
+/// Builds a server-to-client WebSocket close frame (RFC 6455, 5.5.1) with the
+/// given status `code` and `reason` into `buf`, returning the written slice.
+/// It is truncated to fit the 125-byte control-frame payload limit.
+pub fn close_frame(buf: &mut [u8; 127], code: u16, reason: impl Display) -> &[u8] {
+ let mut cursor = Cursor::new(&mut buf[4..]);
+ let write_result = write!(cursor, "{reason}");
+ let mut reason_len = cursor.position() as usize;
+ if write_result.is_err() {
+ let trailer = *b"..."; // trailer to indicate truncation
+ reason_len -= trailer.len();
+ // Truncation may have split a multi-byte character
+ if let Err(e) = std::str::from_utf8(&buf[4..4 + reason_len]) {
+ reason_len = e.valid_up_to();
+ }
+ reason_len += trailer.len();
+ *buf[4..4 + reason_len].last_chunk_mut().expect("reason_len >= trailer.len") = *b"...";
+ }
+
+ buf[0] = FIN | CLOSE;
+ buf[1] = (reason_len + 2) as u8;
+ buf[2..4].copy_from_slice(&code.to_be_bytes());
+ &buf[..4 + reason_len]
+}
+
+/// Converts DNS TCP framing (u16) to WebSocket framing in-place.
+///
+/// The input `buffer` must have a prefix area with unspecified data. The prefix
+/// area must contain 2 bytes per DNS message of 126 bytes or larger. The worst
+/// case overhead is 2 * floor(length / 128). The real input data starts at
+/// `offset`. The first returned index is the end of the translated output. The
+/// second returned index is the end of processed input. Unprocessed input
+/// should be supplied at `offset` on the next call.
+pub fn dns_to_ws(buffer: &mut [u8], offset: usize) -> (usize, usize) {
+ let mut input_pos = offset;
+ let mut output_pos = 0;
+ while let Some(&length_array) = buffer.get(input_pos..).and_then(|x| x.first_chunk()) {
+ let len = u16::from_be_bytes(length_array);
+ if input_pos + 2 + usize::from(len) > buffer.len() {
+ break;
+ }
+ if len < EXTENDED_LEN_2.into() {
+ buffer[output_pos] = FIN | BINARY_DATA;
+ buffer[output_pos + 1] = length_array[1];
+ output_pos += 2;
+ } else {
+ buffer[output_pos] = FIN | BINARY_DATA;
+ buffer[output_pos + 1] = EXTENDED_LEN_2;
+ buffer[output_pos + 2] = length_array[0];
+ buffer[output_pos + 3] = length_array[1];
+ output_pos += 4;
+ }
+ input_pos += 2;
+ buffer.copy_within(input_pos..input_pos + usize::from(len), output_pos);
+ input_pos += usize::from(len);
+ output_pos += usize::from(len);
+ }
+ (output_pos, input_pos)
+}
+
+/// Converts WebSocket framing from `ws_data` to DNS TCP framing in `dns_data`,
+/// translating WS binary data frames to DNS messages and answering WS ping
+/// frames.
+///
+/// `dns_data` can already contain the start of a message, in case a
+/// fragment was processed in the previous call. `dns_data_pos` indicates the
+/// end of such a fragment.
+///
+/// The first returned index is the end of complete DNS TCP data. The second
+/// returned index is the end of the current fragment. The third returned index
+/// is the end of the pong area. Pong replies are built in-place at the
+/// beginning of `ws_data`. The fourth returned index is the end of processed
+/// input. Unprocessed input should be supplied at the front on the next call.
+pub fn ws_to_dns(
+ ws_data: &mut [u8],
+ dns_data: &mut [u8],
+ mut dns_data_pos: usize,
+) -> Result<(usize, usize, usize, usize), u16> {
+ let mut ws_pos = 0;
+ let mut dns_data_complete = 0;
+ let mut pong_pos = 0;
+ while let Some(minimal_header) =
+ ws_data.get(ws_pos..).and_then(|x| x.first_chunk::<2>()).copied()
+ {
+ match minimal_header[0] {
+ // Allow BINARY and continuation frames, with or without FIN.
+ // Allow CLOSE, PING, and PONG with FIN only, as fragmented control frames are illegal.
+ 0x00 | 0x02 | 0x80 | 0x82 | 0x88 | 0x89 | 0x8a => {}
+ _ => return Err(1003),
+ }
+ if minimal_header[1] & MASKED != MASKED {
+ return Err(1002);
+ }
+ let (header_len, fragment_len) = match minimal_header[1] & !MASKED {
+ EXTENDED_LEN_2 => match ws_data.get(ws_pos + 2..).and_then(|x| x.first_chunk()) {
+ Some(&x) => (4, u16::from_be_bytes(x)),
+ _ => break,
+ },
+ EXTENDED_LEN_8 => return Err(1009),
+ simple_len => (2, simple_len.into()),
+ };
+ let Some(mask) =
+ ws_data.get(ws_pos + header_len..).and_then(|x| x.first_chunk::<4>()).copied()
+ else {
+ break;
+ };
+ let data_start = ws_pos + header_len + mask.len();
+ let data_range = data_start..data_start + usize::from(fragment_len);
+ if data_range.end > ws_data.len() {
+ break;
+ }
+ let old_ws_pos = ws_pos;
+ ws_pos = data_range.end;
+ if minimal_header[0] == MASKED | CLOSE {
+ return Err(1000);
+ } else if minimal_header[0] == MASKED | PING {
+ let Some(fragment_len) =
+ u8::try_from(fragment_len).ok().filter(|&c| c < EXTENDED_LEN_2)
+ else {
+ return Err(1002);
+ };
+ ws_data[pong_pos] = FIN | PONG;
+ ws_data[pong_pos + 1] = fragment_len;
+ pong_pos += 2;
+ for (i, m) in data_range.zip(mask.iter().cycle()) {
+ ws_data[pong_pos] = ws_data[i] ^ m;
+ pong_pos += 1;
+ }
+ } else if minimal_header[0] != MASKED | PONG {
+ let start_new_message = minimal_header[0] & TYPE_MASK == BINARY_DATA;
+ if start_new_message != (dns_data_pos == dns_data_complete) {
+ return Err(1002);
+ }
+ let header_size = if start_new_message { 2 } else { 0 };
+
+ let message_len =
+ dns_data_pos + header_size - dns_data_complete - 2 + usize::from(fragment_len);
+ let Ok(message_len) = u16::try_from(message_len) else {
+ return Err(1009);
+ };
+ if dns_data_pos + header_size + data_range.len() > dns_data.len() {
+ ws_pos = old_ws_pos;
+ break;
+ }
+ dns_data_pos += header_size;
+ for (i, m) in data_range.zip(mask.iter().cycle()) {
+ dns_data[dns_data_pos] = ws_data[i] ^ m;
+ dns_data_pos += 1;
+ }
+ if minimal_header[0] & FIN == FIN {
+ dns_data[dns_data_complete] = message_len.to_be_bytes()[0];
+ dns_data[dns_data_complete + 1] = message_len.to_be_bytes()[1];
+ dns_data_complete = dns_data_pos;
+ }
+ }
+ }
+ Ok((dns_data_complete, dns_data_pos, pong_pos, ws_pos))
+}
diff --git a/src/translate/tests.rs b/src/translate/tests.rs
new file mode 100644
index 0000000..9eba721
--- /dev/null
+++ b/src/translate/tests.rs
@@ -0,0 +1,248 @@
+// SPDX-FileCopyrightText: 2026 Famedly GmbH (info@famedly.com)
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+use super::{
+ BINARY_DATA, CLOSE, EXTENDED_LEN_2, EXTENDED_LEN_8, FIN, MASKED, PING, PONG, close_frame,
+ dns_to_ws, ws_to_dns,
+};
+
+#[test]
+fn close_frame_without_reason() {
+ let mut buf = [0; _];
+ // 1000 == 0x03e8 (normal closure).
+ assert_eq!(close_frame(&mut buf, 1000, ""), [FIN | CLOSE, 2, 0x03, 0xe8]);
+}
+
+#[test]
+fn close_frame_with_reason() {
+ let mut buf = [0; _];
+ // 1011 == 0x03f3 (internal error).
+ assert_eq!(
+ close_frame(&mut buf, 1011, "boom"),
+ [FIN | CLOSE, 6, 0x03, 0xf3, b'b', b'o', b'o', b'm']
+ );
+}
+
+#[test]
+fn close_frame_truncates_overlong_reason() {
+ let mut buf = [0; _];
+ let reason = "x".repeat(200);
+ let frame = close_frame(&mut buf, 1000, &reason);
+ // The payload is capped at the 125-byte control-frame maximum (2-byte
+ // code + 123-byte reason).
+ assert_eq!(frame.len(), 2 + 125);
+ assert_eq!(frame[1], 125);
+ assert_eq!(&frame[4..frame.len() - 3], vec![b'x'; 120].as_slice());
+ assert_eq!(&frame[frame.len() - 3..], *b"...");
+}
+
+#[test]
+fn close_frame_truncates_on_char_boundary() {
+ let mut buf = [0; _];
+ for i in 0.."๐".len() {
+ // Shift the UTF-8 character to every possible byte position
+ let reason = format!("{}{}", " ".repeat(i), "๐".repeat(42));
+ let frame = close_frame(&mut buf, 1000, reason);
+ assert!(std::str::from_utf8(&frame[4..]).is_ok());
+ }
+}
+
+#[test]
+fn dns_to_ws_two_short_messages() {
+ let mut buf = [255, 255, 255, 255, 0, 4, 1, 2, 3, 4, 0, 3, 1, 2, 3];
+ let (translated_size, end) = dns_to_ws(&mut buf, 4);
+ assert_eq!(end, buf.len());
+ assert_eq!(buf[..translated_size], [0x82, 4, 1, 2, 3, 4, 0x82, 3, 1, 2, 3]);
+}
+
+#[test]
+fn dns_to_ws_extended_length() {
+ // A 126-byte message uses the 2-byte extended length encoding.
+ let mut buf = vec![255, 255, 255, 255, 0, 126];
+ buf.extend(std::iter::repeat_n(7u8, 126));
+ let (translated_size, end) = dns_to_ws(&mut buf, 4);
+ assert_eq!(end, buf.len());
+ assert_eq!(translated_size, 130);
+ assert_eq!(buf[..4], [0x82, 126, 0x00, 126]);
+ assert!(buf[4..130].iter().all(|&b| b == 7));
+}
+
+#[test]
+fn dns_to_ws_incomplete_message() {
+ // The declared length (10) exceeds the bytes actually available.
+ let mut buf = [0, 0, 0, 0, 0, 10, 1, 2, 3];
+ let (translated_size, end) = dns_to_ws(&mut buf, 4);
+ assert_eq!(translated_size, 0);
+ assert_eq!(end, 4);
+}
+
+#[test]
+fn ws_to_dns_two_short_messages() {
+ let mut messages = [
+ [FIN | BINARY_DATA, MASKED | 3, 0xf0, 0xf0, 0xf0, 0xf0, 1, 2, 3],
+ [FIN | BINARY_DATA, MASKED | 3, 0xf0, 0xf0, 0xf0, 0xf0, 4, 5, 6],
+ ];
+ let buf = messages.as_flattened_mut();
+ let mut dns_data = [0; 32];
+ let (translated_size, fragment_end, pong, end) = ws_to_dns(buf, &mut dns_data, 0).unwrap();
+ assert_eq!(pong, 0);
+ assert_eq!(fragment_end, translated_size);
+ assert_eq!(end, buf.len());
+ assert_eq!(dns_data[..translated_size], [0, 3, 0xf1, 0xf2, 0xf3, 0, 3, 0xf4, 0xf5, 0xf6]);
+}
+
+#[test]
+fn ws_to_dns_invalid_opcode() {
+ // Opcode 0x1 is a text message (not allowed by DoWS).
+ let mut buf = [FIN | 0x1, MASKED];
+ assert_eq!(ws_to_dns(&mut buf, &mut [], 0), Err(1003));
+}
+
+#[test]
+fn ws_to_dns_unmasked() {
+ // Client frames must be masked.
+ let mut buf = [FIN | BINARY_DATA, 0x04];
+ assert_eq!(ws_to_dns(&mut buf, &mut [], 0), Err(1002));
+}
+
+#[test]
+fn ws_to_dns_extended_length() {
+ // A 126-byte fragment uses the 2-byte extended length encoding.
+ let mut buf = vec![FIN | BINARY_DATA, MASKED | EXTENDED_LEN_2, 0, 126, 0, 0, 0, 0];
+ buf.extend(std::iter::repeat_n(9u8, 126));
+ let mut dns_data = [0; 128];
+ let (translated_size, fragment_end, pong, end) = ws_to_dns(&mut buf, &mut dns_data, 0).unwrap();
+ assert_eq!(pong, 0);
+ assert_eq!(translated_size, 128);
+ assert_eq!(fragment_end, translated_size);
+ assert_eq!(end, buf.len());
+ assert_eq!(dns_data[..2], [0, 126]);
+ assert!(dns_data[2..128].iter().all(|&b| b == 9));
+}
+
+#[test]
+fn ws_to_dns_truncated_extended_length() {
+ // The extended length prefix is incomplete, so processing stops.
+ let mut buf = [FIN | BINARY_DATA, MASKED | EXTENDED_LEN_2, 0x00];
+ assert_eq!(ws_to_dns(&mut buf, &mut [], 0), Ok((0, 0, 0, 0)));
+}
+
+#[test]
+fn ws_to_dns_eight_byte_length() {
+ // The 8-byte extended length never occurs in DoWS and is rejected.
+ let mut buf = [FIN | BINARY_DATA, MASKED | EXTENDED_LEN_8];
+ assert_eq!(ws_to_dns(&mut buf, &mut [], 0), Err(1009));
+}
+
+#[test]
+fn ws_to_dns_truncated_mask() {
+ // Only 2 of the 4 mask bytes are present, so processing stops.
+ let mut buf = [FIN | BINARY_DATA, MASKED | 2, 0xf0, 0xf0];
+ assert_eq!(ws_to_dns(&mut buf, &mut [], 0), Ok((0, 0, 0, 0)));
+}
+
+#[test]
+fn ws_to_dns_truncated_data() {
+ // The frame declares 4 payload bytes but only 2 are present.
+ let mut buf = [FIN | BINARY_DATA, MASKED | 4, 0xf0, 0xf0, 0xf0, 0xf0, 1, 2];
+ let mut dns_data = [0; 8];
+ assert_eq!(ws_to_dns(&mut buf, &mut dns_data, 0), Ok((0, 0, 0, 0)));
+}
+
+#[test]
+fn ws_to_dns_close() {
+ // A CLOSE frame maps to a normal-closure error.
+ let mut buf = [FIN | CLOSE, MASKED, 0, 0, 0, 0];
+ assert_eq!(ws_to_dns(&mut buf, &mut [], 0), Err(1000));
+}
+
+#[test]
+fn ws_to_dns_ping() {
+ // A PING is answered by a PONG written in place at the front of ws_data.
+ let mut buf = [FIN | PING, MASKED | 2, 0xf0, 0xf0, 0xf0, 0xf0, 1, 2];
+ let mut dns_data = [0; 8];
+ let (translated_size, fragment_end, pong, end) = ws_to_dns(&mut buf, &mut dns_data, 0).unwrap();
+ assert_eq!(translated_size, 0);
+ assert_eq!(fragment_end, 0);
+ assert_eq!(pong, 4);
+ assert_eq!(end, buf.len());
+ assert_eq!(buf[..pong], [FIN | PONG, 2, 0xf1, 0xf2]);
+}
+
+#[test]
+fn ws_to_dns_ping_too_long() {
+ // Ping frames must not carry more than 125 bytes.
+ let mut buf = vec![FIN | PING, MASKED | EXTENDED_LEN_2, 0, 126, 0, 0, 0, 0];
+ buf.extend(std::iter::repeat_n(0, 126));
+ assert_eq!(ws_to_dns(&mut buf, &mut [], 0), Err(1002));
+}
+
+#[test]
+fn ws_to_dns_pong_is_ignored() {
+ // Incoming PONG frames are simply skipped.
+ let mut buf = [FIN | PONG, MASKED | 2, 0xf0, 0xf0, 0xf0, 0xf0, 1, 2];
+ let mut dns_data = [0; 8];
+ let (translated_size, fragment_end, pong, end) = ws_to_dns(&mut buf, &mut dns_data, 0).unwrap();
+ assert_eq!(translated_size, 0);
+ assert_eq!(fragment_end, 0);
+ assert_eq!(pong, 0);
+ assert_eq!(end, buf.len());
+}
+
+#[test]
+fn ws_to_dns_illegal_continuation() {
+ // A continuation frame with no message in progress is illegal.
+ let mut buf = [FIN, MASKED | 2, 0xf0, 0xf0, 0xf0, 0xf0, 1, 2];
+ let mut dns_data = [0; 8];
+ assert_eq!(ws_to_dns(&mut buf, &mut dns_data, 0), Err(1002));
+}
+
+#[test]
+fn ws_to_dns_fragmented_message() {
+ // A binary frame without FIN followed by a continuation frame with FIN
+ // form a single DNS message.
+ let mut fragments = [
+ [BINARY_DATA, MASKED | 2, 0xf0, 0xf0, 0xf0, 0xf0, 1, 2],
+ [FIN, MASKED | 2, 0xf0, 0xf0, 0xf0, 0xf0, 3, 4],
+ ];
+ let buf = fragments.as_flattened_mut();
+ let mut dns_data = [0; 8];
+ let (translated_size, fragment_end, pong, end) = ws_to_dns(buf, &mut dns_data, 0).unwrap();
+ assert_eq!(pong, 0);
+ assert_eq!(translated_size, 6);
+ assert_eq!(fragment_end, translated_size);
+ assert_eq!(end, buf.len());
+ assert_eq!(dns_data[..translated_size], [0, 4, 0xf1, 0xf2, 0xf3, 0xf4]);
+}
+
+#[test]
+fn ws_to_dns_output_full() {
+ // The first message fits, the second does not, so processing stops and
+ // ws_pos is rewound to the start of the unprocessed frame.
+ let mut messages = [
+ [FIN | BINARY_DATA, MASKED | 2, 0xf0, 0xf0, 0xf0, 0xf0, 1, 2],
+ [FIN | BINARY_DATA, MASKED | 2, 0xf0, 0xf0, 0xf0, 0xf0, 1, 2],
+ ];
+ let buf = messages.as_flattened_mut();
+ let mut dns_data = [0; 4];
+ let (translated_size, fragment_end, pong, end) = ws_to_dns(buf, &mut dns_data, 0).unwrap();
+ assert_eq!(pong, 0);
+ assert_eq!(translated_size, 4);
+ assert_eq!(fragment_end, 4);
+ assert_eq!(end, 8);
+ assert_eq!(dns_data[..translated_size], [0, 2, 0xf1, 0xf2]);
+}
+
+#[test]
+fn ws_to_dns_message_too_long() {
+ // Two 65535-byte fragments accumulate into a message that no longer
+ // fits in the u16 DNS length prefix.
+ let mut buf = vec![BINARY_DATA, MASKED | EXTENDED_LEN_2, 0xFF, 0xFF, 0, 0, 0, 0];
+ buf.extend(std::iter::repeat_n(0, 65535));
+ buf.extend_from_slice(&[FIN, MASKED | EXTENDED_LEN_2, 0xFF, 0xFF, 0, 0, 0, 0]);
+ buf.extend(std::iter::repeat_n(0, 65535));
+ // 1 free byte in addition to the partial DNS message from to the first fragment
+ let mut dns_data = vec![0; 65535 + 2 + 1];
+ assert_eq!(ws_to_dns(&mut buf, &mut dns_data, 0), Err(1009));
+}
diff --git a/tests/proxy.rs b/tests/proxy.rs
new file mode 100644
index 0000000..2fd5960
--- /dev/null
+++ b/tests/proxy.rs
@@ -0,0 +1,328 @@
+// SPDX-FileCopyrightText: 2026 Famedly GmbH (info@famedly.com)
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! End-to-end integration tests for the DoWS proxy.
+//!
+//! Each test starts a tiny in-process DNS over TCP server on a random port,
+//! spawns the compiled `dows` proxy binary (which prints its own listening
+//! address on startup), and then talks to the DNS server through the proxy
+//! using a real WebSocket client (`tokio-tungstenite`).
+//!
+//! The proxy treats the DNS payload as opaque bytes and only cares about the
+//! 2-byte big-endian length prefix used by DNS over TCP (RFC 1035 ยง4.2.2), so
+//! the test server implements just that framing rather than pulling in a full
+//! DNS stack.
+
+use std::{
+ io::{BufRead, BufReader},
+ net::{Ipv6Addr, SocketAddr},
+ process::{Child, Command, Stdio},
+};
+
+use futures_util::{SinkExt, StreamExt};
+use nix::{
+ sys::signal::{Signal, kill},
+ unistd::Pid,
+};
+use tokio::{
+ io::{AsyncReadExt, AsyncWriteExt},
+ net::{TcpListener, TcpStream},
+ task::{JoinHandle, JoinSet},
+};
+use tokio_tungstenite::{
+ connect_async,
+ tungstenite::{Message as WsMessage, protocol::frame::coding::CloseCode},
+};
+
+/// Terminates the spawned proxy process when the test finishes (or
+/// panics).
+///
+/// The proxy is asked to exit cleanly with SIGTERM instead of SIGKILL so
+/// that its exit hooks run; coverage instrumentation relies on those to
+/// write the profile data of the child process. SIGKILL is the fallback
+/// in case the proxy fails to shut down on its own.
+struct ChildGuard(Child);
+
+impl Drop for ChildGuard {
+ fn drop(&mut self) {
+ let pid = Pid::from_raw(self.0.id().try_into().expect("pid fits into i32"));
+ let _ = kill(pid, Signal::SIGTERM);
+ let terminated = std::iter::repeat_with(|| {
+ std::thread::sleep(std::time::Duration::from_millis(10));
+ self.0.try_wait()
+ })
+ .take(500)
+ .any(|status| !matches!(status, Ok(None)));
+ if !terminated {
+ let _ = self.0.kill();
+ let _ = self.0.wait();
+ }
+ }
+}
+
+/// A running proxy + DNS server, with the WebSocket URL to reach the DNS
+/// server through the proxy.
+struct Harness {
+ dns_server: JoinHandle<()>,
+ dns_endpoint: SocketAddr,
+ proxy_endpoint: String,
+ ws_base: String,
+ _child: ChildGuard,
+}
+
+impl Harness {
+ async fn start() -> Self {
+ // Start the DNS server on a random TCP port.
+ let listener = TcpListener::bind((Ipv6Addr::LOCALHOST, 0)).await.unwrap();
+ let dns_endpoint = listener.local_addr().unwrap();
+ let dns_server = tokio::spawn(run_dns_server(listener));
+
+ // Spawn the proxy binary, letting the OS pick the port. The proxy prints
+ // its actual listening address on the first line of stdout.
+ let mut child = Command::new(env!("CARGO_BIN_EXE_dows"))
+ .env("DOWS_ALLOWED_UPSTREAMS", "*")
+ .env("DOWS_ALLOWED_ORIGINS", "*")
+ .arg("[::1]:0")
+ .stdin(Stdio::null())
+ .stdout(Stdio::piped())
+ .spawn()
+ .expect("spawn dows proxy binary");
+
+ let mut stdout = BufReader::new(child.stdout.take().expect("capture proxy stdout"));
+ let mut line = String::new();
+ let endpoint = loop {
+ line.clear();
+ stdout.read_line(&mut line).expect("read proxy address");
+ assert!(!line.is_empty(), "dows should print listener address before closing stdout");
+ if let Some(endpoint) = line.strip_prefix("listening on ") {
+ break endpoint.trim().to_owned();
+ }
+ };
+
+ Self {
+ dns_endpoint,
+ ws_base: format!("ws://{endpoint}"),
+ proxy_endpoint: endpoint,
+ dns_server,
+ _child: ChildGuard(child),
+ }
+ }
+
+ fn ws_url(&self) -> String {
+ format!("{}/{}", self.ws_base, self.dns_endpoint)
+ }
+}
+
+/// A minimal DNS over TCP server: for every length-prefixed query it replies
+/// with a length-prefixed response (all-zero except the echoed transaction ID
+/// and the QR bit).
+async fn run_dns_server(listener: TcpListener) {
+ // Aborting the server task drops this set, which in turn cancels all
+ // connection tasks and closes their sockets.
+ let mut connections = JoinSet::new();
+ while let Ok((mut sock, _)) = listener.accept().await {
+ connections.spawn(async move {
+ let mut len = [0; 2];
+ while sock.read_exact(&mut len).await.is_ok() {
+ let mut query = vec![0; usize::from(u16::from_be_bytes(len))];
+ sock.read_exact(&mut query).await?;
+ let Some([a, b]) = query.first_chunk().copied() else {
+ break;
+ };
+ sock.write_all(&[0, 12, a, b, 0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0]).await?;
+ }
+ std::io::Result::Ok(())
+ });
+ }
+}
+
+/// Sends a raw HTTP request to the proxy and returns the response as text,
+/// reading until the proxy closes the connection.
+async fn raw_http_request(proxy_endpoint: &str, request: &str) -> String {
+ let mut sock = TcpStream::connect(proxy_endpoint).await.expect("connect to proxy");
+ sock.write_all(request.as_bytes()).await.expect("send request");
+ let mut response = Vec::new();
+ sock.read_to_end(&mut response).await.expect("read response");
+ String::from_utf8(response).expect("response should be valid UTF-8")
+}
+
+#[tokio::test]
+async fn single_query_is_proxied_to_dns() {
+ let harness = Harness::start().await;
+ let (mut ws, _resp) = connect_async(&harness.ws_url()).await.expect("websocket handshake");
+
+ let query: &[u8] = &[0x12, 0x34, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
+ ws.send(WsMessage::Binary(query.into())).await.expect("send query");
+
+ let reply = ws.next().await.transpose().expect("low level errors not expected");
+ let Some(WsMessage::Binary(response)) = reply else {
+ panic!("expected a binary DNS response, got {reply:?}");
+ };
+
+ assert_eq!(&response[0..2], &[0x12, 0x34], "response should echo the query ID");
+ assert_eq!(response[2] & 0x80, 0x80, "QR bit should mark this as a response");
+
+ ws.close(None).await.expect("close websocket");
+}
+
+#[tokio::test]
+async fn maximum_size_query_is_proxied_to_dns() {
+ let harness = Harness::start().await;
+ let (mut ws, _resp) = connect_async(&harness.ws_url()).await.expect("websocket handshake");
+
+ // The largest message DNS over TCP can carry: the 2-byte big-endian
+ // length prefix caps a message at 65535 bytes.
+ let mut query = vec![0; 65535];
+ query[0] = 0xAB;
+ query[1] = 0xCD;
+ ws.send(WsMessage::Binary(query.into())).await.expect("send query");
+
+ let reply = ws.next().await.transpose().expect("low level errors not expected");
+ let Some(WsMessage::Binary(response)) = reply else {
+ panic!("expected a binary DNS response, got {reply:?}");
+ };
+
+ assert_eq!(&response[0..2], &[0xAB, 0xCD], "response should echo the query ID");
+ assert_eq!(response[2] & 0x80, 0x80, "QR bit should mark this as a response");
+
+ ws.close(None).await.expect("close websocket");
+}
+
+#[tokio::test]
+async fn ping_is_answered_with_pong() {
+ let harness = Harness::start().await;
+ let (mut ws, _resp) = connect_async(&harness.ws_url()).await.expect("websocket handshake");
+
+ let payload = vec![0xDE, 0xAD, 0xBE, 0xEF];
+ ws.send(WsMessage::Ping(payload.clone().into())).await.expect("send ping");
+
+ let reply = ws.next().await.transpose().expect("low level errors not expected");
+ let Some(WsMessage::Pong(pong)) = reply else {
+ panic!("expected a pong, got {reply:?}");
+ };
+ assert_eq!(pong.as_ref(), payload.as_slice());
+
+ ws.close(None).await.expect("close websocket");
+}
+
+#[tokio::test]
+async fn clean_closure_is_handled() {
+ let harness = Harness::start().await;
+ let (mut ws, _resp) = connect_async(&harness.ws_url()).await.expect("websocket handshake");
+
+ // Initiate a clean closing handshake.
+ ws.close(None).await.expect("send close");
+
+ // The proxy should reply with a Close frame and then let the stream end,
+ // without any protocol error.
+ let mut saw_close = false;
+ while let Some(message) = ws.next().await.transpose().expect("low level errors not expected") {
+ if message.is_close() {
+ saw_close = true;
+ }
+ }
+ assert!(saw_close, "expected the proxy to echo a Close frame");
+}
+
+#[tokio::test]
+async fn invalid_upstream_returns_close_with_reason() {
+ let harness = Harness::start().await;
+ // Port 0 is not a connectable endpoint, so the proxy will fail to reach it.
+ let url = format!("{}/localhost:0", harness.ws_base);
+ let (mut ws, _resp) = connect_async(&url).await.expect("websocket handshake");
+
+ // The upgrade succeeds, then the proxy reports the upstream failure with a
+ // Close frame that carries a code and a non-empty reason.
+ let reply = ws.next().await.transpose().expect("low level errors not expected");
+ let Some(WsMessage::Close(frame)) = reply else {
+ panic!("expected a close frame, got {reply:?}");
+ };
+ let frame = frame.expect("close frame should include a code and reason");
+ assert!(!frame.reason.as_str().is_empty(), "close reason should not be empty");
+}
+
+#[tokio::test]
+async fn root_path_returns_info_page() {
+ let harness = Harness::start().await;
+ let response =
+ raw_http_request(&harness.proxy_endpoint, "GET / HTTP/1.1\r\nHost: localhost\r\n\r\n")
+ .await;
+
+ assert!(response.starts_with("HTTP/1.1 200 OK\r\n"), "unexpected response: {response}");
+ assert!(
+ response.contains(concat!("\r\n\r\n", env!("CARGO_PKG_NAME"))),
+ "body should start with the package name: {response}"
+ );
+}
+
+#[tokio::test]
+async fn non_upgrade_request_returns_upgrade_required() {
+ let harness = Harness::start().await;
+ let response = raw_http_request(
+ &harness.proxy_endpoint,
+ &format!("GET /{} HTTP/1.1\r\nHost: localhost\r\n\r\n", harness.dns_endpoint),
+ )
+ .await;
+
+ assert!(
+ response.starts_with("HTTP/1.1 426 Upgrade Required\r\n"),
+ "unexpected response: {response}"
+ );
+ assert!(
+ response.contains("\r\nUpgrade: websocket\r\n"),
+ "response should advertise the websocket upgrade: {response}"
+ );
+}
+
+#[tokio::test]
+async fn upgrade_request_with_body_returns_bad_request() {
+ let harness = Harness::start().await;
+ // A well-formed upgrade request, but with stray body bytes after the
+ // header section. GET requests have no body, and any pipelined data
+ // before the connection switches protocols is bogus.
+ let response = raw_http_request(
+ &harness.proxy_endpoint,
+ &format!(
+ "GET /{} HTTP/1.1\r\n\
+ Host: localhost\r\n\
+ Upgrade: websocket\r\n\
+ Connection: Upgrade\r\n\
+ Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n\
+ Sec-WebSocket-Version: 13\r\n\r\n\
+ bogus",
+ harness.dns_endpoint
+ ),
+ )
+ .await;
+
+ assert!(
+ response.starts_with("HTTP/1.1 400 Bad Request\r\n"),
+ "unexpected response: {response}"
+ );
+}
+
+#[tokio::test]
+async fn upstream_closure_returns_clean_close_frame() {
+ let harness = Harness::start().await;
+ let (mut ws, _resp) = connect_async(&harness.ws_url()).await.expect("websocket handshake");
+
+ // Complete one round trip so the proxy's upstream connection is
+ // established before the DNS server goes away.
+ let query: &[u8] = &[0x56, 0x78, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
+ ws.send(WsMessage::Binary(query.into())).await.expect("send query");
+ let reply = ws.next().await.transpose().expect("low level errors not expected");
+ assert!(matches!(reply, Some(WsMessage::Binary(_))), "expected a DNS response, got {reply:?}");
+
+ // Kill the DNS server; dropping its JoinSet cancels the connection
+ // tasks, closing the proxy's upstream socket.
+ harness.dns_server.abort();
+
+ // The proxy should report the closed upstream with a clean Close frame.
+ let reply = ws.next().await.transpose().expect("low level errors not expected");
+ let Some(WsMessage::Close(frame)) = reply else {
+ panic!("expected a close frame, got {reply:?}");
+ };
+ let frame = frame.expect("close frame should include a code");
+ assert_eq!(frame.code, CloseCode::Normal);
+}
diff --git a/treefmt.toml b/treefmt.toml
new file mode 100644
index 0000000..bfc3951
--- /dev/null
+++ b/treefmt.toml
@@ -0,0 +1,40 @@
+allowMissingFormatter = false
+excludes = [
+ "*.lock",
+ "*.patch",
+ "package-lock.json",
+ "go.mod",
+ "go.sum",
+ ".gitattributes",
+ ".gitignore",
+ ".gitmodules",
+ ".hgignore",
+ ".svnignore",
+ "LICENSE",
+ ".pre-commit-config.yaml",
+ ".github/workflows/build.yml",
+ ".github/workflows/check-pre-commit-hooks.yml",
+ ".github/workflows/tests.yml",
+ ".gitattributes",
+ "treefmt.toml",
+ "rustfmt.toml",
+]
+walk = "git"
+
+[formatter.mdformat]
+command = "mdformat"
+excludes = []
+includes = ["*.md"]
+options = ["--wrap", "80"]
+
+[formatter.nixfmt]
+command = "nixfmt"
+excludes = []
+includes = ["*.nix"]
+options = ["--strict"]
+
+[formatter.rustfmt]
+command = "rustfmt"
+excludes = []
+includes = ["*.rs"]
+options = ["--config", "skip_children=true", "--edition", "2024"]