rust

Rust Codebase Guidance

ALWAYS use this subagent for ANY task involving:

• Reading, editing, or understanding Rust code
• kubectl-client/ or kubectl-telemetry/ directories
• Tokio async patterns, runtime, or collectors
• mlua FFI bindings or Lua exports
• Go FFI integration
• Telemetry, tracing, or logging setup
• Researching Rust code for documentation

For Lua-side integration, also consult the lua subagent.

---

Guidance for working with the Rust codebase (kubectl-client/).

Context: Neovim Plugin Dylib

This is a cdylib loaded by Neovim via the mlua Lua FFI. This context imposes critical constraints:

Runtime Constraints

Single Tokio Runtime: A singleton OnceLock<Runtime> manages all async operations. Never create additional runtimes.

Blocking Bridge: Lua calls are synchronous. Use block_on() to bridge async Rust to sync Lua:

fn block_on<F: std::future::Future>(fut: F) -> F::Output {
    match Handle::try_current() {
        Ok(h) => task::block_in_place(|| h.block_on(fut)),
        Err(_) => {
            let rt = RUNTIME.get_or_init(|| Runtime::new().expect("tokio runtime"));
            rt.block_on(fut)
        }
    }
}

Client Lifecycle: Kubernetes clients are stored in global Mutex<Option<Client>>. Use with_client() helper for safe access:

pub fn with_client<F, Fut, R>(f: F) -> LuaResult<R>
where
    F: FnOnce(Client) -> Fut,
    Fut: Future<Output = LuaResult<R>>,
{
    let client = CLIENT_INSTANCE.lock()...;
    block_on(f(client))
}

mlua FFI Patterns

Module Export: The #[mlua::lua_module(skip_memory_check)] attribute exports the module. All public functions must be registered in the exports table:

exports.set("function_name", lua.create_function(function_name)?)?;
exports.set("async_function", lua.create_async_function(async_function)?)?;

Async Functions: Use lua.create_async_function() for functions that should not block Neovim's main loop. These functions take Lua by value (not reference).