Claude (backend session) 9b23e8c024 Land the platform reading surface: chapters, units, notes, bank and the event stream, with a materialization debt that survives a restart and account-level halts

2026-08-20 23:56:11 +03:00

28 KiB

Raw Blame History

Развёртывание платформы

Одна VM, systemd, бинари артефактами CI (PLATFORM_DIRECTION.md §3). Не Kubernetes: дети-tmctl живут часами и держат эксклюзивный лок на файлах книги на локальном диске — оркестратор, способный переселить под посреди прогона, этой нагрузке враждебен.

Файлы

tmplatformd.service — юнит контрольной панели. Тело юнита проверено systemd-analyze verify (systemd 259) — exit 0, без замечаний. ⚠ Проверять надо с ПОДСТАВЛЕННЫМ существующим ExecStart=: дословно юнит даёт exit 1, потому что verify проверяет и наличие бинаря, а /usr/local/bin/tmplatformd на стенде нет. ⚠ юнит целиком под systemd не запускался — нет sudo и нет бинаря на стенде.

Отдельные свойства песочницы при этом проверены ЖИВЫМ прогоном в пользовательском systemd 259 (systemd-run --user --wait), а не вычитаны из доки: ProtectSystem=strict + ReadWritePaths= на несуществующем пути → 226/NAMESPACE, юнит не стартует; тот же путь созданным → 0/SUCCESS; префикс - на несуществующем → 0/SUCCESS (строка игнорируется — потому мы её и не префиксуем); ProtectHome=yes → /home пуст, чтение /home/<user> даёт Permission denied; ProtectHome=tmpfs + BindPaths=<каталог> → каталог виден. Ресурсные потолки (MemoryMax=80%, OOMPolicy=continue) живьём не проверялись — вывод из systemd.resource-control(5)/systemd.service(5).

Откат релиза: не ниже версии 5

goose down до версии 4 и ниже НЕ РАБОТАЕТ на живой базе: down-путь 00005 восстанавливает users_email_key и email NOT NULL, а обе формы нарушают строки, которые пишет боевой код (неподтверждённая личность даёт email = NULL; один адрес законно принадлежит двум аккаунтам). Откат транзакционный, поэтому падение ничего не портит — но планировать откат ниже 5 нельзя, план отката — накатить вперёд. Разбор: docs/STACK_DECISIONS.md §8.

Что юнит закрывает содержательно

⚠ ПЕРЕ-ДИСПОЗИЦИЯ (P4, D39.106): прогон НЕ ребёнок этого юнита и не живёт в его cgroup. Каждый прогон — транзиентный юнит в СОБСТВЕННОМ systemd-менеджере пользователя tmplatform, в срезе tm-runs.slice, потому что перевод обязан пережить деплой платформы. Следствия для установки: обязателен loginctl enable-linger tmplatform; юниту нужен доступ к своей же пользовательской шине (ProtectHome=tmpfs + BindPaths=/run/user/%U + DBUS_SESSION_BUS_ADDRESS); ресурсные потолки НИЖЕ ограничивают только контрол-плейн.
PD-13 (осиротевшие процессы движка) закрыт теперь ТАМ, где прогон: собственным cgroup прогона (TM_PLATFORM_RUN_MEMORY_MAX/_TASKS_MAX), и это ИЗМЕРЕНО — в дефолтном app.slice пользовательского менеджера лимиты принимаются и не применяются (STACK_DECISIONS §16). Дев-путь супервизора с группой процессов остаётся дев-путём.
TimeoutStopSec=90 больше, чем дренаж платформы (15 с) плюс grace движка (30 с). Меньше — и systemd прибьёт tmctl посреди остановки, оставив лок проекта.
Секреты через LoadCredential=, а не через окружение: переменная окружения видна в /proc/<pid>/environ и наследуется каждым ребёнком-tmctl. Конфиг читает *_FILE первым.

Установка (набросок, исполняется владельцем)

