iia-arg/dsh-plugins--packages-dsh-vypusk-watch ↗★ 2
dsh-vypusk-watch
Сторож окна выпуска: сверяет каждый установленный пакет с git-меткой его версии и поднимает одну тревогу, если бой разошёлся с выпуском · Release window watchdog: compares every installed package with the git tag of its version and raises one alarm if production diverged from the release
安装
此插件尚未提供可验证的 bundle,或兼容性检查未通过。请先阅读仓库说明。 阅读完整 README ↗
说明文档
阅读完整 README ↗dsh-vypusk-watch · сторож окна выпуска · release window watchdog
Версия · Version: 3.1.8
Сторож, который сверяет каждый установленный пакет с git-меткой его версии и громко говорит, если в бой попало не то, что выпускали.
A watchdog that compares every installed package with the git tag of its version and speaks up loudly if what reached production is not what was released.
Без непустого VYPUSK_REPO сторож отказывает кодом 3 до helper окна, канала тревог и файлов состояния: это ошибка вызова, а не тревога СЛЕПОТЫ. Правило действует и с --avto-montazh. При заданном дереве остальные ошибки настроек/чтения остаются слепотой с прежним кодом 2 и уведомлением.
Missing/empty VYPUSK_REPO is invocation error 3 before the window helper, alert channel or state files, including --avto-montazh. With an explicit tree, other missing settings or read failures keep their existing blindness2/alert contract.
Читатель кода 3 в бою: vypusk-okno-watch.service (SuccessExitStatus=0 1 2 ⇒ failed) → /etc/agent-registry/storozha-sutochnye.txt:53 (vypusk-okno-watch.service 1) → /usr/local/sbin/sadik-watch: каждые 10 минут проверяет is-failed и формирует владельцу FAILED, кроме подтверждённой отсрочки окном монтажа; эту запись перечня сохраняйте.
Production reader of exit 3: vypusk-okno-watch.service (SuccessExitStatus=0 1 2 ⇒ failed) → /etc/agent-registry/storozha-sutochnye.txt:53 (vypusk-okno-watch.service 1) → /usr/local/sbin/sadik-watch: checks is-failed every 10 minutes and reports FAILED to the owner, except for a confirmed deployment-window deferral; preserve this list entry.
Зачем нужно · Why it exists
Пакет ставят в рабочий каталог («бой») из рабочего дерева. Если поставить его без метки выпуска или поправить файлы на месте, номер версии остаётся прежним — и ничто этого не покажет: номер не различает две разные редакции. Однажды так дважды за три часа пакет ушёл в бой без метки, и оба раза находку принёс человек, а не прибор.
A package is installed into the production directory from the working tree. If it is installed without a release tag, or files are edited in place, the version number stays the same — and nothing shows it: the number does not distinguish two different builds. Once a package reached production without a tag twice within three hours, and both times a human, not a tool, caught it.
Сторож закрывает этот класс: для каждого пакета дерева он находит установленные копии, читает их версию, находит метку своей версии и сверяет суммы файлов. Совпало — молчит. Разошлось — одна тревога, без повторов, пока картина не изменится.
The watchdog closes this class: for every package in the tree it finds the installed copies, reads their version, finds the tag of their own version and compares file checksums. Match — silence. Divergence — one alarm, with no repeats until the picture changes.
Место в системе · Place in the system
flowchart LR
T["Таймер systemd · systemd timer
(вне пакета · outside the package)"] --> W["vypusk-okno-watch.sh
(root)"]
REPO[("Рабочее дерево с метками · working tree with tags
<имя>-v<версия>")] -- "git show / git tag" --> W
LIVE[("Боевые каталоги · production dirs
корни по имени пакета · roots by package name")] -- "суммы файлов · file checksums" --> W
INFO[("Чужие копии · foreign copies
только сведение · informational only")] --> W
W -- "одна тревога на картину · one alarm per picture" --> A["agent-alert"]
W --> S[("Файл состояния · state file
отпечаток последней тревоги · last alarm fingerprint")]
Пакет содержит исходник, пустой список исключений, документацию, стенды и образец systemd/vypusk-okno-watch.service: автоматически не устанавливает исполняемый файл, юнит или таймер. На машине авторов служба живёт по пути /usr/local/sbin/vypusk-okno-watch.sh, а src/vypusk-okno-watch.sh — её побайтный снимок.
The package contains source, an empty exception list, documentation, stands and a sample systemd/vypusk-okno-watch.service: it automatically installs no executable, unit or timer. On the authors' machine the service lives at /usr/local/sbin/vypusk-okno-watch.sh, and src/vypusk-okno-watch.sh is its byte-for-byte snapshot.
Установка · Installation
Требования: Linux, bash, python3 ≥ 3.9, PyYAML (python3-yaml), git, jq, штатные coreutils; npm — только как оболочка для npm test. Права чтения ко всем боевым каталогам (на машине авторов сторож работает от root).
Requirements: Linux, bash, python3 ≥ 3.9, PyYAML (python3-yaml), git, jq, standard coreutils; npm only as the npm test wrapper. Read access to all production directories (on the authors' machine the watchdog runs as root).
Установка — вручную: скопировать src/vypusk-okno-watch.sh в системный путь и пустой src/vypusk-okno-watch.exceptions.list рядом с ним (либо явно задать путь VYPUSK_ISKLYUCHENIYA), задать окружение (см. docs/SETTINGS.md) и завести свой таймер. Пример юнита и таймера — в docs/ARCHITECTURE.md.
Installation is manual: copy src/vypusk-okno-watch.sh to a system path and the empty src/vypusk-okno-watch.exceptions.list next to it (or set its path through VYPUSK_ISKLYUCHENIYA), set the environment (see docs/SETTINGS.md) and create your own timer. A sample unit and timer are in docs/ARCHITECTURE.md.
Для git ≥ 2.35.2 владелец дерева должен совпадать с пользователем юнита. Иначе администратор доверяет именно этому дереву: git config --system --add safe.directory /path/to/tree (не *). Ошибка dubious ownership ведёт в слепоту; первая строка stderr git печатается рядом с причиной.
For git ≥ 2.35.2 the tree owner must match the unit user. Otherwise an administrator trusts that specific tree with git config --system --add safe.directory /path/to/tree (never *). dubious ownership is blindness; its first stderr line is retained.
Зависимости от соседей · Neighbor dependencies
agent-alert поставляется пакетом dsh-trevogi: $1 — один довод с текстом тревоги, HTML-экранированным сторожем (&, ``). Код 0 — канал подтвердил доставку; прочтение человеком не проверено. Один вызов за прогон, предел 90 с + 5 с до SIGKILL; внутренние повторы — договор отправителя. plugins.yaml и поля derevo описаны в README пакета dsh-montazh; читаются только разделы plugins и services.
dsh-trevogi supplies agent-alert: $1 is one argument containing the alarm text, HTML-escaped by the watchdog (&, ``). Exit 0 confirms delivery at the channel, not human reading. One call per run, 90 seconds plus 5 seconds before SIGKILL; internal retries belong to the sender. The dsh-montazh README defines plugins.yaml and derevo; only the plugins and services sections are read.
Быстрый старт · Quick start
VYPUSK_TIHO=1 VYPUSK_REPO=/path/to/tree VYPUSK_KORNI=/path/to/plugins/node_modules \
VYPUSK_AGENT_KORNI= VYPUSK_INFO_KORNI= VYPUSK_SOOTVETSTVIYA= VYPUSK_SSYLKI= VYPUSK_RASKLADKA= VYPUSK_REESTR= \
VYPUSK_ISKLYUCHENIYA=src/vypusk-okno-watch.exceptions.list bash src/vypusk-okno-watch.sh; echo "код · exit $?"
VYPUSK_TIHO=1 — без канала тревог: прогон только печатает. Пустые значения выключают необязательные проверки; не задать их вовсе нельзя — это слепота. Работает — значит, код 0 и строки сошлось: … N из N файлов, метка …. Код 1 — расхождение (тревога), 2 — слепота (сверять нечем), 3 — ошибка вызова: единственный разрешённый довод — --avto-montazh, любой иной довод (--dry-run тоже) даёт отказ с кодом 3 до чтения дерева — ничего не сверено, тревог нет, состояние не тронуто; всё задаётся окружением.
VYPUSK_TIHO=1 means no alarm channel: the run only prints. Empty values disable the optional checks; leaving them unset is not allowed — that is blindness. It works when the exit code is 0 and lines read сошлось: … N из N файлов, метка … (matched: N of N files, tag …). Exit 1 is divergence (alarm), 2 is blindness (nothing to compare against), 3 is a call error: the watchdog accepts only --avto-montazh; any other argument (--dry-run included) is refused with exit 3 before the tree is read — nothing compared, no alarm, state untouched; everything is set through the environment.
Настройки · Settings
| Переменная · Variable | Значит · Meaning |
|---|---|
VYPUSK_REPO | рабочее дерево с метками · working tree with tags |
VYPUSK_KORNI | корни боевых каталогов через : · production roots, :-separated |
VYPUSK_AGENT_KORNI, VYPUSK_AGENT_POISK | корни копий агентов: явный перечень или родители для поиска /*/plugins · agent copy roots: an explicit list or parents to search ` |
| /*/plugins` | |
VYPUSK_INFO_KORNI | политика чужих копий: только сведение; корни также должны входить в поиск (VYPUSK_KORNI/VYPUSK_AGENT_*) · foreign-copy policy only; these roots must also be included in the search (VYPUSK_KORNI/VYPUSK_AGENT_*) |
VYPUSK_SOOTVETSTVIYA | пары ключ=путь1:путь2, по строке; ключ — каталог, имя или прежнее имя; повтор ключа — слепота · one key=path1:path2 pair per line; key is directory, package name or former name; duplicate keys are blindness |
VYPUSK_SSYLKI | символические ссылки монтажа, которые обязаны существовать · install symlinks that must exist |
VYPUSK_RASKLADKA | пакеты без package.json, сверяемые по раскладке bin, sbin, libexec, lib → /usr/local, systemd → /etc/systemd/system · manifest-less packages compared by the fixed install layout |
VYPUSK_REESTR | реестр (plugins.yaml) с записями derevo: пакет сверяется с меткой ref по парам local ↔ remote, с режимом и владельцем · registry with derevo entries: the package is compared with its ref tag by local ↔ remote pairs, mode and owner |
VYPUSK_ISKLYUCHENIYA | прощённые пропуски записи CHANGELOG · forgiven missing CHANGELOG entries |
VYPUSK_SOSTOYANIE, VYPUSK_NAPOMINAT | файл состояния и интервал повтора тревоги (86400 с) · state file and alarm repeat interval (86400 s) |
VYPUSK_ALERT, VYPUSK_TIHO | отправитель тревог; 1 — не звать его · alarm sender; 1 — do not call it |
Подробно, с умолчаниями и тем, что сломается при неверном значении, — docs/SETTINGS.md.
Details, with defaults and what breaks with a wrong value: docs/SETTINGS.md.
Как работает · How it works
Правило тревоги — «бой разошёлся с меткой своей версии». Версия совпадает, а суммы файлов разные — тревога: это главный класс, номер не различает редакции. Своей метки нет, хотя выпуски этого пакета известны, — тоже расхождение: смонтировано невыпущенное. Совсем нет меток или две «своих» — слепота. Есть более новый выпуск, а своя метка на месте, — только сведение (INFO). Всё совпало — молчание: сторож, который говорит всегда, перестают читать.
The alarm rule is "production diverged from the tag of its own version". Same version but different file checksums — alarm: this is the main class, the number does not distinguish builds. No own tag while releases of this package are known — also divergence: something unreleased was installed. No tags at all, or two "own" tags — blindness. A newer release exists while the own tag is in place — information only (INFO). Everything matches — silence: a watchdog that always talks stops being read.
Режим счёта. Суммы считаются по всем файлам вне node_modules, без *.bak*, *.tar, *.tgz; режим печатается в выводе, чтобы числа не расходились. Файл, который есть в метке, но не входит в состав публикации (files манифеста) и отсутствует в бою, расхождением не считается: установка его не кладёт. Обратная сторона — файл есть в бою, а в метке нет — расхождение всегда: его положили руками.
Counting mode. Checksums cover every file outside node_modules, excluding *.bak*, *.tar, *.tgz; the mode is printed in the output so numbers stay comparable. A file present in the tag but not in the published file list (files in the manifest) and absent from production is not a divergence: installation does not place it. The other side — a file present in production but not in the tag — is always a divergence: it was put there by hand.
Дополнительные проверки. У версии в бою должна быть непустая запись в CHANGELOG — и в бою, и в метке (прощения — списком исключений с причиной, кем и когда). Пакеты, чей бой живёт не в корнях по имени, сверяются по составу публикации через пары соответствий. Названные символические ссылки монтажа проверяются отдельно: пропавшая ссылка не видна сверке файлов.
Extra checks. The version in production must have a non-empty CHANGELOG entry — both in production and in the tag (forgiveness via an exception list with reason, who and when). Packages whose production copy lives outside the name-based roots are checked by their published file list via correspondence pairs. Named install symlinks are checked separately: a missing link is invisible to file comparison.
Когда замолкает. Одну и ту же картину расхождения сторож отправляет один раз; дальше пишет только в журнал, пока картина не изменится или не пройдёт VYPUSK_NAPOMINAT секунд (по умолчанию сутки). Отпечаток картины считается по суммам, а не по тексту тревоги: вторая правка того же файла меняет картину. Отметка ставится только после подтверждённой доставки — отказ канала не глушится как «уже отправлено».
When it goes quiet. The watchdog sends the same divergence picture once; after that it only writes to the journal until the picture changes or VYPUSK_NAPOMINAT seconds pass (one day by default). The picture fingerprint is computed from checksums, not from the alarm text: a second edit of the same file changes the picture. The mark is set only after confirmed delivery — a channel failure is not silenced as "already sent".
Сторожа и проверки · Guards and checks
Перечень из 15 входов (12 shell-обёрток и три прямых Python-стенда) приведён по именам в docs/GUARDS.md. npm test запускает только копии выпуска и договор своей метки; остальные запускаются отдельно. Проверка исходников без установленного сторожа:
The 15 entry points (12 shell wrappers and three direct Python stands) are listed by name in docs/GUARDS.md. npm test runs only release copies and the own-tag contract; run the others separately. To check source without an installed watchdog:
VYPUSK_TEST_WATCH=src/vypusk-okno-watch.sh VYPUSK_TEST_REFERENCE=src/vypusk-okno-watch.sh npm test
Подмена эталона проверяет кандидат, а не тождество боевому файлу. Настройки — 7 проб: отсутствие REPO, KORNI, SSYLKI, AGENT-корней, RASKLADKA, REESTR и явно пустые необязательные значения.
An overridden reference checks the candidate, not equality with production. Settings have 7 probes: missing REPO, KORNI, SSYLKI, AGENT roots, RASKLADKA, REESTR and explicit empty optional values.
Границы · Limits
- Не отличает «смонтировали и пометили» от «не монтировали вовсе»: оба дают «метка = бой», то есть зелёное. Он ловит несоответствие боя выпуску, а не отсутствие работы.
- Не ловит правку в памяти процесса: сверяет диск с диском. Живую версию показывает только журнал работающего процесса.
- Не ловит пакеты вне дерева, подмену самой метки, верность кода (одинаково плохой код в обоих местах — зелёный), содержимое
node_modulesи файлы, исключённые режимом счёта. - Не ловит неверное значение переменной окружения (
VYPUSK_TIHO=да— не «1», режим боевой) и опечатку в имени необязательной (VYPUSK_TIH0=1— ноль вместо «O», переменная не прочитана вовсе; так же сVYPUSK_NAPOMINATи др.). Опечатка в имени обязательной настройки ловится: VYPUSK_REPO — отказ3 без канала, остальные — слепота2 «не задана». src/vypusk-okno-watch.sh— снимок установленного файла, и стенд сверяет их суммы: правка снимка без выпуска нового боевого файла