# SQLx-core 0.9.0: bounded maintenance и упорядочивание публикации idle Этот документ описывает единственный отслеживаемый патч стороннего крейта в репозитории: `sqlx-core` 0.9.0. Относительно архива crates.io меняется только код `src/pool/inner.rs` (два private seam, детерминированные regression-тесты и modification notice); дополнительно два файла лицензий восстановлены полным текстом с закреплённого upstream-тега. Публичный API, feature-набор, таймауты и семантика пула не меняются. ## Provenance - Package: `sqlx-core` версии `0.9.0`. - Лицензия в манифесте: `MIT OR Apache-2.0`. - Источник vendoring: `index.crates.io-1949cf8c6b5b557f/sqlx-core-0.9.0.crate`. - SHA-256 архива: `05b44e85bf579a8eeb4ceaa77a3a523baf2bf0e9bac7e40f405d537b5d2d5ccb`. Совпадает с checksum в исходном `Cargo.lock` до патча. - Размещение: `vendor/sqlx-core/` (безопасное извлечение архива целиком). - `LICENSE-MIT` и `LICENSE-APACHE` в опубликованном крейте — текстовые заглушки `../LICENSE-MIT` / `../LICENSE-APACHE`. При vendoring они восстановлены полным оригинальным текстом с закреплённого upstream-тега (см. «Лицензии» ниже). - Метаданные registry-кэша (`.cargo-checksum.json`) не добавлялись. - Нормализованный upstream-манифест `vendor/sqlx-core/Cargo.toml` не переписывался; version, features и зависимости не менялись. ### Подключение В корневом `Cargo.toml`: ```toml [workspace] exclude = ["vendor/sqlx-core"] [patch.crates-io] sqlx-core = { path = "vendor/sqlx-core" } ``` В `Cargo.lock` запись `sqlx-core` перестаёт быть registry-пакетом: удаляются строки `source = "registry+..."` и `checksum = "..."`, пакет становится path. Других изменений в `Cargo.lock` нет. ### Изменённые относительно архива файлы `diff -rq` против распакованного архива `sqlx-core-0.9.0.crate` даёт ровно три отличия: - `src/pool/inner.rs` — единственный изменённый **код** (seams, regression-тесты, modification notice); - `LICENSE-MIT` и `LICENSE-APACHE` — восстановлены из upstream-тега. Остальные файлы архива (включая `Cargo.toml`, `Cargo.toml.orig`, `Cargo.lock`, `.cargo_vcs_info.json` и весь остальной `src/`) побайтово не менялись. ### Лицензии Полные тексты взяты из закреплённого upstream-тега `v0.9.0`: - `LICENSE-MIT` — , SHA-256 `5abbdd842310c8f1650fcde3a5a51a3e09412b9e5a6eea87519e0db9e32b339d`; - `LICENSE-APACHE` — , SHA-256 `c8f5453612253e8ea8bad241617fe74c4a6d5d592ba64ff881668c211b50ac99`. Копирайт- и лицензионные уведомления upstream не удалялись и не переписывались. ## Наблюдавшийся дефект При повторном полном gate на ревизии `1b9f7f66f9f89dcfed8d4d2efa71986063741ca0` существовавший integration-тест `community_access_usage` повторно уходил в sustained Tokio CPU busy loop. Собрано 100 userspace instruction-pointer samples; среди них присутствуют: - `sqlx_core::pool::inner::spawn_maintenance_tasks::{{closure}}::{{closure}}` на `src/pool/inner.rs:549`; - `PoolInner::try_acquire` (`inner.rs:182`) и `PoolInner::release`; - `crossbeam_queue::array_queue::ArrayQueue::pop`, `core::sync::atomic::Atomic::fetch_sub/fetch_add`. Важная оговорка: **live-значения `num_idle`/`MAX` не снимались**. Захват samples показывает hotspot, но не доказывает, что в проде наблюдался именно `usize::MAX`. Считаем наблюдаемым только сам hot loop; MAX-сценарий демонстрируется отдельно, принудительным interleaving в unit-тесте. ### Достижимая гонка в исходнике В upstream `release()` соединение публикуется в `idle_conns`, затем отпускается permit, и только потом увеличивается `num_idle`: ```rust if self.idle_conns.push(idle).is_err() { /* panic */ } guard.release_permit(); self.num_idle.fetch_add(1, Ordering::AcqRel); ``` Параллельный `try_acquire()` может выполнить `pop_idle()` в окне между `push`/`release_permit` и `fetch_add`. Тогда `num_idle.fetch_sub(1)` при исходном нуле временно уходит в underflow (`0 - 1` → `usize::MAX`), а последующий `fetch_add(1)` возвращает счётчик к нулю. В этом окне maintenance task читает `num_idle` и выполняет `for _ in 0..pool.num_idle()` — без ограничения сверху, то есть потенциально огромный диапазон. ## Патч Полные unified diff лежат в evidence рядом с completion-отчётом: [`docs/epic-1-completion/evidence/sqlx-red.patch`](../epic-1-completion/evidence/sqlx-red.patch) (исходное RED-состояние) и [`docs/epic-1-completion/evidence/sqlx-accepted.patch`](../epic-1-completion/evidence/sqlx-accepted.patch) (принятая версия). SHA-256 патчей зафиксированы в metadata. Ниже — суть принятого изменения. ### 1. Bounded maintenance batch Новый private helper, используемый реальным for-loop в `spawn_maintenance_tasks`: ```rust fn maintenance_batch_size(num_idle: usize, capacity: usize) -> usize { cmp::min(num_idle, capacity) } ``` ```rust let batch_size = maintenance_batch_size( pool.num_idle(), pool.options.max_connections as usize, ); for _ in 0..batch_size { if let Some(conn) = pool.try_acquire() { /* ... */ } } ``` `num_idle` не может легитимно превышать capacity; ограничение не отключает maintenance и не меняет период/таймауты. ### 2. Резервирование idle-счётчика до публикации `release()` теперь публикует через helper, который увеличивает `num_idle` до вызова публикующего callback и откатывает изменение при ошибке: ```rust fn publish_idle_connection(num_idle: &AtomicUsize, publish: F) -> Result<(), E> where F: FnOnce() -> Result<(), E>, { num_idle.fetch_add(1, Ordering::AcqRel); if let Err(error) = publish() { num_idle.fetch_sub(1, Ordering::AcqRel); return Err(error); } Ok(()) } ``` Callback естественно возвращает ошибку push как `Result<(), Idle>`: ```rust let published = publish_idle_connection(&self.num_idle, move || { // NOTE: permit отпускается только после удачного push self.idle_conns .push(idle) .map(|()| guard.release_permit()) }); if published.is_err() { panic!("BUG: connection queue overflow in release()"); } ``` `guard.release_permit()` вызывается только при удачном push, то есть порядок push-before-release-permit сохранён. Существующий `panic!("BUG: connection queue overflow in release()")` сохранён, но вынесен **наружу** `publish_idle_connection` и срабатывает уже после отката резерва. Поэтому ветка отката — реальный production-путь (переполнение очереди), а не защитная недостижимая ветка. Важно: `maintenance_batch_size` ограничивает только объём maintenance-скана по capacity. Это **не** защита от переполнения `idle_conns` — это разные инварианты, и один не подменяет другой. ### Регрессионные тесты Тесты используют фактический private helper, применяемый в `release()`, а не проверку текста исходника: - `maintenance_batch_size_bounds_scan_by_capacity` — оракул для `0`, `1`, `capacity`, `capacity + 1`, `usize::MAX`; ожидается ограничение capacity при сохранении нормальных значений. MAX проверяется без запуска цикла на `usize::MAX`. - `publish_reserves_idle_counter_before_connection_is_visible` — детерминированная модель гонки: `ArrayQueue` + `AtomicUsize` + две фазы `Barrier` в двух потоках. Producer публикует соединение, затем сигналит consumer и ждёт его `pop` до возврата из callback. Consumer записывает *предыдущее* значение `fetch_sub` и не утверждает его до второго barrier/join, чтобы RED не превратился в deadlock. Ожидается `previous == 1` и финальный счётчик `0`. В исходном порядке наблюдается `previous == 0` (даже если поздний wrapping-`fetch_add` возвращает `0`). - `publish_rolls_back_idle_counter_when_publication_fails` — при `Err` из callback счётчик не должен «утечь». Production `release()` возвращает именно ошибку push (`Idle`); тест использует строковую ошибку, чтобы проверить тот же контракт helper без конструирования подключения к БД. Никаких test-only sleep, mock DB, файлов или сети; все утверждения детерминированы и ограничены. ## Evidence Команда запускалась напрямую по манифесту vendored-крейта как самостоятельного пакета: ```text cargo test --manifest-path vendor/sqlx-core/Cargo.toml --locked --lib ``` Запуск использовал изолированные `CARGO_HOME` и `CARGO_TARGET_DIR`, поэтому отслеживаемый `Cargo.lock` крейта и глобальный cargo cache не изменялись; конкретные пути машины здесь не приводятся. RED (`sqlx-red.log`, exit `101`): ```text test pool::inner::tests::maintenance_batch_size_bounds_scan_by_capacity ... FAILED test pool::inner::tests::publish_reserves_idle_counter_before_connection_is_visible ... FAILED test pool::inner::tests::publish_rolls_back_idle_counter_when_publication_fails ... ok test result: FAILED. 1 passed; 2 failed; 0 ignored; 0 measured; 2 filtered out ``` Падения RED: `left: 9, right: 8` (не ограничено capacity) и `idle counter must be reserved before the connection is visible, saw 0` (подтверждён `previous == 0`). Deadlock не возник, потому что проверка отложена до join. GREEN (`sqlx-green.log`, exit `0`): ```text test io::read_buf::test_read_buf_bytes_mut ... ok test pool::assert_pool_traits ... ok test pool::inner::tests::maintenance_batch_size_bounds_scan_by_capacity ... ok test pool::inner::tests::publish_reserves_idle_counter_before_connection_is_visible ... ok test pool::inner::tests::publish_rolls_back_idle_counter_when_publication_fails ... ok test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out ``` Существующие upstream-тесты (`pool::assert_pool_traits`, `io::read_buf::test_read_buf_bytes_mut`) не отключены и проходят. Принятая версия (после follow-up правок: natural `Result<(), Idle>` с panic снаружи helper, восстановленные лицензии, modification notice) повторно прогнана тем же `cargo test --manifest-path vendor/sqlx-core/Cargo.toml --locked --lib` с результатом `5 passed; 0 failed` (полный лог — `sqlx-accepted.log`). Дополнительно на принятой версии: - `cargo check -p crank-registry -p admin-api` (`SQLX_OFFLINE=true`, `--offline`) — успешно; - `cargo deny --locked check advisories bans licenses sources` — `advisories ok, bans ok, licenses ok, sources ok`; - `rustfmt --edition 2021 --check vendor/sqlx-core/src/pool/inner.rs` — чисто. ## Ограничения и maintenance burden - Unit-тесты моделируют достижимое interleaving, но **не доказывают, что в production наблюдался `usize::MAX`**. Наблюдаемым фактом остаются hot loop и цепочка maintenance/try_acquire/release по samples. - Это отслеживаемый source patch сторонней зависимости. Он требует ручного переприменения/rebase при обновлении `sqlx-core` и должен быть удалён, как только подтверждённый upstream-fix войдёт в используемую версию. - Публичный API, схемы, feature-набор и таймауты не менялись; maintenance не отключался. - Тесты не отключались; глобальный cargo cache не редактировался.