useradd --system --home-dir /srv/textmachine tmplatform
# ⚠ Каталог создаём ЯВНО: --system не создаёт домашний каталог, а `ReadWritePaths=/srv/textmachine`
# при `ProtectSystem=strict` на несуществующем пути валит сборку mount-namespace — юнит не стартует
# вовсе (PD-91, systemd.exec(5)). Это первая команда, которую пропускают, читая набросок сверху вниз.
install -d -m0750 -o tmplatform -g tmplatform /srv/textmachine
install -D -m0755 tmplatformd  /usr/local/bin/tmplatformd
install -D -m0755 tmplatformctl /usr/local/bin/tmplatformctl
# ⚠ БЕЗ ЭТОГО НИ ОДИН ПРОГОН НЕ СТАРТУЕТ. Прогоны — транзиентные юниты в пользовательском
# менеджере `tmplatform`, а он существует вне сессии входа только при включённом linger.
# Проверка: `systemctl --user -M tmplatform@ is-system-running` отвечает, а не «Failed to connect».
loginctl enable-linger tmplatform
# Движок кладётся по ВЕРСИОНИРОВАННОМУ пути: попытка прогона пиннится к тому, с которого началась
# (строка 139), поэтому выкат новой версии не подменяет исполняемое у идущего прогона.
install -D -m0755 tmctl /opt/textmachine/engine/<версия>/tmctl
install -d -m0700 -o root -g root /etc/tmplatform
printf '%s' 'postgres://...' > /etc/tmplatform/dsn && chmod 0400 /etc/tmplatform/dsn
printf '%s' '<oauth client secret>' > /etc/tmplatform/oidc_client_secret && chmod 0400 /etc/tmplatform/oidc_client_secret

/etc/tmplatform/env — несекретное окружение:

TM_PLATFORM_ADDR=127.0.0.1:8080
TM_PLATFORM_TRUSTED_ORIGINS=https://app.example.org
TM_PLATFORM_OIDC_ISSUER=https://accounts.google.com
TM_PLATFORM_OIDC_CLIENT_ID=...
TM_PLATFORM_OIDC_REDIRECT_URL=https://app.example.org/auth/callback
TM_PLATFORM_AFTER_LOGIN=/library
TM_PLATFORM_LANGUAGE_PAIRS=zh>ru
TM_PLATFORM_BOOKS_DIR=/srv/textmachine/books
TM_PLATFORM_BOOK_TEMPLATE=/srv/textmachine/book-template.yaml
TM_PLATFORM_METRICS_ADDR=127.0.0.1:9464

⚠ TM_PLATFORM_SIGNUP_GRANT_USD здесь НЕТ намеренно (PD-104, слово владельца 16.08): на бете грант по умолчанию НОЛЬ и начисляется руками — tmplatformctl grant. Строка =5 в этом блоке включала обратно ровно тот самообслуживаемый безлимитный грант, который дефолт выключает.

⚠ TM_PLATFORM_LANGUAGE_PAIRS обязателен. Пустой список делает /capabilities и интейк противоположными: провод говорит «этот деплой не умеет ни одной пары», а интейк принимает любую.

Шаблон книги (`TM_PLATFORM_BOOK_TEMPLATE`) — артефакт ОПЕРАТОРА

Загруженной книге нужен book.yaml, и пишет его платформа — ОДИН раз, при первом разборе, из этого шаблона (форма Б, D39.130). Дальше файл принадлежит оператору: платформа его не читает и никогда не перезаписывает (O_EXCL), поэтому правка потолка или пайплайна в конкретной книге переживает всё.

Платформа подставляет ровно то, что знает только она: book_id · title · source_lang · target_lang · source_file. Всё остальное едет из шаблона нетронутым — включая ключи, о которых эта версия платформы не слышала, и включая genre: он ушёл из контракта и из интейка в 0.3.0 (Б-23), поэтому теперь это значение ОПЕРАТОРА и платформа его не трогает.

# /srv/textmachine/book-template.yaml
pipeline: /opt/textmachine/configs/pipeline-c1.yaml
models: /opt/textmachine/configs/models.yaml
langpack_root: /opt/textmachine/configs/langpacks
audience: взрослые читатели вебновелл
venuti: 0.6
honorifics: keep
transcription: palladius
footnotes: minimal
ceilings:
  book_usd: 25

⚠ Пути внутри шаблона — АБСОЛЮТНЫЕ. Движок резолвит относительный путь от каталога КНИГИ, а не от каталога шаблона, поэтому ../configs/pipeline.yaml в шаблоне указывает на разные файлы для каждой книги и ни на один из них — правильно.

⚠ ceilings.day_usd в шаблоне НЕ НУЖЕН — и в примере его нет намеренно (решение владельца 15.08). Трату прогона уже жёстко ограничивает купленный пользователем объём: платформа держит холд и передаёт движку --ceiling-usd, флаш к этому холду. Дневная ось поверх этого — второй лимит на ту же трату, и стоит он дороже, чем даёт: остановленный им прогон приезжает paused (не failed), но продолжить его платформа не может — resume отвечает 409, потому что следующая попытка упёрлась бы в тот же лимит в тот же день, а пользователю эта пауза необъяснима: лимит не его и он его не видит.

