playbooks

home / skills / redisearch / redisearch / minimize-rust-ffi-crate-surface

minimize-rust-ffi-crate-surface skill

/.skills/minimize-rust-ffi-crate-surface

This skill analyzes Rust FFI crates to remove symbols unused or only used in tests, reducing surface area and compilation overhead.

npx playbooks add skill redisearch/redisearch --skill minimize-rust-ffi-crate-surface

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.4 KB
---
name: minimize-rust-ffi-crate-surface
description: Remove Rust-defined C symbols that are either unused or only used in C/C++ unit tests.
---

# Minimize Rust FFI Crate Surface

Remove C symbols defined in a Rust FFI crate or file that are either unused or only used in C/C++ unit tests.

## Arguments
- `<path>`: Path to the Rust crate or file.
- `<path 1> <path 2>`: Multiple Rust crates/files.

If the path doesn't start with `src/`, assume it to be in the `src/redisearch_rs/c_entrypoint` directory. E.g. `numeric_range_tree_ffi` becomes `src/redisearch_rs/numeric_range_tree_ffi`.
If the path points to a directory, review the documentation of all Rust files in that directory.

## Instructions

- Use [analyze-rust-ffi-crate-surface](../analyze-rust-ffi-crate-surface/SKILL.md) to enumerate and analyze the usage of all the FFI symbols exposed by the Rust crate or file (e.g. `extern "C" fn` annotated with `#[unsafe(no_mangle)]` or type definitions).
- For each unused symbol:
  - Delete its Rust definition.
  - Run C/C++ unit tests to ensure the symbol was indeed unused (via `./build.sh RUN_UNIT_TESTS`)
- For each symbol that is only used in C/C++ unit tests, elaborate a plan to either:
  - Refactor the C/C++ unit tests not to use it.
  - Remove the C/C++ unit tests (or assertions) that rely on it, since they are prying into the implementation details of the Rust crate.
  - Keep the symbol, but mark it as "test only" in the Rust documentation.

Overview

This skill helps shrink the C ABI surface exposed by a Rust FFI crate or file by identifying and removing Rust-defined C symbols that are unused or only required by C/C++ unit tests. It guides safe deletion, test verification, and documentation for remaining test-only symbols. The goal is a minimal, stable FFI boundary with fewer maintenance and compatibility risks.

How this skill works

The skill inspects Rust sources for FFI items (extern "C" functions, #[no_mangle] symbols, and type definitions) and enumerates where each symbol is referenced. It relies on an analysis pass that reports usage in Rust, C/C++ sources, and unit tests. For unused symbols it prescribes deletion and running the C/C++ unit test suite to confirm no dependencies remain. For symbols only used by tests it produces remediation options: refactor tests, drop intrusive assertions, or mark the symbol as test-only in docs.

When to use it

  • Before a release to ensure the FFI surface exposes only necessary symbols.
  • When preparing a stable public API and minimizing compatibility obligations.
  • After adding or refactoring Rust FFI code to remove accidental exposures.
  • When cleaning up technical debt introduced by C/C++ tests that access internals.
  • When trying to reduce binary size or surface area for security review.

Best practices

  • Run the analyzer to get a complete mapping of symbol definitions and cross-language references before modifying code.
  • Always run the full C/C++ unit tests (./build.sh RUN_UNIT_TESTS) after deleting an FFI symbol to detect hidden dependencies.
  • Prefer refactoring tests to use public APIs instead of keeping internal symbols for testing.
  • If a symbol must remain for testing, clearly document it as "test-only" and restrict visibility when possible.
  • Batch removals and use version control so you can revert quickly if tests reveal unexpected usage.

Example use cases

  • Remove an internal allocator or helper function that was accidentally exported from a Rust crate but never used by C code.
  • Find symbols only exercised by C++ unit tests that peek into Rust internals and refactor tests to use public APIs.
  • Shrink the exported surface of a Redis module crate before publishing to reduce maintenance guarantees.
  • Identify FFI type definitions that are vestigial after a refactor and safe to delete.

FAQ

What if deleting a symbol breaks a downstream native integration?

Run the full native unit tests and, if available, integration tests in downstream consumers. If a break is detected, restore the symbol and plan a controlled deprecation with documentation and versioning.

When should I mark a symbol as "test-only" instead of removing it?

Mark as test-only only when refactoring tests is infeasible or the symbol is expensive to exercise through public APIs. Document clearly and consider gating its export behind a feature flag or cfg(test) where possible.