torrent-gateway/README.md

# BitTorrent Gateway

A comprehensive unified content distribution system that seamlessly integrates BitTorrent protocol, WebSeed technology, DHT peer discovery, built-in tracker, and Nostr announcements. This gateway provides intelligent content distribution by automatically selecting the optimal delivery method based on file size and network conditions.

## Architecture Overview

The BitTorrent Gateway operates as a unified system with multiple specialized components working together:

### Core Components

**1. Gateway HTTP API Server (Port 9877)**
- Main web interface and API endpoints
- File upload/download management
- Smart proxy for reassembling chunked content
- WebSeed implementation with advanced LRU caching
- Rate limiting and abuse prevention

**2. Embedded Blossom Server (Port 8082)**
- Nostr-compatible blob storage protocol
- Direct blob storage for small files (<100MB)
- Integration with gateway for seamless operation

**3. DHT Node (Port 6883)**
- Distributed peer discovery
- BitTorrent DHT protocol implementation
- Bootstrap connectivity with major DHT networks
- Automatic torrent announcement and peer sharing

**4. Built-in BitTorrent Tracker**
- Full BitTorrent tracker implementation
- Announce/scrape protocol support
- P2P coordination and peer ranking
- Client compatibility optimizations for qBittorrent, Transmission, WebTorrent, Deluge, uTorrent

### Smart Storage Strategy

The system uses an intelligent dual-storage approach:

- **Small Files (<100MB)**: Stored directly as blobs using Blossom protocol
- **Large Files (≥100MB)**: Automatically chunked into 2MB pieces, stored as torrents with WebSeed fallback

### P2P Coordination System

A sophisticated P2P coordinator manages all networking components:

- **Unified Peer Discovery**: Aggregates peers from tracker, DHT, and WebSeed sources
- **Smart Peer Ranking**: Geographic proximity and performance-based peer selection
- **Load Balancing**: Distributes load across multiple peer sources
- **Health Monitoring**: Real-time monitoring of all P2P components with automatic alerting

## Installation

### Prerequisites

- Go 1.21 or later
- SQLite3
- 10MB+ available storage

### Quick Start

```bash
# Clone repository
git clone https://git.sovbit.dev/enki/torrentGateway.git
cd torrentGateway

# Build the gateway
go build -o gateway ./cmd/gateway

# Run with default configuration
./gateway
```

The web interface will be available at http://localhost:9876

### Configuration

The default configuration is in `configs/config.yaml`. Customize settings there:

```yaml
gateway:
  host: "0.0.0.0"
  port: 9876
  storage_path: "./storage"

blossom:
  enabled: true
  host: "0.0.0.0"
  port: 8081
  max_blob_size: 10485760  # 10MB

dht:
  enabled: true
  port: 6882
  bootstrap_nodes:
    - "router.bittorrent.com:6881"
    - "dht.transmissionbt.com:6881"

database:
  path: "./gateway.db"

nostr:
  relays:
    - "wss://relay.damus.io"
    - "wss://nos.lol"

admin:
  enabled: false
  pubkeys: []  # Add admin Nostr pubkeys here

rate_limiting:
  upload:
    requests_per_second: 1.0    # Max uploads per second per IP
    burst_size: 5               # Burst allowance
    max_file_size: "100MB"      # Maximum file size
  download:
    requests_per_second: 50.0   # Global download rate limit
    burst_size: 100             # Global burst allowance
  stream:
    requests_per_second: 10.0   # Max streams per second per file
    burst_size: 20              # Stream burst allowance
    max_concurrent: 50          # Max concurrent streams
  auth:
    login_attempts_per_minute: 10  # Login attempts per IP per minute
    burst_size: 5                  # Login burst allowance
```

## API Reference

### Authentication

All endpoints support Nostr-based authentication via:
- **NIP-07**: Browser extension (Alby, nos2x)
- **NIP-46**: Remote signer/bunker URL

```bash
# Get challenge
curl http://localhost:9876/api/auth/challenge

# Login (requires signed Nostr event)
curl -X POST http://localhost:9876/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"auth_type": "nip07", "auth_event": "..."}'
```

### File Operations

```bash
# Upload file
curl -X POST http://localhost:9876/api/upload \
  -F "file=@example.mp4" \
  -F "announce_dht=true"

# Download file
curl http://localhost:9876/api/download/[hash] -o downloaded_file

# Get torrent
curl http://localhost:9876/api/torrent/[hash] -o file.torrent

# Stream video (HLS)
curl http://localhost:9876/api/stream/[hash]/playlist.m3u8
```

### User Management

```bash
# Get user stats (requires auth)
curl http://localhost:9876/api/users/me/stats \
  -H "Authorization: Bearer [session_token]"

# List user files
curl http://localhost:9876/api/users/me/files \
  -H "Authorization: Bearer [session_token]"

# Delete file
curl -X DELETE http://localhost:9876/api/users/me/files/[hash] \
  -H "Authorization: Bearer [session_token]"
```

## Nostr Integration

The system announces new content to configured Nostr relays:

- **Event Type**: Custom torrent announcement events
- **Content**: Torrent magnet links and metadata
- **Discovery**: Enables decentralized content discovery
- **Relay Configuration**: Multiple relays for redundancy

Example Nostr event:
```json
{
  "kind": 1063,
  "content": "New torrent available",
  "tags": [
    ["magnet", "magnet:?xt=urn:btih:..."],
    ["size", "104857600"],
    ["name", "example-file.zip"]
  ]
}
```

## Performance & Scaling

### Optimization Features
- **Concurrent Downloads**: Multiple parallel piece downloads
- **Geographic Peer Selection**: Prioritizes nearby peers for faster transfers  
- **Smart Caching**: LRU eviction with configurable cache sizes
- **Rate Limiting**: Prevents abuse while maintaining performance
- **Connection Pooling**: Efficient resource utilization

### Monitoring & Alerting
- **Component Health Scores**: 0-100 scoring for all P2P components
- **Performance Metrics**: Response times, throughput, error rates
- **Automatic Alerts**: Configurable thresholds for degraded performance
- **Diagnostic Endpoints**: Detailed system introspection

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with comprehensive tests
4. Submit a pull request

## License

[Add your license information here]

## Support

- **Issues**: Report bugs and feature requests via GitHub issues
- **Documentation**: Additional documentation in `/docs`
- **Community**: [Add community links if available]