OpenHFDS 0.1.0__tar.gz

openhfds-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+venv/
+__pycache__/
+.pypirc
+*.egg-info/
+dist
+MANIFEST
+tmp
+*.bak

openhfds-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ty Porter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openhfds-0.1.0/OpenHFDS/__init__.py

@@ -0,0 +1,3 @@
+from OpenHFDS.version import __version__
+
+__all__ = ["__version__"]

openhfds-0.1.0/OpenHFDS/cli.py

@@ -0,0 +1,77 @@
+import argparse
+from OpenHFDS.hf_session import (
+    DEFAULT_TTL,
+    DEFAULT_MAX_ENTRIES,
+    CLIENT_HEARTBEAT_SECONDS,
+)
+
+DEFAULT_BIND = "127.0.0.1"
+DEFAULT_PORT = 10666
+LOG_LEVELS = ("DEBUG", "INFO", "WARNING", "ERROR")
+
+
+def _int_in_range(name: str, low: int, high: int | None = None):
+    def parse(text: str) -> int:
+        try:
+            value = int(text, 0)
+        except ValueError:
+            raise argparse.ArgumentTypeError(f"{text!r} is not a whole number")
+
+        if value < low or (high is not None and value > high):
+            bounds = f"at least {low}" if high is None else f"between {low} and {high}"
+            raise argparse.ArgumentTypeError(f"{name} must be {bounds}, got {value}")
+
+        return value
+
+    return parse
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="openhfds",
+        description="HellFighter directory server: lists hosted game sessions for the game's server browser.",
+    )
+    parser.add_argument(
+        "--bind",
+        default=DEFAULT_BIND,
+        metavar="ADDRESS",
+        help="address to listen on; use 0.0.0.0 to accept other machines (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--port",
+        type=_int_in_range("port", 1, 65535),
+        default=DEFAULT_PORT,
+        help="UDP port to listen on; the game itself always uses %(default)s (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--ttl",
+        type=_int_in_range("ttl", 1),
+        default=DEFAULT_TTL,
+        metavar="SECONDS",
+        help=f"drop a host after this long without a 'set'; by default the game sends one every {CLIENT_HEARTBEAT_SECONDS}s "
+        "(default: %(default)s)",
+    )
+    parser.add_argument(
+        "--max-entries",
+        type=_int_in_range("max-entries", 1, DEFAULT_MAX_ENTRIES),
+        default=DEFAULT_MAX_ENTRIES,
+        metavar="COUNT",
+        help=f"most sessions to list; the game can't hold more than {DEFAULT_MAX_ENTRIES} (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--spoof",
+        type=_int_in_range("spoof", 0, DEFAULT_MAX_ENTRIES),
+        default=0,
+        metavar="COUNT",
+        help="start with this many made-up sessions, to try out the game's server browser; "
+        "they can't be joined and expire after --ttl (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--log-level",
+        type=str.upper,
+        choices=LOG_LEVELS,
+        default="INFO",
+        help="logging verbosity; INFO includes every packet received and sent (default: %(default)s)",
+    )
+
+    return parser.parse_args(argv)

openhfds-0.1.0/OpenHFDS/hf_client_request.py

