Résoudre les CAPTCHA avec pgmq sur Postgres

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 vise pas les sites tiers que vous ne contrôlez pas.

Une file d'attente pgmq adossée à Postgres transforme la résolution de CAPTCHA en un traitement asynchrone, rejouable et facile à superviser. Au lieu d'appeler l'API en pleine requête HTTP, vous déposez une tâche dans la file, un pool de workers la consomme, résout le défi via CaptchaAI, puis écrit le token dans la même transaction Postgres.

Ce guide déroule un flux prêt pour la production, de la préparation de la file au dépannage.

Pourquoi piloter la résolution depuis une file pgmq

pgmq est une extension qui ajoute des files transactionnelles à une base Postgres que vous exploitez déjà : inutile d'ajouter Redis ou Kafka pour orchestrer quelques milliers de résolutions par jour. Trois propriétés en font un bon support : la visibilité des messages (un worker verrouille sa tâche le temps de la traiter), la relivraison automatique en cas d'échec, et l'atomicité — token et état métier écrits dans la même transaction, un seul système à sauvegarder.

Le flux de résolution, étape par étape

1. Préparez l'environnement et la file. Isolez la QA de la production, stockez la clé CaptchaAI dans un secret de CI, puis créez la file avec pgmq.create('captcha_tasks').
2. Fixez le délai de visibilité au-delà de votre temps de résolution (de l'ordre de 120 s) pour qu'un worker lent ne provoque pas de double traitement.
3. Encapsulez l'appel à CaptchaAI dans une fonction réutilisable qui reçoit la sitekey et l'URL de votre page et renvoie un token.
4. Consommez la file : chaque worker lit un message, appelle cette fonction, puis interroge le résultat jusqu'au token.
5. Vérifiez puis acquittez. Validez le token côté backend, puis supprimez le message avec pgmq.delete.

Exemple de code

La fonction ci-dessous crée une tâche Turnstile et renvoie l'identifiant à interroger :

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

Vérifier le token côté backend

Le token renvoyé doit être validé par votre propre backend avant toute opération métier. Appliquez-le dans la même session que celle qui a déclenché le défi — même contexte de navigateur, même client HTTP, même cookie jar. C'est la première cause de rejet : un token valide présenté dans une session étrangère est refusé côté serveur.

Indicateurs à suivre

Instrumentez chaque appel : durée d'obtention du token, code retour HTTP et profondeur de la file pgmq. Surveillez la latence médiane et son 95ᵉ centile, le taux de réussite et surtout l'écart entre résolution réussie et acceptation côté backend : c'est lui qui trahit un problème de session.

Liste de contrôle avant la mise en production

• Le périmètre reste limité à vos propres applications ou à des sources autorisées.
• La clé CaptchaAI est stockée dans un secret de CI ou un coffre, jamais en clair.
• Le délai de visibilité pgmq est supérieur à votre p95, et un retry idempotent (backoff exponentiel borné) couvre les erreurs transitoires.

Dépannage

FAQ

Pourquoi choisir pgmq plutôt que Redis ou Kafka ?

Parce que la file vit dans la base Postgres que vous exploitez déjà : une seule dépendance à sécuriser, sans infrastructure de messagerie dédiée. Redis ou Kafka gardent leur intérêt à très haut débit, mais pour quelques milliers de résolutions par jour, Postgres suffit.

CaptchaAI prend-il en charge hCaptcha ?

Non — pas encore pris en charge, pas plus que FunCaptcha (Arkose Labs) ni GeeTest v4 (à venir). CaptchaAI couvre en revanche reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, les CAPTCHA image/OCR et les grilles d'images, avec CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta).

Quel plan CaptchaAI choisir pour un pool de workers ?

La facturation repose sur les threads (résolutions simultanées), avec un nombre de résolutions illimité par thread. Dimensionnez le plan sur le nombre de workers en parallèle : BASIC ($15/mois, 5 threads) suffit à un pool de QA, STANDARD ($30/mois, 15 threads) ou au-delà à un pipeline de production.

Guides connexes

• Démarrage rapide CaptchaAI
• Tester vos formulaires via l'endpoint API
• Intégrer la résolution CAPTCHA à votre CI
• Résoudre reCAPTCHA v2 via l'API
• QA CAPTCHA en environnements autorisés

Déployez une file pgmq robuste et mesurez vos propres temps de résolution. – Créez votre clé CaptchaAI.