# apollo-rust-client
A robust Rust client for the Apollo Configuration Centre, with support for WebAssembly for browser and Node.js environments.
[](https://crates.io/crates/apollo-rust-client)
[](https://docs.rs/apollo-rust-client)
[](LICENSE)
[](https://github.com/qqiao/apollo-rust-client/actions/workflows/rust.yml)
## Features
- **Multiple Configuration Formats**: Support for Properties, JSON, YAML, Text formats with planned XML support
- **Automatic Format Detection**: Based on namespace file extensions
- **Type-Safe Configuration Management**: Compile-time guarantees and runtime type conversion
- **Cross-Platform Support**: Native Rust and WebAssembly targets
- **TLS Support**: Switchable TLS implementations (native-tls by default, rustls via feature flag)
- **Real-Time Updates**: Background polling with configurable intervals and event listeners
- **Comprehensive Caching**: Multi-level caching with file persistence (native) and memory-only (WASM)
- **Async/Await Support**: Full asynchronous API for non-blocking operations
- **Error Handling**: Detailed error diagnostics with comprehensive error types
- **Grayscale Release Support**: IP and label-based configuration targeting
- **Flexible Configuration**: Direct instantiation or environment variable configuration
- **Memory Management**: Automatic cleanup with explicit control for WASM environments
## Installation
### Rust
Add the following to your `Cargo.toml`:
```toml
[dependencies]
apollo-rust-client = "0.6.3"
```
If you prefer to use `rustls` instead of the system's native TLS (useful for minimal images like Alpine):
```toml
[dependencies]
apollo-rust-client = { version = "0.6.3", default-features = false, features = ["rustls"] }
```
**Note on TLS Support:**
- **Non-WASM Targets**: `native-tls` (enabled by default) and `rustls` are mutually exclusive. You must disable default features if you want to use `rustls`.
- **WASM Targets**: Only `native-tls` (which uses the browser's fetch API) is supported. Enabling the `rustls` feature on WASM targets will result in a compile error.
Alternatively, you can use `cargo add`:
```bash
cargo add apollo-rust-client
```
### WebAssembly (npm)
```bash
npm install @qqiao/apollo-rust-client
```
## Quick Start
### Rust Usage
```rust
use apollo_rust_client::Client;
use apollo_rust_client::client_config::ClientConfig;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create client configuration
let client_config = ClientConfig {
app_id: "your_app_id".to_string(),
cluster: "default".to_string(),
config_server: "http://your-apollo-server:8080".to_string(),
secret: Some("your_apollo_secret".to_string()),
cache_dir: None, // Uses default: /opt/data/{app_id}/config-cache
label: None, // For grayscale releases
ip: None, // For grayscale releases
allow_insecure_https: None, // Allow self-signed certificates
#[cfg(not(target_arch = "wasm32"))]
cache_ttl: None, // Uses default: 600 seconds (10 minutes)
};
let mut client = Client::new(client_config);
// Start background polling for configuration updates
client.start().await?;
// Get configuration for different namespace formats
let namespace = client.namespace("application").await?;
// Handle different configuration formats
match namespace {
apollo_rust_client::namespace::Namespace::Properties(properties) => {
// Properties format (default) - key-value pairs
if let Some(app_name) = properties.get_string("app.name") {
println!("Application name: {}", app_name);
}
if let Some(port) = properties.get_int("server.port") {
println!("Server port: {}", port);
}
if let Some(debug) = properties.get_bool("debug.enabled") {
println!("Debug enabled: {}", debug);
}
}
apollo_rust_client::namespace::Namespace::Json(json) => {
// JSON format - structured data
#[derive(serde::Deserialize)]
struct Config {
name: String,
version: String,
}
let config: Config = json.to_object()?;
println!("Config: {} v{}", config.name, config.version);
}
apollo_rust_client::namespace::Namespace::Text(text) => {
// Text format - plain text content
println!("Text content: {}", text);
}
}
// Add event listener for configuration changes
client.add_listener("application", std::sync::Arc::new(|result| {
match result {
Ok(namespace) => println!("Configuration updated: {:?}", namespace),
Err(e) => eprintln!("Configuration update error: {}", e),
}
})).await;
Ok(())
}
```
#### Configuration via Environment Variables
```rust
use apollo_rust_client::client_config::ClientConfig;
// Initialize from environment variables
let client_config = ClientConfig::from_env()?;
```
**Environment Variables:**
- `APP_ID`: Your application ID (required)
- `APOLLO_CONFIG_SERVICE`: The Apollo config server URL (required)
- `IDC`: The cluster name (optional, defaults to "default")
- `APOLLO_ACCESS_KEY_SECRET`: The secret key for authentication (optional)
- `APOLLO_LABEL`: Comma-separated list of labels for grayscale rules (optional)
- `APOLLO_CACHE_DIR`: Directory to store local cache (optional)
- `APOLLO_CACHE_TTL`: Time-to-live for cache in seconds (optional, defaults to 600, native targets only)
- `APOLLO_ALLOW_INSECURE_HTTPS`: Whether to allow insecure HTTPS connections (optional, defaults to false)
### JavaScript/WebAssembly Usage
```javascript
import { Client, ClientConfig } from "@qqiao/apollo-rust-client";
async function main() {
// Create client configuration
const clientConfig = new ClientConfig(
"your_app_id",
"http://your-apollo-server:8080",
"default"
);
// Set optional properties
clientConfig.secret = "your_apollo_secret";
clientConfig.label = "production";
clientConfig.ip = "192.168.1.100";
const client = new Client(clientConfig);
// Start background polling
await client.start();
// Get configuration cache
const cache = await client.namespace("application");
// Retrieve different data types
const appName = await cache.get_string("app.name");
const serverPort = await cache.get_int("server.port");
const debugEnabled = await cache.get_bool("debug.enabled");
const timeout = await cache.get_float("timeout.seconds");
console.log(`App: ${appName}, Port: ${serverPort}, Debug: ${debugEnabled}`);
// Add event listener for configuration changes
await cache.add_listener((data, error) => {
if (error) {
console.error("Configuration update error:", error);
} else {
console.log("Configuration updated:", data);
}
});
// IMPORTANT: Release memory when done
cache.free();
client.free();
clientConfig.free();
}
main().catch(console.error);
```
## Configuration Formats
The library automatically detects configuration formats based on namespace names:
### Properties Format (Default)
- **Namespace**: `"application"`, `"config.properties"`
- **Format**: Key-value pairs
- **Example**:
```properties
app.name = MyApp
server.port = 8080
```
### JSON Format
- **Namespace**: `"config.json"`, `"settings.json"`
- **Format**: Structured JSON data
- **Example**: `{"database": {"host": "localhost", "port": 5432}}`
### Text Format
- **Namespace**: `"readme.txt"`, `"content.txt"`
- **Format**: Plain text content
- **Example**: Raw text content
### YAML Format
- **Namespace**: `"config.yaml"`, `"config.yml"`
- **Format**: Structured YAML data
- **Example**: Complex configuration structures with nested objects
```rust
#[derive(serde::Deserialize)]
struct AppConfig {
server: ServerConfig,
database: DatabaseConfig,
}
#[derive(serde::Deserialize)]
struct ServerConfig {
host: String,
port: u16,
}
#[derive(serde::Deserialize)]
struct DatabaseConfig {
host: String,
port: u16,
ssl: bool,
}
if let apollo_rust_client::namespace::Namespace::Yaml(yaml) = namespace {
let config: AppConfig = yaml.to_object()?;
println!("Server: {}:{}", config.server.host, config.server.port);
println!("Database: {}:{}", config.database.host, config.database.port);
}
```
### Planned Formats
- **XML**: `"config.xml"`
## Configuration Options
### ClientConfig Fields
- **`app_id`**: Your application ID in Apollo (required)
- **`config_server`**: The Apollo config server URL (required)
- **`cluster`**: The cluster name (required, typically "default")
- **`secret`**: Optional secret key for authentication
- **`cache_dir`**: Directory for local cache files (native only)
- Default: `/opt/data/{app_id}/config-cache`
- WASM: Always `None` (memory-only caching)
- **`label`**: Label for grayscale releases (optional)
- **`ip`**: IP address for grayscale releases (optional)
## Error Handling
The library provides comprehensive error handling:
```rust
use apollo_rust_client::Error;
match client.namespace("application").await {
Ok(namespace) => {
// Handle successful configuration retrieval
}
Err(Error::Cache(cache_error)) => {
// Handle cache-related errors (network, parsing, etc.)
eprintln!("Cache error: {}", cache_error);
}
Err(Error::Namespace(namespace_error)) => {
// Handle namespace-related errors (format detection, etc.)
eprintln!("Namespace error: {}", namespace_error);
}
Err(e) => {
// Handle other errors
eprintln!("Error: {}", e);
}
}
```
## Memory Management (WASM)
For WebAssembly environments, explicit memory management is required:
```javascript
// Always call free() on WASM objects when done
cache.free();
client.free();
clientConfig.free();
```
This prevents memory leaks by releasing Rust-allocated memory on the WebAssembly heap.
## Advanced Usage
### Event Listeners
```rust
// Rust - Add event listener
client.add_listener("application", std::sync::Arc::new(|result| {
match result {
Ok(namespace) => println!("Config updated: {:?}", namespace),
Err(e) => eprintln!("Update error: {}", e),
}
})).await;
```
```javascript
// JavaScript - Add event listener
await cache.add_listener((data, error) => {
if (error) {
console.error("Update error:", error);
} else {
console.log("Config updated:", data);
}
});
```
### Grayscale Releases
```rust
let client_config = ClientConfig {
app_id: "my-app".to_string(),
config_server: "http://apollo-server:8080".to_string(),
cluster: "default".to_string(),
secret: None,
cache_dir: None,
label: Some("canary,beta".to_string()), // Multiple labels
ip: Some("192.168.1.100".to_string()), // Client IP
#[cfg(not(target_arch = "wasm32"))]
cache_ttl: None,
};
```
### Custom JSON Deserialization
```rust
use serde::{Deserialize, Serialize};
#[derive(Deserialize, Serialize)]
struct DatabaseConfig {
host: String,
port: u16,
ssl: bool,
}
if let apollo_rust_client::namespace::Namespace::Json(json) = namespace {
let db_config: DatabaseConfig = json.to_object()?;
println!("Database: {}:{}", db_config.host, db_config.port);
}
```
## API Changes in v0.6.0
- **Typed Namespaces**: Support for multiple configuration formats with automatic detection
- **Event Listeners**: Real-time configuration change notifications
- **Enhanced Error Handling**: Comprehensive error types and better error reporting
- **WASM Improvements**: Better memory management and JavaScript interop
- **Background Polling**: Configurable automatic configuration refresh
## Documentation
For comprehensive documentation, visit our [wiki](docs/wiki/en/Home.md):
- **[Installation Guide](docs/wiki/en/Installation.md)** - Setup instructions
- **[Rust Usage](docs/wiki/en/Rust-Usage.md)** - Native Rust examples
- **[JavaScript Usage](docs/wiki/en/JavaScript-Usage.md)** - WASM usage in JavaScript
- **[Configuration](docs/wiki/en/Configuration.md)** - Configuration options
- **[Features](docs/wiki/en/Features.md)** - Feature overview
- **[Error Handling](docs/wiki/en/Error-Handling.md)** - Error handling guide
- **[Design Overview](docs/wiki/en/Design-Overview.md)** - Architecture documentation
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the Apache License Version 2.0 - see the [LICENSE](LICENSE) file for details.