# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
Batata-client is a Rust client library for the Batata/Nacos microservices platform, providing configuration management and service discovery capabilities via gRPC.
## Build Commands
```bash
cargo build # Build the library
cargo build --release # Build optimized version
cargo build --examples # Build examples
cargo test # Run all tests
cargo test <test_name> # Run a specific test
cargo fmt # Format code
cargo clippy # Run linter
cargo doc --open # Generate and view documentation
```
## Running Examples
```bash
cargo run --example config_example # Config service demo
cargo run --example naming_example # Naming service demo
```
## Architecture
### Module Structure
- **lib.rs** - Main entry point exposing `BatataClient` with builder pattern
- **api/** - gRPC service definitions and request/response traits
- **auth/** - Authentication: `Credentials`, `AuthManager`, `AccessToken`
- **cache/** - File-based cache for failover: `FileCache`
- **config/** - Configuration management: `ConfigService`, `ConfigCache`, change listeners
- **naming/** - Service discovery: `NamingService`, `ServiceInfoCache`, subscribers
- **remote/** - RPC layer: `RpcClient`, `GrpcConnection`, `ServerListManager`
- **common/** - Utilities (MD5, UUID, parsing) and constants
### Key Design Patterns
- **Builder Pattern**: `BatataClientBuilder` for client configuration
- **Service Pattern**: Separate `ConfigService` and `NamingService`
- **Arc + RwLock/DashMap**: Thread-safe shared state
- **Async/Await**: Full async support via Tokio
### Component Flow
```
BatataClient
├── RpcClient (gRPC communication)
│ ├── GrpcConnection (channel lifecycle)
│ └── ServerListManager (server tracking)
├── ConfigService
│ ├── ConfigCache (local caching with MD5 validation)
│ └── ListenerRegistry (change notifications)
└── NamingService
├── ServiceInfoCache (instance caching)
└── SubscriberRegistry (service change events)
```
## Features
### Authentication
- Username/Password authentication via `username_password()`
- AccessKey/SecretKey authentication via `access_key()`
- Automatic token refresh
### TLS/SSL
- TLS configuration via `TlsConfig`
- CA certificate, client certificate, and key support
- Skip verification option (for development)
### Configuration Service
- `get_config()` / `publish_config()` / `remove_config()`
- `search_config()` - Search configurations with pagination
- `add_listener()` / `remove_listener()` - Config change notifications
### Naming Service
- `register_instance()` / `deregister_instance()` / `update_instance()`
- `get_all_instances()` / `select_instances()` / `select_one_healthy_instance()`
- `get_service()` - Get service with cluster filtering
- `subscribe()` / `unsubscribe()` - Service change notifications
### Cache Persistence
- `FileCache` for local disk caching
- Failover support when server is unavailable
- Configurable cache directory via `cache_dir()`
## Proto Generation
The `build.rs` script compiles `proto/nacos_grpc_service.proto` using tonic-build. Generated code appears in the `api` module.
## Default Ports
- HTTP API: 8848
- gRPC: HTTP port + 1000 (default: 9848)