dreamtunnel 0.1.0__tar.gz

dreamtunnel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dreamcatchered
+
+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.

dreamtunnel-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: dreamtunnel
+Version: 0.1.0
+Summary: Python SDK for dreamTunnel — instant public HTTPS tunnels
+License: MIT
+Project-URL: Homepage, https://tunnel.swag.best
+Project-URL: Repository, https://github.com/dreamcatchered/dreamTunnel
+Keywords: tunnel,ngrok,https,webhook,localhost,self-hosted
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# dreamtunnel (Python SDK)
+
+Python-обёртка над CLI `dt`: запускает туннель **из кода**, отдаёт публичный
+URL, присылает события (включая переподключения) и корректно всё останавливает.
+
+Токен уже встроен в бинарник — после установки ничего настраивать не нужно.
+
+```bash
+pip install "git+https://github.com/dreamcatchered/dreamTunnel.git#subdirectory=sdk/python"
+```
+
+Из локальной копии репозитория — так же просто:
+
+```bash
+git clone https://github.com/dreamcatchered/dreamTunnel
+pip install -e dreamTunnel/sdk/python
+```
+
+Если `dt` ещё нет, SDK скачает его сам при первом запуске.
+
+## Быстрый старт
+
+```python
+from dreamtunnel import Tunnel
+
+with Tunnel(port=8080) as tun:
+    print(tun.url)        # https://k7f3m9ab.maiuni.online
+    ...                   # туннель живёт, пока мы внутри блока
+# выход из блока — туннель закрыт
+```
+
+Свой поддомен:
+
+```python
+with Tunnel(port=8080, subdomain="my-api") as tun:
+    print(tun.url)        # https://my-api.maiuni.online
+```
+
+## Управление вручную
+
+```python
+tun = Tunnel(port=3000, subdomain="dev")
+tun.start()               # ждёт, пока релей подтвердит туннель
+print(tun.url, tun.host, tun.local_url, tun.pid)
+
+tun.stop()                # SIGTERM, при необходимости SIGKILL
+tun.restart()             # перезапуск с тем же поддоменом
+
+tun.connect()             # синоним start()
+tun.disconnect()          # синоним stop()
+```
+
+## События и переподключение
+
+`dt` сам держит соединение и переподключается при обрыве. SDK отдаёт это наружу:
+
+```python
+def on_event(event: dict) -> None:
+    # event["event"]: ready | reconnected | disconnected | error | request | response
+    print(event)
+
+tun = Tunnel(port=8080, on_event=on_event)
+tun.start()
+
+tun.events          # все события, что видели
+tun.connected       # True, пока туннель на связи
+tun.stderr          # что писал dt в stderr
+```
+
+## Запуск приложения вместе с туннелем
+
+```python
+import threading, time
+from flask import Flask
+from dreamtunnel import Tunnel
+
+app = Flask(__name__)
+
+@app.route("/")
+def index():
+    return "привет"
+
+threading.Thread(
+    target=lambda: app.run(host="127.0.0.1", port=8080, use_reloader=False),
+    daemon=True,
+).start()
+time.sleep(0.5)
+
+with Tunnel(port=8080, subdomain="my-api") as tun:
+    print(tun.url)
+    while True:
+        time.sleep(1)
+```
+
+Рабочие примеры — в [`examples/`](examples): `flask_app.py`, `fastapi_app.py`.
+
+## CLI
+
+```bash
+dreamtunnel http 8080                 # как `dt http`, но через SDK
+dreamtunnel http 8080 my-api --json   # машинный вывод (NDJSON)
+dreamtunnel tcp 25565
+python -m dreamtunnel http 8080
+```
+
+## Параметры `Tunnel`
+
+| Параметр | По умолчанию | Смысл |
+|---|---|---|
+| `port` | — | локальный порт |
+| `subdomain` | случайный | желаемое имя: `my-api` → `my-api.maiuni.online` |
+| `mode` | `"http"` | `"http"` или `"tcp"` |
+| `server` | `tunnel.swag.best:444` | адрес control-канала |
+| `token` | встроенный | свой токен, если нужен приватный доступ |
+| `dt_binary` | авто | путь к `dt` |
+| `auto_install` | `True` | скачивать `dt`, если не найден |
+| `ready_timeout` | `30` | сколько ждать подтверждения |
+| `on_event` | `None` | колбэк на каждое событие |
+| `session` | `True` | свой файл настроек и сессия для этого туннеля |
+| `config_path` | — | явный путь к файлу настроек `dt` |
+
+## Исключения
+
+| Исключение | Когда |
+|---|---|
+| `BinaryNotFound` | `dt` не найден и автоустановка выключена |
+| `TunnelTimeout` | релей не ответил за `ready_timeout` |
+| `TunnelExited` | процесс `dt` умер до подключения (в `.output` — его вывод) |
+| `TunnelError` | релей отказал (плохой токен, занятый поддомен) |
+
+## Переменные окружения
+
+| Переменная | Смысл |
+|---|---|
+| `DT_BINARY` | путь к `dt` |
+| `DT_TOKEN` | токен доступа |
+| `DT_SERVER` | адрес control-канала |
+| `DT_SUB` | поддомен |
+| `DT_CONFIG` | файл настроек `dt` (SDK задаёт свой на каждый туннель) |
+| `DREAMTUNNEL_BASE_URL` | откуда скачивать бинарник (по умолчанию `https://tunnel.swag.best`) |
+| `DREAMTUNNEL_HOME` | куда класть скачанный бинарник и сессии (по умолчанию `~/.dreamtunnel`) |
+
+## Как это устроено
+
+SDK не переписывает протокол: он запускает `dt <mode> <port> --json` и
+разбирает поток NDJSON-событий (`ready`, `disconnected`, `error`, …). Если
+попался старый бинарник без `--json`, строки вида
+`Forwarding https://… -> http://…` разбираются регуляркой — поддержка
+обратной совместимости встроена.
+
+Каждому туннелю SDK выдаёт **свой** файл настроек `dt` (переменная
+`DT_CONFIG`), поэтому сессии не пересекаются: несколько туннелей с одной
+машины (и даже из одного процесса) работают одновременно и не выбивают друг
+друга. `tun.stop()` сохраняет файл — перезапуск получает тот же адрес,
+`tun.close()` его удаляет.
+
+Практический смысл: `dt` хранит session-id в `~/.dreamtunnel/config.env`, и
+если два процесса используют один файл, второй забирает сессию себе, а первый
+теряет туннель.
+
+## Тесты
+
+```bash
+pip install -e ".[test]"
+pytest                       # юнит-тесты на фейковом dt
+DREAMTUNNEL_LIVE=1 pytest tests/test_live.py -v   # боевой релей
+```
+
+Лицензия: MIT.