@@ -0,0 +1,123 @@
+from OpenHFDS.logger import log_received_udp_data, log_sent_udp_data, Logger
+from OpenHFDS.hf_session import HFSessionList, HFSession
+from collections.abc import Callable
+import socket
+
+HF_REQUEST_FIELD_SEPARATOR = " "
+HF_REPLY_TERMINATOR = b"\0"
+HF_CLIENT_FIELD_MAX = (
+    63  # client reads each %s into a 64-byte buffer with no bounds check
+)
+
+
+class HFUnknownClientRequest(RuntimeError):
+    """The datagram isn't an OpenHFDS request at all (stray traffic, scanners), so it isn't worth a traceback."""
+
+
+HFRequestHandler = Callable[[str, HFSessionList, socket.socket, tuple[str, int]], None]
+
+
+def decode_hf_udp(data: bytes, addr: tuple[str, int]) -> tuple[str, HFRequestHandler]:
+    log_received_udp_data(data, addr)
+
+    try:
+        request = data.decode("ascii")
+    except UnicodeDecodeError:
+        raise HFUnknownClientRequest(f"Unable to decode {data!r} as ASCII")
+
+    if request.startswith("info"):
+        return (request, handle_info)
+    elif request.startswith("get"):
+        return (request, handle_get)
+    elif request.startswith("set"):
+        return (request, handle_set)
+    elif request.startswith("delete me"):
+        return (request, handle_delete)
+    else:
+        raise HFUnknownClientRequest(f"Unable to handle '{request}'")
+
+
+def handle_info(
+    _request: str, sessions: HFSessionList, sock: socket.socket, addr: tuple[str, int]
+) -> None:
+    """Handles <info> requests. Sends the session count to the client."""
+    _send(sock, f"info {sessions.count} 0 0 0 0".encode("ascii"), addr)
+
+
+def handle_get(
+    request: str, sessions: HFSessionList, sock: socket.socket, addr: tuple[str, int]
+) -> None:
+    """Handles <get STARTID STOPID> requests. Sends all available sessions in the range, one datagram each."""
+    args = request.split(HF_REQUEST_FIELD_SEPARATOR)
+    start = int(args[1])
+    stop = (int(args[2]) if len(args) > 2 else start) + 1
+
+    # IDs are always 0..count-1, so don't loop over absurd ranges from a bad or hostile request
+    start = max(start, 0)
+    stop = min(stop, sessions.count)
+
+    for ID in range(start, stop):
+        session = sessions.get_by_id(ID)
+
+        if session is not None:
+            field_values = [
+                str(getattr(session, f.name)) for f in HFSession.visible_fields(session)
+            ]
+            # The ID is the session's position in the list, so it's written here and not stored on the session
+            _send(sock, f"get {ID} {' '.join(field_values)}".encode("ascii"), addr)
+
+
+def handle_set(
+    request: str, sessions: HFSessionList, _sock: socket.socket, addr: tuple[str, int]
+) -> None:
+    """
+    Handles <set NAME LOCATION CONNECTION CURPLAYERS MAXPLAYERS FLAGS VERSION> requests.
+
+    If the session does not exist, it creates it. Otherwise, the existing entry is updated with the new values.
+    Either way the `last_seen` attribute of the session is ticked, so this request also functions as a heartbeat.
+    Clients should send it faster than the list's TTL setting, otherwise the session is automatically removed.
+    """
+    name, location, connection, current, maximum, flags, version = request.split(
+        HF_REQUEST_FIELD_SEPARATOR
+    )[1:]
+
+    # Parse everything before touching the session, so a bad value can't leave an entry half-updated
+    values = {
+        "name": name[:HF_CLIENT_FIELD_MAX],
+        "location": location[:HF_CLIENT_FIELD_MAX],
+        "connection": connection[:HF_CLIENT_FIELD_MAX],
+        "current_players": int(current),
+        "max_players": int(maximum),
+        "flags": int(flags),
+        "version": version[:HF_CLIENT_FIELD_MAX],
+    }
+
+    session = sessions.get_by_hostname(addr[0])
+    existing = session is not None
+    session = session or HFSession(hostname=addr[0])
+
+    for attr, value in values.items():
+        setattr(session, attr, value)
+    session.heartbeat()
+
+    if not existing:
+        sessions.add(session)
+
+
+def handle_delete(
+    _request: str, sessions: HFSessionList, _sock: socket.socket, addr: tuple[str, int]
+) -> None:
+    """Handles <delete me> requests. Fetches by hostname and deletes the session from the list."""
+    session = sessions.get_by_hostname(addr[0])
+    if session is None:
+        return
+
+    sessions.remove(session)
+
+
+def _send(sock: socket.socket, data: bytes, addr: tuple[str, int]) -> None:
+    # The client expects a null-terminated string for anything sent to it,
+    # although it is not so kind to do that to its own requests.
+    data += HF_REPLY_TERMINATOR
+    log_sent_udp_data(data, addr)
+    sock.sendto(data, addr)

openhfds-0.1.0/OpenHFDS/hf_session.py

