Setup & Seguridad

---

Dependencias

Todas las dependencias están incluidas en requirements.txt del proyecto. El pipeline requiere:

Paquetes Python Obligatorios

pip install -r requirements.txt

Paquete	Versión	Uso
requests	≥2.28.0	HTTP GET/POST/PATCH con sesiones y timeouts
beautifulsoup4	≥4.11.0	Parseo HTML de formularios y scraping de IDs

Dependencias del Sistema

Componente	Requerido Para
Python 3.8+	Ejecución de scripts
curl / wget	Descargas manuales de imágenes (opcional)

Verificación Pre-Vuelo

python3 -c "import requests, bs4; print('✅ Dependencias OK')"

---

Configuración Inicial

1. Extraer Cookie de Sesión

La autenticación se realiza mediante cookie de sesión. Es la forma más directa de acceder a endpoints protegidos sin exponer contraseñas.

Obtener Cookie (Firefox / Chrome)

1. Abre el navegador y inicia sesión en tu tracker UNIT3D
2. Abre DevTools (F12 en la mayoría de navegadores)
3. Ve a Application (Chrome) o Storage (Firefox)
4. Selecciona Cookies → https://tu-tracker.org
5. Busca una cookie con nombre similar a:
6. session (genérico)
7. milnueve_session (específico de Milnueve)
8. tracker_name_session
9. Copia el valor completo (largo string)

Guardar en .env

# .env
UNIT3D_COOKIE_NAME=milnueve_session
UNIT3D_COOKIE_VALUE=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...muy_largo...

2. Configurar TMP_ROOT

Esta es la carpeta donde RawLoadrr almacena los metadatos (meta.json) de tus subidas.

# .env
TMPDIR_PATH=/path/to/RawLoadrr/tmp

Estructura esperada:

TMP_ROOT/
├── torrents_subido_1/
│   ├── meta.json
│   ├── [MILNU]DESCRIPTION.txt
│   └── (archivos de media)
├── torrents_subido_2/
│   ├── meta.json
│   ├── [MILNU]DESCRIPTION.txt
│   └── (archivos de media)
└── ...

3. APIs para Resurrección de Imágenes (Opcional)

El script 04_image_resurrector.py sube imágenes a hosting externo. Requiere API keys.

ImgBB (Recomendado)

1. Regístrate en imgbb.com
2. Ve a API → API Documentation
3. Genera un nuevo API key
4. Configura:

   IMGBB_API=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
   

PtScreens (Fallback)

Opcional, para fallback si ImgBB no funciona:

PTSCREENS_API=optional_key_here

SIN APIs Configuradas

Si no configuras APIs, el script 04_image_resurrector.py registra imágenes como "pendientes" pero no falla. Las descripciones se limpian igual, solo sin reupload.

---

⚠️ Consideraciones Críticas de Seguridad

1. Cookies de Sesión = Contraseñas

TRATA LA COOKIE COMO UNA CONTRASEÑA

• Nunca la hagas commit en Git
• Nunca la compartas en Slack/Discord/email
• Nunca la expongas en logs o screenshots
• Usa .env o variables de entorno cifradas en CI/CD
• Rota periódicamente (cada 30 días en producción)

Revocación de Sesión

Si accidentalmente expones tu cookie:

1. Inicia sesión en tu cuenta del tracker
2. Ve a Settings → Sessions o Logout All
3. Cierra todas las sesiones
4. Genera una cookie nueva

2. Sistema de Jitter Anti-Bot

NO DESACTIVES EL JITTER

El script incluye retrasos aleatorios (random.uniform(4.5, 7.5) segundos) entre peticiones para: - Simular comportamiento humano - Evitar ser bloqueado por Cloudflare / WAF - Respetar límites de rate limiting (429)

Si los desactivas: - ⚠️ Riesgo de IP ban temporal (24-48h) - ⚠️ Possibilidad de ban permanente si se detecta automatización agresiva - ⚠️ Tracker puede implementar CAPTCHA para tu cuenta

Duración estimada: - 1000 torrents × 5.5s media Jitter ≈ 1.5 horas - Esto es aceptable y sostenible

Acelerar Responsablemente

Si necesitas ir más rápido: - Consulta al admin del tracker sobre limits - Usa rangos más pequeños (ID_START=1 ID_END=100) - Ejecuta en horarios de baja carga (madrugada)

3. Manejo de Errores Críticos

Rate Limiting (HTTP 429)

if post_res.status_code == 429:
    # Script pausa 30 segundos e intenta hasta 3 veces
    time.sleep(30)
    reintentos += 1

Acción recomendada: Deja que el script maneje esto automáticamente. Si se repite, el script se detiene para evitar ban.

Cloudflare (HTTP 502, 503, 504)

El tracker está detrás de Cloudflare. Si recibo estos códigos:

if res.status_code in [502, 503, 504]:
    return False, "CLOUDFLARE_ERROR"
    # Pausa 30 segundos, intenta 3 veces

Acción recomendada: Esperar. Cloudflare suele recuperarse en 5-10 minutos. El script reintenta automáticamente.

Cookie Expirada (HTTP 422 persistente)

Error 422: {
  "errors": {
    "name": ["Campo requerido"],
    "imdb": ["Formato inválido"]
  }
}

Si ves 422 repentinamente después de funcionar bien, la cookie probó expiró.

Acción inmediata: 1. Renuevalatokenfresco desde las DevTools del navegador 2. Actualiza .env o config.py 3. Reinicia el script (detectará el nuevo checkpoint)

