rust-cache-server 0.1.0

# rust-cache (Redis-like cache in Rust)

**English** | [ไทย](#ไทย)

---

## English

### Redis-like cache in Rust

In-memory key-value cache server written in Rust, designed as a lightweight Redis-like alternative.
It speaks the Redis RESP protocol sufficiently for basic commands and can be used with `ioredis`
from Node.js.

This project is developed by **SIAMINNOVATOR CO., LTD. (Thailand)** as an open source
alternative for those who need a Redis-like cache server without worrying about Redis
licensing issues.

### Quick Install

**Option 1: One-line install (requires Rust)**
```bash
curl -fsSL https://raw.githubusercontent.com/SiamInnovator/rust-cache/main/install-universal.sh | bash
```

**Option 2: From source**
```bash
git clone https://github.com/SiamInnovator/rust-cache.git
cd rust-cache
./install.sh
```

**Option 3: Using Cargo (if published to crates.io)**
```bash
cargo install rust-cache
```

### Features

- Basic commands: `PING`, `GET`, `SET`, `DEL`, `EXPIRE`, `TTL`, `KEYS`, `INCR`, `DECR`, `INCRBY`, `DECRBY`, `FLUSHALL`
- Optional TTL support for `SET` via `EX` option
- In-memory store using sharded concurrent map (`dashmap`)
- Background cleanup task for expired keys
- Async TCP server based on Tokio, multiple concurrent clients
- Authentication support (username/password)
- Rate limiting for failed login attempts
- Configurable memory limits and buffer sizes
- JSON data storage support

### Build (Linux)

```bash
git clone https://github.com/SiamInnovator/rust-cache.git
cd rust-cache
cargo build --release
```

The resulting binary will be at:

```bash
target/release/rust-cache
target/release/rust-cache-cli
```

### Run & Config

The server searches for config files in this order (first found wins):

1. `RUST_CACHE_CONFIG` environment variable (explicit override)
2. `/etc/rust-cache/rust-cache.conf` (system-wide config)
3. `~/.config/rust-cache/rust-cache.toml` (user config)
4. `./rust-cache.toml` (local, current working directory)

If no config file is found, defaults are used:

- Listen on `127.0.0.1:7777`
- Auto-detect total RAM on Linux and use ~50% as max memory
- Use 4 KB socket read buffer per connection

Example:

```bash
# Use system config
sudo mkdir -p /etc/rust-cache
sudo cp rust-cache.toml /etc/rust-cache/rust-cache.conf
./target/release/rust-cache

# Or use user config
mkdir -p ~/.config/rust-cache
cp rust-cache.toml ~/.config/rust-cache/
./target/release/rust-cache

# Or override with env
RUST_CACHE_CONFIG=/path/to/custom.toml ./target/release/rust-cache
```

See `rust-cache.toml` for all available options.

### Storing JSON Data

Yes! `rust-cache` stores data as binary (bytes), so you can store JSON strings directly.
Just serialize your JSON on the client side before `SET`, and deserialize after `GET`:

**Node.js example:**
```javascript
const Redis = require('ioredis');
// Without authentication
const redis = new Redis({ host: '127.0.0.1', port: 7777 });

// With password
const redis = new Redis({ host: '127.0.0.1', port: 7777, password: 'your-password' });

// With username and password
const redis = new Redis({ host: '127.0.0.1', port: 7777, username: 'admin', password: 'your-password' });

// Store JSON
const data = { name: 'test', value: 123 };
await redis.set('mykey', JSON.stringify(data));

// Retrieve JSON
const jsonStr = await redis.get('mykey');
const parsed = JSON.parse(jsonStr);
```

**CLI example:**
```bash
rust-cache-cli
rust-cache> SET user:1 '{"name":"John","age":30}'
OK
rust-cache> GET user:1
{"name":"John","age":30}
```

### Use from Node.js with ioredis

Install `ioredis` in your Node.js project:

```bash
npm install ioredis
```

Example client (see `examples/ioredis-client.js`):

```bash
# Without authentication
node examples/ioredis-client.js

# With password (configure in examples/.env)
# Create examples/.env file with: REDIS_PASSWORD=your-password
node examples/ioredis-client.js

# With username and password
# Create examples/.env file with:
# REDIS_USERNAME=admin
# REDIS_PASSWORD=your-password
node examples/ioredis-client.js
```

The example will connect to `127.0.0.1:7777`, run `PING`, `SET`, `GET`, `EXPIRE`, `TTL`, and log results.

### Systemd Service

Install as a systemd service:

```bash
sudo cp rust-cache.service.example /etc/systemd/system/rust-cache.service
sudo systemctl daemon-reload
sudo systemctl enable rust-cache
sudo systemctl start rust-cache
```

After changing config, restart:

```bash
sudo systemctl restart rust-cache
```

### License

This software is provided under the MIT License. You are free to use, modify, and
distribute it without restriction, including for commercial purposes. See the `LICENSE`
file for the full text.

---

## ไทย

### Redis-like cache ใน Rust

เซิร์ฟเวอร์ cache แบบ key-value ในหน่วยความจำที่เขียนด้วย Rust ออกแบบมาเป็นทางเลือก
ที่เบาและเร็วกว่า Redis รองรับโปรโตคอล Redis RESP สำหรับคำสั่งพื้นฐานและใช้งานร่วมกับ
`ioredis` จาก Node.js ได้

โปรเจกต์นี้พัฒนาโดย **SIAMINNOVATOR CO., LTD. (ประเทศไทย)** เพื่อเป็นทางเลือก
open source ที่ไม่มีปัญหาลิขสิทธิ์สำหรับผู้ที่ต้องการใช้ Redis-like cache
server โดยไม่ต้องกังวลเรื่องลิขสิทธิ์ของ Redis

### ติดตั้งแบบรวดเร็ว

**วิธีที่ 1: ติดตั้งด้วยคำสั่งเดียว (ต้องมี Rust)**
```bash
curl -fsSL https://raw.githubusercontent.com/SiamInnovator/rust-cache/main/install-universal.sh | bash
```

**วิธีที่ 2: จาก source code**
```bash
git clone https://github.com/SiamInnovator/rust-cache.git
cd rust-cache
./install.sh
```

**วิธีที่ 3: ใช้ Cargo (ถ้า publish ไป crates.io แล้ว)**
```bash
cargo install rust-cache
```

### ฟีเจอร์

- คำสั่งพื้นฐาน: `PING`, `GET`, `SET`, `DEL`, `EXPIRE`, `TTL`, `KEYS`, `INCR`, `DECR`, `INCRBY`, `DECRBY`, `FLUSHALL`
- รองรับ TTL สำหรับ `SET` ผ่าน option `EX`
- เก็บข้อมูลในหน่วยความจำด้วย sharded concurrent map (`dashmap`)
- มี background task ทำความสะอาด key ที่หมดอายุ
- Async TCP server ใช้ Tokio รองรับหลาย client พร้อมกัน
- รองรับการยืนยันตัวตน (username/password)
- Rate limiting สำหรับการ login ที่ล้มเหลว
- กำหนดขีดจำกัดหน่วยความจำและขนาด buffer ได้
- รองรับการเก็บข้อมูล JSON

### Build (Linux)

```bash
git clone https://github.com/SiamInnovator/rust-cache.git
cd rust-cache
cargo build --release
```

Binary ที่ได้จะอยู่ที่:

```bash
target/release/rust-cache
target/release/rust-cache-cli
```

### รันและตั้งค่า

เซิร์ฟเวอร์จะค้นหาไฟล์ config ตามลำดับนี้ (ใช้ตัวแรกที่เจอ):

1. ตัวแปร environment `RUST_CACHE_CONFIG` (override)
2. `/etc/rust-cache/rust-cache.conf` (config ระดับระบบ)
3. `~/.config/rust-cache/rust-cache.toml` (config ของผู้ใช้)
4. `./rust-cache.toml` (config ในโฟลเดอร์ปัจจุบัน)

ถ้าไม่เจอไฟล์ config จะใช้ค่า default:

- ฟังที่ `127.0.0.1:7777`
- ตรวจจับ RAM ทั้งหมดบน Linux อัตโนมัติและใช้ ~50% เป็น max memory
- ใช้ socket read buffer 4 KB ต่อ connection

ตัวอย่าง:

```bash
# ใช้ config ระดับระบบ
sudo mkdir -p /etc/rust-cache
sudo cp rust-cache.toml /etc/rust-cache/rust-cache.conf
./target/release/rust-cache

# หรือใช้ config ของผู้ใช้
mkdir -p ~/.config/rust-cache
cp rust-cache.toml ~/.config/rust-cache/
./target/release/rust-cache

# หรือ override ด้วย env
RUST_CACHE_CONFIG=/path/to/custom.toml ./target/release/rust-cache
```

ดูตัวเลือกทั้งหมดได้ใน `rust-cache.toml`

### เก็บข้อมูล JSON

ได้เลย! `rust-cache` เก็บข้อมูลเป็น binary (bytes) ดังนั้นสามารถเก็บ JSON string ได้โดยตรง
แค่ serialize JSON ฝั่ง client ก่อน `SET` และ deserialize หลัง `GET`:

**ตัวอย่าง Node.js:**
```javascript
const Redis = require('ioredis');
// ไม่มี authentication
const redis = new Redis({ host: '127.0.0.1', port: 7777 });

// มี password
const redis = new Redis({ host: '127.0.0.1', port: 7777, password: 'your-password' });

// มี username และ password
const redis = new Redis({ host: '127.0.0.1', port: 7777, username: 'admin', password: 'your-password' });

// เก็บ JSON
const data = { name: 'test', value: 123 };
await redis.set('mykey', JSON.stringify(data));

// ดึง JSON
const jsonStr = await redis.get('mykey');
const parsed = JSON.parse(jsonStr);
```

**ตัวอย่าง CLI:**
```bash
rust-cache-cli
rust-cache> SET user:1 '{"name":"John","age":30}'
OK
rust-cache> GET user:1
{"name":"John","age":30}
```

### ใช้งานจาก Node.js กับ ioredis

ติดตั้ง `ioredis` ในโปรเจกต์ Node.js:

```bash
npm install ioredis
```

ตัวอย่าง client (ดู `examples/ioredis-client.js`):

```bash
# ไม่มี authentication
node examples/ioredis-client.js

# มี password (ตั้งค่าใน examples/.env)
# สร้างไฟล์ examples/.env แล้วใส่: REDIS_PASSWORD=your-password
node examples/ioredis-client.js

# มี username และ password
# สร้างไฟล์ examples/.env แล้วใส่:
# REDIS_USERNAME=admin
# REDIS_PASSWORD=your-password
node examples/ioredis-client.js
```

ตัวอย่างจะเชื่อมต่อไปที่ `127.0.0.1:7777` แล้วรัน `PING`, `SET`, `GET`, `EXPIRE`, `TTL` และแสดงผลลัพธ์

### Systemd Service

ติดตั้งเป็น systemd service:

```bash
sudo cp rust-cache.service.example /etc/systemd/system/rust-cache.service
sudo systemctl daemon-reload
sudo systemctl enable rust-cache
sudo systemctl start rust-cache
```

หลังจากแก้ config แล้ว restart:

```bash
sudo systemctl restart rust-cache
```

### สิทธิ์การใช้งาน

ซอฟต์แวร์นี้เปิดให้ใช้งานได้อย่างเสรี ไม่มีค่าใช้จ่าย และไม่มีข้อจำกัดในการใช้งาน
เชิงพาณิชย์ ดูรายละเอียดเพิ่มเติมในไฟล์ `LICENSE`

---

**พัฒนาโดย SIAMINNOVATOR CO., LTD. (ประเทศไทย)**