TBBinary: drop FirefoxBinary and manage Tor Browser process directly

[IamYipi]

Selenium's FirefoxBinary is deprecated and breaks/produces warnings with Selenium 4.40+, impacting Tor Browser startup and lifecycle handling.

Replace the FirefoxBinary dependency with a standalone TBBinary that launches and manages the Tor Browser process via subprocess for simpler, more reliable process control.

Keep kill() for backwards compatibility, since callers rely on it to force-terminate the browser when it becomes unresponsive.

Fixes #220

[IamYipi]

Tested successfully in a Debian Bookworm–based Docker environment
using Selenium 4, with no compatibility issues observed.

The change was built and validated using the following setup:

• Debian bookworm-slim
• Tor Browser 15.0.6
• Geckodriver 0.36.0
• Firefox ESR
• Selenium 4.x
• Xvfb headless environment

Tor Browser launches correctly, process lifecycle management works as
expected, and the TBBinary subprocess handling behaves reliably under
containerized execution.

Dockerfile used for validation:

FROM debian:bookworm-slim

ENV DEBIAN_FRONTEND=noninteractive \
    LANG=C.UTF-8 \
    TZ=Etc/UTC \
    DISPLAY=:99 \
    TBB_DIR=/opt/tor-browser/

ENV GECKODRIVER_URL="https://github.com/mozilla/geckodriver/releases/download/v0.36.0/geckodriver-v0.36.0-linux64.tar.gz" \
    TOR_BROWSER_URL="https://www.torproject.org/dist/torbrowser/15.0.6/tor-browser-linux-x86_64-15.0.6.tar.xz"

RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates \
    wget \
    tar \
    xz-utils \
    bzip2 \
    gnupg \
    x11-xserver-utils \
    xvfb \
    libgtk-3-0 \
    libdbus-glib-1-2 \
    libdbus-1-3 \
    libasound2 \
    libx11-6 \
    libx11-xcb1 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    libxss1 \
    libxt6 \
    libnss3 \
    libcurl4 \
    libssl3 \
    libstdc++6 \
    python3 \
    python3-pip \
    python3-setuptools \
    unzip \
 && rm -rf /var/lib/apt/lists/*

RUN apt-get update && apt-get install -y firefox-esr


RUN useradd -m -s /bin/bash tbuser
WORKDIR /home/tbuser

RUN wget -qO /tmp/geckodriver.tar.gz "${GECKODRIVER_URL}" \
    && tar -xzf /tmp/geckodriver.tar.gz -C /tmp/ \
    && mv /tmp/geckodriver /usr/local/bin/geckodriver \
    && chmod +x /usr/local/bin/geckodriver \
    && rm -f /tmp/geckodriver.tar.gz

RUN mkdir -p /opt && \
    wget -qO /tmp/tor-browser.tar.xz "${TOR_BROWSER_URL}" \
    && tar -xJf /tmp/tor-browser.tar.xz -C /opt/ \
    && mv /opt/tor-browser_* /opt/tor-browser || true \
    && rm -f /tmp/tor-browser.tar.xz

RUN mkdir -p /opt && \
    wget -qO /tmp/tor-browser.tar.xz "${TOR_BROWSER_URL}" && \
    tar -xJf /tmp/tor-browser.tar.xz -C /tmp/ && \
    inner_tar=$(find /tmp -maxdepth 2 -type f -name '*.tar.gz' | head -n1) && \
    tar -xzf "$inner_tar" -C /opt/ && \
    mv /opt/tor-browser_* /opt/tor-browser || true && \
    rm -f /tmp/tor-browser.tar.xz "$inner_tar"

RUN chmod -R a+rx /opt/tor-browser

COPY requirements.txt /tmp/requirements.txt
RUN pip3 install --break-system-packages --no-cache-dir -r /tmp/requirements.txt

COPY tbselenium-0.9.0-py3-none-any.whl /tmp/tbselenium-0.9.0-py3-none-any.whl
RUN pip3 install --break-system-packages --no-cache-dir /tmp/tbselenium-0.9.0-py3-none-any.whl && rm -f /tmp/tbselenium-0.9.0-py3-none-any.whl

COPY app /home/tbuser/app
COPY entrypoint.sh /home/tbuser/entrypoint.sh
RUN chmod +x /home/tbuser/entrypoint.sh

RUN chown -R tbuser:tbuser /home/tbuser /opt/tor-browser

USER tbuser
ENV PATH="/usr/local/bin:${PATH}"
WORKDIR /home/tbuser/app

EXPOSE 8000

ENTRYPOINT ["/home/tbuser/entrypoint.sh"]

entrypoint.sh

#!/usr/bin/env bash
set -e

# iniciar Xvfb para entorno gráfico virtual
Xvfb :99 -screen 0 1920x1080x24 -ac >/tmp/xvfb.log 2>&1 &
sleep 1
export DISPLAY=:99

echo "Xvfb iniciado en DISPLAY=:99"
echo "Tor será iniciado por Stem cuando sea necesario"

echo "Iniciando servidor FastAPI..."
exec uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1

main.py not provided but is a simple python fastapi main file for test tbselenium

[gunesacar]

@IamYipi Thanks so much for the pull request. I'm planning to get rid of the FirefoxBinary class altogether, following Selenium's approach. Mirroring the upstream repo's structure makes things simpler. I already have a WIP branch and hoping to push it soon. Many thanks again for the pull request, though.