Движка это не касается — ceilings.day_usd у него остаётся, и вписать его в конкретную книгу руками оператор вправе. Именно на этот случай платформенная обработка daily_ceiling/409 из P6 и остаётся предохранителем: она делает такую остановку различимой и честной, а не дефолтом, который её вызывает.

Битый или отсутствующий шаблон — беда деплоя, а не книги: загрузки не отклоняются и не удаляются, книги ждут в parsing (метрика books_parsing), в логе — ERROR с причиной. Починили файл — ближайший свип разбирает всё накопившееся.

Апгрейд ПЛАТФОРМЫ: миграция и бинарь едут вместе

⚠ Схема и бинарь платформы — один шаг, а не два. Миграция 00016 УДАЛЯЕТ колонки, которые прежний бинарь читает (books.note_count, books.genre, chapters.heading, таблица notes), поэтому инстанс старой сборки рядом с уже мигрированной базой отвечает 500 на КАЖДОЕ чтение книги. ⚠ То же повторяет 00021 (акт 5 P7): она сносит chapters.units_done, который прежний бинарь читает в проекции книги. Правило, значит, не «про 00016», а постоянное: любая миграция, снимающая колонку, делает перекрытие версий невозможным, и проверять это надо на каждой. Порядок: остановить старую версию → накатить миграцию (TM_PLATFORM_MIGRATE=1 на одном инстансе или goose руками) → поднять новую. Роллинг-апгрейд с перекрытием версий на этом шаге не поддерживается; дефолт TM_PLATFORM_MIGRATE выключен именно поэтому — накат должен быть решением, а не побочным эффектом старта реплики.

⚠ Отредактированная миграция не перезапускается. goose ключуется НОМЕРОМ и не хранит ни имени, ни контрольной суммы, так что правка уже применённого файла невидима: на стенде это лечится сносом базы, в проде — гейтом internal/pgstore/migrations.sha256, который делает правку выпущенной миграции видимой ревьюеру. Поймано живой пробой P7 (правка 00016 после её применения на стенде).

Апгрейд ДВИЖКА: порядок против деадлока (строка 174 единого бэклога)

Read-only команды движка отказывают файлу проекта СТАРЕЕ бинаря — exit 13 и токен schema_mismatch found=N expected=M на stderr (форма финализирована D39.134; прежняя цитата «schema vN … expects vM» в этом доке была МЁРТВОЙ — движок её не печатает), а платформа зовёт status перед каждым спавном и на расчёте денег. Значит выкат нового движка на хост с существующими книгами запирает их до миграции файла проекта.

⚠ Проверено исполнением на стенде (P7): проектная БД, отведённая на схему v14 при бинаре v15, даёт tmctl status --json → exit 13 с этим токеном; tmctl migrate --config <book.yaml> делает пред-миграционный бэкап и переводит v14 → v15; тот же status после неё — exit 0.

⚠ Жёсткое правило: эмиттер-бинарь не выкатывается, пока tmctl migrate не заленден ($0-команда движка, открывающая файл на запись без прогона). До того новую платформу проверяют против журналов, писанных своей сборкой движка вне репозитория.

Порядок, когда migrate приедет. ⚠ Ключевое: migrate гоняется НОВЫМ бинарём — старый уводит файл в свою же схему, то есть не делает ничего, и деадлок остаётся. Поэтому бинарь кладётся ДО миграции, а TM_PLATFORM_ENGINE_BIN переключается ПОСЛЕ.

# 0. Закрыть приём. Между списком и миграцией окно, в которое пользователь может стартовать прогон
#    на книге, только что названной безопасной; остановленный демон не принимает ни стартов, ни
#    резюмов. Идущие прогоны переживают это по построению — они в своём менеджере (P4, D39.106).
systemctl stop tmplatformd

# 1. Дренаж. «Прогонов нет» — это ТРИ факта, а не один: нет живых юнитов, нет открытых
#    (резюмируемых) попыток И нет незакрытых холдов.
tmplatformctl books           # колонка MIGRATE и причина, если «no»

# 2. Новый бинарь — на ВЕРСИОНИРОВАННЫЙ путь. Безопасно ещё до переключения: идущие попытки
#    запинены к своим путям, а этот никто пока не зовёт.
install -D -m0755 tmctl /opt/textmachine/engine/<новая версия>/tmctl

