Add files via upload

README.md

@@ -22,8 +22,9 @@ AI-ассистент в Telegram: автоматический выбор ме
 ### Опциональные (есть разумные значения по умолчанию)
 | Переменная | По умолчанию | Назначение |
 |---|---|---|
-| `TELEGRAM_API_BASE_URL` | `https://api.telegram.org` | Базовый URL Telegram Bot API. В проде указывает на прокси `https://tg-proxy.silverelixir.deno.net`, т.к. HF Spaces не имеет прямого исходящего доступа к Telegram. |
+| `TELEGRAM_API_BASE_URL` | `https://api.telegram.org` | Базовый URL Telegram Bot API. В проде указывает на прокси (см. раздел "Прокси" ниже), т.к. HF Spaces не имеет прямого исходящего доступа к Telegram — датацентровые IP блокируются на уровне TLS-handshake. |
 | `TELEGRAM_API_BASE_URL_FALLBACKS` | — | Список резервных прокси через запятую. При срабатывании circuit breaker (см. `_rotate_telegram_proxy`) бот переключается на следующий адрес по кругу вместо того, чтобы просто ждать паузу на единственном известном прокси. Не задано — поведение как раньше, один прокси. |
+| `TIKWM_API_BASE_URL` | — (пусто — прямые запросы к TikWM) | Базовый URL прокси для запросов к TikWM (см. раздел "Прокси" ниже). НАЙДЕНО ПРИ ОТЛАДКЕ (август 2026, подтверждено вручную): TikWM стабильно отвечает HTTP 403 с пустым телом на запросы с датацентровых IP HF Spaces — тот же класс блокировки, что уже задокументирован ниже для YouTube. Троттлинг, ретраи, валидация URL и заголовки Referer/Origin (см. `_fetch_tikwm_media_data` в `lumen_tiktok.py`) не помогают — единственное подтверждённое рабочее решение — прокси с другого IP. Пусто по умолчанию — старое поведение (прямые запросы к обоим зеркалам tikwm.com), обратная совместимость сохранена. |
 | `TG_PROXY_COOLDOWN_SEC` | `20` (сек) | Пауза после срабатывания circuit breaker (когда прокси перед Telegram признан недоступным). |
 | `TG_PROXY_TRIP_THRESHOLD` | `3` | Сколько сбоев подряд (без единого успеха между ними) нужно, чтобы circuit breaker сработал — защита от того, чтобы одна разовая заминка на одной ноде anycast-CDN глушила ответы бота всем чатам. |
 | `ADMIN_SECRET_SEED` | значение `BOT_TOKEN` | Отдельная соль для вывода `WEBHOOK_SECRET`/`ADMIN_PANEL_KEY` — если задана, оба секрета можно ротировать независимо от `BOT_TOKEN`, не трогая сам токен бота у @BotFather. |
@@ -52,6 +53,22 @@ AI-ассистент в Telegram: автоматический выбор ме
 | `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN` | — | Если заданы ОБА — состояние (история чатов, квоты) пишется в Upstash Redis вместо эфемерного диска контейнера и переживает редеплой. См. раздел "Персистентное хранилище" ниже. |
 | `SENTRY_DSN` | — | Если задан — включает персистентный трекинг ошибок через Sentry (переживает редеплой, в отличие от `bot.log` на эфемерном диске). См. раздел "Трекинг ошибок (Sentry, бесплатно)" ниже. |
 
+## Прокси (Telegram + TikWM)
+
+HF Spaces не имеет прямого исходящего доступа к части внешних сервисов — датацентровые IP блокируются на уровне сети: Telegram Bot API блокируется полностью (на уровне TLS-handshake — без прокси бот вообще не может ходить в Telegram), TikWM отвечает HTTP 403 с пустым телом на все запросы (найдено при отладке, август 2026 — подтверждено вручную: та же ссылка с не-датацентрового IP, например с телефона на мобильной сети, скачивается через TikWM без проблем; троттлинг, ретраи, валидация URL и заголовки Referer/Origin, добавленные в `_fetch_tikwm_media_data`, не помогли — реальная причина именно блокировка IP, а не что-либо на стороне кода бота).
+
+Оба случая закрывает **один и тот же** прокси — небольшой self-hosted скрипт на Deno Deploy. Бесплатный тариф Deno Deploy: 1 млн запросов/мес, 20 ГБ исходящего трафика/мес, лимиты общие на весь аккаунт (не на отдельный проект) — поэтому смысла заводить два раздельных Deno-приложения (одно под Telegram, другое под TikWM) нет, они бы всё равно делили одну и ту же квоту.
+
+Прокси — прозрачный allowlisted pass-through: `https://<домен>/fetch/<host>/<путь>` пробрасывается в `https://<host>/<путь>` как есть (метод/заголовки/тело запроса и статус/заголовки/тело ответа — без изменений, тело стримится, а не буферизуется целиком в памяти — важно для загрузки видео в Telegram через `sendVideo`/`sendMediaGroup`). Разрешённые хосты — явный список внутри самого скрипта прокси (`api.telegram.org`, `www.tikwm.com`, `tikwm.com`) — без него прокси был бы открытым анонимным релеем на произвольный адрес, что тратило бы общую квоту трафика аккаунта и могло бы привлечь к аккаунту внимание как к источнику абьюза.
+
+Настройка:
+1. Задеплоить скрипт прокси (исходник — `proxy.ts`, живёт отдельно от этого Python-репозитория) как приложение на Deno Deploy.
+2. В HF Spaces secrets/variables:
+   - `TELEGRAM_API_BASE_URL = https://<домен>/fetch/api.telegram.org`
+   - `TIKWM_API_BASE_URL = https://<домен>/fetch/www.tikwm.com`
+
+`bot.py` дальше сам достраивает нужные пути (`/bot<token>/<method>`, `/file/bot<token>/<path>` для Telegram; `/api/?url=...` для TikWM) поверх этой базы — менять код при смене адреса прокси не нужно, только значения переменных окружения.
+
 ## Персистентное хранилище (Upstash Redis, бесплатно)
 
 По умолчанию `chat_state.json`/`global_quota.json` живут на диске контейнера HF Spaces — он эфемерный, при каждом редеплое (новый пуш кода) всё обнуляется. Чтобы это исправить бесплатно и без риска случайного списания денег:
