14 KiB
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:
[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-2565abbdd842310c8f1650fcde3a5a51a3e09412b9e5a6eea87519e0db9e32b339d;LICENSE-APACHE— https://raw.githubusercontent.com/transact-rs/sqlx/v0.9.0/LICENSE-APACHE, SHA-256c8f5453612253e8ea8bad241617fe74c4a6d5d592ba64ff881668c211b50ac99.
Копирайт- и лицензионные уведомления 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:
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
(исходное RED-состояние) и
docs/epic-1-completion/evidence/sqlx-accepted.patch
(принятая версия). SHA-256 патчей зафиксированы в metadata. Ниже — суть
принятого изменения.
1. Bounded maintenance batch
Новый private helper, используемый реальным for-loop в
spawn_maintenance_tasks:
fn maintenance_batch_size(num_idle: usize, capacity: usize) -> usize {
cmp::min(num_idle, capacity)
}
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 и откатывает изменение при ошибке:
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>>:
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 счётчик не должен «утечь». Productionrelease()возвращает именно ошибку push (Idle<DB>); тест использует строковую ошибку, чтобы проверить тот же контракт helper без конструирования подключения к БД.
Никаких test-only sleep, mock DB, файлов или сети; все утверждения детерминированы и ограничены.
Evidence
Команда запускалась напрямую по манифесту vendored-крейта как самостоятельного пакета:
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):
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):
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 не редактировался.