From 3d5b8b36d04c195cfd732df4aab8e02596a83cc5 Mon Sep 17 00:00:00 2001 From: Marikondo Date: Sun, 22 Feb 2026 10:27:54 -0300 Subject: [PATCH] [margarita] docs: Add FODA and ROADMAP analysis --- docs/FODA.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/ROADMAP.md | 112 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 233 insertions(+) create mode 100644 docs/FODA.md create mode 100644 docs/ROADMAP.md diff --git a/docs/FODA.md b/docs/FODA.md new file mode 100644 index 0000000..38bb50e --- /dev/null +++ b/docs/FODA.md @@ -0,0 +1,121 @@ +# Análisis FODA - tor-session-manager + +**Fecha:** 2026-02-22 +**Analista:** Margarita (AI) + +--- + +## 🟢 Fortalezas + +### Código +- **API limpia y Pythonic:** Context managers, type hints, docstrings completos +- **Principio de responsabilidad única:** Client separado de excepciones +- **Exceptions bien diseñadas:** Jerarquía clara con base class `TorSessionError` +- **Logging integrado:** Debug mode disponible para troubleshooting + +### Arquitectura +- **Dependencia mínima:** Solo `stem` y `requests`, sin bloat +- **Configurable:** Puertos, passwords, delays son parámetros +- **Helpers útiles:** `rotate_and_get_ip()` one-liner, propiedad `proxies` +- **Context manager flexible:** `rotated_session()` para circuitos frescos + +### Documentación +- **README excelente:** Ejemplos, troubleshooting, disclaimers legales +- **Docstrings completos:** Todas las clases y métodos documentados +- **Instalación clara:** Instrucciones para macOS, Linux, Windows + +### Testing +- **CI configurado:** GitHub Actions con pytest +- **Tests existentes:** Base para agregar más coverage + +--- + +## 🔴 Debilidades + +### Distribución +- **No publicado en PyPI:** README dice `pip install tor-session-manager` pero no existe +- **Sin setup.py/pyproject.toml:** Falta configuración de empaquetado + +### Funcionalidad +- **Solo IPv4:** No valida ni soporta IPv6 +- **Un solo método de IP check:** Dependencia de api.ipify.org +- **Sin connection pooling:** Crea nueva sesión en cada llamada sin context manager + +### Testing +- **Coverage desconocido:** No hay badge ni reporte +- **Sin tests de integración:** Los tests requieren Tor corriendo + +### Seguridad +- **Cookie auth asumida:** Si falla, el error no es claro +- **Sin validación de IP:** Confía ciegamente en respuesta de ipify + +--- + +## 🟡 Oportunidades + +### Publicación +- **PyPI release:** Publicar en PyPI para cumplir la promesa del README +- **GitHub Releases:** Tags versionados con changelogs +- **Badges:** Coverage, PyPI version, downloads + +### Mejoras técnicas +- **Async support:** `aiohttp` + `asyncio` para scraping concurrente +- **Connection pool:** Reutilizar conexiones entre requests +- **Multiple IP checkers:** Fallback si ipify falla (ifconfig.me, httpbin.org) +- **IPv6 support:** Validar y soportar ambos protocolos + +### Features +- **Circuit info:** Exponer información del circuito actual (país de salida, etc.) +- **Wait for new IP:** Rotar hasta obtener IP diferente a la actual +- **Proxy chain:** Soporte para Tor → otro proxy + +### Integraciones +- **Plugin para pytest:** Fixture que provee cliente Tor +- **Scrapy middleware:** Integración nativa con Scrapy +- **CLI tool:** Comando `tor-rotate` para uso en shell scripts + +--- + +## 🔵 Amenazas + +### Técnicas +- **Rate limits de Tor:** 10 rotaciones/min puede no ser suficiente +- **Cambios en stem:** Dependencia de librería de terceros +- **ipify downtime:** Single point of failure para get_ip() + +### Legales +- **Mal uso:** La herramienta puede usarse para actividades no éticas +- **Responsabilidad:** README tiene disclaimer pero podría no ser suficiente + +### Competencia +- **Alternativas existentes:** `torpy`, `requests-tor`, etc. +- **VPN services:** Para muchos casos, VPN es más simple que Tor + +### Adopción +- **Nicho pequeño:** El público objetivo (scraping ético + Tor) es limitado +- **Sin publicar:** Nadie puede instalarlo sin clonar el repo + +--- + +## 📊 Matriz de Prioridades + +| Acción | Impacto | Esfuerzo | Prioridad | +|--------|---------|----------|-----------| +| Publicar en PyPI | Alto | Bajo | 🔴 Alta | +| Multiple IP checkers | Medio | Bajo | 🔴 Alta | +| Agregar más tests | Medio | Medio | 🟡 Media | +| Async support | Alto | Alto | 🟡 Media | +| CLI tool | Bajo | Medio | 🟢 Baja | + +--- + +## 🎯 Recomendación Principal + +**Prioridad #1:** Publicar en PyPI. El README promete `pip install tor-session-manager` que actualmente no funciona. Esto es confuso para usuarios y daña credibilidad. + +**Pasos:** +1. Crear `pyproject.toml` con metadata +2. Configurar GitHub Actions para publish automático +3. Primer release como v0.1.0 + +**Quick win:** Agregar fallback IP checkers para mayor robustez. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..81c73e7 --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,112 @@ +# Roadmap - tor-session-manager + +**Última actualización:** 2026-02-22 + +--- + +## 🎯 Visión + +Librería de referencia en Python para gestión de sesiones Tor, publicada en PyPI con excelente documentación y soporte para casos de uso modernos (async, scraping frameworks). + +--- + +## Fase 1: Release inicial (Inmediato) + +### 1.1 Empaquetado +- [ ] **Crear pyproject.toml** con metadata completa +- [ ] **Configurar GitHub Actions** para publish a PyPI +- [ ] **Primer release v0.1.0** en PyPI y GitHub Releases +- [ ] **Actualizar README** con badge de PyPI + +### 1.2 Robustez +- [ ] **Multiple IP checkers**: Fallback a ifconfig.me, httpbin.org/ip +- [ ] **Timeout configurable** para get_ip() +- [ ] **Retry en get_ip()** si primer intento falla + +### 1.3 Testing +- [ ] **Aumentar coverage** a 80%+ +- [ ] **Badge de coverage** en README +- [ ] **Mock de Tor** para tests sin Tor real + +--- + +## Fase 2: Features avanzados (Q2 2026) + +### 2.1 Async support +- [ ] **TorClientAsync** con aiohttp +- [ ] **Async context manager** +- [ ] **Ejemplos de uso** con asyncio + +### 2.2 Circuit info +- [ ] **get_exit_country()**: País del nodo de salida +- [ ] **get_circuit_info()**: Detalles del circuito actual +- [ ] **wait_for_new_ip()**: Rotar hasta obtener IP diferente + +### 2.3 Integraciones +- [ ] **pytest-tor-session**: Fixture para tests +- [ ] **Scrapy middleware**: TorRotateMiddleware + +--- + +## Fase 3: Ecosistema (Q3-Q4 2026) + +### 3.1 CLI +- [ ] **Comando tor-session**: Uso desde terminal +- [ ] **tor-session rotate**: Rotar y mostrar nueva IP +- [ ] **tor-session check**: Verificar estado de Tor + +### 3.2 Documentación +- [ ] **Sphinx docs** en Read the Docs +- [ ] **Ejemplos completos** para casos de uso comunes +- [ ] **Blog post** sobre scraping ético + +### 3.3 Comunidad +- [ ] **Issue templates** para bugs y features +- [ ] **Contributing guide** +- [ ] **Code of conduct** + +--- + +## 📋 Backlog técnico + +| Tarea | Prioridad | Estimación | +|-------|-----------|------------| +| pyproject.toml + PyPI | Alta | 1h | +| Multiple IP checkers | Alta | 30min | +| Badge de coverage | Media | 30min | +| Async client | Media | 4h | +| pytest plugin | Baja | 2h | +| CLI tool | Baja | 3h | + +--- + +## 🚫 Out of scope (por ahora) + +- GUI/Desktop app +- Proxy chain (Tor → otro proxy) +- Hidden services (.onion) +- Mobile support + +--- + +## 📝 Notas de decisiones + +### ¿Por qué stem? +- Librería oficial de Tor Project +- Mantenida activamente +- API estable y bien documentada + +### ¿Por qué no torpy? +- torpy incluye su propio Tor, más pesado +- Queremos usar Tor del sistema para control +- stem es más liviana y flexible + +### ¿Por qué socks5h? +- La "h" significa que DNS se resuelve por Tor +- Sin ella, DNS leakea la IP real +- Es el modo correcto para anonimato + +### Versioning +- Seguimos SemVer (MAJOR.MINOR.PATCH) +- Breaking changes incrementan MAJOR +- v0.x.x significa API no estable aún