dreamtunnel-0.1.0/README.md

@@ -0,0 +1,169 @@
+# dreamtunnel (Python SDK)
+
+Python-обёртка над CLI `dt`: запускает туннель **из кода**, отдаёт публичный
+URL, присылает события (включая переподключения) и корректно всё останавливает.
+
+Токен уже встроен в бинарник — после установки ничего настраивать не нужно.
+
+```bash
+pip install "git+https://github.com/dreamcatchered/dreamTunnel.git#subdirectory=sdk/python"
+```
+
+Из локальной копии репозитория — так же просто:
+
+```bash
+git clone https://github.com/dreamcatchered/dreamTunnel
+pip install -e dreamTunnel/sdk/python
+```
+
+Если `dt` ещё нет, SDK скачает его сам при первом запуске.
+
+## Быстрый старт
+
+```python
+from dreamtunnel import Tunnel
+
+with Tunnel(port=8080) as tun:
+    print(tun.url)        # https://k7f3m9ab.maiuni.online
+    ...                   # туннель живёт, пока мы внутри блока
+# выход из блока — туннель закрыт
+```
+
+Свой поддомен:
+
+```python
+with Tunnel(port=8080, subdomain="my-api") as tun:
+    print(tun.url)        # https://my-api.maiuni.online
+```
+
+## Управление вручную
+
+```python
+tun = Tunnel(port=3000, subdomain="dev")
+tun.start()               # ждёт, пока релей подтвердит туннель
+print(tun.url, tun.host, tun.local_url, tun.pid)
+
+tun.stop()                # SIGTERM, при необходимости SIGKILL
+tun.restart()             # перезапуск с тем же поддоменом
+
+tun.connect()             # синоним start()
+tun.disconnect()          # синоним stop()
+```
+
+## События и переподключение
+
+`dt` сам держит соединение и переподключается при обрыве. SDK отдаёт это наружу:
+
+```python
+def on_event(event: dict) -> None:
+    # event["event"]: ready | reconnected | disconnected | error | request | response
+    print(event)
+
+tun = Tunnel(port=8080, on_event=on_event)
+tun.start()
+
+tun.events          # все события, что видели
+tun.connected       # True, пока туннель на связи
+tun.stderr          # что писал dt в stderr
+```
+
+## Запуск приложения вместе с туннелем
+
+```python
+import threading, time
+from flask import Flask
+from dreamtunnel import Tunnel
+
+app = Flask(__name__)
+
+@app.route("/")
+def index():
+    return "привет"
+
+threading.Thread(
+    target=lambda: app.run(host="127.0.0.1", port=8080, use_reloader=False),
+    daemon=True,
+).start()
+time.sleep(0.5)
+
+with Tunnel(port=8080, subdomain="my-api") as tun:
+    print(tun.url)
+    while True:
+        time.sleep(1)
+```
+
+Рабочие примеры — в [`examples/`](examples): `flask_app.py`, `fastapi_app.py`.
+
+## CLI
+
+```bash
+dreamtunnel http 8080                 # как `dt http`, но через SDK
+dreamtunnel http 8080 my-api --json   # машинный вывод (NDJSON)
+dreamtunnel tcp 25565
+python -m dreamtunnel http 8080
+```
+
+## Параметры `Tunnel`
+
+| Параметр | По умолчанию | Смысл |
+|---|---|---|
+| `port` | — | локальный порт |
+| `subdomain` | случайный | желаемое имя: `my-api` → `my-api.maiuni.online` |
+| `mode` | `"http"` | `"http"` или `"tcp"` |
+| `server` | `tunnel.swag.best:444` | адрес control-канала |
+| `token` | встроенный | свой токен, если нужен приватный доступ |
+| `dt_binary` | авто | путь к `dt` |
+| `auto_install` | `True` | скачивать `dt`, если не найден |
+| `ready_timeout` | `30` | сколько ждать подтверждения |
+| `on_event` | `None` | колбэк на каждое событие |
+| `session` | `True` | свой файл настроек и сессия для этого туннеля |
+| `config_path` | — | явный путь к файлу настроек `dt` |
+
+## Исключения
+
+| Исключение | Когда |
+|---|---|
+| `BinaryNotFound` | `dt` не найден и автоустановка выключена |
+| `TunnelTimeout` | релей не ответил за `ready_timeout` |
+| `TunnelExited` | процесс `dt` умер до подключения (в `.output` — его вывод) |
+| `TunnelError` | релей отказал (плохой токен, занятый поддомен) |
+
+## Переменные окружения
+
+| Переменная | Смысл |
+|---|---|
+| `DT_BINARY` | путь к `dt` |
+| `DT_TOKEN` | токен доступа |
+| `DT_SERVER` | адрес control-канала |
+| `DT_SUB` | поддомен |
+| `DT_CONFIG` | файл настроек `dt` (SDK задаёт свой на каждый туннель) |
+| `DREAMTUNNEL_BASE_URL` | откуда скачивать бинарник (по умолчанию `https://tunnel.swag.best`) |
+| `DREAMTUNNEL_HOME` | куда класть скачанный бинарник и сессии (по умолчанию `~/.dreamtunnel`) |
+
+## Как это устроено
+
+SDK не переписывает протокол: он запускает `dt <mode> <port> --json` и
+разбирает поток NDJSON-событий (`ready`, `disconnected`, `error`, …). Если
+попался старый бинарник без `--json`, строки вида
+`Forwarding https://… -> http://…` разбираются регуляркой — поддержка
+обратной совместимости встроена.
+
+Каждому туннелю SDK выдаёт **свой** файл настроек `dt` (переменная
+`DT_CONFIG`), поэтому сессии не пересекаются: несколько туннелей с одной
+машины (и даже из одного процесса) работают одновременно и не выбивают друг
+друга. `tun.stop()` сохраняет файл — перезапуск получает тот же адрес,
+`tun.close()` его удаляет.
+
+Практический смысл: `dt` хранит session-id в `~/.dreamtunnel/config.env`, и
+если два процесса используют один файл, второй забирает сессию себе, а первый
+теряет туннель.
+
+## Тесты
+
+```bash
+pip install -e ".[test]"
+pytest                       # юнит-тесты на фейковом dt
+DREAMTUNNEL_LIVE=1 pytest tests/test_live.py -v   # боевой релей
+```
+
+Лицензия: MIT.

