Add sync API for transactional client

[odecode]

For issue #289 a synchronous API for transactional client.

I have programmed a fair bit but new to OSS and Rust. I consulted AI heavily for this to try and get an understanding of what this part of the project is about and how it works, but I tried using it a teacher rather than just "vibe coding".

Summary by CodeRabbit

• New Features
  • Added synchronous transaction and snapshot APIs providing blocking access alongside the existing async interfaces.
• Bug Fixes
  • Runtime validation now surfaces a clear user-facing error when attempting to use the sync APIs from within an active async runtime.
• Tests
  • Added extensive integration tests covering sync client behavior, transactions, snapshots, scans, and edge cases.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign niedhui for approval. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[ti-chi-bot]

Welcome @odecode!

It looks like this is your first PR to tikv/client-rust 🎉.

I'm the bot to help you request reviewers, add labels and more, See available commands.

We want to make sure your contribution gets all the attention it needs!



Thank you, and welcome to tikv/client-rust. 😃

[Copilot]

Pull request overview

This PR adds a synchronous API wrapper for the TiKV transactional client to address issue #289. The implementation provides blocking alternatives to the existing async transaction APIs.

Changes:

• Introduced SyncTransactionClient, SyncTransaction, and SyncSnapshot structs that wrap their async counterparts
• Each sync type contains an Arc-wrapped Tokio runtime and uses block_on to execute async operations synchronously
• Added comprehensive integration tests mirroring the async test patterns

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/transaction/sync_client.rs	New synchronous client wrapper providing blocking transaction operations
src/transaction/sync_transaction.rs	Synchronous transaction wrapper that blocks on async transaction methods
src/transaction/sync_snapshot.rs	Synchronous snapshot wrapper for read-only operations
src/transaction/mod.rs	Module declarations for new sync components
src/lib.rs	Public API exports for sync types
tests/sync_transaction_tests.rs	Comprehensive integration tests covering all sync APIs
tests/common/mod.rs	Added init_sync() helper for synchronous test setup

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[odecode]

Thank you for the review comments, I have made changes according to the comments

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[odecode]

I have made changes requested by the review comments

[odecode]

Thank you for your patience so far! I have made the review's suggested change.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[odecode]

Copilot left no new comments. Are some actions required by me for the "tide" pending check?

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[odecode]

Is it possible for me to request review from Copilot myself? Then I could address all its concerns and not bother you on every iteration.

EDIT: I figured out that I can ask Copilot to review uncommitted changes in my code editor, I will do that for the next round of changes if Copilot or you request more improvements

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a synchronous transaction API: new types SyncTransactionClient, SyncTransaction, SyncSnapshot, a NestedRuntimeError variant, synchronous test helper, and extensive integration tests. The sync types wrap existing async components and block on their futures via an internal Tokio runtime.

Changes

Cohort / File(s)	Summary
Error Handling src/common/errors.rs	Added NestedRuntimeError(String) to the public Error enum with user-facing message about not using SyncTransactionClient inside a Tokio async runtime.
Crate Re-exports src/lib.rs, src/transaction/mod.rs	Publicly re-exported SyncSnapshot, SyncTransaction, and SyncTransactionClient; added module declarations for sync implementations.
Sync Client Implementation src/transaction/sync_client.rs	New SyncTransactionClient wrapping async client + Tokio runtime; implements new, new_with_config, nested-runtime detection (check_nested_runtime), safe_block_on, sync transactional entry points (begin_*, snapshot, current_timestamp, gc, cleanup_locks, unsafe_destroy_range, cfg-gated scan_locks), Clone, and unit tests for nested-runtime behavior.
Sync Snapshot Implementation src/transaction/sync_snapshot.rs	New SyncSnapshot wrapping async Snapshot with blocking accessors (get, key_exists, batch_get, scan, scan_keys, scan_reverse, scan_keys_reverse) using runtime.
Sync Transaction Implementation src/transaction/sync_transaction.rs	New SyncTransaction wrapping async Transaction; provides blocking transactional API (get, get_for_update, key_exists, batch ops, scans, put/insert/delete, batch_mutate, lock_keys, commit, rollback, send_heart_beat) delegating via safe_block_on.
Test Infrastructure tests/common/mod.rs	Added init_sync() helper to initialize test infra synchronously with a dedicated single-thread Tokio runtime (panics if called from async contexts).
Integration Test Suite tests/sync_transaction_tests.rs	Added extensive integration tests for sync client: nested-runtime checks, timestamp retrieval, optimistic/pessimistic flows, CRUD, batch operations, snapshot semantics, scans, locking, heartbeat, cloning, and edge cases.

Sequence Diagram(s)

sequenceDiagram
    participant U as User Code
    participant SC as SyncTransactionClient
    participant RT as check_nested_runtime()
    participant SB as safe_block_on()
    participant TRT as Tokio Runtime
    participant AC as Async TransactionClient

    U->>SC: call sync method (e.g., begin_optimistic())
    SC->>RT: check_nested_runtime()
    alt nested runtime detected
        RT-->>SC: Err(NestedRuntimeError)
        SC-->>U: return Err(NestedRuntimeError)
    else no nested runtime
        RT-->>SC: Ok(())
        SC->>SB: wrap async_op into future
        SB->>TRT: block_on(future)
        TRT->>AC: execute async operation
        AC-->>TRT: result
        TRT-->>SB: unblock with result
        SB-->>SC: Result<T>
        SC-->>U: return Result<T>
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 I hop between async and sync today,
I check runtimes lest I stray,
I block with care, I wrap and send,
Transactions safe from end to end,
A rabbit's cheer for syncs that play!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add sync API for transactional client' is a concise, specific summary that accurately describes the main objective of the pull request, which is to add synchronous API wrappers for the TiKV transactional client.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[odecode]

added extra test coverage for the sync snapshot public api surface, and error handling to prevent panic when sync client is called from within an async runtime.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@src/transaction/sync_snapshot.rs`:
- Around line 18-70: SyncSnapshot methods call self.runtime.block_on(...)
directly which will panic if invoked inside an active Tokio runtime; add a
private helper on SyncSnapshot (e.g., safe_block_on_snapshot) that mirrors
sync_client::safe_block_on by checking
tokio::runtime::Handle::try_current().is_ok() and returning
Err(Error::NestedRuntimeError) when a current runtime exists, otherwise invoking
self.runtime.block_on; replace direct self.runtime.block_on(...) calls in the
public methods get, key_exists, batch_get, scan, scan_keys, scan_reverse, and
scan_keys_reverse to use this helper so nested runtime usage is guarded.

In `@src/transaction/sync_transaction.rs`:
- Around line 20-126: All SyncTransaction and SyncSnapshot methods currently
call self.runtime.block_on(...) and can panic if invoked inside an existing
Tokio runtime; make the existing check_nested_runtime/safe_block_on helpers
accessible (move to a shared module or change to pub(crate)), then replace every
direct self.runtime.block_on(self.inner.<method>(...)) call in SyncTransaction
and SyncSnapshot (e.g., get, get_for_update, key_exists, batch_get,
batch_get_for_update, scan, scan_keys, scan_reverse, scan_keys_reverse, put,
insert, delete, batch_mutate, lock_keys, commit, rollback, send_heart_beat) with
the safe helper usage (run the nested-runtime check and call safe_block_on
around the inner async call) so callers get a NestedRuntimeError instead of a
panic.