# 3. Мигрируем ЕГО бинарём и только те книги, которые команда назвала безопасными.
for d in $(tmplatformctl books --migratable); do
    /opt/textmachine/engine/<новая версия>/tmctl migrate --config "$d/book.yaml"
done

# 4. И только теперь новая версия становится рабочей: TM_PLATFORM_ENGINE_BIN в /etc/tmplatform/env,
#    затем поднять демон.
systemctl start tmplatformd

Почему шаг 1 — про три факта, а не про один. Остановленная попытка ждёт резюма на бинаре, к которому она ЗАПИНЕНА (строка 139): миграция уводит файл вперёд, старый бинарь его больше не откроет, и резюм пришлось бы форсить на новую сборку — риск пере-оплаты уже купленных вызовов. По той же причине блокирует НЕЗАКРЫТЫЙ холд: расчёт денег читает committed_usd тем же запиненным бинарём, и после миграции цифру уже не прочитать. Все три предиката запинены тестом (TestEachOfTheThreeBlockersAloneKeepsABookOutOfTheMigrationList) — каждый по отдельности, потому что «блокер, который тихо перестал блокировать» виден только на уже прошедшем апгрейде.

Книга, застрявшая на daily_ceiling или на вечно незакрытом холде, блокирует апгрейд бессрочно, и выхода для оператора сегодня нет (строка регистра PD-217): такую книгу придётся либо дождаться, либо разрешить вручную в БД. Форсирующего флага у команды нет намеренно — он бы и был тем самым способом пере-оплатить купленное.

⚠ Проверка исполнением ЖДЁТ. Порядок записан, tmplatformctl books --migratable проверен на стенде (P6), но сам шаг tmctl migrate не гонялся: движковой команды ещё нет. Пометить сделанным можно только после прогона на стенде с настоящим migrate.

⚠ Хвост, который НЕ построен и построен вслепую не будет: движковый migrate придёт с машиноразличимой ошибкой «версия не совпала». Когда придёт — платформа сможет лечиться сама (поймала ошибку → migrate, если у книги нет открытых попыток → повтор), без стоп-мира. Строка регистра PD-201.

Дев-стенд: живая платформа для фронта (П-16)

Фронт разрабатывается против ЖИВОЙ платформы, а не против своих моков. Рецепт целиком:

# 1. Postgres без root (docs/STACK_DECISIONS.md §«Postgres на стенде без root»).
~/.local/pgsql/bin/pg_ctl -D ~/.local/share/tmstand/pgdata \
    -l ~/.local/share/tmstand/pg.log -o "-k /tmp -p 55433 -c listen_addresses=''" start

# 2. Окружение стенда. ⚠ ДВА гейта на старте, оба про «стендовое окружение уехало в прод»:
#    TM_PLATFORM_DEV_LOGIN вместе с OIDC — отказ; TM_PLATFORM_INSECURE_COOKIES вместе с OIDC,
#    чей callback НЕ http:// — тоже отказ (боевой вход в куках без Secure и с выключенным HSTS).
#    Локальный провайдер по http на стенде при этом законен и работает.
export TM_PLATFORM_DSN='postgres://postgres@/tmstand?host=/tmp&port=55433&sslmode=disable'
export TM_PLATFORM_ADDR=127.0.0.1:8080
export TM_PLATFORM_MIGRATE=1
export TM_PLATFORM_INSECURE_COOKIES=1      # дев-профиль куки: __Host- требует Secure
export TM_PLATFORM_DEV_LOGIN=dev@stand     # вход без внешнего провайдера — ТОЛЬКО стенд
export TM_PLATFORM_BOOKS_DIR=$HOME/.local/share/tmstand/books
export TM_PLATFORM_STATE_DIR=$HOME/.local/share/tmstand/state
export TM_PLATFORM_ENGINE_BIN=$HOME/.local/bin/tmctl
export TM_PLATFORM_CTL_BIN=$PWD/tmplatformctl          # абсолютный: systemd отвергает иной
export TM_PLATFORM_BOOK_TEMPLATE=$HOME/.local/share/tmstand/book-template.yaml
# ⚠ ОБЯЗАТЕЛЬНО, как и в бою: инстанс, принимающий загрузки, обязан объявить хотя бы одну ДОСТУПНУЮ
#    пару, иначе демон отказывается стартовать. Пустой список — это «не объявлено ничего», а не
#    «пускать всё»: без гейта стенд принимал книги, которые мог только провалить.
export TM_PLATFORM_LANGUAGE_PAIRS='zh>ru'
mkdir -p "$TM_PLATFORM_BOOKS_DIR" "$TM_PLATFORM_STATE_DIR"

