cubenet_backend/SHARED_LIBS_GUIDE.md

Shared Libraries Architecture - Абстракция для микросервисов

📋 Концепция

Shared libraries - это набор переиспользуемых абстракций для всех сервисов. Каждая библиотека предоставляет определенную функциональность через trait-based architecture.

🏗️ Структура

shared_libs/
├── audit_logger/           ✅ Логирование действий пользователей
│   ├── src/
│   │   ├── lib.rs
│   │   ├── models.rs       # AuditLog, ActionType, ActionStatus
│   │   ├── store.rs        # AuditStore trait, InMemoryAuditStore
│   │   └── logger.rs       # AuditLogger implementation
│   └── Cargo.toml
│
├── db_orm/                 (Планируется)
│   ├── src/
│   │   ├── lib.rs
│   │   ├── models.rs       # Shared models
│   │   ├── repository.rs   # Repository pattern
│   │   └── migrations.rs   # DB migrations
│   └── Cargo.toml
│
├── auth/                   (Планируется)
│   ├── src/
│   │   ├── lib.rs
│   │   ├── jwt.rs          # JWT token handling
│   │   └── permissions.rs  # RBAC
│   └── Cargo.toml
│
└── common/                 (Планируется)
    ├── src/
    │   ├── lib.rs
    │   ├── errors.rs       # Common error types
    │   ├── config.rs       # Configuration
    │   └── utils.rs        # Utilities
    └── Cargo.toml

✅ audit_logger (Реализовано)

Описание

Централизованное логирование всех действий пользователей во всех микросервисах.

Особенности

• ✅ Структурированное логирование
• ✅ Типобезопасные действия (enum ActionType)
• ✅ Отслеживание успеха/ошибок
• ✅ Метаданные (IP, User Agent, время)
• ✅ Extensible storage (trait AuditStore)
• ✅ In-memory backend для разработки

Использование

let store = Arc::new(InMemoryAuditStore::new());
let logger = AuditLogger::new(store, "service_name");

logger.log_action(
    Some("user_id".to_string()),
    ActionType::Create,
    "resource".to_string(),
    "/endpoint".to_string(),
).await?;

Расширяемость

Можно реализовать собственный backend для хранения:

• PostgreSQL backend
• Elasticsearch backend
• Kafka backend
• Другие хранилища

🔌 Интеграция в сервисы

API Gateway

use audit_logger::{AuditLogger, InMemoryAuditStore};
use std::sync::Arc;

let logger = Arc::new(AuditLogger::new(
    Arc::new(InMemoryAuditStore::new()),
    "api_gateway",
));

// В handlers используйте logger

API Layer

let logger = Arc::new(AuditLogger::new(
    Arc::new(InMemoryAuditStore::new()),
    "api",
));

Microservices

pub struct UserServiceImpl {
    audit_logger: Arc<AuditLogger>,
}

impl UserService for UserServiceImpl {
    async fn get_users(&self, _request: Request<GetUsersRequest>) {
        self.audit_logger.log_action(
            None,
            ActionType::Read,
            "users".to_string(),
            "/GetUsers".to_string(),
        ).await.ok();
        
        // ...
    }
}

🔮 Планируемые библиотеки

Phase 2: db_orm

Назначение: Абстракция для работы с БД

pub trait Repository<T>: Send + Sync {
    async fn create(&self, item: T) -> Result<T>;
    async fn read(&self, id: i32) -> Result<T>;
    async fn update(&self, item: T) -> Result<T>;
    async fn delete(&self, id: i32) -> Result<()>;
    async fn list(&self, limit: usize, offset: usize) -> Result<Vec<T>>;
}

Backends:

• SQLx для type-safe queries
• Diesel для ORM
• Sea-ORM для async ORM

Phase 2: auth

Назначение: Аутентификация и авторизация

pub trait AuthProvider {
    async fn verify_token(&self, token: &str) -> Result<Claims>;
    async fn create_token(&self, user_id: &str) -> Result<String>;
    async fn has_permission(&self, user: &User, action: &str) -> Result<bool>;
}

Функции:

• JWT token handling
• RBAC (Role-Based Access Control)
• OAuth2 integration (будущее)

Phase 2: common

Назначение: Общие типы и утилиты

