Metadata-Version: 2.4
Name: syncgate
Version: 1.0.0
Summary: Lightweight multi-storage routing and sync abstraction layer
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: boto3>=1.34.0
Requires-Dist: paramiko>=3.0.0
Requires-Dist: psycopg2-binary>=2.9.9
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# SyncGate 🎯

> 轻量级多存储路由与同步抽象层

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-168%2B-green.svg)]()
[![Coverage](https://img.shields.io/badge/coverage-70%25-green.svg)]()

## 🎯 产品定位

**SyncGate** 是轻量级多存储路由与同步抽象层，统一管理本地文件、HTTP 链接和多种云存储。

### 核心功能

1. **🔗 统一路径** - 多种存储一个命令访问
2. **🌳 虚拟文件系统** - 不移动源文件，只管理链接
3. **✅ 链接验证** - 自动验证链接有效性
4. **📊 监控统计** - 跟踪使用情况和健康评分
5. **🔄 批量操作** - 批量创建/删除/验证
6. **⚡ 错误处理** - 重试机制和熔断器

### 支持的存储

| 存储类型 | 状态 | 协议 |
|----------|------|------|
| 本地文件 | ✅ | local:/path/to/file |
| HTTP/HTTPS | ✅ | https://example.com/file |
| AWS S3 | ✅ | s3://bucket/key |
| WebDAV | ✅ | webdav://server.com/path |
| FTP | ✅ | ftp://server.com/path |
| SFTP | ✅ | sftp://user@server.com/path |

## 🚀 快速开始

### 安装

```bash
pip install syncgate
```

### 演示

```bash
python3 demo_complete.py
```

输出：
```
🎯 SyncGate Complete Demo
============================================================

📝 Step 1: 创建链接
  ✅ Local:  /docs/notes.txt
  ✅ HTTP:   /online/api.json
  ✅ S3:     /cloud/data.csv

📂 Step 2: 虚拟文件系统结构
virtual/
├── 📁 docs/  → local:/path/to/files
├── 📁 online/ → https://api.example.com
└── 📁 cloud/  → s3://my-bucket/data

🔍 Step 3: 链接验证
  ✅ /docs/notes.txt
  ✅ /online/api.json

✅ 演示完成!
```

### 使用

```bash
# 创建链接
syncgate link /docs/a.txt local:/path/to/file.txt local
syncgate link /online/api.json https://api.example.com/data.json http
syncgate link /cloud/data.csv s3://my-bucket/data/2024.csv s3

# 列出目录
syncgate ls /docs

# 树形结构
syncgate tree /

# 验证链接
syncgate validate /docs/a.txt

# 查看状态
syncgate status /docs/a.txt
```

## 📖 文档

- [Usage](USAGE.md) - 完整使用指南
- [Quick Start](QUICK_START.md) - 5 分钟快速开始
- [Project](PROJECT.md) - 架构设计
- [Changelog](CHANGELOG.md) - 更新日志

## 🛠️ 功能模块

### CLI 命令

| 命令 | 说明 |
|------|------|
| `link` | 创建链接 |
| `unlink` | 删除链接 |
| `ls` | 列出目录 |
| `tree` | 树形结构 |
| `validate` | 验证链接 |
| `status` | 查看状态 |

### REST API

```bash
# 启动 API 服务器
python -m syncgate.api --port 8080
```

| 端点 | 说明 |
|------|------|
| GET /api/stats | 获取统计 |
| GET /api/links | 获取所有链接 |
| POST /api/links | 创建链接 |
| DELETE /api/links/{path} | 删除链接 |

### 高级功能

```python
from syncgate.batch import BatchOperations
from syncgate.monitor import StatsCollector
from syncgate.error_handler import retry, CircuitBreaker

# 批量操作
batch = BatchOperations(vfs_root="virtual")
batch.batch_create([...])

# 监控统计
stats = StatsCollector(vfs_root="virtual")
stats.record_create("local")
health = stats.get_health_score()

# 错误处理
@retry(max_retries=3, delay=1.0)
def fragile_operation():
    ...
```

## 🧪 测试

```bash
# 运行所有测试
pytest tests/ -v

# 运行性能测试
python3 tests/benchmark_streaming.py
```

**测试覆盖**: 168+ 测试用例

## 📈 性能

| 场景 | 性能 |
|------|------|
| 初始化 (5000 文件) | 0.04ms |
| 首屏加载 | 2ms (50 条) |
| 流式滚动 | 流畅无卡顿 |

## 🏗️ 开发

```bash
# 克隆项目
git clone https://github.com/cyydark/syncgate.git
cd syncgate

# 安装开发依赖
pip install -e ".[dev]"

# 运行演示
python3 demo_complete.py

# 运行测试
pytest tests/ -v
```

## 🤝 贡献

欢迎提交 Issue 和 PR！

反馈: [GitHub Issues](https://github.com/cyydark/syncgate/issues)

## 📄 许可

MIT License - see [LICENSE](LICENSE)

---

**SyncGate** - 统一管理散落在各处的文件 📁🌐☁️