@@ -209,7 +226,7 @@ AI-ассистент в Telegram: автоматический выбор ме
 - **Скачивание с YouTube не поддерживается** (датацентровые IP HF Spaces блокируются на уровне TLS-handshake) — доступен только просмотр/анализ по ссылке через встроенную возможность Gemini, не скачивание файла.
 - **Автоматический мониторинг падений — только опционально.** Без настроенного `SENTRY_DSN` (см. раздел "Трекинг ошибок" выше) узнать, что бот не отвечает, можно только по логам или жалобам пользователей — `bot.log` при этом живёт на эфемерном диске и не переживает редеплой. `_notify_owner` отдельно шлёт ЛС владельцу на два конкретных сценария (срабатывание circuit breaker прокси, полное исчерпание квоты Gemini), но это точечные алерты, а не общая история ошибок. `/diag` — ручная проверка по запросу.
 - **Стриминг не тестировался против реальных API** (см. выше) — только через мокнутые asyncio-клиент (Gemini) и aiohttp-сессию (OpenRouter, SSE). Логика проверена, но стоит последить за логами `[stream]`/`[identity-leak]`/`[injection-echo]` первые несколько дней после деплоя — особенно для OpenRouter-стриминга, добавленного позже Gemini-версии.
-- **Скачивание TikTok зависит от неофициального стороннего API (TikWM)**, а не от официального API TikTok (которого для скачивания попросту не существует публично) — при изменении TikWM формата ответа или его временной недоступности скачивание может сломаться до соответствующей правки кода. Диагностический лог `[tikwm][diag]` (см. раздел выше) — первое место, куда стоит смотреть при таких сбоях.
+- **Скачивание TikTok зависит от неофициального стороннего API (TikWM)**, а не от официального API TikTok (которого для скачивания попросту не существует публично) — при изменении TikWM формата ответа или его временной недоступности скачивание может сломаться до соответствующей правки кода. Диагностический лог `[tikwm][diag]` (см. раздел выше) — первое место, куда стоит смотреть при таких сбоях. TikWM также блокирует датацентровые IP HF Spaces (см. раздел "Прокси" выше, `TIKWM_API_BASE_URL`) — без настроенного прокси скачивание TikTok стабильно не работает вообще.
 - **Разрешение фото в TikTok-слайдшоу не проверено попиксельно** — сопоставление с оригиналом в приложении TikTok руками не делалось; по виду URL (`~tplv-photomode-image.jpeg`, без явных суффиксов вида `zoomcover:WxH`, которые обычно означают уменьшенную обложку/превью) похоже на полноразмерный кадр, но это косвенный, а не стопроцентно подтверждённый признак.
 
 ## Тесты

bot.py

