diff --git a/.wiki/concepts/openapi-generator-3-1-spec-gotchas.md b/.wiki/concepts/openapi-generator-3-1-spec-gotchas.md index f36d631..5e03b56 100644 --- a/.wiki/concepts/openapi-generator-3-1-spec-gotchas.md +++ b/.wiki/concepts/openapi-generator-3-1-spec-gotchas.md @@ -8,12 +8,38 @@ updated: 2026-08-18 # openapi-generator + OpenAPI 3.1 — gotchas -Проверено вживую на F&F-раунде sched «клиент на любом ЯП одной командой» -(2026-08-18): Python-клиент из `@sched/admin-api@0.1.2` спеки (3.1.0, 15 путей) -через `openapi-generator` **7.24.0** (`-g python`, pydantic v2). Спеку НЕ чинили -(их импл, TDD) — обходили. Находки F-1..F-5 полные — в -`sched/.agents/inbox/2026-08-18T19-15-43Z-admin-fnf-openapi-client-report.md`; -здесь — переиспользуемая суть. +Проверено вживую на F&F-раундах sched «клиент на любом ЯП одной командой» +(2026-08-18): Python-клиент из спеки `@sched/admin-api` через +`openapi-generator` **7.24.0** (`-g python`, pydantic v2). Спеку НЕ чинили — +обходили (round 1, 0.1.2). Round 2 (0.2.0): все гочи 1–4 **закрыты фиксами +спеки/сервера**, raw-обход удалён — см. «Статус после round 2» ниже. + +## Статус после round 2 (0.2.0 / daemon 0.3.5) + +Все 5 находок round 1 подтверждены закрытыми (ретест 2026-08-18, отчёт +`sched/.agents/inbox/2026-08-18T22-55-00Z-admin-openapi-fixes-round2-retest.md`): + +- **Гоча 1 (wrapped-ответы) — FIXED (спека).** Мутации теперь объявляют + `{task}/{run}/{schedule}` (response-компоненты TaskMutation/RunMutation/ + ScheduleMutation), `GET /runs/{id}?logFromOffset` — RunLogChunk (allOf + RunRecord + logChunk/logTotalLength). Генератор выдаёт **InlineObjectN**- + модели (поля task/run/schedule/ok), десериализация нативная. `raw_ops.py` + из примера **удалён**. +- **Гоча 2 (const:true) — FIXED.** `const` убран из спеки; `Health200Response.ok` + = обычный `StrictBool`. +- **Гоча 3 (oneOf+discriminator) — FIXED.** `Schedule` стал плоской схемой + (`kind` + опциональные `cron/timezone/ms/at`); `rec.schedule.cron` читается + с типизированной модели. Normalization живьём: `once`→`{kind:once, at:ISO}`, + `interval`→`{kind:interval, ms}`. +- **F-1 (health auth) — FIXED (сервер).** `/health` всегда открыт, auth — + после health-роута; прочие роуты с ключом 401. +- **F-5 (dedupKey fail-fast) — FIXED (сервер).** POST/PATCH /schedules с + неизвестным top-level полем → 400 с именем поля. +- Итог ретеста: **11/11 ранее-сырых операций идут через типизированный клиент, + сьют 24/24, smoke 19/19** (коммит sched `d658ff0`). + +Гочи 1–3 ниже — описание сломанного состояния round 1 (0.1.2) + паттерн обхода +(потребительский escape-hatch, если спека где-то ещё сырая). ## Гоча 1 — ответы `{}` в спеке ломают десериализацию (главная) @@ -47,20 +73,35 @@ updated: 2026-08-18 модели приходит с `actual_instance=None` — правило (`cron`) недостижимо через модель, только через raw JSON: `raw["schedule"]["schedule"]["cron"]`. Касается любого oneOf+discriminator на этой версии генератора (3.1-ветка). +Фикс (round 2): плоская output-схема вместо oneOf — `kind` + опциональные +поля; per-kind валидация на сервере (parseScheduleEntry). ## Окружение (Windows) - `openapi-generator` 7.x требует **Java 11+**: системная Java 8 падает на class-load; ставь `JAVA_HOME` на новый JDK (Temurin 25 работает). + **Важно (round-2 уточнение):** CLI-обёртка (`@openapitools/openapi-generator-cli`) + спавнит `java` из **PATH**, не из `JAVA_HOME` — одного JAVA_HOME мало: + `$env:Path = "$env:JAVA_HOME\bin;" + $env:Path` до запуска, иначе + UnsupportedClassVersionError (class file 55.0 vs JRE 52.0 = Java 8 в PATH). Запуск: `npx --yes @openapitools/openapi-generator-cli generate -i spec.json -g python -o out --additional-properties=packageName=...` +- Wrapped-ответы, объявленные **инлайн в `components.responses`**, дают имена + `InlineObject..InlineObjectN` и доступ `resp.schedule.schedule.cron` (двойной + `.schedule`). Работает; красивее — именованные схемы в `components.schemas`. +- `info.version` спеки НЕ бьётся вместе с версией пакета (в 0.1.2 и 0.2.0 — + `0.1.0`); версия живёт только в package.json / dist-tags. - Windows excluded port ranges (Hyper-V/WinNAT) резервируют порты (напр. 8090/8091): `EACCES` на listen. Проверка: `netsh interface ipv4 show excludedportrange protocol=tcp`. - Консоль cp1251: не печатай `→`/`«»` в скриптах — `'charmap' codec can't encode`; ASCII-only. -## Паттерн обхода (потребитель, клиент не трогаем) +## Паттерн обхода (потребитель, клиент не трогаем) — исторический -Тонкий raw-слой рядом с сгенерированным пакетом (в примере — `raw_ops.py`): +Тонкий raw-слой рядом с сгенерированным пакетом (в примере был `raw_ops.py`): только операции, где спека `{}`, через `call_api`; остальное — через типизированный клиент. Сгенерированный пакет остаётся перегенерируемым. -Пример целиком: `sched/examples/admin-client-python/` (24/24 сьют, 19/19 smoke). +> **Статус:** после round 2 (0.2.0) обход не нужен — `raw_ops.py` удалён из +> примера. Паттерн остаётся escape-hatch'ем для сырых спек в других проектах. + +Пример целиком: `sched/examples/admin-client-python/` (24/24 сьют, 19/19 smoke, +typed-only). diff --git a/.wiki/concepts/sched-admin-client-openapi.md b/.wiki/concepts/sched-admin-client-openapi.md index 014f698..8968d9b 100644 --- a/.wiki/concepts/sched-admin-client-openapi.md +++ b/.wiki/concepts/sched-admin-client-openapi.md @@ -6,14 +6,28 @@ related: [[openapi-generator-3-1-spec-gotchas]], [[sched-fnf-r8-verification-sta updated: 2026-08-18 --- -# sched admin-client openapi — F&F раунд +# sched admin-client openapi — F&F раунды Живая проверка claim'а sched openapi-spec: **«клиент на любом ЯП одной -командой»**. Вердикт: **claim подтверждён с оговорками** — генерация одной -командой работает, но 3.1-спека до «любого ЯП без правок» не дотягивает -(8 операций требуют raw-обхода). +командой»**. Вердикт round 1: **claim подтверждён с оговорками** (8 операций +требуют raw-обхода). Вердикт round 2 (0.2.0/0.3.5): **claim подтверждён +полностью** — все находки F-1..F-5 закрыты, raw-обход удалён, клиент +типизированный end-to-end. -## Что делал / ожидал / получил +## Round 2 — ретест фиксов (0.2.0 / daemon 0.3.5), 2026-08-18 + +| | | +|---|---| +| Что | `generate.ps1` заново против `@sched/admin-api@0.2.0` (tarball spec byte-identical pinned), сьют+smoke против `@sched/daemon@0.3.5` (:8127, no auth) | +| Ожидал | все 5 находок закрыты, `raw_ops.py` не нужен | +| Получил | **все 5 закрыты**; сьют **24/24** (3 прогона), smoke **19/19** — **полностью через типизированный клиент, 0 операций на обходе**; `raw_ops.py` **удалён**; F-1/F-5 подтверждены живьём на keyed-инстансе (:8128): health 200 open, /tasks 401 без ключа, 400 на неизвестные поля schedule body/patch | + +Deliverables round 2: коммит sched `d658ff0` (пример обновлён: openapi.json +0.2.0, tests/smoke typed-only, raw_ops удалён, README+generate.ps1); репорт +`sched/.agents/inbox/2026-08-18T22-55-00Z-admin-openapi-fixes-round2-retest.md`. +Механика фиксов и генераторные грабли — [[openapi-generator-3-1-spec-gotchas]]. + +## Round 1 — 2026-08-18 (0.1.2 / daemon 0.3.4) | | | |---|---| @@ -45,12 +59,14 @@ updated: 2026-08-18 ```powershell cd sched/examples/admin-client-python $env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-25.0.2.10-hotspot" +$env:Path = "$env:JAVA_HOME\bin;" + $env:Path # генератор спавнит java из PATH, не из JAVA_HOME .\generate.ps1 pip install -r requirements.txt pytest SCHED_ADMIN_URL=http://127.0.0.1:8127/api python -m pytest tests/ -v python smoke.py --url http://127.0.0.1:8127/api ``` -Стенд раунда: published `@sched/daemon` 0.3.4, `--admin-port 8127`, NO AUTH, -scratch sqlite (`/tmp/sched-acpy-stand/acpy.db`). Письменный `:8080` — под ключом -(`SCHED_ADMIN_KEY=dev-key`), `:8123` — стейл-билд (health 0.1.8, нет POST /tasks). +Стенд round 2: published `@sched/daemon` 0.3.5, `--admin-port 8127`, NO AUTH, +scratch sqlite (`/tmp/sched-acpy-stand/acpy.db`). Round 1 стоял на 0.3.4. +Письменный `:8080` — под ключом (`SCHED_ADMIN_KEY=dev-key`), `:8123` — стейл-билд +(health 0.1.8, нет POST /tasks). diff --git a/.wiki/index.md b/.wiki/index.md index 51bf8bb..9c5e2c8 100644 --- a/.wiki/index.md +++ b/.wiki/index.md @@ -21,8 +21,8 @@ Catalog of all wiki pages. One line per page, organized by type. Updated on ever - [windows-recovery-host](entities/windows-recovery-host.md) — Windows Recovery Host (рабочий PC пользователя) ## Concepts -- [sched-admin-client-openapi](concepts/sched-admin-client-openapi.md) — F&F раунд 2026-08-18: Python-клиент одной командой из спеки (openapi-generator 7.24.0), 24/24 + smoke 19/19, вердикт «claim подтверждён с оговорками», находки F-1..F-5 -- [openapi-generator-3-1-spec-gotchas](concepts/openapi-generator-3-1-spec-gotchas.md) — генерация клиентов из 3.1-спеки (openapi-generator 7.24.0, python): ответы `{}` + wrapped-тело → ValidationError (raw-обход + by_alias), `const:true` → строковый enum, oneOf+discriminator → actual_instance=None, Java 11+, Windows excluded-порты +- [sched-admin-client-openapi](concepts/sched-admin-client-openapi.md) — F&F раунды 2026-08-18: Python-клиент одной командой из спеки (openapi-generator 7.24.0); r1 0.1.2 — 24/24+smoke 19/19, находки F-1..F-5 (8 операций на raw-обходе); r2 0.2.0/0.3.5 — все 5 закрыты, raw_ops удалён, 11/11 typed-only, вердикт «claim подтверждён полностью» +- [openapi-generator-3-1-spec-gotchas](concepts/openapi-generator-3-1-spec-gotchas.md) — генерация клиентов из 3.1-спеки (openapi-generator 7.24.0, python): wrapped-ответы {} → ValidationError (raw-обход историчен: r2 спека фикснута), const:true → строковый enum, oneOf+discriminator → actual_instance=None (r2: плоская схема), java из PATH а не JAVA_HOME, InlineObjectN-имена, info.version не бьётся - [nvm-junction-ismain-gate-gotcha](concepts/nvm-junction-ismain-gate-gotcha.md) — ESM isMain-гейт молча не выполняется под junction'нутым npm-рутом (nvm/mise/volta); realpath-фикс; диагностика за 30 сек - [nvm-windows-node-switch](concepts/nvm-windows-node-switch.md) — смена версии Node на nvm-windows: junction, per-version глобалы, PATH-кэш, npm 11 allow-scripts; Node 22→24 evidence - [sched-fnf-r8-verification-stand](concepts/sched-fnf-r8-verification-stand.md) — стенд верификации F&F r8 (schedule-as-entity): путь, версии core 0.40.2/ui 0.2.0, карта репро-скриптов (миграции/движок/политики/API 52/UI 13), подтверждённый контракт (ceiling, retryCount, snapshot, pause AND, tz-hoist, PATCH-merge), находки №5 (U1 форма-tz, U2 вёрстка), как закрыть раунд diff --git a/.wiki/log.md b/.wiki/log.md index 139aaa2..80204aa 100644 --- a/.wiki/log.md +++ b/.wiki/log.md @@ -137,3 +137,4 @@ Append-only log of wiki operations (ingests, promotions, lints, migrations). ## [2026-08-18] ingest | NEW concepts/nvm-junction-ismain-gate-gotcha.md — ESM isMain-гейт молча no-op под junction-префиксом npm-рута (C:\nvm4w\nodejs → realpath …\nvm\v22.22.0): import.meta.url резолвится в realpath, argv[1] держит литеральный → main() не выполняется, exit 0. Бьёт global-install под любым version-manager'ом (nvm/mise/volta). Фикс realpath-сравнения (sched bd38aab, daemon 0.3.2). NEW concepts/nvm-windows-node-switch.md — Node 22→24.19.0 рецепт: junction-свап, per-version глобалы, PATH-кэш shell'а, npm 11 allow-scripts. Оба из сессии CLI-F&F sched 2026-08-18. index.md updated (+2). ## [2026-08-18] ingest | NEW concepts/openapi-generator-3-1-spec-gotchas.md — из F&F openapi-client sched (2026-08-18): генерация Python-клиента из 3.1-спеки openapi-generator 7.24.0. Гочи: (1) ответы `{}` в спеке + wrapped-тело ({task/run/schedule:…}) → pydantic ValidationError, фикс — реальные схемы ответов, обход raw-транспорт + by_alias=True; (2) `const:true` → строковый enum ('true') ломает boolean; (3) oneOf+discriminator → actual_instance=None, контент только через raw JSON; Java 11+ обязателен (системная 8 падает), Windows excluded-порты 8090/8091 (EACCES), консоль cp1251 без →/«». Полные находки F-1..F-5: sched/.agents/inbox репорт 19:15Z; пример sched/examples/admin-client-python (24/24). index.md updated. ## [2026-08-18] ingest | NEW concepts/sched-admin-client-openapi.md — F&F раунд openapi-claim sched (по предписанию таски): Python-клиент одной командой (openapi-generator 7.24.0 из спеки verdaccio 0.1.2), сьют 24/24 + smoke 19/19 против published daemon 0.3.4 (:8127), вердикт «claim подтверждён с оговорками» (8 операций требуют raw-обхода). Код sched/examples/admin-client-python (e89e868), репорт — sched инбокс 19:15Z, находки F-1..F-5 (спеку не чинил). Таска [sched-admin-client-openapi] 🟢. Гочи генерации — concepts/openapi-generator-3-1-spec-gotchas.md. index.md updated. +## [2026-08-18] ingest | UPDATE concepts/openapi-generator-3-1-spec-gotchas.md + concepts/sched-admin-client-openapi.md — round 2 ретест (0.2.0/daemon 0.3.5): все 5 находок F-1..F-5 закрыты, raw_ops.py удалён, 11/11 ранее-сырых операций typed-only, сьют 24/24 + smoke 19/19 (коммит sched d658ff0, репорт sched инбокс 22:55Z). Новые грабли в окружение: CLI спавнит java из PATH а не JAVA_HOME; wrapped-ответы в components.responses → InlineObjectN; info.version не бьётся с версией пакета. index.md hooks обновлены.