diff --git a/openspec/changes/folder-transport/.openspec.yaml b/openspec/changes/folder-transport/.openspec.yaml new file mode 100644 index 0000000..b9ebfc7 --- /dev/null +++ b/openspec/changes/folder-transport/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-12 diff --git a/openspec/changes/folder-transport/design.md b/openspec/changes/folder-transport/design.md new file mode 100644 index 0000000..270f1ab --- /dev/null +++ b/openspec/changes/folder-transport/design.md @@ -0,0 +1,81 @@ +## Context + +Мост из `bridge-core`: хаб (`jira-hub serve`, Mac mini, launchd, `0.0.0.0:8790`) и агент (`agent.py` на виртуалке, +Python 3.9, stdlib). Агент обращается к хабу шестью запросами (`claim` с ожиданием до 30 с, `settings`, `commands/{id}`, +`result`, `state`, `known-keys`); все идут через `Http.call()` агента, ошибки сведены к `ConnectionError` (хаб +недоступен) и `HttpError` (код ответа). Повторы отчёта, журнал `claimed/started/finished/acked` и восстановление опираются +только на эти два исключения. В хабе `serve()` уже держит фоновый поток `ticker`. + +При включённом VPN «Континент ZTN» сеть между виртуалкой и Mac mini закрыта (см. proposal.md). Общая папка UTM +(VirtioFS) проверена: круг 0,75–0,82 с, атомарное переименование видно целиком, удаления видны с обеих сторон. + +## Goals / Non-Goals + +Goals: агент работает с хабом при включённом Континенте; всё, что проверено прогоном на моке Jira 12.10.2026 (пакет всех +типов, повтор без записей, остановка в паузе, обрыв Jira), работает так же через папку; HTTP API хаба не меняется. +Non-goals — см. proposal.md. + +## Decisions + +1. **Реле внутри `serve` (вариант A, решение владельца).** Один сервис под launchd, один лог. Поток реле стартует всегда и + спит, пока `relay_dir` пуст; включение и выключение — правкой настройки, без перезапуска. +2. **Реле — HTTP-клиент своего же хаба.** Запрос из файла пересылается на `127.0.0.1:` с заголовком + `Authorization` из файла. Маршрутизация, проверка токенов, лимит тела и коды ошибок остаются в одном месте. +3. **Папка моста** `` с подпапками `req/` (запросы агента), `resp/` (ответы), `work/` (взятые реле запросы). + Обе стороны пишут файл под именем с точкой и переименовывают в `.json`; имена с точкой никто не читает. +4. **Формат.** Запрос: `{id, method, path, body, authorization, deadline}`; `deadline` — момент UTC (ISO 8601), после + которого ответ агенту не нужен. Ответ: `{id, status, body}`. +5. **Взятие запроса — переименование `req/.json` → `work/.json`.** Повторно его никто не возьмёт; каждый взятый + запрос обрабатывается в своём потоке, потому что `claim` держит ответ до 30 с. +6. **Ошибки агента — те же, что у HTTP.** Ответ 2xx → тело; иной код → `HttpError(status, body)`; нет ответа к `deadline` → + агент удаляет свой запрос (если его ещё не взяли) и выбрасывает `ConnectionError`. Runner, журнал и восстановление + не меняются. +7. **Защита `claim` по запасу времени.** Реле пересылает `POST /agent/claim`, только если до `deadline` осталось ≥ 35 с + (хаб держит `claim` ≤ 30 с); иначе запрос выбрасывается без ответа. Агент ставит для `claim` `deadline` = сейчас + + max(timeout, 45) с, как сейчас ставит таймаут HTTP. Это закрывает потерю ответа `claim` из-за медленной папки; общий + случай M-2 остаётся отложенным. +8. **Просроченные запросы выбрасываются без ответа** (агент уже ушёл с `ConnectionError`). Если `deadline` истёк после + пересылки, ответ всё равно пишется — его уберёт уборка. +9. **Хаб недоступен изнутри** (сбой соединения с `127.0.0.1`) — ответ со статусом 502 и текстом ошибки. +10. **Перезапуск реле**: файлы в `work/` удаляются с записью в лог; агент дождётся своего `deadline` и повторит. +11. **Уборка раз в минуту**: ответы в `resp/` старше 10 мин, запросы в `req/` с `deadline` старше 60 с, файлы с точкой + старше 10 мин. +12. **Папки нет** (SSD не подключён) — одно предупреждение в лог, реле ждёт и проверяет снова; подпапки `req/`, `resp/`, + `work/` реле создаёт само, когда `relay_dir` существует. +13. **Лог** — одна строка на запрос в лог хаба: `relay <секунды>`. +14. **Агент выбирает транспорт по `hub_url`**: `http://…`/`https://…` — как сейчас, `folder:<путь>` — файловый клиент + с тем же интерфейсом `HubClient`. `check` печатает «хаб: доступен через папку <путь>, настройки vN» или + «НЕДОСТУПЕН» с причиной (нет папки; реле не ответило за 10 с). Версия агента — 2. +15. **Токен агента остаётся в файле запроса.** Общая папка доступна только Mac mini и виртуалке; пароль Jira туда не + попадает (как и в HTTP-транспорте, хаб получает только результаты и состояние). + +## Risks / Trade-offs + +- **Доступ launchd к внешнему диску.** macOS может не пустить процесс из launchd на `/Volumes/externalSSD` без разрешения + «Съёмные тома» или «Полный доступ к диску». Проверяется первым шагом приёмки на настоящей папке; при отказе — выдать + доступ `uv`/python в «Конфиденциальность и безопасность». +- **Кеш VirtioFS** даёт постоянные ~0,75 с на круг. Для команд с паузами 30–120 с несущественно; `refresh` на 140 задач — + около 10 обменов. +- **Токен агента в файлах общей папки** живёт до ответа и уборки. Приемлемо для домашней пары машин. +- **Опоздавший ответ** на `result`/`state`: агент повторит запрос; `result` идемпотентен, повторная загрузка `state` + перезаписывает те же строки зеркала. + +## Migration Plan + +1. Слить PR хаба, перезапустить launchd-задание хаба; `settings_set relay_dir "/Volumes/externalSSD/utm/rshb/jira-bridge"`. +2. Прогон на моке Jira через временную папку (сценарий 12.10.2026), затем короткий прогон через настоящую папку. +3. Слить PR агента; на виртуалке заменить `agent.py`, в `agent.json` — `"hub_url": "folder:/Volumes/My Shared Files/RSHB/jira-bridge"`. +4. При включённом Континенте: `check` (обе строки «доступен»), запуск агента, `refresh full`, `jira-hub import`, сверка с CSV. +Откат: `relay_dir = null` и прежний `hub_url` (сеть работает только без Континента). + +## Decisions made without discussion + +| Дата | Решение | Обоснование | Цена ошибки | +|---|---|---|---| +| 2026-10-12 | Имя файла — `uuid4().hex` агента; ответ под тем же именем | уникальность без координации сторон | нет | +| 2026-10-12 | Тело ответа в файле — строка (как пришло от HTTP), агент разбирает JSON сам | реле не трактует ответы хаба; не-JSON ответ даёт ту же ошибку, что по HTTP | нет | +| 2026-10-12 | `deadline` — абсолютное время UTC, а не таймаут | реле на другой машине сравнивает со своими часами; Mac mini и виртуалка синхронизируют время с одного роутера/NTP | расхождение часов > 10 с ломает защиту `claim`; лечится запасом или переходом на относительный срок | +| 2026-10-12 | Реле перечитывает `relay_dir` раз в 5 с, опрос `req/` — каждые 0,1 с, агент опрашивает `resp/` каждые 0,1 с | быстрее не нужно (кеш VirtioFS ~0,75 с), реже — заметная задержка | лишние вызовы `listdir` — дёшево | +| 2026-10-12 | `relay_dir` — абсолютный путь строкой или `null`; относительный путь — 422 | путь читает процесс launchd с неочевидным cwd | нет | +| 2026-10-12 | Нечитаемый JSON запроса или ответа перечитывается до 2 с, затем запрос выбрасывается (реле) / `ConnectionError` (агент) | атомарное переименование делает это маловероятным (проверка: 0 случаев) | нет | +| 2026-10-12 | `relay_dir` не входит в настройки для агента (`AGENT_KEYS`) | агенту путь на стороне Mac mini не нужен | нет | diff --git a/openspec/changes/folder-transport/proposal.md b/openspec/changes/folder-transport/proposal.md new file mode 100644 index 0000000..3742c7d --- /dev/null +++ b/openspec/changes/folder-transport/proposal.md @@ -0,0 +1,36 @@ +## Why + +Живой запуск моста 12.10.2026 упёрся в сеть: доступ к Jira банка на виртуалке даёт VPN «Континент ZTN», и его пакетный +фильтр (pf-anchor `continentztn`) закрывает локальную сеть в обе стороны — роутер `192.168.0.1` отвечает, Mac mini +(`192.168.0.108`) нет, `nc` на порт хаба 8790 — таймаут; входящие на виртуалку (`:22`) тоже режутся. Фильтр включается при +первом подключении Континента и остаётся загруженным после отключения VPN, до выхода из клиента или перезагрузки. Агенту +одновременно нужны Jira (только через VPN) и хаб, поэтому сеть для моста не годится. Править правила Континента нельзя — +это средство защиты банка. + +Канал, который фильтр не видит, — общая папка гипервизора UTM (VirtioFS): на Mac mini `/Volumes/externalSSD/utm/rshb`, +на виртуалке `/Volumes/My Shared Files/RSHB`. Проверка 12.10.2026 при включённом Континенте: 30 обменов из 30 через +временный файл и переименование, время круга 0,75–0,82 с независимо от размера (200 Б – 300 КБ), недописанных и +«залипших» удалённых файлов 0 с обеих сторон. + +Решения владельца 12.10.2026 (сессия brainstorming): транспорт через общую папку; вариант A — реле внутри `jira-hub serve` +(не отдельный процесс и не обмен пакетами целиком); HTTP API хаба и обработчики не меняются; у агента транспорт выбирается +по `hub_url`; HTTP-транспорт остаётся; дизайн частей 1–4 (формат обмена, ошибки и уборка, настройки и запуск, тесты) +одобрен. + +## What Changes + +- **jira-hub**: поток реле в `serve`, включаемый настройкой `relay_dir`. Реле забирает файлы-запросы агента из + `/req/`, пересылает их в свой HTTP на `127.0.0.1:` и кладёт ответы в `/resp/`. + Новая настройка `relay_dir` (строка или `null`), проверяется при записи. +- **jira-agent**: транспорт `folder:` — `hub_url = "folder:<путь>"` создаёт файловый клиент хаба с тем же интерфейсом, + ошибки сводятся к тем же `ConnectionError`/`HttpError`; `check` сообщает транспорт; версия агента 2. +- Спеки: `hub-api` (ADDED: реле), `data-model` (MODIFIED: настройки), `agent` (MODIFIED: состав и настройки; ADDED: + транспорт через общую папку). + +## Non-goals + +- Изменения HTTP API, обработчиков, токенов, очереди и контракта команд. +- Обмен пакетами команд целиком через файлы (вариант C), работа агента без хаба. +- Несколько агентов на одной папке, шифрование файлов в общей папке. +- Обход или настройка фильтра Континента; запрос исключения в ИБ банка — вне репозиториев. +- Исправление находки M-2 (потерянный ответ `claim`) в общем виде; здесь только защита по запасу времени для реле. diff --git a/openspec/changes/folder-transport/specs/agent/spec.md b/openspec/changes/folder-transport/specs/agent/spec.md new file mode 100644 index 0000000..527989f --- /dev/null +++ b/openspec/changes/folder-transport/specs/agent/spec.md @@ -0,0 +1,53 @@ +## MODIFIED Requirements + +### Requirement: Состав и настройки агента +Агент SHALL состоять из одного файла `agent.py` (Python ≥ 3.9, только стандартная библиотека) и файла `agent.json`: +`hub_url`, `hub_token`, `jira.base_url`, `jira.auth` (`basic` с `user`/`password` или `bearer` с `token`), `verify_ssl`, +`ca_bundle`, `timeout`, `poll_seconds`. `hub_url` вида `http://…` или `https://…` SHALL означать HTTP-транспорт, вида +`folder:<абсолютный путь>` — транспорт через общую папку. Всё остальное (id полей, типы, карта переходов, типы связей, +доска, темп) агент SHALL получать от хаба при старте и при изменении `settings_version`. Учётные данные Jira MUST NOT +отправляться в хаб и MUST NOT попадать в журнал, логи и общую папку. + +#### Scenario: Проверка без записи +- **WHEN** `python3 agent.py check` +- **THEN** агент печатает доступность хаба (версия настроек) и Jira (`GET /myself`), в Jira ничего не пишет + +#### Scenario: Проверка через папку +- **WHEN** `hub_url = "folder:/Volumes/My Shared Files/RSHB/jira-bridge"` и реле хаба работает +- **THEN** `check` печатает «хаб: доступен через папку /Volumes/My Shared Files/RSHB/jira-bridge, настройки v, проект + »; если каталога нет или реле не ответило за 10 с — строка с «НЕДОСТУПЕН» и причиной, код выхода 1 + +### Requirement: Доставка и запуск +README агента SHALL описывать: копирование `agent.py` и `agent.example.json` через общую папку, заполнение `agent.json` +(включая выбор транспорта в `hub_url`), `check`, запуск в терминале и через `nohup` с логом, опциональный launchd-plist, +`prune`. Версия агента SHALL быть в константе файла (2 — с транспортом через папку) и в каждом отчёте; хаб предупреждает +в `agent_status`, если версия ниже минимальной из настроек. + +#### Scenario: Устаревший агент +- **WHEN** агент версии 1 выходит на связь, а в настройках `min_agent_version = 2` +- **THEN** `agent_status.warning` = «обновите агента», команды выдаются по-прежнему + +## ADDED Requirements + +### Requirement: Транспорт через общую папку +При `hub_url = "folder:<путь>"` агент SHALL обращаться к хабу теми же запросами, что по HTTP, через файлы в `<путь>`: +на каждый вызов записать `req/.json` = `{id, method, path, body, authorization, deadline}` (`id` — `uuid4().hex`, +`authorization` — `Bearer `, `deadline` — момент UTC = сейчас + таймаут вызова; для `claim` таймаут не меньше +45 с) через временный файл с именем на точку и переименование, затем опрашивать `resp/.json` каждые 0,1 с. +Полученный ответ агент SHALL удалить; `status` 2xx — вернуть разобранное тело, иной — выбросить `HttpError(status, body)` +так же, как HTTP-клиент. Если к `deadline` ответа нет, агент SHALL удалить свой `req/.json` (если он ещё там) и +выбросить `ConnectionError`. Нечитаемый JSON ответа SHALL перечитываться до 2 с, затем `ConnectionError`. Чужие файлы +в `resp/` агент MUST NOT трогать. Цикл выполнения, журнал, повторы отчёта и восстановление SHALL работать без изменений. + +#### Scenario: Ответ хаба через папку +- **WHEN** агент вызвал `settings`, реле положило `resp/.json` со `status = 200` +- **THEN** агент получает настройки, файл ответа удалён + +#### Scenario: Реле не отвечает +- **WHEN** агент вызвал `claim`, а ответа нет 45 с +- **THEN** `req/.json` удалён агентом, выброшен `ConnectionError`; цикл пишет «хаб недоступен» и повторяет `claim` + через `poll_seconds`, как при недоступном хабе по сети + +#### Scenario: Код ошибки хаба через папку +- **WHEN** агент отправил `result` по команде, которой в хабе нет, реле положило ответ со `status = 404` +- **THEN** агент получает `HttpError(404)` и считает команду закрытой, как по HTTP diff --git a/openspec/changes/folder-transport/specs/data-model/spec.md b/openspec/changes/folder-transport/specs/data-model/spec.md new file mode 100644 index 0000000..a57e403 --- /dev/null +++ b/openspec/changes/folder-transport/specs/data-model/spec.md @@ -0,0 +1,17 @@ +## MODIFIED Requirements + +### Requirement: Настройки +Таблица `setting` SHALL хранить парами ключ–JSON: `base_jql`, `field_ids`, `issue_types`, `priority_map`, `link_types`, +`transitions_map`, `pacing`, `board_id`, `sprint_names`, `tokens` (агентский и клиентский), `settings_version` +(увеличивается при любой правке), `backup_keep`, `auto_refresh_minutes`, `relay_dir` (абсолютный путь папки реле или +`null`, по умолчанию `null`; относительный путь и не-строка при записи — 422; агенту не передаётся). Начальные значения +SHALL импортироваться из `admin/jira-sync/config.example.json` командой `jira-hub init`; пароль и логин Jira в настройках +MUST NOT присутствовать. + +#### Scenario: Правка настроек поднимает версию +- **WHEN** через API изменён `pacing` +- **THEN** `settings_version` увеличен, следующий `claim` отдаёт агенту новую версию + +#### Scenario: Неверный relay_dir +- **WHEN** `PUT /settings` с `relay_dir = "rshb/jira-bridge"` +- **THEN** 422, значение не записано, `settings_version` не изменился diff --git a/openspec/changes/folder-transport/specs/hub-api/spec.md b/openspec/changes/folder-transport/specs/hub-api/spec.md new file mode 100644 index 0000000..352f055 --- /dev/null +++ b/openspec/changes/folder-transport/specs/hub-api/spec.md @@ -0,0 +1,44 @@ +## ADDED Requirements + +### Requirement: Реле через общую папку +`jira-hub serve` SHALL запускать поток реле вместе с HTTP-сервером. Пока настройка `relay_dir` пуста (`null`), реле +бездействует; настройку оно SHALL перечитывать не реже раза в 5 с, включение и выключение не требуют перезапуска. Если +каталог `relay_dir` существует, реле SHALL создать в нём подкаталоги `req/`, `resp/`, `work/`; если не существует — +записать одно предупреждение в лог и проверять снова. + +Обмен: +- запрос агента — файл `req/.json`: `{id, method, path, body, authorization, deadline}`, где `deadline` — момент UTC + (ISO 8601), после которого ответ не нужен; файлы, имя которых начинается с точки, реле MUST NOT читать; +- реле SHALL брать запрос переименованием в `work/.json` и обрабатывать каждый взятый запрос в отдельном потоке; +- запрос с истёкшим `deadline` SHALL выбрасываться без ответа; `POST /agent/claim` SHALL пересылаться, только если до + `deadline` осталось не меньше 35 с, иначе выбрасываться без ответа; +- остальные запросы реле SHALL пересылать в свой HTTP на `127.0.0.1:` тем же методом, путём и телом, с заголовком + `Authorization` из файла, и записывать ответ `resp/.json` = `{id, status, body}` (тело — строка ответа HTTP) через + временный файл с именем на точку и переименование; затем удалять `work/.json`; +- если соединение с `127.0.0.1:` не удалось, ответ SHALL иметь `status = 502` и текст ошибки в `body`; +- нечитаемый JSON запроса SHALL перечитываться до 2 с, затем запрос выбрасывается с записью в лог. + +При старте реле SHALL удалить файлы из `work/` с записью в лог. Раз в минуту реле SHALL удалять ответы в `resp/` старше +10 мин, запросы в `req/` с `deadline` старше 60 с и файлы с именем на точку старше 10 мин. На каждый обработанный запрос +реле SHALL писать в лог хаба строку `relay <секунды>`. HTTP API, обработчики и проверка токенов +при этом не меняются. + +#### Scenario: Запрос через папку +- **WHEN** в `req/` появился `a1.json` с `GET /agent/settings`, агентским токеном и `deadline` через 60 с +- **THEN** в `resp/` появляется `a1.json` со `status = 200` и телом настроек; `work/a1.json` удалён + +#### Scenario: Чужой токен через папку +- **WHEN** в файле запроса `GET /issues` с агентским токеном +- **THEN** ответ со `status = 401`, как по HTTP + +#### Scenario: Просроченный claim +- **WHEN** реле взяло `POST /agent/claim`, до `deadline` которого осталось 20 с +- **THEN** запрос выброшен без ответа и без обращения к хабу; команда в очереди осталась `queued` + +#### Scenario: Долгий claim не задерживает другие запросы +- **WHEN** реле пересылает `claim`, который ждёт команду 30 с, и в это время в `req/` появляется `GET /agent/settings` +- **THEN** ответ на `settings` пишется, не дожидаясь `claim` + +#### Scenario: Папка не подключена +- **WHEN** `relay_dir` задан, но каталога нет; через минуту каталог появился +- **THEN** в логе одно предупреждение; после появления каталога реле создаёт подкаталоги и обрабатывает запросы