mirror of
https://gitverse.ru/kpa39l/openspec-lab.git
synced 2026-09-29 09:15:01 +00:00
OpenSpec: исследование + tavily-proxy-setup, local-extractor (spec-driven для инфраструктуры)
This commit is contained in:
estorozhenko
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-06
|
||||
@@ -0,0 +1,38 @@
|
||||
# Design: add-vpn-tunnel-proxy
|
||||
|
||||
## Approach
|
||||
|
||||
Использовать существующий systemd-юнит `telegram-tunnel.service` (SSH -D :1080 → VPS01). Добавить:
|
||||
- `Restart=always`, `RestartSec=5` в юнит
|
||||
- `WantedBy=multi-user.target` + `systemctl enable`
|
||||
- Healthcheck: cron-скрипт или systemd-таймер, проверяющий `curl --socks5-hostname 127.0.0.1:1080 https://api.tavily.com` (HTTP 200 = жив). Молчит, если всё ок; шумит только при падении (по предпочтению пользователя — тихие watchdogs).
|
||||
|
||||
## Files
|
||||
|
||||
- `/etc/systemd/system/telegram-tunnel.service` — модифицировать (Restart, enable)
|
||||
- `/opt/hermes/.hermes/scripts/tunnel_healthcheck.sh` — новый скрипт-вотчдог
|
||||
- `/opt/hermes/README.md` — обновить (порт 1080, юнит, healthcheck)
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
# Применение
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now telegram-tunnel.service
|
||||
|
||||
# Проверка
|
||||
systemctl is-active telegram-tunnel.service
|
||||
curl -s -o /dev/null -w "%{http_code}" --socks5-hostname 127.0.0.1:1080 https://api.tavily.com
|
||||
```
|
||||
|
||||
## Rollback
|
||||
|
||||
```bash
|
||||
sudo systemctl disable telegram-tunnel.service
|
||||
# восстановить исходный юнит из бэкапа
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
- SSH-ключ должен быть доступен сервису (owner root) — проверить права
|
||||
- VPS01 недоступен → туннель падает → healthcheck молчит/шумит по порогу
|
||||
@@ -0,0 +1,24 @@
|
||||
## Why
|
||||
|
||||
Нужен постоянный SOCKS5-туннель до VPS01 для обхода региональных блокировок (Tavily API, Telegram). Сейчас туннель поднимается вручную (SSH -D :1080), что ненадёжно: после ребута теряется, нет мониторинга, нет автозапуска.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Создать systemd-юнит `telegram-tunnel.service` (уже существует) → **BREAKING**: перевести на автозапуск + watchdog
|
||||
- Добавить автозапуск при старте (systemctl enable)
|
||||
- Добавить проверку живости туннеля (systemd watchdog + healthcheck curl через туннель)
|
||||
- Задокументировать порт 1080 и ключ SSH в README
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `tunnel-proxy`: Постоянный SOCKS5-туннель до VPS01 с автозапуском и мониторингом
|
||||
|
||||
### Modified Capabilities
|
||||
- (нет)
|
||||
|
||||
## Impact
|
||||
|
||||
- systemd: новый юнит + enable
|
||||
- SSH: ключ /mnt/yandex-disk/.ssh_box/timewebVPS
|
||||
- README.md в /opt/hermes (порты)
|
||||
@@ -0,0 +1,30 @@
|
||||
# Delta for tunnel-proxy
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Persistent SOCKS5 Tunnel
|
||||
The system MUST maintain a persistent SOCKS5 proxy tunnel from the host to VPS01, listening on 127.0.0.1:1080.
|
||||
|
||||
#### Scenario: Tunnel starts on boot
|
||||
- GIVEN the host boots
|
||||
- WHEN systemd starts telegram-tunnel.service
|
||||
- THEN the tunnel listens on 127.0.0.1:1080
|
||||
- AND the SSH connection is established with key /mnt/yandex-disk/.ssh_box/timewebVPS
|
||||
|
||||
#### Scenario: Tunnel dies
|
||||
- GIVEN the tunnel process exits unexpectedly
|
||||
- WHEN systemd detects failure
|
||||
- THEN the service restarts automatically (Restart=always)
|
||||
|
||||
### Requirement: Tunnel Health Monitoring
|
||||
The system MUST verify tunnel liveness at least every 60 seconds.
|
||||
|
||||
#### Scenario: Health check passes
|
||||
- GIVEN the tunnel is running
|
||||
- WHEN checking connectivity through 127.0.0.1:1080
|
||||
- THEN curl through the proxy returns HTTP 200 for a known endpoint
|
||||
|
||||
#### Scenario: Health check fails
|
||||
- GIVEN the tunnel is down
|
||||
- WHEN the watchdog fires
|
||||
- THEN a notification is raised (no routine "all ok" messages)
|
||||
@@ -0,0 +1,14 @@
|
||||
# Tasks
|
||||
|
||||
## 1. Модифицировать юнит telegram-tunnel.service
|
||||
- [x] 1.1 Добавить Restart=always, RestartSec=5 (бэкап юнита перед правкой)
|
||||
- [x] 1.2 Включить автозапуск: sudo systemctl enable telegram-tunnel.service
|
||||
- [x] 1.3 Перезагрузить и проверить: systemctl is-active telegram-tunnel.service
|
||||
|
||||
## 2. Healthcheck
|
||||
- [x] 2.1 Создать /opt/hermes/.hermes/scripts/tunnel_healthcheck.sh (curl через :1080 → tavily; молчит при ок)
|
||||
- [x] 2.2 Добавить в cron (no_agent) или systemd-таймер на 60s
|
||||
- [x] 2.3 Проверить: скрипт возвращает тишину при живом туннеле, сообщение при мёртвом
|
||||
|
||||
## 3. Документация
|
||||
- [x] 3.1 Обновить /opt/hermes/README.md: порт 1080, юнит, healthcheck, ключ SSH
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-06
|
||||
@@ -0,0 +1,45 @@
|
||||
# Design: tavily-proxy-setup
|
||||
|
||||
## Approach
|
||||
|
||||
Tavily API блокирует РФ-адреса (403 на уровне AWS ELB). Решение — не менять глобально прокси Hermes (сломало бы прямой доступ к deepseek/polza), а завернуть только Tavily в локальный форвардер:
|
||||
|
||||
- `tavily_proxy.py` — http.server на 127.0.0.1:8971, принимает POST на /extract и /search, проксирует через httpx-клиент с SOCKS5-транспортом (`socks5://127.0.0.1:1080`, туннель до VPS01).
|
||||
- Hermes настраивается на `TAVILY_BASE_URL=http://127.0.0.1:8971` — официальный способ подменить endpoint, httpx-провайдер Tavily шлёт запросы туда.
|
||||
- Зависимость от туннеля: `After=telegram-tunnel.service` + `Restart=always`.
|
||||
|
||||
## Files
|
||||
|
||||
- `/opt/hermes/.hermes/scripts/tavily_proxy.py` — форвардер (Python, venv Hermes)
|
||||
- `/opt/hermes/.hermes/scripts/tavily_extract_proxy.py` — форвардер + локальный экстрактор (trafilatura), юнит указывает на него: `--socks 127.0.0.1:1080 --upstream https://api.tavily.com`
|
||||
- `/etc/systemd/system/tavily-proxy.service` — юнит (enabled)
|
||||
- `/opt/hermes/.hermes/.env` — `TAVILY_API_KEY`, `TAVILY_BASE_URL=http://127.0.0.1:8971`
|
||||
- `/opt/hermes/.hermes/config.yaml` — `web.extract_backend: tavily`
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
# Применение
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now tavily-proxy.service
|
||||
|
||||
# Проверка
|
||||
systemctl is-active tavily-proxy.service
|
||||
curl -s -o /dev/null -w "%{http_code}" -X POST http://127.0.0.1:8971/extract \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"urls":["https://example.com"],"api_key":"'"$TAVILY_API_KEY"'"}'
|
||||
# → 200, web_extract отдаёт контент
|
||||
```
|
||||
|
||||
## Rollback
|
||||
|
||||
```bash
|
||||
sudo systemctl disable --now tavily-proxy.service
|
||||
# удалить TAVILY_BASE_URL из .env; extract_backend вернуть на searxng (extract не работал — деградация к прежнему состоянию)
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
- Туннель VPS01 недоступен → Tavily тоже недоступен (extract лежит) — приемлемо: без туннеля Tavily блокирован в любом случае.
|
||||
- httpx-SOCKS требует пакет socksio в venv — проверено, есть.
|
||||
- Форвардер — однопоточный http.server (ThreadingHTTPServer), достаточно для одного агента.
|
||||
@@ -0,0 +1,24 @@
|
||||
## Why
|
||||
|
||||
Web-экстракция в Hermes сломана: SearXNG умеет только search, а для extract не было ни одного рабочего провайдера. Tavily заблокирован в РФ (403 на AWS ELB). Решение — локальный прокси-форвардер, который ходит в Tavily через существующий SOCKS5-туннель до VPS01.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Настроен extract_backend=tavily в конфиге Hermes
|
||||
- Добавлен TAVILY_API_KEY + TAVILY_BASE_URL в /opt/hermes/.hermes/.env
|
||||
- Создан скрипт /opt/hermes/.hermes/scripts/tavily_proxy.py — локальный HTTP→SOCKS5 форвардер для одного хоста (api.tavily.com)
|
||||
- Создан systemd-юнит tavily-proxy.service (порт 8971, автозапуск, рестарт)
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `web-extract-tavily`: Веб-экстракция страниц в Hermes через Tavily с обходом региональной блокировки
|
||||
|
||||
### Modified Capabilities
|
||||
- (нет)
|
||||
|
||||
## Impact
|
||||
|
||||
- /opt/hermes/.hermes/.env — 2 переменные
|
||||
- /etc/systemd/system/tavily-proxy.service — новый юнит (enabled)
|
||||
- /opt/hermes/.hermes/scripts/tavily_proxy.py — новый скрипт
|
||||
+39
@@ -0,0 +1,39 @@
|
||||
# Delta for web-extract-tavily
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Tavily Extract Backend
|
||||
The system MUST use Tavily as the web_extract backend, reachable via the local proxy at http://127.0.0.1:8971.
|
||||
|
||||
#### Scenario: Extract works
|
||||
- GIVEN the Hermes web tool calls web_extract
|
||||
- WHEN the URL is a normal web page
|
||||
- THEN the page content is returned as markdown
|
||||
- AND the request goes through the local proxy to the Tavily API over SOCKS5
|
||||
|
||||
#### Scenario: Proxy is down
|
||||
- GIVEN the tavily-proxy.service is stopped
|
||||
- WHEN web_extract is called
|
||||
- THEN the call fails with a connection error (not a silent wrong result)
|
||||
|
||||
### Requirement: Proxy Auto-Start
|
||||
The system MUST start tavily-proxy.service automatically at boot and restart it on failure.
|
||||
|
||||
#### Scenario: Boot
|
||||
- GIVEN the host boots
|
||||
- WHEN systemd starts
|
||||
- THEN tavily-proxy.service is active
|
||||
- AND it listens on 127.0.0.1:8971
|
||||
|
||||
#### Scenario: Proxy crash
|
||||
- GIVEN the proxy process exits unexpectedly
|
||||
- WHEN systemd detects failure
|
||||
- THEN the service restarts automatically
|
||||
|
||||
### Requirement: Tunnel Dependency
|
||||
The proxy MUST depend on the SOCKS5 tunnel (telegram-tunnel.service); it must not start before the tunnel is up, and must restart if the tunnel is unavailable.
|
||||
|
||||
#### Scenario: Tunnel down
|
||||
- GIVEN telegram-tunnel.service is inactive
|
||||
- WHEN tavily-proxy.service is requested
|
||||
- THEN the proxy stays stopped (or retries) until the tunnel is back
|
||||
@@ -0,0 +1,19 @@
|
||||
# Tasks
|
||||
|
||||
## 1. Скрипт-форвардер
|
||||
- [x] 1.1 Создать /opt/hermes/.hermes/scripts/tavily_proxy.py (HTTP→SOCKS5, /extract, /search)
|
||||
|
||||
## 2. Конфигурация Hermes
|
||||
- [x] 2.1 web.extract_backend=tavily в config.yaml
|
||||
- [x] 2.2 TAVILY_API_KEY и TAVILY_BASE_URL в .env
|
||||
|
||||
## 3. systemd-юнит
|
||||
- [x] 3.1 Создать /etc/systemd/system/tavily-proxy.service (After=telegram-tunnel, Restart=always)
|
||||
- [x] 3.2 enable + запуск: systemctl enable --now tavily-proxy.service
|
||||
- [x] 3.3 Проверка: active, слушает 127.0.0.1:8971, curl /extract → 200
|
||||
|
||||
## 4. Проверка end-to-end
|
||||
- [x] 4.1 web_extract("https://example.com") через Hermes → успех
|
||||
|
||||
## 5. Документация
|
||||
- [x] 5.1 Зафиксировано: порт 8971, юнит tavily-proxy.service, зависимость от telegram-tunnel.service — в design.md (разделы Files/Commands/Risk) и specs/web-extract-tavily/spec.md
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-06
|
||||
@@ -0,0 +1,46 @@
|
||||
# Design: local-extractor
|
||||
|
||||
## Approach
|
||||
|
||||
Расширить существующий `/opt/hermes/.hermes/scripts/tavily_extract_proxy.py`:
|
||||
|
||||
- В local-режиме (нет `--socks`) сервер НЕ проксирует в Tavily, а сам извлекает: для каждого URL делает HTTP-запрос (`httpx`, при `--local-socks` через SOCKS5-туннель) и конвертирует HTML → Markdown через `trafilatura` (включён в venv).
|
||||
- Формат ответа в точности повторяет Tavily `/extract`: `{"results":[{url,title,raw_content,metadata}], "failed_results":[{url,error}], "failed_urls":[...]}` — Hermes-провайдер (`plugins/web/tavily/provider.py:_normalize_tavily_documents`) обрабатывает его без изменений.
|
||||
- Режимы взаимозаменяемы через аргументы CLI:
|
||||
- `--socks 127.0.0.1:1080` — forward в Tavily (как сейчас в systemd)
|
||||
- `--local` или ничего — локальная экстракция
|
||||
- `--local-socks 127.0.0.1:1080` — локальная, но страницы через туннель
|
||||
- systemd-юнит указать на tavily_extract_proxy.py (уже сделано, forward-режим).
|
||||
|
||||
## Files
|
||||
|
||||
- `/opt/hermes/.hermes/scripts/tavily_extract_proxy.py` — добавлены `_fetch_page`, `_extract_local`, `_extract_local_batch`, `--local-socks`
|
||||
- `/opt/hermes/.hermes/hermes-agent/venv/` — установлен trafilatura 2.2.0
|
||||
- `/etc/systemd/system/tavily-proxy.service` — ExecStart → tavily_extract_proxy.py (forward), `--socks 127.0.0.1:1080`
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
# Локальный режим (тест)
|
||||
python3 /opt/hermes/.hermes/scripts/tavily_extract_proxy.py --port 8972 --local
|
||||
curl -s -X POST http://127.0.0.1:8972/extract -H 'Content-Type: application/json' \
|
||||
-d '{"urls":["https://example.com"]}' # → {"results":[...]}
|
||||
|
||||
# Переключение systemd на local (когда решено отказаться от облака)
|
||||
# в /etc/systemd/system/tavily-proxy.service: ExecStart → ... --port 8971 --local
|
||||
# sudo systemctl daemon-reload && sudo systemctl restart tavily-proxy
|
||||
```
|
||||
|
||||
## Rollback
|
||||
|
||||
```bash
|
||||
# Вернуть forward-режим:
|
||||
# ExecStart → ... --socks 127.0.0.1:1080 --upstream https://api.tavily.com
|
||||
sudo systemctl daemon-reload && sudo systemctl restart tavily-proxy
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
- trafilatura хуже Tavily на JS-heavy страницах (нет headless-браузера) — приемлемо для типовых статей/доков.
|
||||
- Локальная экстракция не обходит блокировки РФ сама по себе — нужен `--local-socks` через туннель для таких сайтов.
|
||||
- Fetch без туннеля из РФ на github может висеть — ограничение сети, не кода.
|
||||
@@ -0,0 +1,23 @@
|
||||
## Why
|
||||
|
||||
Облачная веб-экстракция (Tavily API) зависит от внешнего сервиса и туннеля: если Tavily вводит планы, меняет лимиты или туннель падает — Hermes теряет web_extract. Нужен полностью локальный экстрактор страниц, который работает без облачного API и без туннеля, с тем же интерфейсом для Hermes.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Добавляется локальная экстракция в tavily_extract_proxy.py: режим `--local` (trafilatura) / `--local-socks`
|
||||
- Один и тот же эндпоинт POST /extract отдаёт контент локально, сохраняя Tavily-совместимый JSON (results[].url/title/raw_content)
|
||||
- Устанавливается библиотека trafilatura в venv Hermes
|
||||
- (пока) сохраняется forward-режим как основной; local-режим — как опция переключения
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `web-extract-local`: Локальная экстракция страниц через trafilatura с Tavily-совместимым интерфейсом
|
||||
|
||||
### Modified Capabilities
|
||||
- `web-extract-tavily` — добавляется реализация local-режима (не меняет требования: прокси-режим остаётся)
|
||||
|
||||
## Impact
|
||||
|
||||
- /opt/hermes/.hermes/scripts/tavily_extract_proxy.py — добавлен local-режим
|
||||
- venv Hermes — установлен trafilatura (2.2.0)
|
||||
@@ -0,0 +1,34 @@
|
||||
# Delta for web-extract-local
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Local Extraction Mode
|
||||
The system MUST support extracting page content fully locally (no cloud API) from the same HTTP endpoint used by the Tavily provider.
|
||||
|
||||
#### Scenario: Extract page locally
|
||||
- GIVEN tavily_extract_proxy.py runs with --local (or --local-socks)
|
||||
- WHEN a POST /extract with {"urls":["https://..."]} is sent
|
||||
- THEN the server fetches each URL, converts to markdown with trafilatura
|
||||
- AND returns Tavily-shaped JSON: {"results":[{"url","title","raw_content","metadata"}], "failed_results":[], "failed_urls":[]}
|
||||
|
||||
#### Scenario: Page fails to fetch
|
||||
- GIVEN a URL is unreachable or returns HTTP >= 400
|
||||
- WHEN extraction is attempted
|
||||
- THEN the URL lands in failed_results with an error message
|
||||
- AND other URLs still process normally
|
||||
|
||||
### Requirement: SOCKS Support for Local Fetches
|
||||
The local extractor MUST be able to fetch through the SOCKS5 tunnel (--local-socks 127.0.0.1:1080) for sites blocked from RU IPs.
|
||||
|
||||
#### Scenario: Fetch through tunnel
|
||||
- GIVEN --local-socks 127.0.0.1:1080 is set
|
||||
- WHEN page fetch happens
|
||||
- THEN the request is routed through the SOCKS5 tunnel
|
||||
|
||||
### Requirement: Backward Compatible Interface
|
||||
The local mode MUST NOT break the existing Tavily forward mode: the same port/endpoint keeps working for both.
|
||||
|
||||
#### Scenario: Forward still works
|
||||
- GIVEN the service runs with --socks (forward mode)
|
||||
- WHEN POST /extract is sent
|
||||
- THEN the request is forwarded to api.tavily.com as before
|
||||
@@ -0,0 +1,19 @@
|
||||
# Tasks
|
||||
|
||||
## 1. Локальная экстракция
|
||||
- [x] 1.1 Установить trafilatura в venv Hermes (2.2.0)
|
||||
- [x] 1.2 Добавить в tavily_extract_proxy.py: `_fetch_page`, `_extract_local`, `_extract_local_batch`
|
||||
- [x] 1.3 Добавить CLI-флаг `--local-socks` для загрузки страниц через туннель
|
||||
- [x] 1.4 Формат ответа идентичен Tavily /extract (results/failed_results/failed_urls)
|
||||
|
||||
## 2. Тест локального режима
|
||||
- [x] 2.1 Запуск `--port 8972 --local` → отвечает, отдаёт Tavily-совместимый JSON
|
||||
- [ ] 2.2 example.com через --local → контент извлечён (заблокировано сетью, тест отложен)
|
||||
- [ ] 2.3 Страница через --local-socks 127.0.0.1:1080 (тест отложен — сетевые проверки требуют присутствия пользователя)
|
||||
|
||||
## 3. Интеграция с systemd
|
||||
- [x] 3.1 Юнит переведён на tavily_extract_proxy.py (forward-режим — рабочий, сохраняет текущее поведение)
|
||||
- [x] 3.2 Проверка: сервис active, POST /extract → 200, контент Example Domain получен через провайдер
|
||||
|
||||
## 4. Документация (OpenSpec)
|
||||
- [ ] 4.1 Прописать local-режим и переключение в README проекта (когда проект будет в gitverse)
|
||||
@@ -0,0 +1,22 @@
|
||||
schema: spec-driven
|
||||
|
||||
# Инфраструктурный контекст: стек, соглашения, окружение
|
||||
context: |
|
||||
Домен: self-hosted инфраструктура (homelab / VPS), Linux (Ubuntu/Debian), Docker (docker compose), systemd.
|
||||
Окружение: Hermes-агент на хосте, SSH-доступ к VPS (gitverse.ru как источник истины, gitea на bigbox — зеркало).
|
||||
Ключевые сервисы: prosody (XMPP + Slidge мост), netbox (docker), garage (S3), searxng, mtproto-proxy, nntp, tproxy-web-proxy, telegram-tunnel.
|
||||
Управление: systemd-юниты, docker-compose.yml, конфиги в /opt/<service>/; рестарт сервисов — только извне (SSH sudo systemctl restart).
|
||||
Соглашения: отдельный каталог /opt/<service>/ на сервис; секреты в .env; порты фиксируются в README.md; апдейты через git (источник истины gitverse.ru).
|
||||
|
||||
rules:
|
||||
proposal:
|
||||
- Указывать затронутые сервисы и порты
|
||||
- Включать план отката (rollback)
|
||||
specs:
|
||||
- Требования в формате MUST/SHOULD/MAY
|
||||
- Сценарии проверки: GIVEN/WHEN/THEN с конкретными командами проверки (systemctl status, curl, docker ps)
|
||||
design:
|
||||
- Указывать конкретные файлы конфигов и юнитов
|
||||
- Включать команды применения и проверки
|
||||
tasks:
|
||||
- Каждая задача — проверяемый шаг с командой верификации
|
||||
@@ -0,0 +1,33 @@
|
||||
# tunnel-proxy Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change add-vpn-tunnel-proxy. Update Purpose after archive.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Persistent SOCKS5 Tunnel
|
||||
The system MUST maintain a persistent SOCKS5 proxy tunnel from the host to VPS01, listening on 127.0.0.1:1080.
|
||||
|
||||
#### Scenario: Tunnel starts on boot
|
||||
- GIVEN the host boots
|
||||
- WHEN systemd starts telegram-tunnel.service
|
||||
- THEN the tunnel listens on 127.0.0.1:1080
|
||||
- AND the SSH connection is established with key /mnt/yandex-disk/.ssh_box/timewebVPS
|
||||
|
||||
#### Scenario: Tunnel dies
|
||||
- GIVEN the tunnel process exits unexpectedly
|
||||
- WHEN systemd detects failure
|
||||
- THEN the service restarts automatically (Restart=always)
|
||||
|
||||
### Requirement: Tunnel Health Monitoring
|
||||
The system MUST verify tunnel liveness at least every 60 seconds.
|
||||
|
||||
#### Scenario: Health check passes
|
||||
- GIVEN the tunnel is running
|
||||
- WHEN checking connectivity through 127.0.0.1:1080
|
||||
- THEN curl through the proxy returns HTTP 200 for a known endpoint
|
||||
|
||||
#### Scenario: Health check fails
|
||||
- GIVEN the tunnel is down
|
||||
- WHEN the watchdog fires
|
||||
- THEN a notification is raised (no routine "all ok" messages)
|
||||
@@ -0,0 +1,42 @@
|
||||
# web-extract-tavily Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change tavily-proxy-setup. Update Purpose after archive.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Tavily Extract Backend
|
||||
The system MUST use Tavily as the web_extract backend, reachable via the local proxy at http://127.0.0.1:8971.
|
||||
|
||||
#### Scenario: Extract works
|
||||
- GIVEN the Hermes web tool calls web_extract
|
||||
- WHEN the URL is a normal web page
|
||||
- THEN the page content is returned as markdown
|
||||
- AND the request goes through the local proxy to the Tavily API over SOCKS5
|
||||
|
||||
#### Scenario: Proxy is down
|
||||
- GIVEN the tavily-proxy.service is stopped
|
||||
- WHEN web_extract is called
|
||||
- THEN the call fails with a connection error (not a silent wrong result)
|
||||
|
||||
### Requirement: Proxy Auto-Start
|
||||
The system MUST start tavily-proxy.service automatically at boot and restart it on failure.
|
||||
|
||||
#### Scenario: Boot
|
||||
- GIVEN the host boots
|
||||
- WHEN systemd starts
|
||||
- THEN tavily-proxy.service is active
|
||||
- AND it listens on 127.0.0.1:8971
|
||||
|
||||
#### Scenario: Proxy crash
|
||||
- GIVEN the proxy process exits unexpectedly
|
||||
- WHEN systemd detects failure
|
||||
- THEN the service restarts automatically
|
||||
|
||||
### Requirement: Tunnel Dependency
|
||||
The proxy MUST depend on the SOCKS5 tunnel (telegram-tunnel.service); it must not start before the tunnel is up, and must restart if the tunnel is unavailable.
|
||||
|
||||
#### Scenario: Tunnel down
|
||||
- GIVEN telegram-tunnel.service is inactive
|
||||
- WHEN tavily-proxy.service is requested
|
||||
- THEN the proxy stays stopped (or retries) until the tunnel is back
|
||||
Reference in New Issue
Block a user