@@ -0,0 +1,183 @@
+import random
+import time
+from dataclasses import dataclass, field, fields, Field
+from OpenHFDS.logger import Logger
+
+DEFAULT_TTL = 600  # seconds before a silent host is dropped; the client re-sends "set" every 180 s
+DEFAULT_MAX_ENTRIES = 0x1000  # client's HFDS_MAX_ENTRIES
+CLIENT_HEARTBEAT_SECONDS = 180  # how often the game re-sends "set" while hosting
+
+# spoof() mixes these into names like "Leviathan_Outnumbered". No spaces, since the client sends and shows _ as a space.
+# Ship names are picked from the game's NAMES.DAT, which it uses to name the ships in a battle.
+SPOOF_SHIP_NAMES = [
+    "Leviathan",
+    "Nemesis",
+    "Infernal",
+    "Behemoth",
+    "Cthulhu",
+    "Titan",
+    "Zeus",
+    "Shiva",
+    "Yamato",
+    "Excalibur",
+    "Armageddon",
+    "Overlord",
+    "Tyrant",
+    "Pegasus",
+    "Decimator",
+    "Merciless",
+    "Reaper",
+    "Berserker",
+    "Gargoyle",
+    "Manticore",
+    "Chimera",
+    "Punisher",
+    "Tormentor",
+    "Vengeance",
+    "Tiamat",
+    "Sphinx",
+]
+# Battle names come from the game's .HFB battle files: ESCORT1-3, OUTNUM, SHRIKES, WYVERNS, TIMING, LESSON1-2, NET.
+SPOOF_BATTLE_NAMES = [
+    "Escort",
+    "Outnumbered",
+    "Shrikes",
+    "Wyverns",
+    "Timing",
+    "Lesson",
+    "Net",
+]
+
+
+@dataclass
+class HFSession:
+    hostname: str = "hfds.dracova.com"
+    name: str = "Hell_Fighter_Server"
+    location: str = "Unknown"
+    connection: str = "Unknown"
+    current_players: int = 0
+    max_players: int = 24
+    flags: int = 0
+    version: str = "v21.01"
+
+    last_seen: float = field(
+        default_factory=time.time, metadata={"hf_request_exclude": True}
+    )
+
+    def heartbeat(self) -> None:
+        self.last_seen = time.time()
+
+    @staticmethod
+    def visible_fields(session: "HFSession") -> list[Field]:
+        return [f for f in fields(session) if not f.metadata.get("hf_request_exclude")]
+
+
+class HFSessionList:
+    """
+    The sessions currently listed.
+
+    A session's ID is its position in the list. The client asks for IDs 0..count-1 (count being the first "info" int)
+    and uses the ID in each record as its table index, so IDs have to stay contiguous. Removing a session shifts the
+    ones after it down, which keeps them that way.
+    """
+
+    def __init__(
+        self,
+        ttl: int = DEFAULT_TTL,
+        max_entries: int = DEFAULT_MAX_ENTRIES,
+    ) -> None:
+        self._sessions: list[HFSession] = []
+        self._by_host: dict[str, HFSession] = {}
+
+        self.ttl = ttl
+        self.max_entries = max_entries
+
+    @property
+    def count(self) -> int:
+        """The number of sessions in the list."""
+        return len(self._by_host)
+
+    def expire(self) -> list[HFSession]:
+        """Removes sessions whose heartbeat has not been received since the configured TTL."""
+        now = time.time()
+
+        removed = []
+
+        # remove() mutates _by_host, so iterate over a copy
+        for session in list(self._by_host.values()):
+            if now - session.last_seen < self.ttl:
+                continue
+
+            self.remove(session)
+            removed.append(session)
+
+        return removed
+
+    def add(self, session: HFSession) -> None:
+        """Adds a session to the list."""
+        if session.hostname in self._by_host:
+            # Session already exists, so carry on
+            return
+
+        if self.count >= self.max_entries:
+            Logger.warning(
+                f"Full: not adding {session.hostname}, list already has {self.count} sessions"
+            )
+            return
+
+        self._by_host[session.hostname] = session
+        self._sessions.append(session)
+
+    def get_by_id(self, ID: int) -> HFSession | None:
+        """Returns a session by ID, if it exists."""
+        # a negative ID would otherwise index from the end of the list
+        if 0 <= ID < len(self._sessions):
+            return self._sessions[ID]
+
+        return None
+
+    def get_by_hostname(self, hostname: str) -> HFSession | None:
+        """Returns a session by hostname, if it exists."""
+        if hostname in self._by_host:
+            return self._by_host[hostname]
+
+        return None
+
+    def remove(self, session: HFSession) -> None:
+        """Removes a session from the list."""
+        if session.hostname in self._by_host:
+            del self._by_host[session.hostname]
+            self._sessions.remove(session)
+
+    def spoof(self, n: int, seed: int | None = None) -> None:
+        """
+        Fills the list with up to n made-up sessions, for trying out the game's server browser without real hosts.
+
+        The hostnames come from 10.200.0.0/16, which isn't going to be a real host, so joining one won't work.
+        Spoofed sessions are never refreshed, so they expire after the TTL like any silent host.
+        Pass a seed to get the same sessions every time.
+        """
+        rng = random.Random(seed)
+        added = 0
+        candidate = 0
+
+        while added < n and self.count < self.max_entries:
+            hostname = f"10.200.{candidate // 256}.{candidate % 256}"
+            candidate += 1
+
+            if hostname in self._by_host:
+                continue
+
+            max_players = rng.choice([8, 16, 24])
+            self.add(
+                HFSession(
+                    hostname=hostname,
+                    name=f"{rng.choice(SPOOF_SHIP_NAMES)}_{rng.choice(SPOOF_BATTLE_NAMES)}",
+                    location=rng.choice(["Unknown", "North_America", "Europe", "Asia"]),
+                    connection=rng.choice(["Unknown", "LAN", "Internet", "Modem"]),
+                    current_players=rng.randint(0, max_players),
+                    max_players=max_players,
+                    flags=rng.choice([0, 0, 0, 1]),
+                )
+            )
+            added += 1

