AWS Lambda에서 Node.js SDK 사용하기

1. 1.

   의존성 설치

   깨끗한 빌드 디렉터리에서 npm 패키지를 초기화하세요. npm으로 https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz의 공식 tarball을 설치하세요. 이 패키지는 @solvethree/sdk 가져오기를 제공합니다. npm 레지스트리에 릴리스가 있다고 가정하지 마세요.

2. 2.

   워크스페이스 및 대상 설정

   SOLVETHREE_API_KEY, CAPTCHA_SITE, SOLVETHREE_PROXY라는 비공개 Lambda 환경 변수를 설정하세요. 워크스페이스 API 키, 전체 URL이 아닌 대상 호스트 이름, 이 작업에 사용할 프록시를 사용하세요. 워크스페이스에는 해당 사이트의 활성 프로필이 이미 있어야 합니다. 사이트 프로필 설정을 참고하세요.

3. 3.

   핸들러 저장 및 패키징

   아래 예시를 index.mjs로 저장하세요. index.mjs, 패키지 메타데이터, 설치된 node_modules 디렉터리가 상위 프로젝트 디렉터리 안이 아니라 아카이브 루트에 위치하도록 ZIP을 만드세요. ZIP에 인증 정보를 넣지 마세요.

4. 4.

   기존 Lambda 절차로 배포

   Node.js 22 런타임을 사용하고 핸들러를 index.handler로 설정하세요. 권한이 부여된 백엔드 또는 IAM 흐름을 통해 호출하고, 논리적 작업에 대해 일관된 requestId를 제공하세요. 반환된 솔루션 데이터는 비공개로 유지하세요.

예시에서는 액션으로 login을 사용합니다. 배포하기 전에 대상이 요구하는 액션으로 변경하세요. 이 예시는 proxy 하나를 전송하고 기본 요청 유형인 enterprise-v3를 사용합니다. reCAPTCHA type 또는 url 필드를 추가하지 마세요.

import { Solvethree, SolvethreeError, TaskFailedError, ApiError } from '@solvethree/sdk';
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
export const handler = async (event, context) => {
  const timeoutMs = Math.min(180000, context.getRemainingTimeInMillis() - 1500);
  if (timeoutMs < 1000) throw new Error('Not enough execution time to start a task');
  // The caller supplies one stable ID for this logical job; Lambda retries must
  // reuse it. awsRequestId changes with invocations and is not that logical ID.
  if (!event.requestId) throw new Error('Provide a stable requestId');
  try {
    return await client.solve({
      site: process.env.CAPTCHA_SITE, action: 'login', proxy: process.env.SOLVETHREE_PROXY,
      requestId: event.requestId,
    }, { timeoutMs, signal: AbortSignal.timeout(timeoutMs) });
  } catch (error) {
    if (error instanceof TaskFailedError) return { status: 'failed', id: error.taskId, errorCode: error.errorCode };
    if (error instanceof ApiError) return { apiError: error.status, requestId: error.requestId };
    if (error instanceof SolvethreeError) return { interrupted: true, requestId: error.requestId, taskId: error.taskId };
    throw error;
  }
};
// Invoke through your authorized backend/IAM flow. The return value is private
// solution data; do not attach this handler to an unauthenticated public URL.

핸들러는 Lambda의 남은 실행 시간을 읽고, 1,500밀리초를 확보한 뒤, SDK 대기를 최대 180,000밀리초로 제한합니다. 이 상한은 이 예시에 적용되는 값이며, 모든 Lambda에 적용되는 실행 제한이 아닙니다. 확보한 시간을 제외하고 남은 시간이 1초 미만이면 핸들러는 시작하지 않습니다.

SDK 시간 초과와 중단 신호 모두 계산된 제한 시간을 사용합니다. solve는 작업을 한 번 생성하고 준비가 완료되거나 오류가 발생할 때까지 폴링합니다. 확보한 시간은 오류 처리에서 복구 정보를 반환할 여유를 주지만, Lambda가 강제로 종료되면 응답이 전혀 반환되지 않을 수도 있습니다.

호출자는 호출을 재시도해도 event.requestId를 유지해야 합니다. ASCII 영문자, 숫자, 밑줄 또는 하이픈 1–64자를 사용하세요. awsRequestId는 사용하지 마세요. 이는 논리적 해결 요청이 아니라 개별 호출을 식별합니다.

유효성 검사 오류와 예상치 못한 오류는 다시 던집니다. 핸들러는 모든 예외를 중단 응답으로 변환하지 않습니다.

1. 1.

   작업 ID가 있으면 해당 ID로 복구

   getTask로 기존 작업을 조회하세요. pending과 solving은 아직 실행 중임을 의미하며, ready만 사용 가능한 솔루션을 포함합니다. 추가 대기는 새 호출의 남은 가용 시간 내로 제한하세요.

2. 2.

   작업 ID가 없으면 논리적 요청 ID로 복구

   호출자가 처음 사용한 requestId로 동일한 작업 요청을 재시도하세요. 입력이 일치하면 기존 작업을 반환하고, 입력이 다르면 충돌이 발생합니다. 복구 중에는 구성이 변경되더라도 사이트, 액션, 프록시를 그대로 유지하세요.

연결 시간 초과만으로 작업 생성이 실패했다고 단정할 수는 없습니다. 새 논리적 요청 ID를 할당하기 전에 기존 작업을 복구하세요. 기본 동작 규약은 작업 폴링과 API 오류 처리를 참고하세요.

SDK는 솔루션 데이터를 반환하며, 대상에 직접 적용하지는 않습니다. 애플리케이션에서 이를 제출할 때는 구성된 프록시와 반환된 userAgent, secChUa를 사용하세요. 무관한 브라우저 식별 정보나 대상 URL로 대체하지 마세요. 작업이 준비되었다는 것은 솔루션이 생성되었다는 뜻이지, 대상이 후속 요청을 수락했다는 뜻은 아닙니다.