# Abstract Wizard

[English](#english) | [中文](#中文)

---

## English

Secure configuration file management service. Read, modify, and version-control JSON/YAML config files via REST API. Listens on localhost only — access remotely via SSH tunnel.

### Quick Start

#### Docker Compose (Recommended)

```bash
docker compose up -d
```

The service listens on `127.0.0.1:18080`.

#### Run Locally

```bash
go build -o abstract-wizard .
CONFIG_DIR=./configs ./abstract-wizard
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CONFIG_DIR` | `/config` | Base directory for config files |
| `LISTEN_ADDR` | `127.0.0.1:8080` | HTTP listen address |
| `MAX_BACKUPS` | `10` | Max backup versions per file |

### API

#### Health Check

```bash
curl http://127.0.0.1:18080/health
```

#### Read Config

```bash
curl http://127.0.0.1:18080/api/v1/config/app.json
```

#### Full Replace

```bash
curl -X PUT http://127.0.0.1:18080/api/v1/config/app.json \
  -d '{"database": {"host": "localhost", "port": 5432}}'
```

A backup is created automatically before each write. The response includes `backup_version`.

#### Partial Update (Deep Merge)

```bash
curl -X PATCH http://127.0.0.1:18080/api/v1/config/app.json \
  -d '{"database": {"port": 3306}}'
```

Only the specified fields are updated; nested objects are merged recursively.

#### List Backups

```bash
curl http://127.0.0.1:18080/api/v1/backups/app.json
```

#### Rollback

```bash
# Get the version from the backup list, then:
curl -X POST http://127.0.0.1:18080/api/v1/rollback/app.json \
  -d '{"version": "20260215T120000Z"}'
```

#### Mode Switching

Get current mode:

```bash
curl http://127.0.0.1:18080/api/v1/mode
```

Switch to readonly (rejects all writes):

```bash
curl -X PUT http://127.0.0.1:18080/api/v1/mode \
  -d '{"mode": "readonly"}'
```

Switch back to init (read/write):

```bash
curl -X PUT http://127.0.0.1:18080/api/v1/mode \
  -d '{"mode": "init"}'
```

### YAML Support

All endpoints support both JSON and YAML. The format is detected by file extension:

```bash
curl -X PUT http://127.0.0.1:18080/api/v1/config/app.yaml \
  -H "Content-Type: text/yaml" \
  -d '
database:
  host: localhost
  port: 5432
'
```

### Security Model

The service binds to `127.0.0.1` by default and is not exposed externally. Use an SSH tunnel for remote access:

```bash
ssh -L 18080:127.0.0.1:18080 user@server
```

Then access via `http://127.0.0.1:18080` locally.

### Project Structure

```
├── main.go              # Entry point, env config, graceful shutdown
├── config/
│   ├── validation.go    # Path validation, traversal prevention
│   ├── parser.go        # JSON/YAML parse, serialize, deep merge
│   ├── atomic.go        # Atomic write (temp → fsync → rename)
│   └── backup.go        # Timestamped backups, pruning, rollback
├── audit/
│   └── logger.go        # Structured JSON audit log
├── server/
│   ├── server.go        # HTTP server, routing, mode state machine
│   ├── middleware.go     # Request logging middleware
│   └── handlers.go      # API handlers
├── Dockerfile           # Multi-stage build
└── docker-compose.yaml  # Example deployment
```

---

## 中文

安全的配置文件管理服务。通过 REST API 对 JSON/YAML 配置文件进行读取、修改和版本管理，仅监听 localhost，通过 SSH 隧道访问。

### 快速开始

#### Docker Compose（推荐）

```bash
docker compose up -d
```

服务启动后监听 `127.0.0.1:18080`。

#### 本地运行

```bash
go build -o abstract-wizard .
CONFIG_DIR=./configs ./abstract-wizard
```

### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `CONFIG_DIR` | `/config` | 配置文件存放目录 |
| `LISTEN_ADDR` | `127.0.0.1:8080` | 监听地址 |
| `MAX_BACKUPS` | `10` | 每个文件保留的最大备份数 |

### API

#### 健康检查

```bash
curl http://127.0.0.1:18080/health
```

#### 读取配置

```bash
curl http://127.0.0.1:18080/api/v1/config/app.json
```

#### 完整替换配置

```bash
curl -X PUT http://127.0.0.1:18080/api/v1/config/app.json \
  -d '{"database": {"host": "localhost", "port": 5432}}'
```

写入前会自动创建备份，响应中包含 `backup_version`。

#### 局部更新（深度合并）

```bash
curl -X PATCH http://127.0.0.1:18080/api/v1/config/app.json \
  -d '{"database": {"port": 3306}}'
```

仅更新指定字段，嵌套对象递归合并。

#### 查看备份列表

```bash
curl http://127.0.0.1:18080/api/v1/backups/app.json
```

#### 回滚到指定版本

```bash
# 先从备份列表获取版本号，然后：
curl -X POST http://127.0.0.1:18080/api/v1/rollback/app.json \
  -d '{"version": "20260215T120000Z"}'
```

#### 模式切换

查看当前模式：

```bash
curl http://127.0.0.1:18080/api/v1/mode
```

切换为只读模式（拒绝所有写操作）：

```bash
curl -X PUT http://127.0.0.1:18080/api/v1/mode \
  -d '{"mode": "readonly"}'
```

切换回初始化模式（允许读写）：

```bash
curl -X PUT http://127.0.0.1:18080/api/v1/mode \
  -d '{"mode": "init"}'
```

### YAML 支持

所有端点同时支持 JSON 和 YAML，格式由文件扩展名自动判断：

```bash
curl -X PUT http://127.0.0.1:18080/api/v1/config/app.yaml \
  -H "Content-Type: text/yaml" \
  -d '
database:
  host: localhost
  port: 5432
'
```

### 安全模型

服务默认仅监听 `127.0.0.1`，不暴露到外部网络。远程访问通过 SSH 隧道实现：

```bash
ssh -L 18080:127.0.0.1:18080 user@server
```

之后本地即可通过 `http://127.0.0.1:18080` 访问。

### 项目结构

```
├── main.go              # 入口：环境变量、初始化、优雅关闭
├── config/
│   ├── validation.go    # 路径校验，防止目录穿越
│   ├── parser.go        # JSON/YAML 解析、序列化、深度合并
│   ├── atomic.go        # 原子写入（temp → fsync → rename）
│   └── backup.go        # 时间戳备份、清理、回滚
├── audit/
│   └── logger.go        # 结构化 JSON 审计日志
├── server/
│   ├── server.go        # HTTP 服务、路由、模式状态机
│   ├── middleware.go     # 请求日志中间件
│   └── handlers.go      # API 处理函数
├── Dockerfile           # 多阶段构建
└── docker-compose.yaml  # 示例部署配置
```