Gérer les CAPTCHA dans un serveur Elysia + Bun

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 couvre pas l'automatisation de sites tiers que vous ne contrôlez pas.

Un serveur Elysia qui tourne sur Bun répond en quelques millisecondes — jusqu'à ce qu'une route touche un formulaire protégé par un CAPTCHA. À partir de là, la vitesse du runtime ne suffit plus : il faut un contrat d'appel stable vers un service de résolution. Cet article montre comment brancher l'API CaptchaAI dans un serveur Elysia + Bun pour que l'intégration tienne en production, sans surveillance.

Pourquoi les CAPTCHA cassent une intégration Elysia + Bun en production

Le sujet paraît trivial dans un script de test, puis se met à casser dès qu'il tourne sans surveillance. Ce dont vous avez besoin, c'est d'une latence prévisible, de codes d'erreur explicites et d'un handoff de token fiable. CaptchaAI répond à ce besoin avec une API unique pour toutes les familles prises en charge (reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, image/OCR et grilles) et une facturation par thread qui ne pénalise pas la montée en charge. En production — tâche planifiée, worker ou test de bout en bout — la même intégration doit encaisser les déploiements, les coupures réseau et les changements de famille de CAPTCHA.

Architecture cible dans un serveur Elysia + Bun

Votre composant interne appelle CaptchaAI en HTTPS pour récupérer un token, puis l'injecte dans votre formulaire ou votre route d'API. Sur Bun, fetch est natif : un module de service isolé encapsule l'appel et expose une fonction typée à vos handlers Elysia. Gardez la logique de résolution hors des routes — le handler reste mince, et toute la mécanique submit/poll vit dans un module dédié, testable en isolation.

Le workflow submit/poll, étape par étape

L'ordre ne change pas d'une pile à l'autre ; respectez-le et la plupart des pannes disparaissent.

1. Capturez les paramètres attendus (sitekey, URL, action, proxy optionnel). En stocker davantage crée de fausses pistes de débogage.
2. Envoyez la tâche et récupérez son identifiant. Traitez tout statut d'erreur comme un échec : journalisez la réponse et remontez-la vers votre supervision.
3. Interrogez le résultat régulièrement : attendez environ 15 secondes, puis toutes les 5 secondes, avec un plafond de 120 secondes par tâche.
4. Injectez le token dans la même session que celle qui a déclenché le défi (même contexte, même client HTTP, même cookie jar). Un décalage de session est la première cause de rejet.
5. Mesurez latence, retries et acceptation en aval. La réussite du solveur et celle du workflow sont deux métriques distinctes.

Exemple de code côté serveur

Appel HTTP côté serveur dans votre propre service, avec récupération de l'identifiant de tâche :

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;
}

Une fois le taskId obtenu, la boucle d'interrogation récupère le token, que votre handler Elysia transmet au flux appelant. Le contrat submit/poll reste identique quelle que soit la famille : seul le type de tâche change.

Où stocker la clé API dans un déploiement Bun

La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret de CI, jamais dans le code source. Le déploiement la monte en variable d'environnement et Bun la lit via process.env.CAPTCHAAI_KEY. Si vous déployez chez OVHcloud, Scaleway ou sur une région AWS européenne comme eu-west-3 (Paris), utilisez le gestionnaire de secrets de la plateforme plutôt qu'un fichier .env dans l'image. Côté conformité, minimisez les données personnelles qui transitent par vos journaux — c'est aussi une bonne hygiène au regard du RGPD.

Checklist avant de merger l'intégration

• Le périmètre est limité à vos propres applications ou à des sources autorisées.
• La clé CaptchaAI est dans un secret de CI ou un coffre, jamais en clair dans le dépôt.
• Le retry est idempotent, plafonné à trois tentatives avec backoff exponentiel.
• Le token est injecté dans la même session que celle qui a déclenché le défi.

Mesurer la réussite : les KPI à suivre

Reliez ces indicateurs à votre tableau de bord existant. Ces cibles reposent sur des mesures observées ; les résultats varient selon l'environnement, le volume et l'heure.

Observabilité et journalisation

Instrumentez les appels CAPTCHA pour obtenir des métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente. Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué, par exemple via OpenTelemetry : vous rejouez alors un scénario complet depuis un identifiant unique.

Dépannage

Les erreurs ci-dessous couvrent l'essentiel des tickets pour ce type d'intégration.

FAQ

Pourquoi Elysia + Bun plutôt qu'Express pour ce type d'intégration ?

Pour la latence et le fetch natif. Bun démarre vite et Elysia expose un routage typé qui garde vos handlers minces. Le contrat d'appel vers CaptchaAI reste celui de Node.js : c'est la mécanique HTTP qui compte, pas le framework.

Que faire quand un token est refusé après une résolution réussie ?

Vérifiez d'abord la session : le token doit être injecté dans le même contexte ou le même client HTTP que celui qui a déclenché le défi. Une session distincte est la première cause de rejet — regardez-la avant le solveur.

Comment le coût évolue-t-il quand le volume augmente ?

La facturation est par thread, avec des résolutions illimitées par thread — un plan comme BASIC ($15/mois, 5 threads) couvre déjà plusieurs résolutions simultanées. Les surcoûts viennent surtout des mauvais paramètres et des retries en rafale.

Guides connexes

• Le guide de démarrage rapide CaptchaAI
• La QA CAPTCHA en environnements autorisés
• Tester l'endpoint API sur vos formulaires
• Intégrer la résolution de CAPTCHA dans votre CI
• Résoudre reCAPTCHA v2 via l'API

Structurez vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.