269 lines
14 KiB
Markdown
269 lines
14 KiB
Markdown
# 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 не редактировался.
|