dreamtunnel-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dreamtunnel"
+version = "0.1.0"
+description = "Python SDK for dreamTunnel — instant public HTTPS tunnels"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["tunnel", "ngrok", "https", "webhook", "localhost", "self-hosted"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://tunnel.swag.best"
+Repository = "https://github.com/dreamcatchered/dreamTunnel"
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.scripts]
+dreamtunnel = "dreamtunnel.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dreamtunnel-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dreamtunnel-0.1.0/src/dreamtunnel/__init__.py

@@ -0,0 +1,40 @@
+"""Python SDK for dreamTunnel — instant public HTTPS tunnels.
+
+Typical use:
+
+    from dreamtunnel import Tunnel
+
+    with Tunnel(port=8080) as tun:
+        print(tun.url)          # https://k7f3m9ab.maiuni.online
+        ...
+
+The SDK supervises the existing ``dt`` CLI process: it starts the tunnel,
+waits until the relay reports it online, exposes the public URL, forwards the
+relay's events (including reconnects) to your code, and shuts the process down
+cleanly on exit.
+"""
+
+from .binary import ensure_dt, install_dt
+from .errors import (
+    BinaryNotFound,
+    DreamTunnelError,
+    TunnelError,
+    TunnelExited,
+    TunnelTimeout,
+)
+from .tunnel import DEFAULT_SERVER, Tunnel
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Tunnel",
+    "DEFAULT_SERVER",
+    "ensure_dt",
+    "install_dt",
+    "DreamTunnelError",
+    "BinaryNotFound",
+    "TunnelTimeout",
+    "TunnelExited",
+    "TunnelError",
+    "__version__",
+]

