Quantum/README.md

# 🚀 Quantum Web Server

**The next-generation web server with HTTP/3 support that's both powerful and dead simple to configure.**

[![Test Status](https://img.shields.io/badge/tests-72%20passing-brightgreen)](https://github.com/your-repo/quantum) [![Rust](https://img.shields.io/badge/rust-1.75%2B-orange)](https://www.rust-lang.org) [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)

> Quantum combines enterprise-grade performance with idiot-proof configuration. Get a reverse proxy, file server, or cloud sync running with HTTP/3, HTTP/2, and HTTP/1.1 support in seconds with just a few lines of JSON.

---

## ⚡ Quick Start - The 30 Second Setup

### 1. Proxy to Your App
```json
{"proxy": {"localhost:3000": ":8080"}}
```
```bash
quantum --config proxy.json
# ✅ Your app on localhost:3000 is now accessible on port 8080
```

### 2. Serve Static Files  
```json
{"static_files": {"./public": ":8080"}}
```
```bash
quantum --config static.json
# ✅ Files in ./public are now served on port 8080
```

### 3. File Upload/Download API
```json
{"file_sync": {"./uploads": ":8080"}}
```
```bash
quantum --config sync.json
# ✅ Upload/download API running on port 8080 for ./uploads
```

**That's it. No complex nesting, no matchers, no handlers - just tell Quantum what you want.**

---

## 🎯 Why Quantum?

### ✅ **Simple Configuration**
- **Dead simple syntax** - if you can write JSON, you can configure Quantum
- **Smart validation** - helpful error messages guide you to fix issues
- **Auto-detection** - works with both simple and advanced configurations

### ✅ **Production Ready** 
- **🔒 TLS/HTTPS**: Automatic certificate management with ACME/Let's Encrypt
- **🚀 HTTP/2**: Full multiplexed protocol support with TLS
- **⚡ HTTP/3**: Complete QUIC implementation with connection pooling
- **⚖️ Load Balancing**: Multiple algorithms (round-robin, least-conn, etc.)
- **🛡️ Security**: Memory-safe Rust, path traversal prevention
- **📊 Monitoring**: Built-in metrics and logging

### ✅ **Enterprise Features**
- **☁️ File Sync**: Revolutionary cloud storage with local mirroring
- **🔄 Real-time Sync**: WebSocket-based instant synchronization
- **🌐 Web Interface**: Modern file management UI
- **🔗 Middleware**: Extensible CORS, logging, and custom handlers

---

## 📖 Simple Configuration Guide

### Basic Patterns

**Proxy multiple services:**
```json
{
  "proxy": {
    "localhost:3000": ":80",
    "localhost:4000": ":443"
  }
}
```

**Multiple static directories:**
```json
{
  "static_files": {
    "./public": ":8080",
    "./assets": ":8081"
  }
}
```

**Full-stack setup:**
```json
{
  "proxy": {"localhost:3000": ":80"},
  "static_files": {"./public": ":8080"}, 
  "file_sync": {"./uploads": ":9000"},
  "tls": "auto"
}
```

### Configuration Options

| Field | Description | Example |
|-------|-------------|---------|
| `proxy` | Proxy requests to backend services | `{"localhost:3000": ":80"}` |
| `static_files` | Serve files from directories | `{"./public": ":8080"}` |
| `file_sync` | Enable upload/download API | `{"./data": ":9000"}` |
| `tls` | TLS mode: "auto", "off", or cert path | `"auto"` |
| `admin_port` | Admin API port (optional) | `":2019"` |

---

## 🔧 Advanced Configuration

Need advanced features? Quantum supports full Caddy v2 configuration format:

<details>
<summary>Click to see advanced configuration example</summary>

```json
{
  "admin": {"listen": ":2019"},
  "apps": {
    "http": {
      "servers": {
        "api_server": {
          "listen": [":8080"],
          "routes": [
            {
              "match": [{"matcher": "host", "hosts": ["api.example.com"]}],
              "handle": [{
                "handler": "reverse_proxy",
                "upstreams": [{"dial": "backend:8080"}],
                "load_balancing": {"selection_policy": {"policy": "least_conn"}},
                "health_checks": {
                  "active": {"path": "/health", "interval": "30s"}
                }
              }]
            }
          ],
          "tls": {
            "automation": {
              "policies": [{
                "subjects": ["api.example.com"],
                "issuer": {"module": "acme", "email": "admin@example.com"}
              }]
            }
          }
        }
      }
    }
  }
}
```

</details>

<details>
<summary><strong>🔥 HTTP/3 Configuration</strong></summary>

Enable HTTP/3 (QUIC) for ultra-fast modern web apps:

```json
{
  "apps": {
    "http": {
      "http3": {
        "listen": ":443"
      },
      "servers": {
        "srv0": {
          "listen": [":443"],
          "routes": [{
            "handle": [{
              "handler": "reverse_proxy",
              "upstreams": [{"dial": "127.0.0.1:8080"}]
            }]
          }]
        }
      }
    },
    "tls": {
      "certificates": {
        "load_files": [{
          "certificate": "./certs/example.com.crt",
          "key": "./certs/example.com.key",
          "subjects": ["example.com", "www.example.com"]
        }]
      }
    }
  }
}
```

**Features:**
- ✅ **QUIC Protocol** - Ultra-fast HTTP/3 with connection multiplexing
- ✅ **Connection Pooling** - Support for 1000+ concurrent connections
- ✅ **Automatic Translation** - Seamless H3 ↔ HTTP/1.1 conversion
- ✅ **Certificate Integration** - Works with existing TLS certificates
- ✅ **Performance Monitoring** - Real-time connection metrics

</details>

---

## 🚀 Installation & Usage

### Prerequisites
- **Rust 1.75+** with 2024 edition support
- **Cargo** package manager

### Build from Source
```bash
git clone ssh://rockvilleav@git.rockvilletollandsda.church:10443/RTSDA/Quantum.git
cd Quantum
cargo build --release
```

### Usage
```bash
# Run with simple config
quantum --config config.json

# Run with custom port  
quantum --port 3000

# Run with default settings
quantum

# Show help
quantum --help
```

---

## ☁️ Revolutionary File Sync

Quantum revolutionizes web servers by including enterprise-grade cloud storage with local mirroring.

### Quick Start
```bash
# 1. Start server with file sync
echo '{"file_sync": {"./shared": ":8080"}}' > sync.json
quantum --config sync.json

# 2. Start sync client
quantum-sync-client --server http://localhost:8080 --local ./my-folder
```

### How It Works
- **📁 Local Mirroring**: Complete offline access to remote files
- **🔍 Real-time Watching**: Instant detection of file changes
- **🔄 Bidirectional Sync**: Two-way synchronization every 30 seconds
- **⚡ Conflict Resolution**: Smart handling of simultaneous changes
- **🌐 Web Interface**: Modern drag-and-drop file management

### Architecture
```
┌─────────────┐    HTTP API     ┌─────────────┐
│   Server    │ ◄────────────► │   Client    │
│  (Quantum)  │                │(sync-client)│
└─────────────┘                └─────────────┘
       │                              │
       ▼                              ▼
┌─────────────┐                ┌─────────────┐
│ Server Root │                │ Local Mirror│
│ Directory   │                │ Directory   │
└─────────────┘                └─────────────┘
```

**Why Better Than Network Mounting:**
- ✅ **Reliable**: No complex network protocols
- ✅ **Fast**: Native local file access speed  
- ✅ **Offline**: Works when disconnected
- ✅ **Cross-Platform**: Consistent across all OS

---

## 🏗️ Architecture & Performance

### Built for Speed
- **🦀 Rust-powered**: Zero-cost abstractions, no GC pauses
- **⚡ Async I/O**: Tokio-based concurrency throughout
- **🔄 Zero-copy**: Efficient request forwarding
- **📊 Memory-safe**: No buffer overflows or memory leaks

### Revolutionary HTTP/3 Architecture
Unlike other servers that bolt-on HTTP/3, Quantum treats it as a first-class citizen:

```
┌─────────────────┐  ┌─────────────────┐
│   HTTP/1.1/2    │  │     HTTP/3      │
│     Server      │  │     Server      │
└─────────────────┘  └─────────────────┘
         │                     │
         ▼                     ▼
┌─────────────────┐  ┌─────────────────┐
│  Proxy Service  │  │  HTTP/3 Router  │
│ (Request<Inc>)  │  │ (native h3)     │
└─────────────────┘  └─────────────────┘
         │                     │
         └─────────────────────┼─────────
                               ▼
                    ┌─────────────────┐
                    │  Shared Core    │
                    │ - RoutingCore   │
                    │ - Load Balancer │
                    │ - Health Checks │
                    └─────────────────┘
```

### Module Structure
```
src/
├── config/
│   ├── mod.rs              # Full Caddy configuration  
│   └── simple.rs          # Simple configuration format
├── server/mod.rs          # HTTP/HTTPS/HTTP2 server
├── proxy/mod.rs           # Reverse proxy & load balancing
├── middleware/mod.rs      # Request/response pipeline
├── tls/mod.rs            # Certificate management
├── routing/              # Protocol-agnostic routing
│   ├── mod.rs           # Shared routing core
│   └── http3.rs         # HTTP/3 native router
└── file_sync/            # Cloud storage system
```

---

## 🧪 Testing

Quantum includes comprehensive test coverage:

```bash
# Run all tests (72 tests passing!)
cargo test

# Test simple configuration  
cargo test simple

# Test with output
cargo test -- --nocapture
```

**Test Coverage:**
- ✅ **72 passing tests** - Comprehensive feature coverage
- ✅ **Real business logic** - No stub tests, genuine validation
- ✅ **Multiple test suites** - Unit, integration, and module tests
- ✅ **Cross-platform** - Tests run on all supported platforms

---

## 📊 Current Status & Roadmap  

### ✅ **PRODUCTION READY (v0.2.x)**
- **🔒 TLS/HTTPS** with rustls, HTTP/2, and HTTP/3 architecture
- **⚡ HTTP/3** with complete QUIC implementation and connection pooling
- **🔄 Reverse Proxy** with advanced load balancing  
- **📁 File Server** with content-type detection
- **🏥 Health Monitoring** with active/passive checks
- **☁️ File Sync** with WebSocket real-time updates
- **🎯 Route Matching** (host, path, regex, method)
- **🛡️ Security** hardening and validation
- **⚙️ Simple Config** - Dead simple JSON format

### 🚧 **IN PROGRESS (v0.3.x)**
- **🔧 Admin API** - Runtime configuration (70% complete)
- **📊 Metrics** - Prometheus integration (framework ready)
- **🔄 Hot Reload** - Zero-downtime updates (foundation ready)

### 🎯 **PLANNED (v0.4.x+)**
- **🔌 WebSocket** proxying
- **👥 Multi-tenancy** with authentication
- **☁️ Cloud Backends** (S3, GCS, Azure)
- **📱 Mobile Apps** for file sync

**Current Status: ~95% complete** - Ready for production use with ongoing enterprise feature development.

---

## 🤝 Contributing

### Development Setup
```bash
git clone ssh://rockvilleav@git.rockvilletollandsda.church:10443/RTSDA/Quantum.git
cd Quantum
cargo build
cargo test
```

### Code Guidelines
- **🦀 Rust conventions** - snake_case, proper error handling
- **📝 Documentation** - Comprehensive inline docs
- **🧪 Tests first** - All new features need tests
- **🔒 Security** - Memory safety and input validation

### Adding Features
1. **Update config** structures in `src/config/`
2. **Add simple config** support if applicable
3. **Write tests** covering the new functionality  
4. **Update docs** with examples and usage
5. **Submit PR** with clear description

---

## 📄 Documentation

**Getting Started:**
- **[QUICKSTART.md](QUICKSTART.md)** - 60-second setup for common scenarios
- **[SIMPLE-CONFIG.md](SIMPLE-CONFIG.md)** - Complete simple configuration guide
- **[MIGRATION.md](MIGRATION.md)** - Migrate from complex to simple configs

**Reference:**
- **[docs/api.md](docs/api.md)** - Complete API reference (simple + full formats)
- **[docs/development.md](docs/development.md)** - Development and contribution guide
- **[docs/architecture.md](docs/architecture.md)** - Technical architecture details
- **[docs/file-sync.md](docs/file-sync.md)** - File sync system documentation

---

## 🔒 Security

- **🦀 Memory safety** guaranteed by Rust
- **🛡️ Input validation** on all configuration and requests  
- **🔐 Secure defaults** in all configurations
- **🚫 Path traversal** prevention in file serving
- **📋 Security headers** middleware

---

## ⭐ Star History

If you find Quantum useful, please consider giving it a star! ⭐

---

## 📄 License

Copyright (c) 2024 Benjamin Slingo

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

---

**Start simple. Scale to enterprise. All with one binary.**

For questions, issues, or contributions, visit our [repository](ssh://rockvilleav@git.rockvilletollandsda.church:10443/RTSDA/Quantum.git).