Résoudre les CAPTCHA avec Graphile Worker sur Postgres

Périmètre sûr : ce guide s'applique uniquement à vos propres applications, à vos environnements de QA ou de production, ou aux systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne couvre pas l'automatisation de sites tiers ni la neutralisation de protections que vous n'êtes pas autorisé à tester.

Graphile Worker exécute vos tâches d'arrière-plan directement dans PostgreSQL, sans broker externe ni file Redis. Y intégrer la résolution de CAPTCHA revient à traiter chaque défi comme un job idempotent : vous soumettez la tâche à l'API CaptchaAI, attendez le token, puis le validez côté backend. L'enjeu : rendre le flux assez stable pour tourner sans surveillance en CI ou en cron.

Pourquoi Graphile Worker convient à ce cas

Graphile Worker s'appuie sur LISTEN/NOTIFY de PostgreSQL pour distribuer les jobs à faible latence, avec la persistance transactionnelle de la base. Un CAPTCHA à résoudre devient une ligne dans une table de jobs : si le worker plante, la tâche est reprise plutôt que perdue. Vous n'ajoutez aucun composant d'infrastructure, puisque la file vit dans la base que vous sauvegardez déjà. La facturation au thread concurrent de CaptchaAI (BASIC à $15/mois pour 5 threads) suit la même logique : un worker actif occupe un thread, libéré une fois la résolution terminée.

Préparer l'environnement avant le premier job

Un environnement propre évite la plupart des incidents en production. Validez ces points avant d'écrire le premier handler :

• QA isolée de la production, endpoints internes ouverts aux requêtes de test.
• Clé CaptchaAI dans un secret CI ou un coffre, jamais dans le code source.
• Connexion PostgreSQL dédiée au worker, distincte de celle de l'application.
• job_ttl fixé au-dessus de la latence réelle de résolution (plusieurs dizaines de secondes).

Encapsuler l'appel dans une tâche réutilisable

Isolez l'appel à CaptchaAI dans une fonction appelée par le handler : elle prend la sitekey et l'URL de votre propre page, renvoie un token et trace la durée. Cela sépare la logique de file, gérée par Graphile Worker, de la résolution. Voici une tâche Turnstile qui 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;
}

Le handler stocke le taskId, puis interroge le résultat à intervalles espacés jusqu'au token ou à l'expiration du délai.

Valider le token côté backend

Le token renvoyé doit être vérifié par votre backend avant toute opération métier : rien ne doit passer sur la foi d'un token périmé ou contrefait. Appliquez-le dans la session qui a déclenché le défi — même contexte de navigateur, même client HTTP, même cookie jar. Une session dépareillée est la première cause de rejet après résolution.

Observabilité : journaux et métriques par worker

Instrumentez chaque appel pour distinguer deux réussites : la résolution du CAPTCHA et son acceptation en aval. Corrélez chaque identifiant à votre traçage distribué (OpenTelemetry, par exemple) pour rejouer un scénario complet et réduire le diagnostic.

Liste de contrôle avant la mise en production

• Périmètre strictement limité à vos propres applications ou à des sources autorisées.
• Clé CaptchaAI dans un secret CI ou un coffre, jamais en clair dans le dépôt.
• job_ttl et nombre de workers dimensionnés pour la latence réelle de résolution.
• Durées d'appel et codes retour tracés pour chaque exécution.
• Retry idempotent avec backoff exponentiel borné pour les erreurs transitoires.
• Tests rejouables depuis votre intégration continue.

FAQ

Graphile Worker convient-il à des tâches CAPTCHA longues ?

Oui, à condition de dimensionner le job_ttl au-dessus de votre plafond d'interrogation (120 secondes, par exemple), pour qu'un job encore valide ne soit pas rejoué.

Comment gérer les nouvelles tentatives ?

Graphile Worker intègre max_attempts avec backoff exponentiel. Limitez-le à trois tentatives et tracez chaque échec terminal. Une résolution déjà obtenue ne doit jamais être relancée : gardez le handler idempotent.

Faut-il ajouter Redis à côté de Postgres ?

Non. Graphile Worker fait vivre la file dans PostgreSQL via LISTEN/NOTIFY : un composant d'infrastructure en moins, et la cohérence transactionnelle de la base que vous sauvegardez déjà.

Le token peut-il expirer avant d'être appliqué ?

Oui, les tokens ont une durée de vie limitée : traitez la résolution et l'usage du token dans un délai court et la même session, sans constituer de réserve.

Guides connexes

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

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