krabka-client-admin 0.7.1

Operator-side admin client for Krabka clusters
Documentation
# krabka-client-admin

[![Crates.io](https://img.shields.io/crates/v/krabka-client-admin.svg)](https://crates.io/crates/krabka-client-admin)
[![Docs.rs](https://docs.rs/krabka-client-admin/badge.svg)](https://docs.rs/krabka-client-admin)
[![CI](https://github.com/krabka-io/krabka-client-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/krabka-io/krabka-client-rs/actions/workflows/ci.yml)

Operator-side admin client for Krabka and Kafka-compatible clusters.

Part of [Krabka](https://github.com/krabka-io/krabka-client-rs), a Rust implementation
of Apache Kafka-compatible infrastructure and clients.

## Overview

Operators and automation use `krabka-client-admin` as their control-plane
client. It builds on `krabka-client-core` for typed Kafka protocol dispatch and
tracks the active controller for controller-routed RPCs. It retries selected
requests when a broker returns `NOT_CONTROLLER`.

Use this crate when a program must create topics, change topic config, manage
users or ACLs, or inspect log directories. It sends these Kafka admin RPCs
without a dependency on broker internals.

## Capabilities

- Read topic metadata, create and delete topics, and expand partitions.
- Describe dynamic topic config and change it with incremental alter operations.
- Upsert and delete SCRAM user credentials for SHA-256 and SHA-512.
- Create, delete, and describe ACLs.
- Describe and alter client quotas for each user.
- Create, renew, expire, and describe delegation tokens.
- Alter and describe the log directories of each broker.
- List consumer groups and inspect their offsets.
- Push client metrics to the cluster (KIP-714) when a broker client metrics
  subscription matches the client, as a Java admin client does.
  `AdminClientConfig::enable_metrics_push` (default `true`) turns this off.

## Kafka Scope

The public API wraps the Kafka admin RPCs that Krabka operators need now. These
RPCs cover SCRAM credentials (KIP-554), delegation tokens (KIP-48), dynamic
topic configuration, ACLs, client quotas, and log-directory inspection. The API
is not a complete clone of the JVM `AdminClient` surface.

Log-directory calls target the connected broker. They do not retry against the
controller. Quota helpers expose the per-user entity shape that Krabka's
operator controllers use.

## Install

```sh
cargo add krabka-client-admin
```

For workspace development, use the path dependency from this repository.

## Usage

Create a topic and fetch its metadata:

```rust,no_run
use std::collections::BTreeMap;

use krabka_client_admin::{AdminClient, CreateTopicSpec, TopicMutationOptions};

# async fn run() -> Result<(), Box<dyn std::error::Error>> {
let mut admin = AdminClient::connect(&["127.0.0.1:9092".to_string()]).await?;

admin
    .create_topics(
        &[CreateTopicSpec {
            name: "orders".into(),
            partitions: 3,
            replicas: 1,
            configs: BTreeMap::new(),
        }],
        TopicMutationOptions::default(),
    )
    .await?;

let metadata = admin.metadata(&["orders"]).await?;
println!("topics: {:?}", metadata.topics);
# Ok(())
# }
```

## Transport policy

`AdminClientConfig` exposes `client_dns_lookup`, `reconnect_backoff`,
`reconnect_backoff_max`, `send_buffer`, `receive_buffer`,
`dispatch_queue_capacity`, and `frame_max`. Use `connect_with_config` to combine
these settings with DNS/setup/request deadlines, API retries, metadata recovery,
and client metrics policy.

Defaults remain DNS 10s, setup 10s/max 30s, reconnect 50ms/max 1s,
send 128KiB/receive 64KiB, dispatch64, and frame100MiB. The admin idle lifetime
remains five minutes; setting it to zero disables eviction. `None` socket buffers
use OS defaults. Transport policy is validated before I/O, including coherent
setup/reconnect maximum bounds and positive representable request/setup deadlines.

## Documentation

- [API documentation]https://docs.rs/krabka-client-admin
- [krabka-client-rs repository]https://github.com/krabka-io/krabka-client-rs
- [Kafka compatibility matrix]https://github.com/krabka-io/krabka-broker/blob/main/docs/KIP_MATRIX.md

## License

Apache-2.0. Derivative work of [Apache Kafka](https://kafka.apache.org); see
[NOTICE](https://github.com/krabka-io/krabka-client-rs/blob/main/NOTICE).