fix(deps): bound SQLx pool maintenance and reserve idle counters

This commit is contained in:
bsodfather committed 2026-10-04 23:57:40 +03:00
1 parent 7aa854de26
commit 284eb8180e
113 files changed
+21092 -2

No files matched your search

+268
View File
@@ -0,0 +1,268 @@
# 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` — <https://raw.githubusercontent.com/transact-rs/sqlx/v0.9.0/LICENSE-MIT>,
SHA-256 `5abbdd842310c8f1650fcde3a5a51a3e09412b9e5a6eea87519e0db9e32b339d`;
- `LICENSE-APACHE` — <https://raw.githubusercontent.com/transact-rs/sqlx/v0.9.0/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<DB>::try_acquire` (`inner.rs:182`) и `PoolInner<DB>::release`;
- `crossbeam_queue::array_queue::ArrayQueue::pop`,
`core::sync::atomic::Atomic<usize>::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<F, E>(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<DB>>`:
```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<DB>`); тест использует строковую ошибку, чтобы проверить
тот же контракт 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<DB>>` с
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 не редактировался.