4. Resiliencia mediante Checkpoints

El pipeline genera archivos de control que permiten reanudar sin pérdida de progreso:

Archivo	Script	Contenido
ids.txt	01_scraper.py	IDs únicos extraídos
mapeo_maestro.json	02_indexer.py	Mapping
completados.txt	03_mass_updater.py	IDs ya editados (una línea por ID)
completados_resurrector.txt	04_image_resurrector.py	IDs con imágenes reparadas

Ejemplo: Resumen Interrupción

# Ejecuta fase 03, falla en ID 350 (error de red)
python3 03_mass_updater.py
# ℹ️ Total: 523 | ✅ Completados: 349 | ⏳ Pendientes: 174

# [Tu ISP falla 30 minutos]

# Reinicia, automáticamente salta IDs 1-349
python3 03_mass_updater.py
# ℹ️ Total: 523 | ✅ Completados: 349 | ⏳ Pendientes: 174
# [Continúa desde ID 350]

NO hay que hacer nada. Los scripts son idempotentes: procesar el mismo ID dos veces es seguro (segundo intento es NOOP si ya fue completado).

Backup de Checkpoints

Antes de experiments o rollbacks:

cp completados.txt completados.txt.backup_$(date +%s)

---

🛡️ Buenas Prácticas Operacionales

Pre-Ejecución

• [ ] ✅ Cookie vigente (test: GET /users/{USERNAME}/uploads, espero status 200)
• [ ] ✅ TMP_ROOT accesible y contiene meta.json
• [ ] ✅ Conexión a internet estable
• [ ] ✅ Espacio disco suficiente (imágenes temporales pueden requerir 1-2 GB)
• [ ] ✅ No ejecutar múltiples instancias simultáneamente en el mismo directorio

Durante Ejecución

• ⏱️ Monitorea la primera hora (cambios inesperados → para agresivo)
• 📊 Revisa completados.txt cada 100 torrents
• 🚨 Si ves 429 / 502 repetido → detén, espera 1 hora
• 📸 Documenta rate limits observados para ajustar Jitter si es necesario

Post-Ejecución

• [ ] Verificar completados.txt contiene el total esperado
• [ ] Inspeccionar 5-10 torrents aleatorios en el tracker
• [ ] Validar que imágenes nuevas (si aplica) se muestran correctamente
• [ ] Guardar logs en directorio logs/archive/

Rotación de Credenciales

Cada 30 días en producción:

# 1. Extrae cookie fresca desde navegador
# 2. Actualiza .env
export UNIT3D_COOKIE_VALUE="nuevo_valor"

# 3. Test rápido
python3 -c "
import requests
from singularity_config import BASE_URL, COOKIE_VALUE
s = requests.Session()
s.cookies.set('milnueve_session', COOKIE_VALUE)
r = s.get(f'{BASE_URL}/users/TuUsuario/uploads', timeout=5)
print(f'Status: {r.status_code}')
print('✅ Cookie válida' if r.status_code == 200 else '❌ Cookie inválida')
"

---

📋 Checklist de Despliegue

Inicial (Una sola vez)

# 1. Clonar / acceder al proyecto
cd /path/to/RaW_Suite

# 2. Crear .env
cp .env.example .env
# Editar .env con credenciales reales

# 3. Instalar dependencias (si no están)
pip install -r requirements.txt

# 4. Test de conectividad
python3 -c "
import requests
from singularity_config import BASE_URL, COOKIE_VALUE, USERNAME
s = requests.Session()
s.cookies.set('milnueve_session', COOKIE_VALUE)
r = s.get(f'{BASE_URL}/users/{USERNAME}/uploads', timeout=5)
assert r.status_code == 200, f'Error {r.status_code}'
print('✅ Listo para ejecutar pipeline')
"

# 5. Backup de estado inicial
mkdir backups/
tar czf backups/initial_state.tar.gz ./

Por Ejecución

# 1. Actualizar archivos de control si es reanudación
# (Los scripts lo hacen automáticamente)

# 2. Ejecutar pipeline (Orquestador o Manual)
python3 singularity.py
# O manualmente:
# python3 extras/MASS-EDITION-UNIT3D/01_scraper.py
# ...

# 3. Monitorear logs
tail -f logs/unit3d_mass_edition.log

# 4. Validar completados.txt
wc -l completados.txt  # ¿Número esperado?

# 5. Test de muestra
# Abre tracker, revisa 5 torrents aleatorios

# 6. Archivar resultado
mkdir logs/archive/run_$(date +%Y%m%d_%H%M%S)/
mv completados.txt *.log logs/archive/run_*/

---

Troubleshooting

Síntoma	Causa Probable	Solución
Connection refused	Tracker offline	Comprueba BASE_URL, espera a recuperación
403 Forbidden	Cookie expirada	Extrae nueva cookie, actualiza .env
429 Too Many Requests	Rate limit alcanzado	Esperá 30+ minutos, script reintenta automáticamente
422 Unprocessable Entity	Validación tracker fallida	Revisa meta.json, puede faltar campo crítico
KeyError: 'name'	Cookie malformada o credenciales incorrectas	Verifica COOKIE_VALUE, USERNAME en .env
FileNotFoundError: mapeo_maestro.json	Fase 02 no ejecutada	Ejecuta 02_indexer.py antes de 03_mass_updater.py

Debug Avanzado

Para habilitación de logging detallado:

import logging
logging.basicConfig(level=logging.DEBUG)
# Los scripts registrarán requests/responses completas