s2-bucket-proxy 0.1.2
C engine-based bucket proxy server for S2 storage — streaming, decryption, and downloads
Requires Python: >=3.8
Keywords: storage, proxy, bucket, streaming, encryption, aes, cdn

# S2 Bucket Proxy

**C engine-powered proxy server** for streaming and downloading encrypted files from S2 storage buckets. Decrypts AES-256-CBC chunks on-the-fly and serves them over HTTP with full Range request support.

## Features

- **C Engine** — high-performance HTTP server (libmicrohttpd, epoll, thread pool)
- **AES-256-CBC Decryption** — real-time chunk decryption via OpenSSL
- **Full Range Support** — byte-range seeking for video/audio players
- **ETag & Conditional Requests** — `If-None-Match`, `If-Range`, 304 Not Modified
- **CORS** — full preflight support for browser-based streaming
- **Multi-Replica Fallback** — automatic retry across chunk replicas
- **SQLite3 Config** — persistent config, buckets, and stats
- **Docker Support** — production-ready container with env var configuration
- **Interactive CLI** — terminal UI for managing buckets and server

## Install System Dependencies

The C engine compiles from source on `pip install`, so you need build tools and libraries installed first.

### Ubuntu / Debian

```bash
sudo apt update
sudo apt install build-essential libcurl4-openssl-dev libssl-dev libmicrohttpd-dev pkg-config
```

### Fedora / RHEL / CentOS

```bash
sudo dnf install gcc make libcurl-devel openssl-devel libmicrohttpd-devel pkgconf-pkg-config
```

### Arch Linux / Manjaro

```bash
sudo pacman -S base-devel curl openssl libmicrohttpd pkgconf
```

### macOS (Homebrew)

```bash
brew install curl openssl libmicrohttpd pkg-config
```

### Termux (Android)

```bash
pkg update
pkg install clang make libcurl openssl libmicrohttpd pkg-config
```

### Alpine Linux (Docker)

```bash
apk add build-base curl-dev openssl-dev libmicrohttpd-dev pkgconf
```

## Installation

### From PyPI

```bash
pip install s2-bucket-proxy
```

> The C engine compiles automatically during install (~30s). Make sure system dependencies above are installed first.

### From Source

```bash
git clone <repo>
cd bucket_proxy/v2
pip install -e .
```

### Docker (no system deps needed)

```bash
docker build -t s2-bucket-proxy .
docker run -p 8001:8001 \
  -e S2_MAIN_SERVER=https://your-server.com \
  -e S2_TOKEN=bkt_your_token_here \
  -v proxy_data:/data \
  s2-bucket-proxy
```

Or with Docker Compose:

```bash
S2_MAIN_SERVER=https://your-server.com S2_TOKEN=bkt_xxx docker compose up -d
```

## Quick Start

### Interactive Mode

```bash
s2-proxy
# → proxy> add bkt_your_token_here
# → proxy> start
```

### Non-Interactive

```bash
# Add bucket + start in one command
s2-proxy start --server https://your-server.com --token bkt_xxx

# Add a bucket
s2-proxy add bkt_your_token_here

# Start as daemon
s2-proxy start -d

# Stop daemon
s2-proxy stop
```

### Docker Container Management

```bash
# Add a bucket to running container
docker exec s2_bucket_proxy bucket_proxy_engine --docker add-bucket --token bkt_xxx

# List buckets
docker exec s2_bucket_proxy bucket_proxy_engine --docker list-buckets

# View status
docker exec s2_bucket_proxy bucket_proxy_engine --docker status
```

## API Endpoints

| Method | Route | Description |
|--------|-------|-------------|
| `GET` | `/health` | Health check |
| `GET` | `/status` | Server stats + buckets |
| `GET` | `/buckets` | List registered buckets |
| `GET` | `/{bucket}/files?limit=N&offset=N` | List files in bucket |
| `GET` | `/{bucket}/stream/{file_id}` | Stream file (Range supported) |
| `GET` | `/{bucket}/download/{file_id}` | Download file |
| `HEAD` | `/{bucket}/stream/{file_id}` | Get file metadata |
| `HEAD` | `/{bucket}/download/{file_id}` | Get download metadata |
| `OPTIONS` | `*` | CORS preflight |

### Streaming

```bash
# Full file
curl http://localhost:8001/mybucket/stream/file123

# Range request (video seeking)
curl -H "Range: bytes=1000000-2000000" http://localhost:8001/mybucket/stream/file123

# Private file
curl http://localhost:8001/mybucket/stream/file123?token=ftk_xxx
```

### Download

```bash
curl -OJ http://localhost:8001/mybucket/download/file123
```

## Architecture

```
┌──────────────────────────────────────────────────┐
│                    Python CLI                     │
│  s2-proxy (interactive) / s2-proxy start (cmd)   │
└──────────────────┬───────────────────────────────┘
                   │ subprocess
┌──────────────────▼───────────────────────────────┐
│              C Engine (bucket_proxy_engine)       │
│                                                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │ server.c │  │  api.c   │  │ crypto.c │       │
│  │ HTTP svr │  │ curl GET │  │ AES-256  │       │
│  │ epoll    │  │ validate │  │ decrypt  │       │
│  │ Range    │  │ info     │  │ PKCS7    │       │
│  │ CORS     │  │ download │  │          │       │
│  └──────────┘  └──────────┘  └──────────┘       │
│                                                   │
│  ┌──────────┐  ┌──────────┐                      │
│  │  db.c    │  │  main.c  │                      │
│  │ SQLite3  │  │ CLI args │                      │
│  │ config   │  │ daemon   │                      │
│  │ stats    │  │ docker   │                      │
│  └──────────┘  └──────────┘                      │
└──────────────────────────────────────────────────┘
```

## Docker Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `S2_MAIN_SERVER` | Main storage server URL | `http://localhost:8000` |
| `S2_PORT` | Proxy listen port | `8001` |
| `S2_TOKEN` | Bucket token (auto-registers) | — |
| `S2_DB_PATH` | SQLite database path | `/data/proxy.db` |

## License

MIT