openhfds-0.1.0/OpenHFDS/logger.py

@@ -0,0 +1,36 @@
+import logging
+
+formatter = logging.Formatter(
+    "[%(asctime)s] [%(name)s] [%(levelname)s]: %(message)s", datefmt="%Y-%m-%d %H:%M:%S"
+)
+
+# Importing OpenHFDS must not change the host program's logging, so only the server's main() adds a console handler
+Logger = logging.getLogger("OpenHFDS")
+Logger.addHandler(logging.NullHandler())
+
+_console: logging.Handler | None = None
+
+
+def configure_logging(level: int | str) -> None:
+    """Sends the logger's output to the console at the given level."""
+    global _console
+
+    if _console is None:
+        _console = logging.StreamHandler()
+        _console.setFormatter(formatter)
+        Logger.addHandler(_console)
+
+    Logger.setLevel(level)
+    _console.setLevel(level)
+
+
+def log_received_udp_data(data: bytes, addr: tuple[str, int]):
+    _log_udp_xfer("Receive", data, addr)
+
+
+def log_sent_udp_data(data: bytes, addr: tuple[str, int]):
+    _log_udp_xfer("Sent", data, addr)
+
+
+def _log_udp_xfer(label: str, data: bytes, addr: tuple[str, int]) -> None:
+    Logger.info(f"{label}: <{addr[0]}:{addr[1]} {len(data)} {repr(data)}>")

openhfds-0.1.0/OpenHFDS/server.py

