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

14 KiB
Raw Blame History

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:

Копирайт- и лицензионные уведомления 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 счётчик не должен «утечь». Production release() возвращает именно ошибку 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 не редактировался.