pub enum Error {
    NotFound,
    Unauthorized,
    Forbidden,
    Internal,
    ValidationError(String),
}

pub trait Config {
    fn database_url(&self) -> String;
    fn log_level(&self) -> String;
    fn jwt_secret(&self) -> String;
}

📊 Использование в проекте

Текущее состояние

• ✅ audit_logger включен во все сервисы
• ✅ API Gateway логирует все запросы
• ✅ API логирует все действия
• ✅ User Service логирует все операции

Будущие интеграции

Phase 1 (Текущее): audit_logger
    ↓
Phase 2: db_orm + auth + common
    ↓
Phase 3: cache, metrics, tracing libraries
    ↓
Phase 4: service discovery, load balancing

🎯 Дизайн принципы

1. Trait-based Architecture

   • Все библиотеки предоставляют trait'ы
   • Множество реализаций (in-memory, БД, внешние сервисы)

2. Composability

   • Библиотеки независимы
   • Можно комбинировать в разных комбинациях

3. Async-first

   • Все операции асинхронные
   • Оптимизировано для высокого throughput

4. Type Safety

   • Использование Rust типов для безопасности
   • Compile-time checks

5. Extensibility

   • Легко добавлять новые backends
   • Легко добавлять новые функции

💼 Структурирование кода

Правила для shared libraries

1. ✅ Каждая библиотека в отдельной папке shared_libs/
2. ✅ Иметь public API через lib.rs
3. ✅ Документировать через README.md в папке библиотеки
4. ✅ Использовать trait'ы для абстракции
5. ✅ Предоставлять mock/in-memory реализации
6. ✅ Писать unit тесты
7. ✅ Избегать зависимостей от конкретных сервисов

Структура файлов

audit_logger/
├── README.md               # Документация библиотеки
├── Cargo.toml
└── src/
    ├── lib.rs              # Public API
    ├── models.rs           # Data structures
    ├── store.rs            # Storage abstraction
    ├── logger.rs           # Main implementation
    └── backends/           (Optional)
        ├── memory.rs
        ├── postgres.rs
        └── elasticsearch.rs

🔄 Workflow добавления новой библиотеки

1. Создать папку в shared_libs/
2. Создать Cargo.toml с версией из workspace
3. Написать trait'ы для абстракции
4. Реализовать in-memory backend для разработки
5. Добавить в shared_libs/Cargo.toml members
6. Интегрировать в сервисы
7. Документировать в README.md

📦 Добавление библиотеки в сервис

1. Обновить Cargo.toml сервиса

[dependencies]
audit_logger = { path = "../shared_libs/audit_logger" }
db_orm = { path = "../shared_libs/db_orm" }

2. Использовать в коде

use audit_logger::AuditLogger;
use db_orm::Repository;

let logger = AuditLogger::new(...);
let repo = PostgresRepository::new(...);

🧪 Тестирование

# Тестировать конкретную библиотеку
cargo test --package audit_logger

# Тестировать все библиотеки
cargo test --workspace

# Coverage
cargo tarpaulin --package audit_logger

📈 Масштабирование

Для разработки

• Используйте in-memory backends
• Быстро, без внешних зависимостей
• Идеально для unit tests

Для тестирования

• Используйте Docker containers
• PostgreSQL, Redis в containers
• Integration tests

Для production

• Используйте production-grade backends
• PostgreSQL для данных
• Redis для cache
• Elasticsearch для поиска

🚀 Best Practices

1. ✅ Начните с in-memory реализации
2. ✅ Потом добавьте production backends
3. ✅ Всегда используйте trait'ы
4. ✅ Документируйте public API
5. ✅ Пишите тесты для каждой библиотеки
6. ✅ Версионируйте через workspace
7. ✅ Избегайте circular dependencies

📚 Документация

Каждая библиотека должна иметь:

• README.md с примерами
• Doc comments на всех public типах
• Examples в документации
• Unit tests как примеры использования

🔗 Связи

audit_logger
    ├─ используется в api_gateway
    ├─ используется в api
    └─ используется в microservices

db_orm (планируется)
    ├─ может использоваться с auth
    └─ может использовать audit_logger

auth (планируется)
    ├─ middleware в api_gateway
    └─ проверка в microservices

---

Статус: ✅ Foundation готов, готовы Phase 2 библиотеки