Express에서 CAPTCHA 솔버 사용하기

Node.js 22 이상과 Express 5를 사용하세요. 공식 JavaScript SDK가 npm 레지스트리에 배포되어 있다고 가정하지 말고, 문서의 tarball 설치 방법으로 설치하세요. 예제는 핸들러 외부에서 Solvethree 클라이언트 하나를 생성합니다.

• SOLVETHREE_API_KEY: 워크스페이스 API 키입니다. 서버에 보관하세요.
• INTEGRATION_KEY: 신뢰할 수 있는 내부 호출자용 별도 비밀 키입니다. 예제는 x-integration-key 헤더에 이 값을 요구합니다. 브라우저 클라이언트에 배포하지 마세요. 이미 인증 미들웨어가 있다면 예제의 공유 키 검사 대신 해당 미들웨어를 사용하세요.
• CAPTCHA_SITE: 전체 URL이 아닌 대상 호스트 이름입니다. 작업을 생성하기 전에 워크스페이스의 활성 사이트 프로필을 설정하세요. 호스트 이름을 전송해도 프로필이 생성되지는 않습니다.
• SOLVETHREE_PROXY: 이 대상에 사용할 프록시입니다. 예제는 단일 프록시를 제공하며 액션을 login으로 고정합니다. 대상이 다른 액션을 사용한다면 서버 측에서 변경하세요.

이 요청은 기본 reCAPTCHA Enterprise 설정을 사용합니다. type이나 url이 아니라 site, action, 프록시가 필요합니다. 대상이 아직 설정되지 않았다면 사이트 프로필 설정을 참조하세요.

// npm install express and the official solvethree SDK tarball.
import express from 'express';
import { Solvethree, SolvethreeError } from '@solvethree/sdk';
const app = express();
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
const secret = process.env.INTEGRATION_KEY;
if (!secret) throw new Error('Set INTEGRATION_KEY');
app.use((request, response, next) => {
  if (request.get('x-integration-key') !== secret) return response.sendStatus(401);
  next();
});
app.post('/captcha/tasks', async (request, response) => {
  const task = await client.createTask({
    site: process.env.CAPTCHA_SITE, action: 'login', proxy: process.env.SOLVETHREE_PROXY,
    requestId: request.get('x-request-id'),
  }, { waitMs: 0, signal: AbortSignal.timeout(20000) });
  response.json(task);
});
app.get('/captcha/tasks/:id', async (request, response) => {
  response.json(await client.getTask(request.params.id, { waitMs: 15000, signal: AbortSignal.timeout(25000) }));
});
app.use((error, request, response, next) => {
  if (error instanceof SolvethreeError) return response.status(502).json({ requestId: error.requestId, taskId: error.taskId });
  response.status(400).json({ error: 'Invalid task input or ID' });
});
app.listen(3000);

두 라우트 모두 인증 검사를 거칩니다. POST 핸들러는 요청 본문이 아닌 서버 설정에서 호스트 이름, 액션, 프록시를 가져옵니다. 호출자가 제공하는 값은 선택 사항인 생성 식별자뿐입니다.

1. 1.

   생성 전에 요청 ID 할당

   ASCII 영문자, 숫자, 밑줄 또는 하이픈으로 구성된 1–64자의 x-request-id를 보내세요. 연결 시간이 초과되면 생성을 복구할 수 있도록 논리적 요청과 함께 보관하세요.

2. 2.

   /captcha/tasks에 POST 한 번 전송

   핸들러는 waitMs: 0으로 createTask를 호출하고 작업을 반환합니다. 작업 ID를 보관하세요. 성공 응답은 작업이 생성되었다는 뜻이며, 반드시 솔루션이 있다는 뜻은 아닙니다.

3. 3.

   GET으로 상태 조회

   /captcha/tasks/:id를 호출하세요. 상태가 pending 또는 solving인 동안 계속 조회하세요. 진행 상황을 확인하려고 POST를 반복하지 마세요. ready 또는 failed이면 중단하세요.

4. 4.

   준비된 솔루션만 사용

   동일하게 설정된 프록시와 의도한 대상을 사용해 반환된 userAgent, secChUa와 함께 토큰을 제출하세요. SDK가 대신 제출하지는 않습니다. 준비된 작업은 솔루션이 생성되었다는 뜻이지, 대상이 애플리케이션 요청을 수락했다는 뜻은 아닙니다.

POST SDK 호출에는 20초의 AbortSignal 제한 시간이 적용됩니다. GET은 25초의 SDK 호출 제한 시간 내에서 15초 동안 작업을 기다릴 수 있습니다. GET 응답이 여전히 최종 상태가 아닐 수 있으므로, 대기가 끝났다고 해결 실패로 간주하지 말고 상태를 확인하세요.

생성 시간이 초과되었다고 해서 solvethree가 요청을 거부했다고 단정할 수는 없습니다. 작업 ID를 받았다면 조회하세요. 그렇지 않다면 동일한 요청 ID와 변경하지 않은 작업 입력값으로 생성을 다시 요청해 기존 작업을 복구하세요. 다른 입력값으로 같은 ID를 재사용하면 충돌이 발생합니다. 요청 ID를 보관하지 않았다면 새 POST로 별도의 작업이 생성될 위험이 있습니다.

Express 5는 비동기 핸들러에서 거부된 Promise를 오류 미들웨어로 전달합니다. 예제는 SolvethreeError에 대해 HTTP 502를 반환하며, 원본 오류, 인증 정보 또는 솔루션이 아닌 요청 및 작업 식별자만 노출합니다. 대체 응답인 HTTP 400은 일반적인 응답으로, 제한 시간 오류를 비롯한 모든 비 SDK 오류를 정확히 분류하지는 않습니다.

성공 페이로드를 읽기 전에 HTTP 오류를 처리하세요. 이와 별개로 조회한 작업의 상태가 failed일 수 있습니다. errorCode와 error를 확인한 뒤 폴링을 중단하세요. 해결에 실패하면 환불되지만, 잘못된 입력값을 그대로 재시도해도 문제가 해결되지는 않습니다. 보고된 실패를 진단하려면 API 오류 참조를 사용하세요.