uploader-bot/docs/MY_PROTOCOL.md

# MY Network Protocol Specification

## Обзор

MY Network представляет собой децентрализованный overlay протокол для распределенной репликации и синхронизации контента поверх существующей системы my-uploader-bot. Протокол сохраняет все существующие состояния и функциональность, добавляя P2P синхронизацию с кворумным консенсусом.

## Принципы Overlay Protocol

### 1. Совместимость с Существующей Системой
- **Полное сохранение** всех состояний [`StoredContent`](app/core/models/content.py:61)
- **Неизменность** существующих API endpoints
- **Прозрачная интеграция** без нарушения работы текущих клиентов
- **Обратная совместимость** со всеми версиями API

### 2. Состояния Контента в MY Network

#### Поддерживаемые Состояния
```
encrypted: Boolean     - Статус шифрования контента
decrypted: Virtual     - Расшифрованная версия (через decrypted_content_id)
preview: Virtual       - Превью-версия для публичного доступа
```

MY Network реплицирует **все состояния** контента:
- **Encrypted Content** - зашифрованные данные с [`encryption_key_id`](app/core/models/content.py:157)
- **Decrypted Content** - расшифрованные версии через связи
- **Preview Content** - публичные превью для демонстрации
- **Metadata** - все метаданные включая теги, описание, медиа-информацию

#### Связи Между Состояниями
```sql
-- Существующая структура StoredContent поддерживает связи
SELECT * FROM stored_content sc1 
LEFT JOIN stored_content sc2 ON sc1.decrypted_content_id = sc2.id;
```

### 3. P2P Синхронизация Architecture

#### Кворумный Консенсус
```
Минимальный кворум: 3 ноды
Консенсус требует: 2/3 + 1 подтверждений
Timeout для консенсуса: 30 секунд
```

#### Алгоритм Репликации
1. **Content Discovery** - обнаружение нового контента
2. **Integrity Check** - проверка целостности через хеш
3. **Quorum Voting** - голосование за принятие контента
4. **Replication** - репликация на кворум нод
5. **Confirmation** - подтверждение успешной репликации

### 4. Bootstrap Configuration

#### Структура bootstrap.json
```json
{
  "version": "1.0.0",
  "network_id": "my-network-mainnet",
  "bootstrap_nodes": [
    {
      "id": "node-001",
      "address": "my://192.168.1.100:8080",
      "public_key": "ed25519:AAAA...",
      "region": "eu-west-1",
      "weight": 100
    }
  ],
  "consensus": {
    "min_quorum": 3,
    "consensus_threshold": 0.67,
    "timeout_seconds": 30,
    "retry_attempts": 3
  },
  "sync_settings": {
    "sync_interval": 60,
    "max_batch_size": 100,
    "compression": "gzip",
    "encryption": "aes-256-gcm"
  }
}
```

## API Endpoints для MY Network

### Core MY Protocol Endpoints

#### Node Management
```
GET  /api/my/node/status          - Статус текущей ноды
GET  /api/my/node/peers           - Список подключенных пиров
POST /api/my/node/connect         - Подключение к новому пиру
POST /api/my/node/disconnect      - Отключение от пира
```

#### Content Synchronization  
```
GET  /api/my/sync/status          - Статус синхронизации
POST /api/my/sync/request         - Запрос синхронизации контента
GET  /api/my/sync/conflicts       - Список конфликтов синхронизации
POST /api/my/sync/resolve         - Разрешение конфликтов
```

#### Quorum & Consensus
```
GET  /api/my/quorum/status        - Статус кворума
POST /api/my/quorum/vote          - Голосование за контент
GET  /api/my/quorum/results       - Результаты голосования
POST /api/my/consensus/propose    - Предложение изменений
```

#### Content Distribution
```
GET  /api/my/content/{hash}       - Получение контента через MY Network
GET  /api/my/content/{hash}/peers - Список пиров с контентом
POST /api/my/content/announce     - Анонс нового контента
GET  /api/my/content/search       - Поиск контента в сети
```

### Integration API Endpoints

