feat: add async C bindings for TiKV RawKV

[lance6716]

Summary

• Add an asynchronous C ABI for TiKV RawKV operations, with callback-based completion and explicit request ownership, cancellation, and shutdown APIs.
• Add a C API for process-wide metrics snapshots and an explicit gRPC response decoding limit constructor.
• Add C headers, a C example, and C-only documentation.

This extracts the C layer from draft #571. The C++ wrapper remains in that draft for follow-up work.

Validation

• cargo test -p tikv-client-rust-c --lib (12 passed)
• cargo fmt --all -- --check
• clang -std=c11 -Wall -Wextra -Werror -fsyntax-only -Ibindings/c/include bindings/c/examples/raw_async_demo.c

The TiKV-backed example was not run in this split. This PR remains a draft while the inline review findings on request lifetime, cancellation semantics, and metrics are addressed.

[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 coocood 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

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}

[lance6716]

C-only review notes for this draft. The first two comments are request-lifetime safety issues; the others cover cancellation, observability, tests, and maintainability.

[lance6716]

This post-spawn dereference can race with a fast completion. The C contract allows the callback to destroy the request; after it returns, finalize_request can release the last references before the submit thread reaches this block (when cancel_inflight is true). Please set the cancellation state before spawning, or retain an independent submit-side reference until all post-spawn access is finished.

[lance6716]

Cloning this vector copies bare request addresses without retaining their states. A request can finish, be removed, and be freed before the loop dereferences the copied address, causing a use-after-free. tikv_async_client_destroy has the same pattern. Please keep each request alive while marking cancellation, or avoid traversing these pointers.

[lance6716]

Cancellation is only checked after the underlying future finishes, so a write may already have taken effect when the callback reports CANCELLED. The Ok(Err(error)) arm also reports ERROR despite a cancellation request, contrary to the stronger guarantee in the C header. Please settle and document the terminal-status rule, including partial batch effects, and test both success and error after cancellation.

[lance6716]

The current 12 unit tests do not exercise an accepted request's concurrent lifecycle. Please add deterministic tests for destruction inside the callback, shutdown racing with completion, exactly-once callback delivery, and cancellation outcomes. A C compile-and-link smoke check in CI would also protect the public ABI.

[lance6716]

This gathers the whole process-wide registry, but the C sample retains only the type label and the match below drops gauges, summaries, and other metric types. Two series differing in another label become indistinguishable. Please either narrow the public contract to known client-rust counter/histogram families or preserve the full label/type information; the C header should state whichever scope is chosen.

[lance6716]

The existing metrics describe underlying TiKV/PD RPCs, but this async binding has no outcome or in-flight metric for accepted/rejected submissions, cancellation, panics, or callback completion. An RPC may be counted as successful even when the FFI reports CANCELLED. Please consider a small set of binding-level counters and an in-flight gauge so operators can reconcile the two layers.

[lance6716]

This test checks that an infinite histogram bucket exists, but not its cumulative value, finite bucket values, or the histogram sum. Asserting these with a known observation, plus the intended label behavior, would catch incorrect monitoring output rather than only missing samples.