@@ -180,6 +180,19 @@ _TELEGRAM_PROXY_FALLBACKS = [
 _TELEGRAM_PROXY_CANDIDATES: list[str] = [TELEGRAM_API_BASE_URL] + [u for u in _TELEGRAM_PROXY_FALLBACKS if u != TELEGRAM_API_BASE_URL]
 _telegram_proxy_idx = 0  # индекс текущего активного прокси в _TELEGRAM_PROXY_CANDIDATES
 
+# НАЙДЕНО ПРИ ОТЛАДКЕ (11-12 августа 2026, реальный инцидент): TikWM стабильно
+# отвечает HTTP 403 с ПУСТЫМ телом на запросы с IP HF Spaces (см. историю правок
+# в lumen_tiktok.py — троттлинг, ретраи и подмена заголовков не помогли, реальная
+# причина — блокировка исходящего IP, а не что-либо, что чинится на нашей
+# стороне). TIKWM_API_BASE_URL — опциональная база для прокси-запроса к TikWM
+# (единый прокси с Telegram, см. README/proxy.ts — тот же принцип, что уже
+# применяется для TELEGRAM_API_BASE_URL). Пусто по умолчанию — _fetch_tikwm_media_data
+# в этом случае стучится в TikWM напрямую (два зеркала), как и раньше; если
+# задано — идёт ОДНИМ запросом через прокси вместо прямого обращения к двум
+# зеркалам напрямую (сам прокси уже решает, к какому реальному хосту TikWM
+# стучаться — см. proxy.ts).
+TIKWM_API_BASE_URL = os.getenv("TIKWM_API_BASE_URL", "").strip().rstrip("/")
+
 BOT_USERNAME = os.getenv("BOT_USERNAME", "LumenAI_bot").strip().lstrip("@")
 GEMINI_API_KEY = os.getenv("GEMINI_API_KEY", "").strip()
 OPENROUTER_API_KEY = (os.getenv("OPENROUTER_API_KEY") or os.getenv("OPENROUTER_KEY") or "").strip()
@@ -2496,17 +2509,15 @@ async def handle_tiktok(message: Message, url: str) -> None:
          # передавался, и бот молча всегда скачивал видео в обычном качестве, даже
          # когда у TikWM реально была версия получше (см. _tiktok_video_candidates).
          #
-         # ИСПРАВЛЕНО (отладка 11-12 августа 2026, реальный инцидент — оба зеркала TikWM
-         # стабильно отвечали HTTP 403 почти на любую ссылку): запрос к обоим зеркалам
-         # TikWM (www.tikwm.com/tikwm.com) с троттлингом и одной повторной попыткой при
-         # 403 у ОБОИХ зеркал вынесен в _fetch_tikwm_media_data (lumen_tiktok.py). ВАЖНО —
-         # честно зафиксировано по итогам повторной отладки: троттлинг и валидность
-         # резолвленного URL (см. _looks_like_resolved_tiktok_url) сами по себе инцидент
-         # НЕ закрыли — 403 с пустым телом продолжал приходить даже при полностью
-         # корректном URL и правильно разнесённых по времени запросах. См. подробный
-         # диагностический комментарий и лог "[tikwm][diag]" внутри _fetch_tikwm_media_data
-         # — похоже на блокировку исходящего IP этого сервера, а не на баг в нашем коде.
-         media_data = await _fetch_tikwm_media_data(session, resolved_url, headers)
+         # ИСПРАВЛЕНО (отладка 11-13 августа 2026, реальный инцидент — оба зеркала TikWM
+         # стабильно отвечали HTTP 403 почти на любую ссылку): троттлинг, ретраи, валидация
+         # резолвленного URL (см. _looks_like_resolved_tiktok_url) и заголовки Referer/Origin
+         # — НЕ помогли, 403 с пустым телом продолжал приходить даже при полностью корректном
+         # URL и правильно разнесённых по времени запросах. Причина подтверждена вручную —
+         # блокировка исходящего IP HF Spaces (см. подробный диагностический комментарий в
+         # _fetch_tikwm_media_data). TIKWM_API_BASE_URL — единственное реально работающее
+         # решение: запрос уходит через выделенный прокси с другого IP (см. proxy.ts).
+         media_data = await _fetch_tikwm_media_data(session, resolved_url, headers, proxy_base_url=TIKWM_API_BASE_URL)
 
          if not media_data:
               raise TikTokUserFacingError("Не удалось полу��ить видео по этой ссылке — возможно, оно приватное, удалено, заблокировано по региону или ссылка битая.")

lumen_tiktok.py

@@ -291,12 +291,13 @@ async def _tikwm_throttle() -> None:
         _tikwm_last_request_ts = now
 
 
-async def _fetch_tikwm_media_data(session: aiohttp.ClientSession, resolved_url: str, headers: dict, *, hd: bool = True) -> dict | None:
-    """Запрашивает метаданные поста TikTok у публичного API TikWM, пробуя оба
-    известных зеркала (www.tikwm.com и tikwm.com) — см. секцию выше про троттлинг
-    и почему 403 от обоих зеркал заслуживает одной повторной попытки. Возвращает
-    `data` из ответа при успехе (`code == 0`) или None, если ни одно зеркало не
-    отдало рабочих данных даже после повторной попытки.
+async def _fetch_tikwm_media_data(
+    session: aiohttp.ClientSession, resolved_url: str, headers: dict, *, hd: bool = True,
+    proxy_base_url: str = "",
+) -> dict | None:
+    """Запрашивает метаданные поста TikTok у публичного API TikWM. Возвращает
+    `data` из ответа при успехе (`code == 0`) или None, если не отдало рабочих
+    данных даже после повторной попытки.
 
     Ответ с ЛЮБЫМ статусом, кроме 200, логируется вместе с телом ответа (а не
     только кодом статуса) — без текста самой ошибки TikWM невозможно отличить
@@ -304,19 +305,27 @@ async def _fetch_tikwm_media_data(session: aiohttp.ClientSession, resolved_url:
 
     НАЙДЕНО ПРИ ПОВТОРНОЙ ОТЛАДКЕ (12 августа 2026): даже полностью корректный,
     заново провалидированный URL (см. _looks_like_resolved_tiktok_url) и
-    корректно разнесённые по времени запросы (throttle+retry выше — оба реально
+    корректно разнесённые по времени запросы (throttle+retry ниже — оба реально
     сработали в реальном инциденте, см. историю правок) всё равно стабильно
-    получали HTTP 403 с ПОЛНОСТЬЮ ПУСТЫМ телом от ОБОИХ зеркал. Это не похоже
-    на обычную ошибку самого приложения TikWM (та приходит как HTTP 200 с JSON
-    {"code":..., "msg":...}, см. ветку ниже) — пустое тело на 403 гораздо больше
-    похоже на блокировку на уровне прокси/WAF/файрвола ПЕРЕД TikWM (тот же класс
-    проблемы, что уже задокументирован в README для YouTube — блокировка
-    датацентровых IP HF Spaces), чем на что-либо, что чинится тайминг- или URL-
-    правками на нашей стороне. `Referer`/`Origin`, имитирующие вызов со страницы
-    самого tikwm.com — распространённая, но НЕ гарантированная техника обхода
-    подобных анти-скрейпинг проверок; честно говоря, из песочницы разработки нет
-    возможности проверить исходящую сеть до tikwm.com напрямую, поэтому эффект
-    этого изменения можно подтвердить только по реальному продакшен-трафику."""
+    получали HTTP 403 с ПОЛНОСТЬЮ ПУСТЫМ телом от ОБОИХ прямых зеркал TikWM.
+    Это не похоже на обычную ошибку самого приложения TikWM (та приходит как
+    HTTP 200 с JSON {"code":..., "msg":...}, см. ветку ниже) — пустое тело на
+    403 гораздо больше похоже на блокировку исходящего IP HF Spaces на уровне
+    прокси/WAF перед TikWM (тот же класс проблемы, что уже задокументирован в
+    README для YouTube), чем на что-либо, что чинится тайминг- или URL-правками
+    на нашей стороне. Подтверждено вручную владельцем: то же самое видео через
+    собственный веб-интерфейс TikWM с телефона на мобильной сети (не датацентровый
+    IP) скачивается без проблем — единственное отличие от сервера бота именно
+    исходящий IP. `proxy_base_url` ниже — единственное реально рабочее решение из
+    всех попробованных (throttle/URL-валидация/заголовки Referer-Origin не помогли).
+
+    `proxy_base_url` (см. TIKWM_API_BASE_URL в bot.py, proxy.ts в отдельном
+    Deno-репозитории) — если задан, запрос идёт ЧЕРЕЗ выделенный прокси с
+    другого, незаблокированного IP, ОДНИМ эндпоинтом вместо двух прямых зеркал:
+    устойчивость к недоступности одного зеркала (изначальная причина пробовать
+    оба) прокси даёт даром просто тем, что выходит с другого IP — дублировать
+    зеркала друг для друга через прокси уже незачем. Если не задан (пусто по
+    умолчанию) — прежнее поведение, прямые запросы к обоим зеркалам напрямую."""
     api_headers = {
         **headers,
         "Referer": "https://www.tikwm.com/",
@@ -324,10 +333,14 @@ async def _fetch_tikwm_media_data(session: aiohttp.ClientSession, resolved_url:
         "Accept": "application/json, text/plain, */*",
     }
     quoted = urllib.parse.quote(resolved_url)
-    endpoints = [
-        f"https://www.tikwm.com/api/?url={quoted}&hd=1" if hd else f"https://www.tikwm.com/api/?url={quoted}",
-        f"https://tikwm.com/api/?url={quoted}&hd=1" if hd else f"https://tikwm.com/api/?url={quoted}",
-    ]
+    if proxy_base_url:
+        suffix = f"/api/?url={quoted}&hd=1" if hd else f"/api/?url={quoted}"
+        endpoints = [f"{proxy_base_url}{suffix}"]
+    else:
+        endpoints = [
+            f"https://www.tikwm.com/api/?url={quoted}&hd=1" if hd else f"https://www.tikwm.com/api/?url={quoted}",
+            f"https://tikwm.com/api/?url={quoted}&hd=1" if hd else f"https://tikwm.com/api/?url={quoted}",
+        ]
     # Остаётся True только если ВООБЩЕ каждая попытка (оба зеркала, оба раунда)
     # была именно "403 + пустое тело" — ни одной другой ошибки/статуса/исключения
     # среди них не было. Используется только для диагностического лога ниже —

proxy.ts

@@ -0,0 +1,145 @@
+/**
+ * proxy.ts — единая точка выхода для запросов, которые сервер бота (HF Spaces)
+ * не может сделать напрямую, потому что датацентровые IP HF Spaces блокируются
+ * некоторыми сервисами на уровне сети (см. README проекта Lumen):
+ *   - Telegram Bot API (полностью заблокирован на уровне TLS-handshake — без
+ *     этого прокси бот вообще не может ходить в Telegram).
+ *   - TikWM (стабильно отвечает HTTP 403 с пустым телом на исходящие запросы
+ *     с IP HF Spaces — см. историю отладки, /logs с тегом [tikwm][diag]).
+ *
+ * ЗАМЕНЯЕТ собой прежний tg-proxy (умел проксировать только Telegram Bot API
+ * по формату /bot<token>/<method>) — переименован и обобщён. Лимиты Deno
+ * Deploy (free-тариф: 1 млн запросов/мес, 20 ГБ исходящего трафика/мес, 15ч
+ * CPU/мес) общие на ВЕСЬ АККАУНТ, а не на отдельный проект — значит держать
+ * два раздельных Deno-приложения (одно под Telegram, другое под TikWM) не
+ * даёт вообще никакой отдельной квоты, только лишняя сущность для поддержки.
+ * Один универсальный прокси проще: один домен, один секрет, один деплой.
+ *
+ * ── Формат ──
+ * GET/POST/... https://<домен>/fetch/<host>/<путь...>?<query>
+ *   -> https://<host>/<путь...>?<query>
+ * Метод, заголовки и тело запроса передаются как есть; статус, заголовки и
+ * тело ответа — тоже как есть (без буферизации целиком в память — тело
+ * стримится напрямую, это важно для больших file-загрузок в Telegram, см.
+ * sendVideo/sendPhoto/sendMediaGroup у бота).
+ *
+ * ── Почему нужен allowlist хостов ──
+ * Без ограничения на разрешённые хосты это был бы открытый анонимный релей на
+ * ЛЮБОЙ адрес в интернете — кто угодно, узнав домен, мог бы использовать его
+ * для проксирования куда захочет, тратя общую квоту трафика аккаунта (те же
+ * 20 ГБ/мес) и потенциально привлекая к аккаунту внимание как к источнику
+ * абьюза/скана. ALLOWED_HOSTS ниже — единственные хосты, которые реально
+ * нужны боту; расширять список нужно только по факту новой подтверждённой
+ * необходимости (см. тот же принцип "не добавляй заранее" в остальном проекте).
+ *
+ * ── Как настроить бота на использование этого прокси ──
+ * В HF Spaces secrets/variables:
+ *   TELEGRAM_API_BASE_URL = https://<домен>/fetch/api.telegram.org
+ *   TIKWM_API_BASE_URL    = https://<домен>/fetch/www.tikwm.com
+ * bot.py дальше сам достраивает нужные пути (/bot<token>/<method>,
+ * /file/bot<token>/<path>, /api/?url=...) поверх этой базы — никаких других
+ * изменений в Python-коде для смены адреса прокси не требуется.
+ */
+
+export const ALLOWED_HOSTS = new Set([
+  "api.telegram.org",
+  "www.tikwm.com",
+  "tikwm.com",
+]);
+
+// Заголовки, которые нельзя слепо пробрасывать дальше как есть — Host/Connection
+// в запросе относятся к соединению с ЭТИМ (Deno) сервером, а не с реальным
+// апстримом, апстрим сам выставит правильные. Content-Encoding/Content-Length в
+// ОТВЕТЕ — fetch() в Deno уже сам распаковывает gzip/br к моменту, когда тело
+// становится нам доступно, поэтому исходный Content-Encoding больше не описывает
+// реальное тело — клиент, попытавшийся распаковать уже распакованное, получил бы
+// битые данные. Content-Length по той же причине может не совпадать с реальным
+// размером — рантайм сам выставит корректный Transfer-Encoding для стрима.
+const HOP_BY_HOP_REQUEST_HEADERS = ["host", "connection"];
+const HOP_BY_HOP_RESPONSE_HEADERS = ["content-encoding", "content-length", "connection", "transfer-encoding"];
+
+// Разложено на чистые, независимо тестируемые функции (resolveTarget/
+// buildForwardHeaders/buildResponseHeaders) вместо одного большого обработчика —
+// тот же принцип, что и в остальном проекте Lumen (см. lumen_tiktok.py и др.):
+// маршрутизацию и фильтрацию заголовков можно проверить юнит-тестами без единого
+// реального сетевого вызова, а сама сетевая часть (handleRequest) тестируется
+// отдельно через подмену fetch.
+
+export type TargetResolution =
+  | { ok: true; host: string; url: string }
+  | { ok: false; status: 404 | 403; message: string };
+
+export function resolveTarget(pathname: string, search: string): TargetResolution {
+  // pathname всегда начинается с "/", поэтому после split("/") первый элемент —
+  // всегда пустая строка, а реальные сегменты — начиная с индекса 1. Намеренно
+  // НЕ фильтруем пустые сегменты через .filter(Boolean) (как было в первой
+  // версии) — НАЙДЕНО ПРИ ТЕСТИРОВАНИИ: filter(Boolean) съедал завершающий "/"
+  // у путей вида "/fetch/host/api/" (пустой хвостовой сегмент после join
+  // как раз и восстанавливает эту же завершающую "/"), из-за чего запрос
+  // TikWM вида ".../api/?url=..." ушёл бы к апстриму как ".../api?url=..."
+  // без слеша — ровно тот класс "почти правильного, но не совсем" URL, из-за
+  // которого уже был потрачен не один час отладки в этом проекте.
+  const parts = pathname.split("/");
+  if (parts.length < 3 || parts[1] !== "fetch" || parts[2] === "") {
+    return { ok: false, status: 404, message: "Not found — ожидаемый формат пути: /fetch/<host>/<путь>" };
+  }
+  const host = parts[2];
+  if (!ALLOWED_HOSTS.has(host)) {
+    return { ok: false, status: 403, message: "Host not allowed" };
+  }
+  const path = "/" + parts.slice(3).join("/");
+  return { ok: true, host, url: `https://${host}${path}${search}` };
+}
+
+export function buildForwardHeaders(reqHeaders: Headers): Headers {
+  const headers = new Headers(reqHeaders);
+  for (const name of HOP_BY_HOP_REQUEST_HEADERS) headers.delete(name);
+  return headers;
+}
+
+export function buildResponseHeaders(upstreamHeaders: Headers): Headers {
+  const headers = new Headers(upstreamHeaders);
+  for (const name of HOP_BY_HOP_RESPONSE_HEADERS) headers.delete(name);
+  return headers;
+}
+
+// fetchImpl — точка подмены для тестов (тот же приём, что bot._get_http_session
+// и т.п. в Python-части проекта) — реальная сеть не нужна ни одному юнит-тесту.
+export async function handleRequest(req: Request, fetchImpl: typeof fetch = fetch): Promise<Response> {
+  const url = new URL(req.url);
+  const target = resolveTarget(url.pathname, url.search);
+  if (!target.ok) {
+    return new Response(target.message, { status: target.status });
+  }
+
+  const forwardHeaders = buildForwardHeaders(req.headers);
+  let upstreamResp: Response;
+  try {
+    upstreamResp = await fetchImpl(target.url, {
+      method: req.method,
+      headers: forwardHeaders,
+      // GET/HEAD не могут иметь тело запроса (fetch бросит исключение, если
+      // передать body для них) — для остальных методов пробрасываем тело
+      // напрямую как поток, не буферизуя целиком в памяти (важно для
+      // multipart file-загрузок в Telegram, см. докстринг выше).
+      body: (req.method === "GET" || req.method === "HEAD") ? undefined : req.body,
+      // @ts-ignore — Deno требует duplex:"half" для потокового тела запроса
+      // (часть стандарта WHATWG fetch для body типа ReadableStream).
+      duplex: "half",
+    });
+  } catch (e) {
+    return new Response(`Upstream fetch failed: ${e}`, { status: 502 });
+  }
+
+  const respHeaders = buildResponseHeaders(upstreamResp.headers);
+  return new Response(upstreamResp.body, {
+    status: upstreamResp.status,
+    headers: respHeaders,
+  });
+}
+
+// Реальный сервер стартует только при прямом запуске файла (deno run/deploy),
+// не при импорте из proxy_test.ts — и��аче тесты пытались бы забиндить порт.
+if (import.meta.main) {
+  Deno.serve((req) => handleRequest(req));
+}

proxy_test.ts

@@ -0,0 +1,187 @@
+// proxy_test.ts — юнит-тесты на proxy.ts. Намеренно БЕЗ внешних зависимостей
+// (никаких jsr:/npm: импортов) — только простые ручные assert-функции ниже.
+// Так `deno test` работает даже без доступа в интернет и не тянет lock-файл.
+//
+// Запуск:
+//   deno test proxy_test.ts
+
+import {
+  ALLOWED_HOSTS,
+  buildForwardHeaders,
+  buildResponseHeaders,
+  handleRequest,
+  resolveTarget,
+} from "./proxy.ts";
+
+function assert(condition: boolean, message: string): void {
+  if (!condition) throw new Error(message);
+}
+
+function assertEquals<T>(actual: T, expected: T, message?: string): void {
+  const ok = JSON.stringify(actual) === JSON.stringify(expected);
+  if (!ok) {
+    throw new Error(
+      message ?? `Ожидалось ${JSON.stringify(expected)}, получено ${JSON.stringify(actual)}`,
+    );
+  }
+}
+
+// ─────────────────────────── resolveTarget ───────────────────────────
+
+Deno.test("resolveTarget строит корректный URL для разрешённого хоста", () => {
+  const result = resolveTarget("/fetch/api.telegram.org/bot123/getMe", "");
+  assert(result.ok, "ожидался ok=true");
+  if (result.ok) {
+    assertEquals(result.host, "api.telegram.org");
+    assertEquals(result.url, "https://api.telegram.org/bot123/getMe");
+  }
+});
+
+Deno.test("resolveTarget сохраняет query-строку как есть", () => {
+  const result = resolveTarget("/fetch/www.tikwm.com/api/", "?url=https://x&hd=1");
+  assert(result.ok, "ожидался ok=true");
+  if (result.ok) {
+    assertEquals(result.url, "https://www.tikwm.com/api/?url=https://x&hd=1");
+  }
+});
+
+Deno.test("resolveTarget не теряет завершающий слеш в пути (регрессия)", () => {
+  // РЕГРЕССИЯ: первая версия использовала .filter(Boolean) при разборе пути,
+  // который съедал пустой хвостовой сегмент после последнего "/" — путь вида
+  // "/fetch/host/api/" превращался в "https://host/api" (без слеша). Именно
+  // такой формат URL реально нужен TikWM (см. bot.py: ".../api/?url=...").
+  const withSlash = resolveTarget("/fetch/www.tikwm.com/api/", "");
+  assert(withSlash.ok, "ожидался ok=true");
+  if (withSlash.ok) assertEquals(withSlash.url, "https://www.tikwm.com/api/");
+
+  const withoutSlash = resolveTarget("/fetch/www.tikwm.com/api", "");
+  assert(withoutSlash.ok, "ожидался ok=true");
+  if (withoutSlash.ok) assertEquals(withoutSlash.url, "https://www.tikwm.com/api");
+});
+
+Deno.test("resolveTarget корректно строит вложенный путь (Telegram file API)", () => {
+  // Регрессия на реальный формат вызова из bot.py (_download_telegram_file_bytes):
+  // {TELEGRAM_API_BASE_URL}/file/bot{TOKEN}/{file_path}
+  const result = resolveTarget("/fetch/api.telegram.org/file/bot123/photos/file_1.jpg", "");
+  assert(result.ok, "ожидался ok=true");
+  if (result.ok) {
+    assertEquals(result.url, "https://api.telegram.org/file/bot123/photos/file_1.jpg");
+  }
+});
+
+Deno.test("resolveTarget отклоняет неразрешённый хост с 403 и не строит URL на его основе", () => {
+  const result = resolveTarget("/fetch/evil.example.com/steal", "");
+  assert(!result.ok, "ожидался ok=false");
+  if (!result.ok) {
+    assertEquals(result.status, 403);
+  }
+});
+
+Deno.test("resolveTarget отклоняет некорректный формат пути с 404", () => {
+  assertEquals(resolveTarget("/", "").ok, false);
+  assertEquals(resolveTarget("/fetch", "").ok, false);
+  assertEquals(resolveTarget("/fetch/", "").ok, false);
+  assertEquals(resolveTarget("/wrong-prefix/api.telegram.org/getMe", "").ok, false);
+});
+
+Deno.test("ALLOWED_HOSTS содержит ровно те хосты, что реально нужны боту", () => {
+  assertEquals(ALLOWED_HOSTS.has("api.telegram.org"), true);
+  assertEquals(ALLOWED_HOSTS.has("www.tikwm.com"), true);
+  assertEquals(ALLOWED_HOSTS.has("tikwm.com"), true);
+  assertEquals(ALLOWED_HOSTS.size, 3);
+});
+
+// ─────────────────────────── buildForwardHeaders / buildResponseHeaders ───────────────────────────
+
+Deno.test("buildForwardHeaders убирает hop-by-hop заголовки запроса, остальные сохраняет", () => {
+  const original = new Headers({
+    "Host": "proxy.example.com",
+    "Connection": "keep-alive",
+    "User-Agent": "test-ua",
+  });
+  const forwarded = buildForwardHeaders(original);
+  assertEquals(forwarded.has("host"), false);
+  assertEquals(forwarded.has("connection"), false);
+  assertEquals(forwarded.get("user-agent"), "test-ua");
+});
+
+Deno.test("buildResponseHeaders убирает Content-Encoding/Content-Length (см. докстринг про распаковку)", () => {
+  // РЕГРЕССИЯ: fetch() в Deno сам распаковывает gzip/br до того, как тело
+  // становится доступно — пробросить исходный Content-Encoding было бы багом
+  // (клиент попытался бы распаковать уже распакованные данные).
+  const original = new Headers({
+    "Content-Encoding": "gzip",
+    "Content-Length": "1234",
+    "Content-Type": "application/json",
+  });
+  const cleaned = buildResponseHeaders(original);
+  assertEquals(cleaned.has("content-encoding"), false);
+  assertEquals(cleaned.has("content-length"), false);
+  assertEquals(cleaned.get("content-type"), "application/json");
+});
+
+// ─────────────────────────── handleRequest (с подменённым fetch) ───────────────────────────
+
+Deno.test("handleRequest пробрасывает GET без тела и возвращает статус/тело апстрима", async () => {
+  const fakeFetch: typeof fetch = (url, init) => {
+    assertEquals(String(url), "https://www.tikwm.com/api/?url=x");
+    assertEquals(init?.method, "GET");
+    assertEquals(init?.body, undefined);
+    return Promise.resolve(new Response(JSON.stringify({ code: 0 }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    }));
+  };
+  const req = new Request("https://proxy.example/fetch/www.tikwm.com/api/?url=x", { method: "GET" });
+  const resp = await handleRequest(req, fakeFetch);
+  assertEquals(resp.status, 200);
+  const body = await resp.json();
+  assertEquals(body, { code: 0 });
+});
+
+Deno.test("handleRequest возвращает 403 для неразрешённого хоста, не вызывая fetch вообще", async () => {
+  let fetchCalled = false;
+  const fakeFetch: typeof fetch = () => {
+    fetchCalled = true;
+    return Promise.resolve(new Response("не должно случиться"));
+  };
+  const req = new Request("https://proxy.example/fetch/evil.example.com/x", { method: "GET" });
+  const resp = await handleRequest(req, fakeFetch);
+  assertEquals(resp.status, 403);
+  assertEquals(fetchCalled, false, "fetch не должен был вызываться для неразрешённого хоста");
+});
+
+Deno.test("handleRequest возвращает 404 для пути без /fetch/ префикса", async () => {
+  const req = new Request("https://proxy.example/something-else", { method: "GET" });
+  const unusedFetch: typeof fetch = () => Promise.resolve(new Response("unused"));
+  const resp = await handleRequest(req, unusedFetch);
+  assertEquals(resp.status, 404);
+});
+
+Deno.test("handleRequest пробрасывает метод и тело для POST (Telegram sendMessage)", async () => {
+  let capturedMethod: string | undefined;
+  let capturedBodyIsStream = false;
+  const fakeFetch: typeof fetch = (_url, init) => {
+    capturedMethod = init?.method;
+    capturedBodyIsStream = init?.body instanceof ReadableStream;
+    return Promise.resolve(new Response('{"ok":true}', { status: 200 }));
+  };
+  const req = new Request("https://proxy.example/fetch/api.telegram.org/bot123/sendMessage", {
+    method: "POST",
+    body: JSON.stringify({ chat_id: 1, text: "hi" }),
+    headers: { "Content-Type": "application/json" },
+  });
+  const resp = await handleRequest(req, fakeFetch);
+  assertEquals(resp.status, 200);
+  assertEquals(capturedMethod, "POST");
+  assert(capturedBodyIsStream, "тело POST-запроса должно передаваться апстриму как поток (без буферизации целиком)");
+});
+
+Deno.test("handleRequest возвращает 502, если апстрим-fetch упал с исключением", async () => {
+  const fakeFetch: typeof fetch = () => {
+    throw new Error("network unreachable");
+  };
+  const req = new Request("https://proxy.example/fetch/api.telegram.org/getMe", { method: "GET" });
+  const resp = await handleRequest(req, fakeFetch);
+  assertEquals(resp.status, 502);
+});

test_bot.py

@@ -3319,6 +3319,65 @@ def test_fetch_tikwm_media_data_sends_referer_and_origin_headers():
     assert sent_headers["User-Agent"] == "test-ua"
 
 
+# ─────────────────── _fetch_tikwm_media_data: запрос через выделенный прокси (proxy_base_url) ───────────────────
+# Регрессия на итог отладки блокировки IP (см. README/proxy.ts): throttle, ретраи,
+# валидация URL и Referer/Origin не помогли — единственное подтверждённое рабочее
+# решение — прокси с другого IP. Тесты ниже проверяют именно ветку `proxy_base_url`
+# в отрыве от прямых зеркал (та ветка уже покрыта тестами выше).
+
+def test_fetch_tikwm_media_data_uses_single_proxy_endpoint_when_configured():
+    resp = _FakeTikwmApiResponse(status=200, json_body={"code": 0, "data": {"play": "via-proxy"}})
+    session = _FakeTikwmApiSession([resp])
+    result = asyncio.run(bot._fetch_tikwm_media_data(
+        session, "https://www.tiktok.com/@u/video/1", {},
+        proxy_base_url="https://proxy.example.com/fetch/www.tikwm.com",
+    ))
+    assert result == {"play": "via-proxy"}
+    # Ровно ОДИН запрос (не два зеркала) — прокси сам решает, к какому реальному
+    # хосту TikWM стучаться, дублировать зеркала через него уже незачем.
+    assert session.requested_urls == [
+        "https://proxy.example.com/fetch/www.tikwm.com/api/?url=https%3A//www.tiktok.com/%40u/video/1&hd=1"
+    ]
+
+
+def test_fetch_tikwm_media_data_proxy_endpoint_respects_hd_flag():
+    resp = _FakeTikwmApiResponse(status=200, json_body={"code": 0, "data": {"play": "x"}})
+    session = _FakeTikwmApiSession([resp])
+    asyncio.run(bot._fetch_tikwm_media_data(
+        session, "https://www.tiktok.com/@u/video/1", {}, hd=False,
+        proxy_base_url="https://proxy.example.com/fetch/www.tikwm.com",
+    ))
+    assert "&hd=1" not in session.requested_urls[0]
+
+
+def test_fetch_tikwm_media_data_proxy_still_retries_once_on_403():
+    # Ретрай-раунд при 403 (см. _TIKWM_RETRY_BACKOFF_SEC) не завязан на наличие
+    # двух зеркал — с одним прокси-эндпоинтом повторная попытка тоже должна
+    # сработать (мало ли транзиентная ошибка именно на стороне прокси).
+    responses = [
+        _FakeTikwmApiResponse(status=403, body_bytes=b""),
+        _FakeTikwmApiResponse(status=200, json_body={"code": 0, "data": {"play": "retried"}}),
+    ]
+    session = _FakeTikwmApiSession(responses)
+    result = asyncio.run(bot._fetch_tikwm_media_data(
+        session, "https://www.tiktok.com/@u/video/1", {},
+        proxy_base_url="https://proxy.example.com/fetch/www.tikwm.com",
+    ))
+    assert result == {"play": "retried"}
+    assert len(session.requested_urls) == 2
+
+
+def test_fetch_tikwm_media_data_without_proxy_still_uses_both_direct_mirrors():
+    # Регрессия на обратную совместимость: proxy_base_url="" (значение по
+    # умолчанию, как и раньше, когда TIKWM_API_BASE_URL не задан в env) должно
+    # сохранять старое поведение — оба прямых зеркала, без единого изменения.
+    resp = _FakeTikwmApiResponse(status=200, json_body={"code": 0, "data": {"play": "direct"}})
+    session = _FakeTikwmApiSession([resp])
+    result = asyncio.run(bot._fetch_tikwm_media_data(session, "https://www.tiktok.com/@u/video/1", {}))
+    assert result == {"play": "direct"}
+    assert session.requested_urls[0].startswith("https://www.tikwm.com/api/?url=")
+
+
 def test_fetch_tikwm_media_data_logs_ip_block_hint_when_all_attempts_403_with_empty_body(caplog):
     # Регрессия на реальный инцидент (12 августа 2026): корректный URL + корректный
     # троттлинг + ВСЕ попытки (оба зеркала, оба раунда) вернули 403 с пустым телом —