#### Health Check & Discovery
```
GET  /api/my/health               - Проверка здоровья MY ноды
GET  /api/my/discovery/nodes      - Обнаружение новых нод
POST /api/my/discovery/announce   - Анонс собственной ноды
```

#### Metrics & Analytics
```
GET  /api/my/metrics/network      - Метрики сети
GET  /api/my/metrics/content      - Метрики контента
GET  /api/my/metrics/performance  - Метрики производительности
```

## Protocol Messages

### MY Network Message Types

#### Node Communication
```protobuf
message NodeHandshake {
  string node_id = 1;
  string public_key = 2;  
  string network_version = 3;
  repeated string supported_features = 4;
  int64 timestamp = 5;
}

message PeerInfo {
  string node_id = 1;
  string address = 2;
  int32 connection_count = 3;
  int64 last_seen = 4;
  float reputation_score = 5;
}
```

#### Content Sync Messages
```protobuf
message ContentAnnouncement {
  string content_hash = 1;
  int64 file_size = 2;
  string content_type = 3;
  bool encrypted = 4;
  string encryption_key_id = 5;
  repeated string tags = 6;
  int64 timestamp = 7;
}

message SyncRequest {
  repeated string content_hashes = 1;
  string requesting_node = 2;
  int32 priority = 3;
  int64 timestamp = 4;
}
```

#### Consensus Messages
```protobuf
message QuorumVote {
  string content_hash = 1;
  string voter_node_id = 2;
  bool vote = 3;  // true = accept, false = reject
  string signature = 4;
  int64 timestamp = 5;
}

message ConsensusResult {
  string content_hash = 1;
  int32 votes_for = 2;
  int32 votes_against = 3;
  bool consensus_reached = 4;
  repeated string participating_nodes = 5;
}
```

## Security Model

### Cryptographic Security
- **Node Identity**: Ed25519 ключи для идентификации нод
- **Message Signing**: Все сообщения подписываются отправителем
- **Content Integrity**: SHA-256 хеши для проверки целостности
- **Transport Security**: TLS 1.3 для всех сетевых соединений

### Access Control
- **Content Access**: Сохранение существующих прав доступа
- **Network Participation**: Whitelist/blacklist механизмы
- **Rate Limiting**: Защита от спама и DoS атак
- **Reputation System**: Система репутации для узлов

## MY Network Service Layer

### Service Architecture
```
┌─────────────────────┐
│   Existing API      │  <- Без изменений
├─────────────────────┤
│   MY Network Layer  │  <- Новый overlay слой
├─────────────────────┤
│   StoredContent     │  <- Существующая модель
└─────────────────────┘
```

### Service Components
- **MY Node Manager** - управление статусом ноды
- **P2P Communication** - межузловое взаимодействие  
- **Content Replicator** - репликация контента
- **Consensus Engine** - механизм консенсуса
- **Sync Coordinator** - координация синхронизации

## Performance Considerations

### Scalability Targets
- **Network Size**: До 1000 активных нод
- **Content Volume**: До 10TB на ноду
- **Sync Throughput**: 100 MB/s между нодами
- **Consensus Latency**: < 5 секунд для кворума

### Optimization Strategies
- **Content Chunking** - разбиение больших файлов
- **Delta Sync** - синхронизация только изменений
- **Compression** - сжатие передаваемых данных
- **Caching** - кеширование популярного контента
- **Load Balancing** - балансировка нагрузки между нодами

## Future Roadmap

### Phase 1: Core Protocol (Q1 2025)
- [x] Protocol specification
- [ ] Basic P2P communication
- [ ] Simple consensus mechanism
- [ ] Bootstrap node implementation

### Phase 2: Advanced Features (Q2 2025)
- [ ] Content deduplication
- [ ] Advanced routing algorithms
- [ ] Performance optimizations
- [ ] Monitoring and analytics

### Phase 3: Enterprise Features (Q3 2025)
- [ ] Multi-region replication
- [ ] Enterprise security features
- [ ] SLA guarantees
- [ ] Professional support tools