@@ -0,0 +1,70 @@
+import socket
+from datetime import datetime
+from OpenHFDS.logger import Logger, configure_logging
+from OpenHFDS.hf_client_request import decode_hf_udp, HFUnknownClientRequest
+from OpenHFDS.hf_session import HFSessionList, CLIENT_HEARTBEAT_SECONDS
+from OpenHFDS.cli import parse_args
+from OpenHFDS.version import __version__
+
+
+def serve(sock: socket.socket, sessions: HFSessionList) -> None:
+    while True:
+        try:
+            for session in sessions.expire():
+                Logger.info(
+                    f"Expire: session <{session.hostname}> last seen at {datetime.fromtimestamp(session.last_seen).isoformat()}"
+                )
+        except Exception as e:
+            Logger.exception(e)
+
+        try:
+            d, addr = sock.recvfrom(65535)
+        except (socket.timeout, ConnectionResetError):
+            continue
+        try:
+            request, handler = decode_hf_udp(d, addr)
+            handler(request, sessions, sock, addr)
+        except HFUnknownClientRequest as e:
+            Logger.warning(e)
+        except Exception as e:
+            Logger.exception(e)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    configure_logging(args.log_level)
+
+    Logger.info(f"OpenHFDS v{__version__} -- Open HellFighter Directory Server")
+
+    if args.ttl < CLIENT_HEARTBEAT_SECONDS:
+        Logger.warning(
+            f"TTL of {args.ttl} s is shorter than the game's {CLIENT_HEARTBEAT_SECONDS} s heartbeat, "
+            "so hosts might drop off the list while still running"
+        )
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        sock.bind((args.bind, args.port))
+    except OSError as e:
+        Logger.error(f"Could not listen on {args.bind}:{args.port}: {e}")
+        sock.close()
+        return 1
+    sock.settimeout(0.5)
+
+    sessions = HFSessionList(ttl=args.ttl, max_entries=args.max_entries)
+    Logger.info(
+        f"Listening on {args.bind}:{args.port} (ttl {args.ttl}s, up to {args.max_entries} sessions)"
+    )
+
+    if args.spoof:
+        sessions.spoof(args.spoof)
+        Logger.info(f"Spoofed {sessions.count} sessions")
+
+    try:
+        serve(sock, sessions)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        sock.close()
+
+    return 0

openhfds-0.1.0/OpenHFDS/version.py

@@ -0,0 +1,5 @@
+#!/usr/bin/env python
+
+# package version
+__version__ = "0.1.0"
+"""Installed version of OpenHFDS."""

