r2-transfer-service-playbook

name	r2-transfer-service-playbook
description	Manage changes to the R2 transfer pipeline (Python service, Cloudflare Workers, PHP logger) with mandatory validations, allowlists, and regression checks.

R2 Transfer Service Playbook

Portée

Utilise ce skill lorsqu'une tâche touche :

• services/r2_transfer_service.py
• email_processing/orchestrator.py (section delivery_links / r2_url)
• deployment/cloudflare-worker/*
• deployment/public_html/config_api.php, deployment/public_html/test-direct.php, pages de test R2

Pré-requis

• ENV obligatoires : R2_BASE_URL, R2_FETCH_TOKEN, ALLOWED_R2_DOMAINS.
• Virtualenv /mnt/venv_ext4/venv_render_signal_server pour les scripts/tests.
• Accès au déploiement Cloudflare Workers (wrangler).

Workflow

1. Analyse des dépendances
   • Confirmer la présence des ENV ci-dessus.
   • Vérifier les allowlists (Dropbox/FromSmash/SwissTransfer) avant toute nouvelle source.
2. Mises à jour Python
   • Toujours valider les domaines via is_allowed_domain.
   • Injecter le header X-R2-FETCH-TOKEN pour chaque requête Worker.
   • Conserver les logs sans PII et retour fallback raw_url en cas d'échec.
3. Workers Cloudflare
   • Garder le mode fetch avec timeout 120s pour Dropbox /scl/fo/.
   • Mettre à jour httpMetadata.contentDisposition pour préserver le nom de fichier.
   • Exécuter wrangler deploy --dry-run (documenter la sortie).
4. PHP Logger / Diagnostics
   • Assurer que config_api.php continue d'écrire les paires source_url/r2_url.
   • Tester deployment/public_html/test-direct.php pour valider le flux complet.
5. Tests & validation
   • Lancer le helper ./.cline/skills/r2-transfer-service-playbook/test_r2_worker.sh.
   • Compléter si besoin avec des tests ciblés sur les nouvelles sources.
6. Documentation & Memory Bank
   • Mettre à jour docs/processing/file-offload.md ou section dédiée R2.
   • Ajouter une entrée dans la Memory Bank si de nouvelles sources sont supportées.

Ressources

• test_r2_worker.sh : active le venv, exécute les tests R2 et vérifie la page de test PHP.

Conseils

• En cas de nouvelle plateforme de fichiers, créer un helper dédié (normalisation URL, validation).
• Limiter les retries côté Worker, gérer les erreurs HTTP explicitement.
• Garder les scripts de cleanup alignés (expiration 24h par défaut).