Files
crank/docs/dependency-patches/sqlx-core-0.9.0.md
T

269 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 не редактировался.