Périmètre sûr : ce guide s'applique uniquement à vos propres applications et à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni la gestion de protections anti-bot que vous ne contrôlez pas.
Un edge worker Hono résout un CAPTCHA en déléguant le travail à un service externe : le worker envoie les paramètres du défi à l'API CaptchaAI, récupère un token, puis l'injecte dans la requête qui poursuit le parcours. Le worker lui-même ne résout rien localement ; il orchestre un appel HTTPS et attend la réponse. Cette distinction change tout côté architecture, car un edge worker n'est pas un serveur classique : le temps CPU est plafonné, le système de fichiers est absent et chaque milliseconde compte. Voici comment structurer l'intégration pour qu'elle tienne en production.
Ce qu'un edge worker Hono change
Hono s'exécute sur des runtimes edge — Cloudflare Workers, Deno Deploy, Bun, Vercel — qui imposent trois contraintes absentes d'un serveur Node.js classique :
- Temps CPU plafonné : souvent quelques dizaines de millisecondes de calcul actif par requête.
- Ni processus longs, ni disque : aucun état persistant entre deux invocations.
- Facturation au calcul, pas à l'attente : les millisecondes passées sur un appel réseau ne consomment pas de CPU.
Or la résolution d'un CAPTCHA prend plusieurs secondes : envoyer la tâche, attendre, interroger le résultat. Bonne nouvelle, cette attente relève de l'I/O réseau. Sur Cloudflare Workers, waitUntil et un nombre de sous-requêtes maîtrisé suffisent à couvrir le cycle sans épuiser votre budget CPU.
Architecture : appeler CaptchaAI depuis le worker
Le worker reçoit une requête, extrait les paramètres du défi (sitekey, URL de la page, type de CAPTCHA) et appelle l'API CaptchaAI en HTTPS. CaptchaAI expose une seule API pour reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3 et les CAPTCHA image/OCR : vous changez le type de tâche, la boucle envoi/interrogation reste identique. Tracez chaque étape — identifiant de tâche, durée, code retour — pour repérer les régressions lors des montées de version du runtime.
Gérer les secrets sur une plateforme edge
Sur une plateforme edge, la clé API ne vit jamais dans le code. Utilisez le magasin de secrets natif — wrangler secret pour Cloudflare, les variables d'environnement chiffrées de votre plateforme — ou un coffre externe (HashiCorp Vault, AWS Secrets Manager). Le déploiement injecte la clé au runtime, hors du bundle. Pensez aussi au RGPD : un edge worker journalise des requêtes utilisateurs, donc minimisez les données personnelles conservées et documentez la base légale de votre traitement.
Exemple : lancer une tâche Turnstile
Voici un appel HTTP côté serveur, dans votre propre service, pour créer une tâche Turnstile et récupérer son identifiant :
import fetch from 'node-fetch';
const API_KEY = process.env.CAPTCHAAI_KEY;
export async function createTurnstileTask(siteKey, pageUrl) {
const res = await fetch('https://api.captchaai.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientKey: API_KEY,
task: {
type: 'TurnstileTaskProxyless',
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const data = await res.json();
return data.taskId;
}
Le worker renvoie ensuite le taskId, puis interroge le résultat jusqu'à obtention du token. Bornez cette boucle : un plafond de tentatives évite de bloquer une invocation edge indéfiniment.
Observabilité et journalisation
Instrumentez chaque appel CAPTCHA pour obtenir des métriques exploitables : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file interne. Ces signaux alimentent vos tableaux de bord de QA et vos alertes.
Séparez les journaux par environnement (développement, préproduction, production) et conservez un identifiant corrélé à votre traçage distribué, par exemple via OpenTelemetry. Sur un déploiement multirégion — un worker répliqué près de Paris (eu-west-3), par exemple — étiquetez aussi la région : une latence anormale y est souvent locale, pas globale. En cas d'incident, ces journaux réduisent nettement le temps de diagnostic.
Liste de contrôle avant la mise en production
Passez ces points en revue avant de fusionner l'intégration. Chacun correspond à une panne réellement observée sur un déploiement edge.
| Point de contrôle | Pourquoi | Réglage recommandé |
|---|---|---|
| Périmètre | Écarter toute automatisation non autorisée | Limiter aux applications que vous exploitez ou à des sources autorisées |
| Stockage de la clé | Une clé dans le bundle fuit au déploiement | Secret de plateforme (wrangler secret) ou coffre externe |
| Traçabilité | Sans trace, aucun diagnostic n'est possible | Journaliser la durée, le code retour et l'identifiant de tâche |
| Boucle d'interrogation | Une boucle infinie bloque l'invocation edge | Plafonner les tentatives et ajouter un retry idempotent avec backoff |
| Reproductibilité | Un test non rejouable masque les régressions | Rejouer les tests d'intégration depuis la CI |
Dépannage des erreurs courantes
| Symptôme | Cause probable | Correctif |
|---|---|---|
| Clé refusée au démarrage | Clé copiée avec un espace ou mauvais compte | Recopier la clé depuis le tableau de bord vers un secret de plateforme |
| Token rejeté après résolution | Token appliqué dans une autre session que le défi | Réutiliser le même contexte HTTP entre le défi et la soumission |
| Invocation edge interrompue | Boucle d'interrogation non bornée | Limiter les tentatives et prolonger le cycle via waitUntil |
| Solde insuffisant | Compte sous le minimum par tâche | Recharger et poser une alerte de solde dans le tableau de bord |
FAQ
Un edge worker peut-il attendre la résolution d'un CAPTCHA sans dépasser sa limite de temps ?
Oui, car l'attente relève de l'I/O réseau, pas du temps CPU. La plupart des runtimes edge plafonnent le calcul actif, pas les millisecondes passées à attendre une réponse HTTP. Bornez malgré tout la boucle d'interrogation avec un nombre maximal de tentatives et, sur Cloudflare Workers, prolongez le cycle avec waitUntil plutôt que de bloquer la réponse.
Faut-il un proxy pour résoudre le CAPTCHA depuis le worker ?
Pas nécessairement. Le type de tâche Turnstile utilisé ici est « proxyless » : CaptchaAI résout le défi sans proxy fourni de votre côté. Un proxy résidentiel ne devient utile que si la page cible applique un filtrage géographique ou réseau strict que votre worker doit reproduire.
Comment maîtriser le coût quand le trafic augmente ?
La facturation CaptchaAI repose sur le nombre de threads simultanés, pas sur le nombre de résolutions, avec des résolutions illimitées par thread. Le plan BASIC ($15/mois, 5 threads) suffit à un worker à faible concurrence ; passez à STANDARD ($30/mois, 15 threads) ou ADVANCE ($90/mois, 50 threads) quand les tâches simultanées grimpent. Les vrais postes de surcoût restent les boucles de retry et les paramètres erronés.
CaptchaAI prend-il en charge hCaptcha dans ce montage ?
Non — hCaptcha n'est pas pris en charge, pas plus que FunCaptcha (Arkose Labs). CaptchaAI couvre reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3 et les CAPTCHA image/OCR ; GeeTest v4 est annoncé « à venir ». Vérifiez le type affiché sur votre page avant de câbler l'intégration.
Guides connexes
- Démarrage rapide avec CaptchaAI
- Tester vos CAPTCHA en environnement autorisé
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution de CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Structurez vos workflows CAPTCHA avec une méthode reproductible et mesurable. – Créez votre clé API CaptchaAI.