openhfds-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: OpenHFDS
+Version: 0.1.0
+Summary: An open implementation of HellFighter Directory Server
+Project-URL: Homepage, https://github.com/ty-porter/OpenHFDS
+Author-email: Tyler Porter <tyler.b.porter@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: directory-server,hellfighter,udp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Other Audience
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Other/Nonlisted Topic
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# OpenHFDS
+
+[![pypi Badge](https://img.shields.io/pypi/v/OpenHFDS)](https://pypi.org/project/OpenHFDS/)
+
+OpenHFDS is an open-source session directory server for HellFighter v21.0+ clients. HellFighter uses DirectPlay peering for the actual game code, but the v21.0 client is hard-coded to search for peer sessions at `hfds.dracova.com` which is now no longer serving traffic, so the only way to play online is via direct IP connections.
+
+OpenHFDS implements the custom UDP protocol needed to search for HellFighter sessions to enable easy network play.
+
+![Server browser populated by OpenHFDS](assets/server_browser.png)
+
+## Installation
+
+OpenHFDS is dependency-free and only requires Python 3.11 or newer. Installation is as simple as obtaining the source code for this repo and running `python openhfds.py`.
+
+If you'd prefer, you can also grab the latest version from PyPi:
+
+```sh
+pip install OpenHFDS
+```
+
+## Usage
+
+Most people should use the default options provided by OpenHFDS. Unpatched HellFighter clients connect to the HFDS on UDP port 10666.
+
+```sh
+python openhfds.py
+```
+
+If you installed the package (for example with `pip install`), the same server is available as the `openhfds` command or `python -m OpenHFDS`.
+
+### Connecting the game to your server
+
+The game looks for the directory server at the hostname `hfds.dracova.com`, so every player (hosts and joiners) has to make that name point at the machine running OpenHFDS. The simplest way is a `hosts` file entry on each player's computer:
+
+```
+<address of the OpenHFDS machine> hfds.dracova.com
+```
+
+The hosts file is `C:\Windows\System32\drivers\etc\hosts` on Windows (edit it as an administrator) and `/etc/hosts` on Linux and macOS.
+
+Which address to use depends on where the server runs:
+
+- **Same computer as the game:** use `127.0.0.1`. The default `--bind 127.0.0.1` is enough.
+- **Other players on your network or the internet:** start the server with `--bind 0.0.0.0` and use that machine's LAN or public IP. UDP port 10666 must be reachable, so allow it through the firewall and forward it if you're behind a router.
+
+OpenHFDS only lists sessions. Once a player picks one, the game connects to the host directly using DirectPlay, so the host's game must also be reachable by the joiner.
+
+Players only appear in the list once their game has registered, and a host's listed player count can lag by a few minutes because the game only refreshes it periodically.
+
+### All CLI Flags
+
+```
+usage: openhfds [-h] [--bind ADDRESS] [--port PORT] [--ttl SECONDS] [--max-entries COUNT] [--spoof COUNT] [--log-level {DEBUG,INFO,WARNING,ERROR}]
+
+HellFighter directory server: lists hosted game sessions for the game's server browser.
+
+options:
+  -h, --help            show this help message and exit
+  --bind ADDRESS        address to listen on; use 0.0.0.0 to accept other machines (default: 127.0.0.1)
+  --port PORT           UDP port to listen on; the game itself always uses 10666 (default: 10666)
+  --ttl SECONDS         drop a host after this long without a 'set'; by default the game sends one every 180s (default: 600)
+  --max-entries COUNT   most sessions to list; the game can't hold more than 4096 (default: 4096)
+  --spoof COUNT         start with this many made-up sessions, to try out the game's server browser; they can't be joined and expire after --ttl (default: 0)
+  --log-level {DEBUG,INFO,WARNING,ERROR}
+                        logging verbosity; INFO includes every packet received and sent (default: INFO)
+```
+
+## Known Issues
+
+- **`get` requests can be used for amplification.** A `get` request is a few bytes, but the server answers it with one datagram for every session in the requested range, and there is no rate limiting. UDP source addresses can be forged, so a public server could be used to send traffic at a third party. The impact grows with the number of registered sessions. Keep the default `--bind 127.0.0.1`, or only expose the server to people you trust (for example, a firewall that allows your friends' addresses).
+- **Requests are not authenticated.** The HellFighter protocol has no authentication, and OpenHFDS identifies a host by the IP address its packets come from. Anyone who can send UDP to the server can list, add, change, or delete sessions, including by forging another host's address.
+- **Hosts behind the same public IP address collide.** Because a host is identified by IP address, two people hosting from behind the same router share one entry in the list, and the most recent `set` wins.
+- **The listed player count can be out of date.** The game only re-registers its session every 3 minutes (and when it starts), not when players join or leave.
+
+## HFDS Protocol
+
+Please see [docs/protocol.md](docs/protocol.md) for details about how the directory server protocol works.
+
+## Contributing
+
+### Installing Locally
+
+OpenHFDS uses `uv` to manage dependencies.
+
+```sh
+uv sync --group dev
+```
+
+#### Running Tests
+
+```sh
+uv run python -m unittest
+```
+
+#### Lint
+
+```sh
+uv run black .
+```
+
+#### Typechecking
+
+```sh
+uv run mypy .
+```
+
+## Contact
+
+Ty Porter
+
+tyler.b.porter@gmail.com

openhfds-0.1.0/README.md

@@ -0,0 +1,111 @@
+# OpenHFDS
+
+[![pypi Badge](https://img.shields.io/pypi/v/OpenHFDS)](https://pypi.org/project/OpenHFDS/)
+
+OpenHFDS is an open-source session directory server for HellFighter v21.0+ clients. HellFighter uses DirectPlay peering for the actual game code, but the v21.0 client is hard-coded to search for peer sessions at `hfds.dracova.com` which is now no longer serving traffic, so the only way to play online is via direct IP connections.
+
+OpenHFDS implements the custom UDP protocol needed to search for HellFighter sessions to enable easy network play.
+
+![Server browser populated by OpenHFDS](assets/server_browser.png)
+
+## Installation
+
+OpenHFDS is dependency-free and only requires Python 3.11 or newer. Installation is as simple as obtaining the source code for this repo and running `python openhfds.py`.
+
+If you'd prefer, you can also grab the latest version from PyPi:
+
+```sh
+pip install OpenHFDS
+```
+
+## Usage
+
+Most people should use the default options provided by OpenHFDS. Unpatched HellFighter clients connect to the HFDS on UDP port 10666.
+
+```sh
+python openhfds.py
+```
+
+If you installed the package (for example with `pip install`), the same server is available as the `openhfds` command or `python -m OpenHFDS`.
+
+### Connecting the game to your server
+
+The game looks for the directory server at the hostname `hfds.dracova.com`, so every player (hosts and joiners) has to make that name point at the machine running OpenHFDS. The simplest way is a `hosts` file entry on each player's computer:
+
+```
+<address of the OpenHFDS machine> hfds.dracova.com
+```
+
+The hosts file is `C:\Windows\System32\drivers\etc\hosts` on Windows (edit it as an administrator) and `/etc/hosts` on Linux and macOS.
+
+Which address to use depends on where the server runs:
+
+- **Same computer as the game:** use `127.0.0.1`. The default `--bind 127.0.0.1` is enough.
+- **Other players on your network or the internet:** start the server with `--bind 0.0.0.0` and use that machine's LAN or public IP. UDP port 10666 must be reachable, so allow it through the firewall and forward it if you're behind a router.
+
+OpenHFDS only lists sessions. Once a player picks one, the game connects to the host directly using DirectPlay, so the host's game must also be reachable by the joiner.
+
+Players only appear in the list once their game has registered, and a host's listed player count can lag by a few minutes because the game only refreshes it periodically.
+
+### All CLI Flags
+
+```
+usage: openhfds [-h] [--bind ADDRESS] [--port PORT] [--ttl SECONDS] [--max-entries COUNT] [--spoof COUNT] [--log-level {DEBUG,INFO,WARNING,ERROR}]
+
+HellFighter directory server: lists hosted game sessions for the game's server browser.
+
+options:
+  -h, --help            show this help message and exit
+  --bind ADDRESS        address to listen on; use 0.0.0.0 to accept other machines (default: 127.0.0.1)
+  --port PORT           UDP port to listen on; the game itself always uses 10666 (default: 10666)
+  --ttl SECONDS         drop a host after this long without a 'set'; by default the game sends one every 180s (default: 600)
+  --max-entries COUNT   most sessions to list; the game can't hold more than 4096 (default: 4096)
+  --spoof COUNT         start with this many made-up sessions, to try out the game's server browser; they can't be joined and expire after --ttl (default: 0)
+  --log-level {DEBUG,INFO,WARNING,ERROR}
+                        logging verbosity; INFO includes every packet received and sent (default: INFO)
+```
+
+## Known Issues
+
+- **`get` requests can be used for amplification.** A `get` request is a few bytes, but the server answers it with one datagram for every session in the requested range, and there is no rate limiting. UDP source addresses can be forged, so a public server could be used to send traffic at a third party. The impact grows with the number of registered sessions. Keep the default `--bind 127.0.0.1`, or only expose the server to people you trust (for example, a firewall that allows your friends' addresses).
+- **Requests are not authenticated.** The HellFighter protocol has no authentication, and OpenHFDS identifies a host by the IP address its packets come from. Anyone who can send UDP to the server can list, add, change, or delete sessions, including by forging another host's address.
+- **Hosts behind the same public IP address collide.** Because a host is identified by IP address, two people hosting from behind the same router share one entry in the list, and the most recent `set` wins.
+- **The listed player count can be out of date.** The game only re-registers its session every 3 minutes (and when it starts), not when players join or leave.
+
+## HFDS Protocol
+
+Please see [docs/protocol.md](docs/protocol.md) for details about how the directory server protocol works.
+
+## Contributing
+
+### Installing Locally
+
+OpenHFDS uses `uv` to manage dependencies.
+
+```sh
+uv sync --group dev
+```
+
+#### Running Tests
+
+```sh
+uv run python -m unittest
+```
+
+#### Lint
+
+```sh
+uv run black .
+```
+
+#### Typechecking
+
+```sh
+uv run mypy .
+```
+
+## Contact
+
+Ty Porter
+
+tyler.b.porter@gmail.com

openhfds-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "OpenHFDS"
+dynamic = ["version"]
+requires-python = ">=3.11"
+description = "An open implementation of HellFighter Directory Server"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Tyler Porter", email = "tyler.b.porter@gmail.com" },
+]
+keywords = [
+    "hellfighter",
+    "directory-server",
+    "udp",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Other Audience",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Other/Nonlisted Topic",
+]
+
+[project.urls]
+Homepage = "https://github.com/ty-porter/OpenHFDS"
+
+[project.scripts]
+openhfds = "OpenHFDS.server:main"
+
+[tool.black]
+target-version = ["py311"]
+
+[tool.hatch.version]
+path = "OpenHFDS/version.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "OpenHFDS",
+]
+
+[dependency-groups]
+dev = [
+    "black",
+    "mypy"
+]