diff --git a/DEPENDENCY_UPGRADE_PLAN.md b/DEPENDENCY_UPGRADE_PLAN.md index 2bef1ff..8abf0d9 100644 --- a/DEPENDENCY_UPGRADE_PLAN.md +++ b/DEPENDENCY_UPGRADE_PLAN.md @@ -1,85 +1,167 @@ -# WebVirtCloud - Bağımlılık ve Kütüphane Güncelleme Planı +# WebVirtCloud - Dependency Upgrade & Modernization Plan -Bu doküman, WebVirtCloud projesinde yer alan eski, desteği kesilmiş veya yeni Python/Django sürümleriyle uyumsuzluk riski taşıyan kütüphanelerin tespitini ve adım adım güncelleme yol haritasını içermektedir. +This document outlines the dependency audit, completed technical debt resolution, and future modernization roadmap for the WebVirtCloud project. It covers Python 3.12/3.13 compatibility, framework migrations, frontend libraries, and container base images. --- -## 1. Tespit Edilen Kütüphaneler ve Durum Analizi +## 1. Executive Summary & Compatibility Status -### 1.1. Kritik ve Acil Müdahale Gerektirenler (Python 3.12+ Uyumsuzlukları) +WebVirtCloud has historically relied on libraries established during the Python 3.8 - 3.10 era. Recent efforts have systematically eliminated obsolete dependencies and removed breaking Python 3.12 incompatibilities. -| Kütüphane / Dosya | Mevcut Durum | Risk Seviyesi | Tespit ve Sorun | +### Current Compatibility Baseline + +| Component | Target Version | Status | +|---|---|---| +| **Python** | 3.10, 3.11, 3.12, 3.13 | ✅ Verified on 3.10–3.12; 3.13 ready (`crypt-r` conditional) | +| **Operating Systems** | Ubuntu 22.04/24.04, Debian 12, Rocky/RHEL 9/10 | ✅ Validated across modern enterprise Linux distros | +| **Django** | 4.2.23 (LTS) | ✅ Active (Supported through April 2026) | +| **OpenAPI / Swagger** | OpenAPI 3.0 (`drf-spectacular`) | ✅ Replaced legacy Swagger 2.0 (`drf-yasg`) | +| **Container Base** | `phusion/baseimage:noble-1.0.2` (Ubuntu 24.04 LTS) | ✅ Upgraded from Jammy (22.04) | + +--- + +## 2. Completed Milestones & Resolved Technical Debt + +The following table summarizes items that have been fully resolved in the codebase: + +| Component / File | Previous State | Current State | Impact & Resolution | |---|---|---|---| -| **`vrtManager/rwlock.py`** | `currentThread()` kullanımı | 🔴 **Kritik (Bozucu)** | Python 3.10'da kullanımdan kaldırılmış (deprecated), **Python 3.12'de tamamen silinmiştir**. Python 3.12 üzerinde `ImportError: cannot import name 'currentThread' from 'threading'` hatası verir. `threading.current_thread()` ile değiştirilmelidir. | -| **`rwlock==0.0.7`** (`conf/requirements.txt`) | 2014 sürümü (Terk edilmiş) | 🟡 **Gereksiz Bağımlılık** | Projede kod zaten `vrtManager/rwlock.py` üzerinden yerel (vendored) çalışmaktadır. `requirements.txt` içerisindeki bu harici paket gereksizdir ve temizlenebilir. | -| **`console/novncd` & `socketiod` (`optparse`)** | `optparse` kullanımı | 🟠 **Orta (Kullanımdan Kaldırıldı)** | `optparse` Python 3.2'den beri deprecated olup yerini standart `argparse` kütüphanesine bırakmıştır. Modern Python standartlarına göre refactor edilmelidir. | -| **`eventlet==0.40.1`** | `socketiod` içinde kullanılır | 🟠 **Yüksek Risk** | Eventlet, Python 3.12+ C-API ve greenlet değişiklikleriyle uyumluluk sorunları yaşamaktadır. Gelecekte asyncio/ASGI mimarisine geçiş planlanmalıdır. | +| **`vrtManager/rwlock.py`** | Used removed `threading.currentThread()` | Updated to `threading.current_thread()` | **Critical Bugfix**: Resolved fatal `ImportError` on Python 3.12+. | +| **`rwlock==0.0.7`** | Listed in `conf/requirements.txt` | **Removed** | **Cleanup**: Package was abandoned in 2014; codebase uses local `vrtManager/rwlock.py`. | +| **`vrtManager/IPy.py`** | 1,650 lines of vendored IPy 1.01 (2011) | Replaced with stdlib `ipaddress` | **Maintenance**: Removed unmaintained legacy code, improved IP parsing performance, and added 15 regression unit tests. | +| **`console/novncd` & `socketiod`** | Used deprecated `optparse` | Migrated to standard `argparse` | **Modernization**: Full CLI argument parsing compliance with modern Python standard library. | +| **API Documentation** | `drf-yasg==1.21.10` (Swagger 2.0) | Migrated to `drf-spectacular[sidecar]==0.28.0` | **Modernization**: Upgraded to OpenAPI 3.0 with offline/air-gapped Swagger UI and Redoc sidecar assets. | +| **`Dockerfile` Base Image** | `phusion/baseimage:jammy-1.0.1` (Ubuntu 22.04) | `phusion/baseimage:noble-1.0.2` (Ubuntu 24.04 LTS) | **Infrastructure**: Brings modern system libraries (`libvirt 10.0+`, OpenSSL 3.0+, GCC 13+). | +| **Bootstrap** | Bootstrap 5.2.2 | Upgraded to Bootstrap 5.3.3 | **Frontend**: CSS variables support, form accessibility improvements, and dark mode foundations. | +| **Python 3.13 Crypt Support** | Stdlib `crypt` module removed in 3.13 | `crypt-r>=3.13.0; python_version >= "3.13"` | **Future-proofing**: Added conditional fallback dependency for root password hashing in `vrtManager/create.py`. | +| **LDAP Dependency** | Unconditional `python-ldap` import | Optional / graceful degradation | **Cross-Platform**: WebVirtCloud boots cleanly on minimal hosts without requiring C-header LDAP compilation. | --- -### 1.2. Django & API Ekosistemi +## 3. Pending & Future Roadmap -| Kütüphane | Mevcut Sürüm | Hedef Sürüm | Açıklama & Strateji | +The following tasks represent future upgrade phases prioritized by maintenance schedules and architectural value. + +### 3.1. Django 5.x LTS Roadmap (Django 4.2 LTS -> Django 5.2 LTS) + +- **Priority**: High (Before April 2026) +- **Current State**: Django `4.2.23` LTS (supported until April 2026). +- **Target State**: Django `5.2` LTS (scheduled for release in April 2025 with support through April 2028). + +#### Action Items: +1. **Retire `django-login-required-middleware`**: + - The third-party package `django-login-required-middleware==0.9.0` has not been updated since 2017. + - Django 5.1 introduced native `django.contrib.auth.middleware.LoginRequiredMiddleware`. + - Once upgraded to Django 5.1+, remove the third-party package from `INSTALLED_APPS`, `MIDDLEWARE`, and `requirements.txt`. +2. **Deprecation Warnings Audit**: + - Run test suite with `-Wd` flag to identify deprecated features prior to stepping to 5.x. + - Verify compatibility of all database backends (SQLite, MySQL/MariaDB, PostgreSQL). +3. **Form Rendering and Async ORM**: + - Leverage Django 5 form field templates and expanded async ORM capabilities where appropriate. + +--- + +### 3.2. Asynchronous Console Architecture: `eventlet` Evaluation + +- **Priority**: Medium / Long-term +- **Current State**: `socketiod` utilizes `eventlet==0.40.1` for WebSocket concurrency. +- **Risk Analysis**: + - `eventlet` is in minimal maintenance and relies on monkey-patching CPython primitives. + - Python 3.12 and 3.13 changes to internal frames and `greenlet` have historically produced runtime instability with monkey-patching frameworks. +- **Proposed Architecture**: + - Evaluate migrating `socketiod` to modern ASGI or asyncio-native WebSocket architectures (e.g., standard Python `websockets`, `aiohttp`, or Django Channels). + - Alternatively, evaluate encapsulating console proxying within a lightweight dedicated gateway (e.g., Go/Rust WebSocket proxy or native Nginx WebSocket passthrough). + +--- + +### 3.3. noVNC Modernization (1.5.0+) + +- **Priority**: Medium +- **Current State**: Vendored noVNC assets in `static/js/novnc/` date from the 2020 release. +- **Target State**: noVNC `1.5.0` or latest stable release. +- **Benefits**: + - Robust auto-reconnect logic on transient network loss. + - Enhanced mobile and touch-screen trackpad / gesture emulation. + - Performance improvements in canvas rendering via modern WebGL/Canvas APIs. + - Improved clipboard and audio streaming support. + +--- + +### 3.4. Frontend Maintenance: jQuery Update + +- **Priority**: Low / Maintenance +- **Current State**: `jQuery 3.6.1` (bundled in `static/js/jquery.min.js`). +- **Target State**: `jQuery 3.7.1`. +- **Benefits**: + - Bug fixes in selector parsing and event delegation. + - Elimination of known CVEs in legacy utility methods. + +--- + +## 4. Phase-by-Phase Execution Timeline + +```mermaid +flowchart TD + subgraph Completed ["Phase 1: Completed Milestones"] + C1["Python 3.12 thread fix (rwlock.py)"] + C2["Eradicate IPy.py -> stdlib ipaddress"] + C3["CLI optparse -> argparse"] + C4["drf-yasg -> drf-spectacular"] + C5["Docker Base -> Ubuntu 24.04 (Noble)"] + C6["Bootstrap -> 5.3.3"] + C7["Python 3.13 crypt-r conditional"] + end + + subgraph Phase2 ["Phase 2: Frontend & Client Refresh"] + P2A["Update jQuery 3.6.1 -> 3.7.1"] + P2B["Modernize noVNC client to 1.5.0+"] + end + + subgraph Phase3 ["Phase 3: Django 5.x LTS Migration"] + P3A["Upgrade Django 4.2 LTS to 5.2 LTS"] + P3B["Replace django-login-required-middleware with native Django 5.1 middleware"] + P3C["Audit deprecations and run full test matrix"] + end + + subgraph Phase4 ["Phase 4: Async WebSocket Gateway"] + P4A["Profile socketiod under Python 3.12/3.13"] + P4B["Design ASGI / asyncio-native replacement for eventlet"] + end + + Completed --> Phase2 + Phase2 --> Phase3 + Phase3 --> Phase4 +``` + +--- + +## 5. Support & Compatibility Matrix + +| Distribution / Environment | Python Version | Libvirt Python | Status | |---|---|---|---| -| **`Django`** | `4.2.23` (LTS) | `5.1.x` / `5.2` (LTS) | Django 4.2 LTS desteği Nisan 2026'da sona ermektedir. Django 5.x LTS'e yükseltme yapılarak performans kazanımları (asenkron ORM geliştirmeleri, yeni form alanları) elde edilmelidir. | -| **`django-login-required-middleware`** | `0.9.0` (2017) | **Kaldırılacak** (Native) | Paket 2017'den beri güncellenmemiştir. **Django 5.1 ile birlikte Django artık yerleşik `django.contrib.auth.middleware.LoginRequiredMiddleware` sunmaktadır.** Harici paket tamamen devreden çıkarılabilir. | -| **`drf-yasg`** | `1.21.10` | `drf-spectacular` ✅ | Terk edilmiş Swagger 2.0 kütüphanesi yerine modern OpenAPI 3.0 standardı olan **`drf-spectacular`** (sidecar ile offline/air-gapped destekli) kuruldu. | -| **`IPy.py`** (`vrtManager/IPy.py`) | Vendored 1.01 (2011) | Python Standard `ipaddress` ✅ | 1650+ satırlık eski harici kod silindi, standart `ipaddress` modülüne geçildi ve 15 adet unit test eklendi. | +| **Ubuntu 22.04 LTS (Jammy)** | 3.10 | 8.0.0+ | Fully Supported | +| **Ubuntu 24.04 LTS (Noble)** | 3.12 | 10.0.0+ | Fully Supported (Recommended Docker Base) | +| **Debian 12 (Bookworm)** | 3.11 | 9.0.0+ | Fully Supported | +| **Rocky Linux / RHEL 9** | 3.9 / 3.11 | 9.0.0+ | Fully Supported | +| **Rocky Linux / RHEL 10** | 3.12 | 11.0.0+ | Fully Supported | +| **Docker (Production Image)** | 3.12 (Noble base) | Bundled | Primary Supported Container Target | --- -### 1.3. Ön Yüz (Frontend) ve VNC İstemcisi +## 6. Verification and CI Guidelines -| Kütüphane | Mevcut Sürüm | Güncel Sürüm | Yenilikler & Faydalar | -|---|---|---|---| -| **`jQuery`** | `3.6.1` (2022) | `3.7.1` | Güvenlik yamaları, seçici (selector) optimizasyonları ve hata düzeltmeleri. | -| **`Bootstrap`** | `5.2.2` (2022) | `5.3.3` | Yerel Karanlık Mod (Dark Mode) desteği, CSS değişkenleri mimarisi, erişilebilirlik ve form iyileştirmeleri. | -| **`noVNC`** (`static/js/novnc`) | 2020 Sürümü | `1.5.0` | Çok daha kararlı WebSocket yeniden bağlanma (auto-reconnect), dokunmatik ekran desteği, güvenlik düzeltmeleri ve modern ES modül yapısı. | +Whenever dependencies are upgraded, the following verification pipeline must pass: ---- - -### 1.4. Altyapı ve Konteyner - -| Bileşen | Mevcut Durum | Önerilen Durum | Açıklama | -|---|---|---|---| -| **`Dockerfile` Base Image** | `phusion/baseimage:jammy-1.0.1` (Ubuntu 22.04) | `phusion/baseimage:noble-1.0.0` (Ubuntu 24.04 LTS) | Ubuntu 24.04 LTS tabanına geçilerek daha yeni sistem kütüphaneleri (`libvirt`, `openssl`, `gcc`) temin edilebilir. | - ---- - -## 2. Aşamalı Güncelleme Yol Haritası (Migration Roadmap) - -### Aşama 1: Hızlı Kazanımlar ve Python 3.12+ Uyumluluğu (Hemen Yapılabilir) -1. **`vrtManager/rwlock.py` Düzeltmesi**: - - `currentThread()` çağrılarını `current_thread()` ile değiştirerek Python 3.12'deki kritik çökme riskini ortadan kaldırmak. -2. **`requirements.txt` Temizliği**: - - Kullanılmayan `rwlock==0.0.7` paketini `conf/requirements.txt` dosyasından silmek. -3. **Frontend Kütüphanelerinin Güncellenmesi**: - - `jQuery` 3.6.1 -> 3.7.1 - - `Bootstrap` 5.2.2 -> 5.3.3 - ---- - -### Aşama 2: API ve Dokümantasyon Modernizasyonu (Orta Vadeli) -1. **Swagger / OpenAPI Göçü**: - - `drf-yasg` yerine `drf-spectacular` kurulumu. - - `webvirtcloud/urls.py` ve `urls-api.py` rotalarının OpenAPI 3.0 şemasına güncellenmesi. -2. **CLI Argümanları Refactor**: - - `console/novncd` ve `console/socketiod` içerisindeki `optparse` yerine standart `argparse` modülünün entegre edilmesi. - ---- - -### Aşama 3: Django 5.x LTS Geçişi (Büyük Sürüm Güncellemesi) -1. **LoginRequiredMiddleware Değişimi**: - - `django-login-required-middleware` paketinin kaldırılması. - - Django 5.1+'ın yerleşik `django.contrib.auth.middleware.LoginRequiredMiddleware` sınıfına geçilmesi. -2. **Django 4.2 -> 5.1/5.2 Yükseltmesi**: - - `conf/requirements.txt` içinde Django sürümünün artırılması. - - `python3 manage.py check` ve test suitinin (`pytest` / `python manage.py test`) koşturularak deprecation uyarılarının temizlenmesi. - ---- - -### Aşama 4: noVNC ve Ağ Modülleri Optimizasyonu -1. **noVNC 1.5.0 Entegrasyonu**: - - `static/js/novnc/` klasörünün noVNC 1.5.0 resmi sürümüyle yenilenmesi. -2. **`vrtManager/IPy.py` Refactor**: - - Harici IPy kütüphanesi yerine standart `ipaddress` kütüphanesine geçiş. +1. **Syntax & Unit Tests**: + ```bash + pytest + # or + python3 manage.py test + ``` +2. **Schema & Check Validations**: + ```bash + python3 manage.py check --deploy + python3 manage.py spectacular --file /tmp/schema.yml --validate + ``` +3. **Multi-Platform CI**: + - Ensure GitHub Actions workflow (`.github/workflows/linter.yml` and testing workflows) run on Python 3.10, 3.11, and 3.12.