# 3. Демон (мигрирует сам при TM_PLATFORM_MIGRATE=1).
./tmplatformd &

# 4. Сид: аккаунт + кредит + демо-книга ЧЕРЕЗ ЖИВОЙ ИНТЕЙК (не INSERT).
./tmplatformctl seed --url http://127.0.0.1:8080

# 5. Фронт ходит на стенд своим дев-прокси (TM_PLATFORM на его стороне).

Сессию в браузер выдаёт тот же вызов, что делает сид, — один раз из консоли приложения:

await fetch('/auth/dev-login', {method: 'POST'})

⚠ Дев-вход не должен доехать до прода, и это гарантировано четырьмя независимыми свойствами (разбор — internal/login/dev.go): он не монтируется без TM_PLATFORM_DEV_LOGIN; вместе с OIDC демон НЕ СТАРТУЕТ; личность берётся из конфигурации, а не из запроса, поэтому войти «кем-то другим» через него нельзя в принципе; провайдер называется dev и в это пространство имён не может попасть ни один настоящий издатель. На каждый выданный сеанс пишется WARN.

⚠ TM_PLATFORM_BOOKS_DIR — каталог, который сервис ПИШЕТ и, на отклонённом интейке, УДАЛЯЕТ. Всё под ним создано загрузкой книг; книга, заведённая дев-инструментом с чужим --workdir, туда не попадает и не удаляется никогда (гард books.owns). Каталог должен существовать и принадлежать tmplatform, и он обязан быть в ReadWritePaths= юнита — при ProtectSystem=strict отсутствующий путь валит сборку mount-namespace целиком (PD-91, та же грабля, что и с /srv/textmachine):

install -d -m0750 -o tmplatform -g tmplatform /srv/textmachine/books

⚠ /metrics не аутентифицирован — его защищает только адрес привязки. Дефолт 127.0.0.1, то есть снаружи он недостижим; поднять его на внешний адрес значит открыть операционную форму деплоя (глубина очереди, число прогонов, возраст холдов) всем, кто до него дотянется. Скрейпер живёт на том же хосте либо ходит через тот же edge, что и API. Разбор — docs/STACK_DECISIONS.md §24, строка риска — PD-179.

⚠ Загрузка книги идёт минуты, и это касается edge-прокси. Маршрут POST /v0/books принимает до TM_PLATFORM_MAX_UPLOAD_BYTES (64 МиБ) и держит соединение до TM_PLATFORM_UPLOAD_DEADLINE (10 минут). Прокси перед сервисом обязан разрешать столько же: у него свои client_max_body_size и свои таймауты чтения, и молчаливо режет их он, а не мы.

⚠ TM_PLATFORM_STATE_DIR меняется только когда живых прогонов нет. Exit-маркер пишется по пути, вычисленному при СПАВНЕ, а читается по пути из текущей конфигурации: после смены каталога конец идущего прогона становится невидим, и реконсилятор перезапускает его как потерянный (PD-155). Путь обязан быть абсолютным — относительный демон отвергает на старте, потому что маркер пишет юнит из каталога книги, а читает демон из своего.

Миграции выкатываются ОДИН раз, не каждой репликой: TM_PLATFORM_MIGRATE=1 tmplatformd разово либо отдельный шаг деплоя. goose держит advisory-лок, так что параллельный запуск не гонка, но и не норма.

Где на сервере лежат книги

/srv/textmachine — корень библиотеки НА СЕРВЕРЕ. Решение владельца «книги живут в ~/books» относится к машине разработки: под этим юнитом домашние каталоги недоступны вовсе (ProtectHome=yes подставляет пустой /home и детям-tmctl тоже), поэтому библиотека под домашним каталогом на сервере просто не откроется — не «сработает медленнее», а не найдётся. Оператору, которому это нужно, юнит называет ровно две строки замены (ProtectHome=tmpfs + BindPaths=); других изменений не требуется.

⚠ Выбирающего путь кода ещё нет: Supervisor.Workdir задаёт вызывающий, а вызывающий — воркер, которого нет (строка 103 единого бэклога). Когда он появится, корень становится настройкой, и её дефолт — этот каталог.

Чего здесь ещё нет

TLS и домен (перед юнитом предполагается edge-прокси), ограничитель соединений на edge, ротация логов, бэкап Postgres. Всё это — работа с первым реальным деплоем, не раньше.

28 KiB Raw Blame History Unescape Escape