kode-bridge 0.1.3

# kode-bridge

[![Rust](https://img.shields.io/badge/rust-stable-brightgreen.svg)](https://www.rust-lang.org/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0)
[![Crates.io](https://img.shields.io/crates/v/kode-bridge.svg)](https://crates.io/crates/kode-bridge)

**[中文](./README_CN.md) | English**

**kode-bridge** is a modern Rust library designed for cross-platform (macOS, Linux, Windows) IPC HTTP communication. With a unified API, you can easily send HTTP requests via Unix Domain Sockets or Windows Named Pipes, just as simple as using a regular HTTP client.

## ✨ Features

- **🌍 True Cross-Platform**: Automatically detects the platform and uses optimal IPC methods
  - **Unix/Linux/macOS**: Unix Domain Sockets
  - **Windows**: Named Pipes
- **🚀 Zero Configuration**: Unified `IpcHttpClient` API, no platform-specific code required
- **📦 Auto Serialization**: Built-in JSON request and response handling
- **⚡ High Performance**: Optimized connection management strategies for different platforms
- **🔧 Easy Integration**: Based on [interprocess](https://github.com/kotauskas/interprocess) and Tokio async runtime
- **📖 Complete Support**: Includes examples, benchmarks, and comprehensive documentation

## 🚀 Quick Start

### Add Dependencies

```toml
[dependencies]
kode-bridge = "0.1"
tokio = { version = "1", features = ["full"] }
serde_json = "1.0"
```

### Basic Usage

```rust
use kode_bridge::IpcHttpClient;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Automatically detect platform and use appropriate IPC path
    #[cfg(unix)]
    let client = IpcHttpClient::new("/tmp/my_service.sock")?;
    
    #[cfg(windows)]
    let client = IpcHttpClient::new(r"\\.\pipe\my_service")?;
    
    // Send GET request
    let response = client.request("GET", "/api/version", None).await?;
    println!("Status: {}", response.status);
    println!("Response: {}", response.body);
    
    // Send POST request
    let data = json!({"user": "alice", "action": "login"});
    let response = client.request("POST", "/api/auth", Some(&data)).await?;
    println!("Auth result: {}", response.json()?);
    
    Ok(())
}
```

### Using Environment Variables

Create a `.env` file:

```env
# Unix systems
CUSTOM_SOCK=/tmp/my_app.sock

# Windows systems (each backslash needs to be escaped by doubling)
CUSTOM_PIPE=\\\\.\\pipe\\\my_app
```

Then in your code:

```rust
use dotenv::dotenv;
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenv().ok();
    
    #[cfg(unix)]
    let path = env::var("CUSTOM_SOCK").unwrap_or("/tmp/default.sock".to_string());
    
    #[cfg(windows)]
    let path = env::var("CUSTOM_PIPE").unwrap_or(r"\\.\pipe\default".to_string());
    
    let client = IpcHttpClient::new(&path)?;
    let response = client.request("GET", "/status", None).await?;
    
    Ok(())
}
```

## 📋 Examples

Run built-in examples:

```bash
# Basic request example
cargo run --example request

# Large data request example
cargo run --example request_large

# Using custom IPC path
CUSTOM_SOCK=/tmp/my.sock cargo run --example request  # Unix
CUSTOM_PIPE=\\\\.\\pipe\\my_pipe cargo run --example request  # Windows
```

## 🔥 Performance Benchmarks

Run performance benchmarks:

```bash
# Run all benchmarks
cargo bench

# View benchmark reports
open target/criterion/report/index.html
```

Benchmarks automatically:
- Detect the running platform
- Use appropriate environment variables (`CUSTOM_SOCK` or `CUSTOM_PIPE`)
- Apply platform-specific performance optimization strategies

## 🏗️ Architecture Design

```
┌─────────────────────────────────────────┐
│              IpcHttpClient              │
│       (Unified Cross-Platform API)      │
├─────────────────────────────────────────┤
│            http_client.rs               │
│        (HTTP Protocol Handler)          │
├─────────────────────────────────────────┤
│             interprocess                │
│       (Cross-Platform IPC Transport)    │
├─────────────────┬───────────────────────┤
│   Unix Sockets  │    Windows Pipes      │
│   (Unix/Linux)  │     (Windows)         │
└─────────────────┴───────────────────────┘
```

### Core Components

- **`IpcHttpClient`**: Unified client interface that automatically adapts to different platforms
- **`http_client`**: Platform-agnostic HTTP protocol handling with chunked transfer encoding support
- **Smart Platform Detection**: Compile-time automatic selection of optimal IPC implementation

## 🎯 Use Cases

- **Local Service Communication**: Communicate with local processes like Clash, Mihomo, proxy services, etc.
- **Microservice Architecture**: High-performance inter-process HTTP communication
- **System Integration**: Replace traditional REST API local calls
- **Performance-Critical Applications**: Scenarios requiring low-latency local communication

## 🛠️ Development

### Build Project

```bash
git clone https://github.com/KodeBarinn/kode-bridge.git
cd kode-bridge
cargo build
```

### Run Tests

```bash
cargo test
```

### Generate Documentation

```bash
cargo doc --open
```

## 📚 Resources

- [Platform Guide](./PLATFORM_GUIDE.md) - Detailed cross-platform usage guide
- [Examples](./examples/) - Complete example code
- [Benchmarks](./benches/) - Performance benchmarks

## 🤝 Contributing

We welcome Issues and Pull Requests!

## 📄 License

This project is licensed under the [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0).

See the [Licence](./Licence) file for details.