dreamtunnel-0.1.0/src/dreamtunnel/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m dreamtunnel``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dreamtunnel-0.1.0/src/dreamtunnel/binary.py

@@ -0,0 +1,152 @@
+"""Locate or install the ``dt`` binary.
+
+Lookup order:
+
+1. the ``dt_binary`` argument passed to :class:`~dreamtunnel.Tunnel`
+2. the ``DT_BINARY`` environment variable
+3. ``dt`` on ``PATH``
+4. the SDK cache (``~/.dreamtunnel/bin``)
+5. an automatic download from the public release endpoint, unless disabled
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import stat
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from .errors import BinaryNotFound
+
+DEFAULT_BASE_URL = os.environ.get("DREAMTUNNEL_BASE_URL", "https://tunnel.swag.best")
+
+# machine() spellings we accept
+_AMD64 = {"x86_64", "amd64", "x64", "i686", "i386", "x86"}
+_ARM64 = {"aarch64", "arm64"}
+
+
+def cache_root() -> Path:
+    """Root directory used by the SDK (``~/.dreamtunnel`` by default)."""
+    override = os.environ.get("DREAMTUNNEL_HOME")
+    return Path(override).expanduser() if override else Path.home() / ".dreamtunnel"
+
+
+def cache_dir() -> Path:
+    """Directory where downloaded binaries are kept."""
+    return cache_root() / "bin"
+
+
+def platform_binary_name(
+    system: str | None = None, machine: str | None = None
+) -> str:
+    """Return the release file name for the current (or given) platform.
+
+    Raises:
+        BinaryNotFound: for platforms dreamTunnel does not build for.
+    """
+    system = (system or platform.system()).lower()
+    machine = (machine or platform.machine()).lower()
+
+    if machine in _AMD64:
+        arch = "386" if machine in {"i686", "i386", "x86"} else "amd64"
+    elif machine in _ARM64:
+        arch = "arm64"
+    else:
+        raise BinaryNotFound(f"unsupported CPU architecture: {machine!r}")
+
+    if system.startswith("linux"):
+        return f"dt-linux-{arch}"
+    if system.startswith(("darwin", "mac")):
+        return f"dt-darwin-{arch}"
+    if system.startswith("win"):
+        return f"dt-windows-{arch}.exe"
+    raise BinaryNotFound(f"unsupported platform: {system!r}")
+
+
+def _executable_name() -> str:
+    return "dt.exe" if os.name == "nt" else "dt"
+
+
+def _make_executable(path: Path) -> None:
+    if os.name == "nt":
+        return
+    mode = path.stat().st_mode
+    path.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def download_dt(dest: Path | None = None, *, base_url: str = DEFAULT_BASE_URL) -> Path:
+    """Download the ``dt`` binary for this platform into the SDK cache."""
+    name = platform_binary_name()
+    dest = dest or (cache_dir() / _executable_name())
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    url = f"{base_url.rstrip('/')}/dl/{name}"
+    tmp = dest.with_suffix(dest.suffix + ".part")
+    try:
+        with urllib.request.urlopen(url, timeout=60) as resp:  # noqa: S310
+            data = resp.read()
+    except urllib.error.URLError as exc:  # pragma: no cover - network path
+        raise BinaryNotFound(f"could not download {url}: {exc}") from exc
+
+    if len(data) < 1024:
+        raise BinaryNotFound(f"download from {url} looks truncated ({len(data)} bytes)")
+
+    tmp.write_bytes(data)
+    tmp.replace(dest)
+    _make_executable(dest)
+    return dest
+
+
+def install_dt(
+    dest: Path | None = None, *, base_url: str = DEFAULT_BASE_URL, force: bool = False
+) -> Path:
+    """Install ``dt`` into the cache directory and return its path."""
+    dest = dest or (cache_dir() / _executable_name())
+    if dest.exists() and not force:
+        return dest
+    return download_dt(dest, base_url=base_url)
+
+
+def ensure_dt(
+    explicit: str | os.PathLike[str] | None = None,
+    *,
+    auto_install: bool = True,
+    base_url: str = DEFAULT_BASE_URL,
+) -> str:
+    """Return a usable path to ``dt``, installing it if necessary."""
+    if explicit:
+        path = Path(explicit).expanduser()
+        if path.exists():
+            return str(path)
+        raise BinaryNotFound(f"dt binary not found at {path}")
+
+    env = os.environ.get("DT_BINARY")
+    if env:
+        path = Path(env).expanduser()
+        if path.exists():
+            return str(path)
+
+    found = shutil.which("dt")
+    if found:
+        return found
+
+    cached = cache_dir() / _executable_name()
+    if cached.exists():
+        return str(cached)
+
+    if not auto_install:
+        raise BinaryNotFound(
+            "dt not found on PATH; install it with "
+            "`curl -fsSL https://tunnel.swag.best/install.sh | bash` "
+            "or pass dt_binary=..."
+        )
+
+    return str(download_dt(base_url=base_url))
+
+
+def python_supported() -> bool:
+    return sys.version_info >= (3, 10)