fix(deps): bound SQLx pool maintenance and reserve idle counters
This commit is contained in:
1 parent
7aa854de26
commit
284eb8180e
113 files changed
+21092
-2
No files matched your search
@@ -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 не редактировался.
|
||||
Reference in new issue
Block a user