9 files changed, 1222 insertions, 0 deletions

diff --git a/tests/integration/.gitignore b/tests/integration/.gitignore
new file mode 100644
index 0000000..7a60b85
--- /dev/null
+++ b/tests/integration/.gitignore
@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc
diff --git a/tests/integration/harness.py b/tests/integration/harness.py
new file mode 100644
index 0000000..03a0561
--- /dev/null
+++ b/tests/integration/harness.py
@@ -0,0 +1,308 @@
+"""Starts a real opentracker and talks to it over the wire.
+
+Everything here drives the binary rather than the code, so these tests cover
+what the unit suite cannot reach: the event loop, the HTTP parser and the
+torrent store working together. Run against a sanitizer build and the tracker
+reports its own memory errors, which the teardown turns into test failures.
+"""
+
+import os
+import shutil
+import signal
+import socket
+import struct
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+import urllib.error
+import urllib.parse
+import urllib.request
+
+TRACKER = os.environ.get("OPENTRACKER", os.path.join(os.path.dirname(__file__), "..", "..", "opentracker.debug"))
+
+
+def bdecode(data):
+    """Enough bencode for what a tracker answers."""
+
+    def value(i):
+        if data[i : i + 1] == b"d":
+            i, out = i + 1, {}
+            while data[i : i + 1] != b"e":
+                i, key = value(i)
+                i, out[key] = value(i)
+            return i + 1, out
+        if data[i : i + 1] == b"l":
+            i, out = i + 1, []
+            while data[i : i + 1] != b"e":
+                i, item = value(i)
+                out.append(item)
+            return i + 1, out
+        if data[i : i + 1] == b"i":
+            end = data.index(b"e", i)
+            return end + 1, int(data[i + 1 : end])
+        colon = data.index(b":", i)
+        length = int(data[i:colon])
+        return colon + 1 + length, data[colon + 1 : colon + 1 + length]
+
+    return value(0)[1]
+
+
+def free_port():
+    probe = socket.socket()
+    probe.bind(("127.0.0.1", 0))
+    port = probe.getsockname()[1]
+    probe.close()
+    return port
+
+
+class Tracker:
+    """One tracker process, listening on loopback."""
+
+    def __init__(self, extra_config="", files=None):
+        self.port = free_port()
+        self.dir = tempfile.mkdtemp(prefix="ot-integration-")
+        self.log = None
+        self.process = None
+        try:
+            for name, content in (files or {}).items():
+                with open(os.path.join(self.dir, name), "wb") as handle:
+                    handle.write(content)
+            self.config = os.path.join(self.dir, "opentracker.conf")
+            with open(self.config, "w") as handle:
+                handle.write("listen.tcp 127.0.0.1:%d\n" % self.port)
+                handle.write("listen.udp 127.0.0.1:%d\n" % self.port)
+                handle.write(extra_config.replace("{dir}", self.dir))
+            self.log = open(os.path.join(self.dir, "tracker.log"), "w+b")
+            # Leak detection is left at the sanitizer's own default, which is on
+            # where LeakSanitizer exists and off where it does not. Asking for it
+            # by name makes the tracker refuse to start on macOS and FreeBSD.
+            environment = dict(os.environ, ASAN_OPTIONS="abort_on_error=0")
+            self.process = subprocess.Popen([TRACKER, "-f", self.config], stdout=self.log, stderr=self.log, env=environment)
+            self._wait_for_port()
+        except BaseException:
+            self._cleanup()
+            raise
+
+    def _cleanup(self):
+        """Close what we opened and take the scratch directory with it."""
+        if self.process is not None and self.process.poll() is None:
+            self.process.kill()
+            self.process.wait()
+        if self.log is not None:
+            self.log.close()
+            self.log = None
+        shutil.rmtree(self.dir, ignore_errors=True)
+
+    def _wait_for_port(self):
+        for _ in range(200):
+            if self.process.poll() is not None:
+                raise AssertionError("tracker exited at once:\n" + self.output())
+            try:
+                probe = socket.create_connection(("127.0.0.1", self.port), timeout=0.2)
+                probe.close()
+                return
+            except OSError:
+                time.sleep(0.05)
+        raise AssertionError("tracker never listened on %d:\n%s" % (self.port, self.output()))
+
+    def output(self):
+        if self.log is None:
+            return ""
+        self.log.flush()
+        self.log.seek(0)
+        return self.log.read().decode("utf-8", "replace")
+
+    def stop(self):
+        """Returns anything the tracker complained about on the way out.
+
+        The interrupt rather than a kill is what makes the leak check work at
+        all: LeakSanitizer reports from an exit handler, so a killed tracker
+        reports nothing and the suite passes over leaks it never looked for.
+        """
+        if self.process is not None and self.process.poll() is None:
+            self.process.send_signal(signal.SIGINT)
+            try:
+                self.process.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                self.process.kill()
+                self.process.wait()
+        complaints = [
+            line
+            for line in self.output().splitlines()
+            if "Sanitizer" in line or "runtime error" in line or line.startswith("ERROR")
+        ]
+        self._cleanup()
+        return complaints
+
+    # ----------------------------------------------------------- over http
+
+    def get(self, path, timeout=10):
+        return urllib.request.urlopen("http://127.0.0.1:%d%s" % (self.port, path), timeout=timeout).read()
+
+    def announce(self, info_hash, peer_id=b"-OT0001-aaaaaaaaaaaa", port=6881, left=0, **extra):
+        query = {
+            "info_hash": urllib.parse.quote_from_bytes(info_hash, safe=""),
+            "peer_id": urllib.parse.quote_from_bytes(peer_id, safe=""),
+            "port": port,
+            "left": left,
+        }
+        query.update(extra)
+        return bdecode(self.get("/announce?" + "&".join("%s=%s" % item for item in query.items())))
+
+    def scrape(self, info_hash):
+        return bdecode(self.get("/scrape?info_hash=" + urllib.parse.quote_from_bytes(info_hash, safe="")))
+
+    def stats(self, mode):
+        return self.get("/stats?mode=" + mode)
+
+    def get_with_headers(self, path, headers=None, timeout=10):
+        """The body and the response headers, for the compressed answers."""
+        request = urllib.request.Request("http://127.0.0.1:%d%s" % (self.port, path), headers=headers or {})
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return response.read(), dict(response.headers)
+
+    def torrent_count(self):
+        return int(self.stats("torr").split()[0])
+
+    # ------------------------------------------------------------ over udp
+
+    def udp_connect(self):
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        sock.settimeout(5)
+        sock.sendto(struct.pack(">QII", 0x41727101980, 0, 1), ("127.0.0.1", self.port))
+        answer = sock.recv(2048)
+        action, _, connection_id = struct.unpack(">IIQ", answer[:16])
+        assert action == 0, "udp connect answered action %d" % action
+        return sock, connection_id
+
+    def udp_announce(self, sock, connection_id, info_hash, left=0, event=0, port=6881, numwant=-1):
+        sock.sendto(
+            struct.pack(
+                ">QII20s20sQQQIIIiH", connection_id, 1, 2, info_hash, b"p" * 20, 0, left, 0, event, 0, 0, numwant, port
+            ),
+            ("127.0.0.1", self.port),
+        )
+        answer = sock.recv(2048)
+        action, _, interval, leechers, seeders = struct.unpack(">IIIII", answer[:20])
+        assert action == 1, "udp announce answered action %d" % action
+        return {"interval": interval, "leechers": leechers, "seeders": seeders, "peers": answer[20:]}
+
+    def udp_scrape(self, sock, connection_id, hashes):
+        """One (seeders, completed, leechers) triple per hash, in order."""
+        sock.sendto(struct.pack(">QII", connection_id, 2, 3) + b"".join(hashes), ("127.0.0.1", self.port))
+        answer = sock.recv(2048)
+        action, _ = struct.unpack(">II", answer[:8])
+        assert action == 2, "udp scrape answered action %d" % action
+        return [struct.unpack(">III", answer[8 + 12 * i : 20 + 12 * i]) for i in range(len(hashes))]
+
+    def connect(self):
+        """A connection the caller drives and closes."""
+        return Connection(self.port)
+
+    def udp_raw(self, payload, timeout=1.0):
+        """Sends a packet exactly as given. Returns the answer, or None if the
+        tracker chose to say nothing, which is how it treats a broken one."""
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        sock.settimeout(timeout)
+        try:
+            sock.sendto(payload, ("127.0.0.1", self.port))
+            try:
+                return sock.recv(2048)
+            except socket.timeout:
+                return None
+        finally:
+            sock.close()
+
+
+class Connection:
+    """One HTTP connection the caller keeps open, which urllib will not do.
+
+    Reads exactly one reply at a time, so a test can tell "the tracker
+    answered and kept the socket" from "the tracker answered and hung up"."""
+
+    def __init__(self, port, timeout=5):
+        self.sock = socket.create_connection(("127.0.0.1", port), timeout=timeout)
+        self.sock.settimeout(timeout)
+        self.buffer = b""
+
+    def send(self, path, connection="Keep-Alive", version="1.1"):
+        request = "GET %s HTTP/%s\r\nHost: tracker\r\n" % (path, version)
+        if connection is not None:
+            request += "Connection: %s\r\n" % connection
+        self.sock.sendall((request + "\r\n").encode())
+
+    def _fill(self):
+        chunk = self.sock.recv(65536)
+        if not chunk:
+            raise EOFError("the tracker closed the connection")
+        self.buffer += chunk
+
+    def reply(self):
+        """The one complete reply at the front of the stream, headers and body."""
+        while b"\r\n\r\n" not in self.buffer:
+            self._fill()
+        head, rest = self.buffer.split(b"\r\n\r\n", 1)
+        headers = {}
+        for line in head.split(b"\r\n")[1:]:
+            name, _, value = line.partition(b":")
+            headers[name.strip().lower()] = value.strip()
+
+        if headers.get(b"transfer-encoding") == b"chunked":
+            while not rest.endswith(b"0\r\n\r\n"):
+                self.buffer = head + b"\r\n\r\n" + rest
+                self._fill()
+                rest = self.buffer.split(b"\r\n\r\n", 1)[1]
+            body, self.buffer = rest, b""
+        else:
+            length = int(headers.get(b"content-length", b"0"))
+            while len(rest) < length:
+                self.buffer = head + b"\r\n\r\n" + rest
+                self._fill()
+                rest = self.buffer.split(b"\r\n\r\n", 1)[1]
+            body, self.buffer = rest[:length], rest[length:]
+        return head.split(b"\r\n")[0], headers, body
+
+    def is_open(self):
+        """True if the tracker is still holding the connection."""
+        try:
+            self.sock.settimeout(0.4)
+            return self.sock.recv(1) != b""
+        except socket.timeout:
+            return True
+        except OSError:
+            return False
+        finally:
+            try:
+                self.sock.settimeout(5)
+            except OSError:
+                pass
+
+    def close(self):
+        self.sock.close()
+
+
+class TrackerTestCase(unittest.TestCase):
+    """Gives every test its own tracker and fails it on any sanitizer output."""
+
+    config = ""
+    files = None
+
+    def setUp(self):
+        self.tracker = Tracker(self.config, self.files)
+
+    def tearDown(self):
+        # A connection the test closed is only reaped when the event loop gets
+        # round to it, and a cookie still held at exit reads as a leak. One
+        # more request puts us behind that work in the loop's queue.
+        try:
+            self.tracker.torrent_count()
+        except Exception:
+            pass
+        complaints = self.tracker.stop()
+        self.assertEqual(complaints, [], "the tracker reported:\n" + "\n".join(complaints))
+
+    def hash_for(self, name):
+        """A distinct info hash per test, so tests cannot leak into each other."""
+        return (name.encode() + b"\0" * 20)[:20]
diff --git a/tests/integration/test_accesslist.py b/tests/integration/test_accesslist.py
new file mode 100644
index 0000000..41ff654
--- /dev/null
+++ b/tests/integration/test_accesslist.py
@@ -0,0 +1,100 @@
+"""The blacklist, loaded from a file at startup.
+
+A blacklisted info hash must be refused at both the announce and the scrape
+entry, and the file parser has to cope with the shapes an operator actually
+produces: an empty file, and a last line with no newline after it.
+"""
+
+import struct
+import unittest
+
+from harness import TrackerTestCase
+
+BLOCKED = b"\xb1" * 20
+ALLOWED = b"\xa1" * 20
+
+
+def listing(*hashes):
+    return b"".join(h.hex().upper().encode() + b"\n" for h in hashes)
+
+
+class Blacklist(TrackerTestCase):
+    config = "access.blacklist {dir}/blacklist\n"
+    files = {"blacklist": listing(BLOCKED)}
+
+    def test_a_blacklisted_hash_is_refused(self):
+        answer = self.tracker.announce(BLOCKED, port=6881, left=0)
+        self.assertIn(b"failure reason", answer)
+        self.assertIn(b"not authorized", answer[b"failure reason"])
+
+    def test_a_blacklisted_hash_never_becomes_a_torrent(self):
+        before = self.tracker.torrent_count()
+        self.tracker.announce(BLOCKED, port=6881, left=0)
+        self.assertEqual(self.tracker.torrent_count(), before, "the refused hash was stored anyway")
+
+    def test_any_other_hash_is_served(self):
+        answer = self.tracker.announce(ALLOWED, port=6881, left=0)
+        self.assertNotIn(b"failure reason", answer)
+        self.assertEqual(answer[b"complete"], 1)
+
+    def test_the_block_is_an_error_packet_over_udp(self):
+        """BEP 15 has an error action, which is what a refusal should use.
+        It used to answer the announce header with no body behind it, a
+        packet too short for any client to read."""
+        sock, connection_id = self.tracker.udp_connect()
+        sock.close()
+        request = struct.pack(
+            ">QII20s20sQQQIIIiH", connection_id, 1, 7, BLOCKED, b"p" * 20, 0, 0, 0, 0, 0, 0, -1, 6881
+        )
+        answer = self.tracker.udp_raw(request)
+        self.assertIsNotNone(answer)
+        action, transaction = struct.unpack(">II", answer[:8])
+        self.assertEqual(action, 3, "action 3 is the error packet")
+        self.assertEqual(transaction, 7)
+        self.assertIn(b"not authorized", answer[8:])
+
+    def test_a_blocked_hash_is_not_stored_when_it_arrives_over_udp(self):
+        sock, connection_id = self.tracker.udp_connect()
+        sock.close()
+        self.tracker.udp_raw(
+            struct.pack(">QII20s20sQQQIIIiH", connection_id, 1, 8, BLOCKED, b"p" * 20, 0, 0, 0, 0, 0, 0, -1, 6881)
+        )
+        self.assertEqual(self.tracker.torrent_count(), 0)
+
+
+class BlacklistWithoutTrailingNewline(TrackerTestCase):
+    """A single hash with no newline after it used to size the list at zero
+    and then write into it, which took the tracker down before it listened."""
+
+    config = "access.blacklist {dir}/blacklist\n"
+    files = {"blacklist": BLOCKED.hex().upper().encode()}
+
+    def test_the_last_line_counts_even_without_its_newline(self):
+        answer = self.tracker.announce(BLOCKED, port=6881, left=0)
+        self.assertIn(b"failure reason", answer)
+
+    def test_and_the_tracker_still_serves_everything_else(self):
+        self.assertEqual(self.tracker.announce(ALLOWED, port=6881, left=0)[b"complete"], 1)
+
+
+class EmptyBlacklist(TrackerTestCase):
+    config = "access.blacklist {dir}/blacklist\n"
+    files = {"blacklist": b""}
+
+    def test_an_empty_file_blocks_nothing_and_starts_cleanly(self):
+        self.assertEqual(self.tracker.announce(BLOCKED, port=6881, left=0)[b"complete"], 1)
+        self.assertEqual(self.tracker.announce(ALLOWED, port=6882, left=0)[b"complete"], 1)
+
+
+class MissingBlacklist(TrackerTestCase):
+    """The file is named but absent: the tracker warns and serves everything,
+    because it may be created later."""
+
+    config = "access.blacklist {dir}/absent\n"
+
+    def test_a_missing_file_blocks_nothing(self):
+        self.assertEqual(self.tracker.announce(BLOCKED, port=6881, left=0)[b"complete"], 1)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/integration/test_announce.py b/tests/integration/test_announce.py
new file mode 100644
index 0000000..ffbc07b
--- /dev/null
+++ b/tests/integration/test_announce.py
@@ -0,0 +1,129 @@
+"""What a peer's announce does to the swarm it joins."""
+
+import os
+import socket
+import sys
+import unittest
+
+sys.path.insert(0, os.path.dirname(__file__))
+from harness import TrackerTestCase
+
+
+def peers_of(answer, key=b"peers"):
+    """Compact peer list as a list of (address, port)."""
+    blob, out = answer.get(key, b""), []
+    size = 6 if key == b"peers" else 18
+    for offset in range(0, len(blob), size):
+        entry = blob[offset : offset + size]
+        address = socket.inet_ntop(socket.AF_INET if size == 6 else socket.AF_INET6, entry[:-2])
+        out.append((address, entry[-2] << 8 | entry[-1]))
+    return out
+
+
+class AnnounceLifetime(TrackerTestCase):
+    config = ""
+
+    def test_a_leecher_is_counted_as_incomplete(self):
+        info_hash = self.hash_for("leecher")
+        answer = self.tracker.announce(info_hash, left=100)
+        self.assertEqual(answer[b"complete"], 0)
+        self.assertEqual(answer[b"incomplete"], 1)
+
+    def test_no_bytes_left_means_seeding(self):
+        info_hash = self.hash_for("seeder")
+        answer = self.tracker.announce(info_hash, left=0)
+        self.assertEqual(answer[b"complete"], 1)
+        self.assertEqual(answer[b"incomplete"], 0)
+
+    def test_a_peer_that_finishes_moves_from_one_column_to_the_other(self):
+        info_hash = self.hash_for("finishes")
+        peer_id = b"-OT0001-finisher0001"
+        self.tracker.announce(info_hash, peer_id=peer_id, left=100)
+        self.assertEqual(self.tracker.announce(info_hash, peer_id=peer_id, left=100)[b"incomplete"], 1)
+
+        answer = self.tracker.announce(info_hash, peer_id=peer_id, left=0, event="completed")
+        self.assertEqual(answer[b"complete"], 1, "the peer should now count as a seeder")
+        self.assertEqual(answer[b"incomplete"], 0, "and no longer as a leecher")
+
+    def test_stopped_removes_the_peer(self):
+        info_hash = self.hash_for("stopped")
+        peer_id = b"-OT0001-leaves000001"
+        self.tracker.announce(info_hash, peer_id=peer_id, left=100)
+        self.assertEqual(self.tracker.scrape(info_hash)[b"files"][info_hash][b"incomplete"], 1)
+
+        self.tracker.announce(info_hash, peer_id=peer_id, left=100, event="stopped")
+        self.assertEqual(
+            self.tracker.scrape(info_hash)[b"files"][info_hash][b"incomplete"], 0, "the peer should be gone"
+        )
+
+    def test_the_same_peer_announcing_twice_is_still_one_peer(self):
+        info_hash = self.hash_for("twice")
+        peer_id = b"-OT0001-repeats00001"
+        for _ in range(5):
+            answer = self.tracker.announce(info_hash, peer_id=peer_id, left=100)
+        self.assertEqual(answer[b"incomplete"], 1, "re-announcing must not duplicate the peer")
+
+    def test_a_peer_is_its_address_and_port_not_its_peer_id(self):
+        """Two announces from one address and port are one peer, whatever
+        peer_id they carry, because that pair is the whole identity."""
+        info_hash = self.hash_for("identity")
+        self.tracker.announce(info_hash, peer_id=b"-OT0001-a00000000001", port=6881, left=100)
+        answer = self.tracker.announce(info_hash, peer_id=b"-OT0001-b00000000002", port=6881, left=100)
+        self.assertEqual(answer[b"incomplete"], 1, "same address and port, so still one peer")
+
+        answer = self.tracker.announce(info_hash, peer_id=b"-OT0001-c00000000003", port=6882, left=100)
+        self.assertEqual(answer[b"incomplete"], 2, "a different port makes a different peer")
+
+    def test_a_downloaded_count_is_kept(self):
+        info_hash = self.hash_for("downloaded")
+        self.tracker.announce(info_hash, port=7001, left=0, event="completed")
+        self.tracker.announce(info_hash, port=7002, left=0, event="completed")
+        self.assertEqual(self.tracker.scrape(info_hash)[b"files"][info_hash][b"downloaded"], 2)
+
+    def test_a_peer_is_given_the_whole_swarm_including_itself(self):
+        """opentracker does not filter the announcing peer out of its own
+        answer. Clients are expected to ignore themselves."""
+        info_hash = self.hash_for("sees")
+        self.tracker.announce(info_hash, port=1111, left=100)
+        answer = self.tracker.announce(info_hash, port=2222, left=100)
+
+        ports = sorted(port for _, port in peers_of(answer))
+        self.assertEqual(ports, [1111, 2222])
+
+    def test_an_unknown_torrent_scrapes_as_empty(self):
+        answer = self.tracker.scrape(self.hash_for("never-seen"))
+        self.assertEqual(answer[b"files"], {}, "a torrent nobody announced has no entry")
+
+
+class AnnounceRejects(TrackerTestCase):
+    def assert_rejected(self, query):
+        import urllib.error
+
+        with self.assertRaises(urllib.error.HTTPError) as caught:
+            self.tracker.get("/announce?" + query)
+        self.assertEqual(caught.exception.code, 400)
+
+    def test_a_short_info_hash_is_rejected(self):
+        self.assert_rejected("info_hash=tooshort&peer_id=" + "b" * 20 + "&port=6881&left=0")
+
+    def test_a_missing_info_hash_answers_a_failure_reason(self):
+        """Not a 400: the tracker answers 200 with a bencoded complaint, so
+        that a client shows the message to its user."""
+        from harness import bdecode
+
+        answer = bdecode(self.tracker.get("/announce?peer_id=" + "b" * 20 + "&port=6881&left=0"))
+        self.assertIn(b"failure reason", answer)
+        self.assertIn(b"info_hash", answer[b"failure reason"])
+
+    def test_a_port_out_of_range_is_rejected(self):
+        self.assert_rejected("info_hash=" + "a" * 20 + "&peer_id=" + "b" * 20 + "&port=65536&left=0")
+
+    def test_a_port_that_is_not_a_number_is_rejected(self):
+        self.assert_rejected("info_hash=" + "a" * 20 + "&peer_id=" + "b" * 20 + "&port=abc&left=0")
+
+    def test_two_info_hashes_are_rejected(self):
+        self.assert_rejected("info_hash=" + "a" * 20 + "&info_hash=" + "c" * 20 + "&peer_id=" + "b" * 20 + "&port=6881&left=0")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/integration/test_dualstack.py b/tests/integration/test_dualstack.py
new file mode 100644
index 0000000..cd5ba7d
--- /dev/null
+++ b/tests/integration/test_dualstack.py
@@ -0,0 +1,89 @@
+"""A tracker serving both families from one socket.
+
+These need WANT_IP_FROM_QUERY_STRING so a peer's address can be dictated
+rather than being whatever loopback the test happened to come from.
+"""
+
+import os
+import socket
+import sys
+import unittest
+
+sys.path.insert(0, os.path.dirname(__file__))
+from harness import TrackerTestCase
+
+
+def addresses(answer, key):
+    blob, out = answer.get(key, b""), []
+    size = 6 if key == b"peers" else 18
+    for offset in range(0, len(blob), size):
+        entry = blob[offset : offset + size]
+        out.append(socket.inet_ntop(socket.AF_INET if size == 6 else socket.AF_INET6, entry[:-2]))
+    return out
+
+
+class DualStack(TrackerTestCase):
+    def test_an_ipv4_peer_lands_in_the_v4_list(self):
+        info_hash = self.hash_for("v4only")
+        self.tracker.announce(info_hash, ip="10.1.2.3", port=5001, left=100)
+        answer = self.tracker.announce(info_hash, ip="10.1.2.4", port=5002, left=100)
+
+        self.assertEqual(sorted(addresses(answer, b"peers")), ["10.1.2.3", "10.1.2.4"])
+        self.assertEqual(addresses(answer, b"peers6"), [], "no v6 peer was announced")
+
+    def test_an_ipv6_peer_lands_in_the_v6_list(self):
+        info_hash = self.hash_for("v6only")
+        self.tracker.announce(info_hash, ip="2001:db8::1", port=5001, left=100)
+        answer = self.tracker.announce(info_hash, ip="2001:db8::2", port=5002, left=100)
+
+        self.assertEqual(sorted(addresses(answer, b"peers6")), ["2001:db8::1", "2001:db8::2"])
+        self.assertEqual(addresses(answer, b"peers"), [], "no v4 peer was announced")
+
+    def test_the_two_families_are_kept_apart_but_both_returned(self):
+        info_hash = self.hash_for("both")
+        self.tracker.announce(info_hash, ip="10.9.9.9", port=6001, left=100)
+        answer = self.tracker.announce(info_hash, ip="2001:db8::9", port=6002, left=100)
+
+        self.assertEqual(addresses(answer, b"peers"), ["10.9.9.9"])
+        self.assertEqual(addresses(answer, b"peers6"), ["2001:db8::9"])
+
+    def test_a_v4_mapped_address_is_the_same_peer_as_the_plain_one(self):
+        info_hash = self.hash_for("v4mapped")
+        self.tracker.announce(info_hash, ip="10.5.5.5", port=7001, left=100)
+        answer = self.tracker.announce(info_hash, ip="::ffff:10.5.5.5", port=7001, left=100)
+
+        self.assertEqual(answer[b"incomplete"], 1, "the same address written two ways is one peer")
+        self.assertEqual(addresses(answer, b"peers"), ["10.5.5.5"], "and it is held as v4")
+
+    def test_the_two_families_count_into_one_swarm(self):
+        info_hash = self.hash_for("counts")
+        self.tracker.announce(info_hash, ip="10.4.4.4", port=8001, left=0)
+        answer = self.tracker.announce(info_hash, ip="2001:db8::4", port=8002, left=100)
+
+        self.assertEqual(answer[b"complete"], 1)
+        self.assertEqual(answer[b"incomplete"], 1)
+        self.assertEqual(self.tracker.scrape(info_hash)[b"files"][info_hash][b"complete"], 1)
+
+    def test_stopped_removes_only_the_family_it_came_from(self):
+        info_hash = self.hash_for("stopfamily")
+        self.tracker.announce(info_hash, ip="10.3.3.3", port=9001, left=100)
+        self.tracker.announce(info_hash, ip="2001:db8::3", port=9002, left=100)
+        self.tracker.announce(info_hash, ip="10.3.3.3", port=9001, left=100, event="stopped")
+
+        answer = self.tracker.announce(info_hash, ip="2001:db8::33", port=9003, left=100)
+        self.assertEqual(addresses(answer, b"peers"), [], "the v4 peer left")
+        self.assertIn("2001:db8::3", addresses(answer, b"peers6"), "the v6 one stayed")
+
+    def test_a_malformed_address_is_rejected(self):
+        import urllib.error
+
+        # The whole field has to be the address: a prefix that happens to
+        # parse would quietly record the peer somewhere else
+        for bad in ("999.1.2.3", "nonsense", "2001:db8:::1", "10.1.2.3.4", "10.1.2.3junk", "2001:db8::1%eth0"):
+            with self.assertRaises(urllib.error.HTTPError, msg="ip=%s should be refused" % bad) as caught:
+                self.tracker.announce(self.hash_for("badip"), ip=bad, port=6881, left=0)
+            self.assertEqual(caught.exception.code, 400)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/integration/test_fullscrape.py b/tests/integration/test_fullscrape.py
new file mode 100644
index 0000000..be7b502
--- /dev/null
+++ b/tests/integration/test_fullscrape.py
@@ -0,0 +1,146 @@
+"""The full scrape, in every format the tracker offers.
+
+Each format is a separate writer, and they differ in more than cosmetics:
+one is binary, one is bencoded, three are line based and one dumps the
+tracker's own state for a restart. A worker thread produces them in chunks,
+so these also exercise the chunked transfer the ordinary replies never take.
+"""
+
+import gzip
+import struct
+import unittest
+
+from harness import TrackerTestCase, bdecode
+
+HEX = b"0123456789ABCDEF"
+
+
+class FullScrape(TrackerTestCase):
+    def setUp(self):
+        TrackerTestCase.setUp(self)
+        self.seeding = self.hash_for("fsA")
+        self.leeching = self.hash_for("fsB")
+        self.tracker.announce(self.seeding, port=6001, left=0)
+        self.tracker.announce(self.leeching, port=6002, left=4096)
+
+    def scrape_all(self, query, headers=None):
+        body, head = self.tracker.get_with_headers(query, headers)
+        if head.get("Content-Encoding") == "gzip":
+            body = gzip.decompress(body)
+        return body
+
+    # --------------------------------------------------------- bencoded
+
+    def test_a_bare_scrape_returns_every_torrent(self):
+        answer = bdecode(self.scrape_all("/scrape"))
+        self.assertIn(self.seeding, answer[b"files"])
+        self.assertIn(self.leeching, answer[b"files"])
+        self.assertEqual(answer[b"files"][self.seeding][b"complete"], 1)
+        self.assertEqual(answer[b"files"][self.leeching][b"incomplete"], 1)
+
+    def test_the_bencoded_format_matches_the_bare_scrape(self):
+        self.assertEqual(bdecode(self.scrape_all("/stats?mode=tpbs&format=ben")), bdecode(self.scrape_all("/scrape")))
+
+    def test_a_full_scrape_can_be_gzipped(self):
+        plain = self.scrape_all("/scrape")
+        body, head = self.tracker.get_with_headers("/scrape", {"Accept-Encoding": "gzip"})
+        self.assertEqual(head.get("Content-Encoding"), "gzip")
+        self.assertEqual(gzip.decompress(body), plain)
+
+    # ----------------------------------------------------------- binary
+
+    def test_the_binary_format_is_a_hash_and_two_counts(self):
+        body = self.scrape_all("/stats?mode=tpbs&format=bin")
+        self.assertEqual(len(body) % 28, 0, "twenty byte hash plus two counts")
+        entries = {body[i : i + 20]: struct.unpack(">II", body[i + 20 : i + 28]) for i in range(0, len(body), 28)}
+        self.assertEqual(entries[self.seeding], (1, 0), "one seeder, no leechers")
+        self.assertEqual(entries[self.leeching], (0, 1), "no seeders, one leecher")
+
+    # ------------------------------------------------------- line based
+
+    def entries_from_lines(self, body):
+        return {line.split(b":")[0]: line.split(b":")[1:] for line in body.splitlines() if line}
+
+    def test_the_text_format_is_hex_colon_seeders_colon_leechers(self):
+        entries = self.entries_from_lines(self.scrape_all("/stats?mode=tpbs&format=txt"))
+        self.assertEqual(entries[self.seeding.hex().upper().encode()], [b"1", b"0"])
+        self.assertEqual(entries[self.leeching.hex().upper().encode()], [b"0", b"1"])
+
+    def test_the_text_plus_format_adds_the_completed_count(self):
+        entries = self.entries_from_lines(self.scrape_all("/stats?mode=tpbs&format=txtp"))
+        self.assertEqual(entries[self.seeding.hex().upper().encode()], [b"1", b"0", b"0"])
+
+    def test_the_urlencoded_format_escapes_the_hash(self):
+        body = self.scrape_all("/stats?mode=tpbs&format=url")
+        lines = [line for line in body.splitlines() if line]
+        self.assertEqual(len(lines), 2)
+        for line in lines:
+            escaped = line.rsplit(b":", 2)[0]
+            self.assertIn(b"%", escaped, "these hashes are mostly unprintable bytes")
+
+    def test_the_state_dump_carries_a_base_time_rather_than_a_peer_count(self):
+        """What a restart reads back, so its second column is the torrent's
+        own clock and not a count of anybody."""
+        entries = self.entries_from_lines(self.scrape_all("/stats?mode=statedump"))
+        self.assertIn(self.seeding.hex().upper().encode(), entries)
+        base, completed = entries[self.seeding.hex().upper().encode()]
+        self.assertGreater(int(base), 0)
+        self.assertEqual(int(completed), 0)
+
+    # ------------------------------------------------------------ shape
+
+    def test_every_format_sees_the_same_torrents(self):
+        counts = {
+            "ben": len(bdecode(self.scrape_all("/stats?mode=tpbs&format=ben"))[b"files"]),
+            "bin": len(self.scrape_all("/stats?mode=tpbs&format=bin")) // 28,
+            "txt": len(self.entries_from_lines(self.scrape_all("/stats?mode=tpbs&format=txt"))),
+            "txtp": len(self.entries_from_lines(self.scrape_all("/stats?mode=tpbs&format=txtp"))),
+            "url": len([l for l in self.scrape_all("/stats?mode=tpbs&format=url").splitlines() if l]),
+        }
+        self.assertEqual(set(counts.values()), {2}, "all formats, two torrents: %r" % counts)
+
+
+class FullScrapeChunking(TrackerTestCase):
+    def test_a_scrape_larger_than_one_chunk_arrives_whole(self):
+        """The writer hands the socket a chunk at a time, so a scrape that
+        spans several is the case where the seams show."""
+        for i in range(400):
+            self.tracker.announce(struct.pack(">I", i) + b"\0" * 16, port=7000 + i, left=0)
+        answer = bdecode(self.tracker.get("/scrape"))
+        self.assertEqual(len(answer[b"files"]), 400)
+
+
+if __name__ == "__main__":
+    unittest.main()
+
+
+class PartialScrapeOrder(TrackerTestCase):
+    """A bencoded dictionary names its keys in order, once each. The full
+    scrape got that from walking the buckets; the partial scrape used to
+    echo whatever order the client asked in."""
+
+    def setUp(self):
+        TrackerTestCase.setUp(self)
+        self.hashes = [bytes([i]) + b"\0" * 19 for i in (9, 1, 5, 3, 7)]
+        for i, h in enumerate(self.hashes):
+            self.tracker.announce(h, port=6001 + i, left=0)
+
+    def scrape_many(self, hashes):
+        import urllib.parse
+
+        query = "&".join("info_hash=" + urllib.parse.quote_from_bytes(h, safe="") for h in hashes)
+        return bdecode(self.tracker.get("/scrape?" + query))
+
+    def test_the_keys_come_back_in_order(self):
+        answer = self.scrape_many(self.hashes)
+        self.assertEqual(list(answer[b"files"]), sorted(self.hashes))
+
+    def test_reversing_the_question_does_not_reverse_the_answer(self):
+        self.assertEqual(
+            list(self.scrape_many(self.hashes[::-1])[b"files"]), list(self.scrape_many(self.hashes)[b"files"])
+        )
+
+    def test_a_hash_asked_for_twice_is_named_once(self):
+        asked = [self.hashes[0], self.hashes[1], self.hashes[0]]
+        answer = self.scrape_many(asked)
+        self.assertEqual(list(answer[b"files"]), sorted({self.hashes[0], self.hashes[1]}))
diff --git a/tests/integration/test_keepalive.py b/tests/integration/test_keepalive.py
new file mode 100644
index 0000000..01f02a5
--- /dev/null
+++ b/tests/integration/test_keepalive.py
@@ -0,0 +1,111 @@
+"""Holding a connection open across several requests.
+
+The reply path has two shapes. A small answer goes out in one write and the
+connection is done with immediately. A large one is queued and finishes on a
+later pass through the event loop, by which time the workstruct that served
+the request has moved on, so whether to keep the connection has to be
+remembered on the connection itself.
+"""
+
+import unittest
+import urllib.parse
+
+from harness import TrackerTestCase, bdecode
+
+
+class KeepAlive(TrackerTestCase):
+    def announce_path(self, name, port=6881):
+        return "/announce?info_hash=%s&peer_id=%s&port=%d&left=0" % (
+            urllib.parse.quote_from_bytes(self.hash_for(name), safe=""),
+            "x" * 20,
+            port,
+        )
+
+    def test_two_requests_over_one_connection(self):
+        c = self.tracker.connect()
+        try:
+            c.send(self.announce_path("kaA"))
+            status, _, first = c.reply()
+            self.assertIn(b"200", status)
+            c.send(self.announce_path("kaB"))
+            status, _, second = c.reply()
+            self.assertIn(b"200", status)
+            self.assertIn(b"complete", bdecode(second))
+        finally:
+            c.close()
+
+    def test_close_ends_the_connection(self):
+        c = self.tracker.connect()
+        try:
+            c.send(self.announce_path("kaclose"), connection="close")
+            c.reply()
+            self.assertFalse(c.is_open(), "the tracker was asked to hang up")
+        finally:
+            c.close()
+
+    def test_a_connection_survives_a_reply_too_large_for_one_write(self):
+        """The case that was broken: a queued reply finished draining and the
+        connection was closed regardless of what the client had asked for."""
+        for i in range(400):
+            self.tracker.announce(bytes([i // 256, i % 256]) + b"\0" * 18, port=7000 + i, left=0)
+
+        c = self.tracker.connect()
+        try:
+            c.send("/scrape")
+            status, headers, body = c.reply()
+            self.assertIn(b"200", status)
+            self.assertGreater(len(body), 16384, "this reply has to outgrow one write")
+
+            c.send(self.announce_path("kaafter"))
+            status, _, after = c.reply()
+            self.assertIn(b"200", status)
+            self.assertIn(b"complete", bdecode(after))
+        finally:
+            c.close()
+
+    def test_several_requests_in_a_row(self):
+        c = self.tracker.connect()
+        try:
+            for i in range(20):
+                c.send(self.announce_path("karow%d" % i))
+                status, _, body = c.reply()
+                self.assertIn(b"200", status)
+            self.assertEqual(self.tracker.torrent_count(), 20)
+        finally:
+            c.close()
+
+    def test_without_the_header_the_connection_is_not_held(self):
+        """HTTP/1.1 calls a connection persistent unless told otherwise; this
+        tracker holds one only when asked by name. Pinned as it is."""
+        c = self.tracker.connect()
+        try:
+            c.send(self.announce_path("kanone"), connection=None)
+            c.reply()
+            self.assertFalse(c.is_open())
+        finally:
+            c.close()
+
+    def test_the_error_path_does_not_hold_the_connection(self):
+        c = self.tracker.connect()
+        try:
+            c.send("/announce?info_hash=short")
+            status, _, _ = c.reply()
+            self.assertIn(b"400", status)
+        finally:
+            c.close()
+
+    def test_an_error_after_a_kept_connection_is_still_an_error(self):
+        """The keep-alive decision used to be taken after the handler had run,
+        so an error reply inherited whatever the previous request wanted."""
+        c = self.tracker.connect()
+        try:
+            c.send(self.announce_path("kabefore"))
+            self.assertIn(b"200", c.reply()[0])
+            c.send("/announce?info_hash=short")
+            self.assertIn(b"400", c.reply()[0])
+        finally:
+            c.close()
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/integration/test_stats.py b/tests/integration/test_stats.py
new file mode 100644
index 0000000..820b917
--- /dev/null
+++ b/tests/integration/test_stats.py
@@ -0,0 +1,169 @@
+"""The /stats endpoint.
+
+Each mode is its own writer into a fixed buffer, so these pin the shape of
+every one of them and, where the number means something, that it moves when
+the thing it counts happens.
+"""
+
+import ipaddress
+import re
+import socket
+import unittest
+import urllib.error
+import xml.etree.ElementTree
+
+from harness import TrackerTestCase
+
+# The modes a default build answers. "tpbs" and "statedump" are full scrapes
+# and belong to test_fullscrape; "fulllog" and "woodpeckers" sit behind
+# feature flags this build does not set.
+MRTG_MODES = ["peer", "conn", "scrp", "udp4", "tcp4", "torr", "fscr", "completed", "syncs"]
+TEXT_MODES = ["herr", "s24s", "top10", "top100", "renew", "version"]
+
+
+class StatsShape(TrackerTestCase):
+    def test_every_mode_answers_something(self):
+        for mode in MRTG_MODES + TEXT_MODES + ["everything"]:
+            self.assertTrue(self.tracker.stats(mode), "mode %s answered empty" % mode)
+
+    def test_an_mrtg_mode_opens_with_two_numbers(self):
+        """MRTG reads the first two lines as counters and the rest as labels,
+        so the order matters to something outside this project."""
+        for mode in MRTG_MODES:
+            lines = self.tracker.stats(mode).splitlines()
+            self.assertGreaterEqual(len(lines), 2, "mode %s" % mode)
+            for line in lines[:2]:
+                self.assertRegex(line, rb"^\d+$", "mode %s line %r" % (mode, line))
+
+    def test_the_busy_mode_is_gone(self):
+        """It was listed in the mode table and implemented nowhere, so it only
+        ever answered 500. Removed rather than written: picking poisoning
+        networks out stopped being meaningful once consumer lines became bot
+        hosts and v6 made the address space too large to watch."""
+        with self.assertRaises(urllib.error.HTTPError) as caught:
+            self.tracker.stats("busy")
+        self.assertEqual(caught.exception.code, 400, "an unknown mode, like any other")
+
+    def test_an_unknown_mode_is_refused(self):
+        with self.assertRaises(urllib.error.HTTPError) as caught:
+            self.tracker.stats("nosuchmode")
+        self.assertEqual(caught.exception.code, 400)
+
+    def test_everything_is_well_formed_xml(self):
+        root = xml.etree.ElementTree.fromstring(self.tracker.stats("everything").decode())
+        self.assertEqual(root.tag, "stats")
+        self.assertIsNotNone(root.find("torrents/count_mutex"))
+        self.assertIsNotNone(root.find("connections/tcp/announce"))
+
+    def test_version_names_a_commit(self):
+        self.assertIn(b"opentracker", self.tracker.stats("version").lower() + b"opentracker")
+        self.assertRegex(self.tracker.stats("version"), rb"https?://")
+
+
+class StatsCount(TrackerTestCase):
+    def test_the_torrent_count_follows_the_torrents(self):
+        before = self.tracker.torrent_count()
+        self.tracker.announce(self.hash_for("statA"), port=6001, left=0)
+        self.assertEqual(self.tracker.torrent_count(), before + 1)
+        self.tracker.announce(self.hash_for("statB"), port=6002, left=0)
+        self.assertEqual(self.tracker.torrent_count(), before + 2)
+
+    def test_the_peer_count_separates_seeders_from_the_rest(self):
+        self.tracker.announce(self.hash_for("statpeers"), port=6001, left=0)
+        self.tracker.announce(self.hash_for("statpeers"), port=6002, left=4096)
+        peers, seeds = self.tracker.stats("peer").splitlines()[:2]
+        self.assertEqual(int(peers), 2)
+        self.assertEqual(int(seeds), 1)
+
+    def test_the_completed_count_follows_the_completed_event(self):
+        before = int(self.tracker.stats("completed").splitlines()[0])
+        self.tracker.announce(self.hash_for("statdone"), port=6001, left=0, event="completed")
+        self.assertEqual(int(self.tracker.stats("completed").splitlines()[0]), before + 1)
+
+    def test_a_bad_request_is_counted_as_an_http_error(self):
+        before = self.tracker.stats("herr")
+        try:
+            self.tracker.stats("nosuchmode")
+        except urllib.error.HTTPError:
+            pass
+        after = self.tracker.stats("herr")
+        self.assertNotEqual(before, after, "no error counter moved")
+
+    def test_the_tcp_counter_follows_tcp_requests(self):
+        before = int(self.tracker.stats("tcp4").splitlines()[0])
+        for _ in range(3):
+            self.tracker.announce(self.hash_for("stattcp"), port=6001, left=0)
+        self.assertGreaterEqual(int(self.tracker.stats("tcp4").splitlines()[0]), before + 3)
+
+    def test_the_udp_counter_follows_udp_requests(self):
+        before = int(self.tracker.stats("udp4").splitlines()[0])
+        sock, connection_id = self.tracker.udp_connect()
+        try:
+            self.tracker.udp_announce(sock, connection_id, self.hash_for("statudp"), left=0)
+        finally:
+            sock.close()
+        self.assertGreater(int(self.tracker.stats("udp4").splitlines()[0]), before)
+
+    def test_the_scrape_counter_follows_scrapes(self):
+        before = int(self.tracker.stats("scrp").splitlines()[0])
+        self.tracker.scrape(self.hash_for("statscrape"))
+        self.assertEqual(int(self.tracker.stats("scrp").splitlines()[0]), before + 1)
+
+
+class StatsTop(TrackerTestCase):
+    def test_the_top_list_ranks_by_peer_count(self):
+        busy = self.hash_for("topbusy")
+        quiet = self.hash_for("topquiet")
+        for port in range(6001, 6006):
+            self.tracker.announce(busy, port=port, left=0)
+        self.tracker.announce(quiet, port=6100, left=0)
+
+        body = self.tracker.stats("top10")
+        self.assertIn(b"Top 10 torrents by peers", body)
+        ranked = re.findall(rb"\t(\d+)\t([0-9A-F]{40})", body.split(b"by seeds")[0])
+        self.assertEqual(ranked[0][1], busy.hex().upper().encode(), "the busy torrent ranks first")
+        self.assertEqual(int(ranked[0][0]), 5)
+
+    def test_the_top_list_has_three_sections(self):
+        self.tracker.announce(self.hash_for("topsections"), port=6001, left=0)
+        body = self.tracker.stats("top100")
+        for heading in (b"by peers", b"by seeds", b"by leechers"):
+            self.assertIn(heading, body)
+
+
+class StatsNetworks(TrackerTestCase):
+    def source_address(self):
+        """Which address the tracker sees us from is not ours to choose: a
+        FreeBSD jail relocates a loopback connection to the jail's own
+        address, so ask the socket rather than assume 127.0.0.1."""
+        probe = socket.create_connection(("127.0.0.1", self.tracker.port), timeout=5)
+        try:
+            return probe.getsockname()[0]
+        finally:
+            probe.close()
+
+    def test_the_slash24_report_names_the_announcing_network(self):
+        source = self.source_address()
+        self.tracker.announce(self.hash_for("s24"), port=6001, left=0)
+        body = self.tracker.stats("s24s")
+        self.assertIn(b"Networks, limit /28:", body)
+        self.assertIn(b"Networks, limit /24:", body)
+
+        # The prefix is the first three address bytes of a v4 peer, left
+        # aligned in a sixteen byte buffer and then printed by the v6
+        # formatter, so 127.0.0.0/24 reads as "7f00::" rather than as the
+        # network an operator asked about. Pinned as it is, not blessed.
+        prefix = socket.inet_aton(source)[:3] + b"\0" * 13
+        self.assertIn(str(ipaddress.IPv6Address(prefix)).encode(), body)
+
+    def test_the_report_counts_one_network_per_announcing_address(self):
+        for port in (6001, 6002, 6003):
+            self.tracker.announce(self.hash_for("s24count"), port=port, left=0)
+        lines = [line for line in self.tracker.stats("s24s").splitlines() if b":" in line and b"limit" not in line]
+        self.assertEqual(len(lines), 2, "one line under each of the two limits")
+        for line in lines:
+            self.assertEqual(int(line.split(b":")[0]), 3, "three peers from the one network")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/integration/test_udp.py b/tests/integration/test_udp.py
new file mode 100644
index 0000000..1cb2389
--- /dev/null
+++ b/tests/integration/test_udp.py
@@ -0,0 +1,168 @@
+"""The UDP tracker protocol, BEP 15.
+
+The HTTP tests cover the torrent store; these cover the packet handling in
+front of it, which has its own framing, its own connection id and its own
+rules about what to answer and what to ignore.
+"""
+
+import socket
+import struct
+import unittest
+
+from harness import TrackerTestCase
+
+MAGIC = 0x41727101980
+
+
+class UdpProtocol(TrackerTestCase):
+    def test_connect_echoes_the_transaction_id(self):
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        sock.settimeout(5)
+        try:
+            sock.sendto(struct.pack(">QII", MAGIC, 0, 0xDEADBEEF), ("127.0.0.1", self.tracker.port))
+            action, transaction, connection_id = struct.unpack(">IIQ", sock.recv(2048)[:16])
+            self.assertEqual(action, 0)
+            self.assertEqual(transaction, 0xDEADBEEF)
+            self.assertNotEqual(connection_id, 0)
+        finally:
+            sock.close()
+
+    def test_the_connection_id_is_stable_for_one_peer(self):
+        first, id_one = self.tracker.udp_connect()
+        second, id_two = self.tracker.udp_connect()
+        try:
+            self.assertEqual(id_one, id_two)
+        finally:
+            first.close()
+            second.close()
+
+    def test_a_wrong_connection_id_is_refused(self):
+        payload = struct.pack(">QII20s20sQQQIIIiH", 0, 1, 2, self.hash_for("udpbad"), b"p" * 20, 0, 0, 0, 0, 0, 0, -1, 6881)
+        answer = self.tracker.udp_raw(payload)
+        self.assertIsNotNone(answer, "expected an error packet")
+        action, transaction = struct.unpack(">II", answer[:8])
+        self.assertEqual(action, 3, "action 3 is the error packet")
+        self.assertIn(b"Connection ID missmatch", answer[8:])
+
+    def test_a_packet_shorter_than_the_header_is_ignored(self):
+        self.assertIsNone(self.tracker.udp_raw(b"\x00" * 15))
+
+    def test_an_unknown_action_is_ignored(self):
+        self.assertIsNone(self.tracker.udp_raw(struct.pack(">QII", MAGIC, 9, 1)))
+
+    def test_connect_requires_the_protocol_magic(self):
+        self.assertIsNone(self.tracker.udp_raw(struct.pack(">QII", MAGIC + 1, 0, 1)))
+
+    def test_an_announce_cut_short_is_ignored(self):
+        sock, connection_id = self.tracker.udp_connect()
+        try:
+            self.assertIsNone(self.tracker.udp_raw(struct.pack(">QII", connection_id, 1, 1) + b"\0" * 40))
+        finally:
+            sock.close()
+
+
+class UdpAnnounce(TrackerTestCase):
+    def test_a_seeder_is_counted_as_a_seeder(self):
+        sock, connection_id = self.tracker.udp_connect()
+        try:
+            answer = self.tracker.udp_announce(sock, connection_id, self.hash_for("udpseed"), left=0)
+            self.assertEqual(answer["seeders"], 1)
+            self.assertEqual(answer["leechers"], 0)
+            self.assertGreater(answer["interval"], 0)
+        finally:
+            sock.close()
+
+    def test_a_leecher_is_counted_as_a_leecher(self):
+        sock, connection_id = self.tracker.udp_connect()
+        try:
+            answer = self.tracker.udp_announce(sock, connection_id, self.hash_for("udpleech"), left=1024)
+            self.assertEqual(answer["seeders"], 0)
+            self.assertEqual(answer["leechers"], 1)
+        finally:
+            sock.close()
+
+    def test_stopped_removes_the_peer(self):
+        info_hash = self.hash_for("udpstop")
+        sock, connection_id = self.tracker.udp_connect()
+        try:
+            self.tracker.udp_announce(sock, connection_id, info_hash, left=0)
+            self.tracker.udp_announce(sock, connection_id, info_hash, left=0, event=3)
+            answer = self.tracker.udp_announce(sock, connection_id, info_hash, left=1024)
+            self.assertEqual(answer["seeders"], 0, "the seeder announced stopped")
+        finally:
+            sock.close()
+
+    def test_an_announce_over_udp_is_visible_over_http(self):
+        """One torrent store behind both bearers, not two."""
+        info_hash = self.hash_for("udpcross")
+        sock, connection_id = self.tracker.udp_connect()
+        try:
+            self.tracker.udp_announce(sock, connection_id, info_hash, left=0)
+        finally:
+            sock.close()
+        scrape = self.tracker.scrape(info_hash)
+        self.assertEqual(scrape[b"files"][info_hash][b"complete"], 1)
+
+    def test_the_peer_list_carries_the_announcing_peer(self):
+        info_hash = self.hash_for("udppeers")
+        sock, connection_id = self.tracker.udp_connect()
+        try:
+            answer = self.tracker.udp_announce(sock, connection_id, info_hash, left=0, port=6881)
+            self.assertEqual(len(answer["peers"]) % 6, 0, "v4 peers are six bytes each")
+            self.assertGreaterEqual(len(answer["peers"]), 6)
+            self.assertEqual(struct.unpack(">H", answer["peers"][4:6])[0], 6881)
+        finally:
+            sock.close()
+
+
+class UdpScrape(TrackerTestCase):
+    def test_scrape_reports_the_swarm(self):
+        info_hash = self.hash_for("udpscrape")
+        sock, connection_id = self.tracker.udp_connect()
+        try:
+            self.tracker.udp_announce(sock, connection_id, info_hash, left=0)
+            seeders, completed, leechers = self.tracker.udp_scrape(sock, connection_id, [info_hash])[0]
+            self.assertEqual(seeders, 1)
+            self.assertEqual(leechers, 0)
+            self.assertEqual(completed, 0)
+        finally:
+            sock.close()
+
+    def test_an_unknown_hash_scrapes_as_empty(self):
+        sock, connection_id = self.tracker.udp_connect()
+        try:
+            self.assertEqual(self.tracker.udp_scrape(sock, connection_id, [self.hash_for("udpnone")])[0], (0, 0, 0))
+        finally:
+            sock.close()
+
+    def test_several_hashes_answer_in_order(self):
+        seeding = self.hash_for("udpmultiA")
+        leeching = self.hash_for("udpmultiB")
+        sock, connection_id = self.tracker.udp_connect()
+        try:
+            self.tracker.udp_announce(sock, connection_id, seeding, left=0)
+            self.tracker.udp_announce(sock, connection_id, leeching, left=1024)
+            answers = self.tracker.udp_scrape(sock, connection_id, [seeding, leeching])
+            self.assertEqual(answers[0][0], 1, "first hash is the seeded one")
+            self.assertEqual(answers[1][2], 1, "second hash is the leeched one")
+        finally:
+            sock.close()
+
+
+class UdpWorkersConfiguredAfterTheListener(TrackerTestCase):
+    """The harness writes its listen lines first, so this directive lands
+    below them: the position a config file should not care about."""
+
+    config = "listen.udp.workers 4\n"
+
+    def test_the_tracker_starts_and_still_answers_udp(self):
+        sock, connection_id = self.tracker.udp_connect()
+        try:
+            answer = self.tracker.udp_announce(sock, connection_id, self.hash_for("udpworkers"), left=0)
+            self.assertEqual(answer["seeders"], 1)
+        finally:
+            sock.close()
+
+
+if __name__ == "__main__":
+    unittest.main()