Сервис капчи на NestJS: модуль, который решает Turnstile

Чаще всего по запросу про капчу в NestJS хотят защитить сайт на Nest. Это руководство о противоположном случае: ваш сервис должен пройти виджет Cloudflare Turnstile на странице, которую вам можно автоматизировать, и для этого ему нужен токен. Вы оборачиваете пакет capskip в dynamic module, превращаете его ошибки в HTTP-статусы и тестируете всё через Vitest и supertest. Решение выполняет копия решателя CapSkip для Turnstile на ПК с Windows, который есть у вас, без платы за каждое решение. Очередей здесь нет; решения, которым очередь нужна, разобраны в руководстве по воркеру BullMQ.
Что понадобится
- CapSkip на вашем ПК с Windows. Где он принимает подключения, задаётся в разделе настроек подключения. Его описывает руководство по настройке: Local mode оставляет его на 127.0.0.1, а Server mode открывает его для вашей сети.
- Node.js 24.15 или новее в линейке 24, либо 26. Генератор каркаса требует 22.22.3, 24.15 или 26, Vite 8 и его сборщик требуют 20.19 или 22.12, а сам Nest 12 требует 20. Я запускал проект, от каркаса до тестов, на 24.22.0 и 25.2.1, где npm выводил предупреждение об engine для @nestjs/schematics. На 20.11.1 команда создания каркаса и Vitest не работают.
- Nest 12 (здесь 12.4.2) с @nestjs/config 12.1.1 и capskip 1.7.0. Каркас работает только с ESM (пути импорта заканчиваются на .js) и тестируется через Vitest, поэтому моки это vi.fn.
Все запуски ниже шли на написанной мной имитации in.php и res.php и на настоящем пакете capskip 1.7.0. Ни одно задание не дошло до настоящего CapSkip, поэтому я не называю время решения, а каждая задержка и каждый ответ следуют правилам имитации.
Шаг 1: создайте проект и настройки
Выполните это в PowerShell. Команды создают приложение, устанавливают два пакета, удаляют четыре примера файлов, которые заменяет новая структура, и создают папку для модуля.
# Scaffold the app, then npm install capskip @nestjs/config npx @nestjs/cli new capskip-nest --package-manager npm --skip-git cd capskip-nest npm install capskip @nestjs/config Remove-Item src/app.controller.ts, src/app.controller.spec.ts, src/app.service.ts, test/app.e2e-spec.ts New-Item -ItemType Directory src/capskip | Out-Null
Выполните следующий блок в папке проекта. Он записывает .env и .gitignore без редактора, поэтому файл не получит имя .env.txt. Каркас, созданный без git, не содержит .gitignore, а в .env будет лежать ваш ключ, так что внесите его в список исключений до первого использования git. Сам SDK не читает переменные окружения, их читает фабрика из шага 2. CAPSKIP_API_KEY нужен только тогда, когда в CapSkip включена API Key Validation; если его нет, SDK отправляет ключ capskip.
# Create .env and .gitignore without an editor @' CAPSKIP_HOST=127.0.0.1 CAPSKIP_PORT=8080 CAPSKIP_API_KEY=YOUR_API_KEY CAPSKIP_TIMEOUT=20 TARGET_HOSTS=example.com '@ | Set-Content -Path .env -Encoding ascii Set-Content -Path .gitignore -Value '.env', 'node_modules', 'dist' -Encoding ascii
Шаг 2: создайте модуль
Параметры, описанные один раз
Сохраните следующий блок как src/capskip/capskip.options.ts. В Nest есть ConfigurableModuleBuilder, который генерирует статические методы forRoot и forRootAsync и токен внедрения для параметров. Аргумент extras добавляет флаг isGlobal, который остаётся в модуле и не попадает в параметры. Построитель описан в главе Nest о динамических модулях.
// src/capskip/capskip.options.ts
import { ConfigurableModuleBuilder } from '@nestjs/common';
export interface CapSkipModuleOptions {
host?: string;
port?: number;
apiKey?: string;
/** Seconds the SDK may poll for one solve. */
timeoutSeconds?: number;
}
export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =
new ConfigurableModuleBuilder<CapSkipModuleOptions>()
.setClassMethodName('forRoot')
.setExtras({ isGlobal: false }, (definition, extras) => ({
...definition,
global: extras.isGlobal,
}))
.build();Сервис с клиентом за токеном
Сохраните это как src/capskip/capskip.service.ts. Клиент SDK создаётся не внутри сервиса. Он приходит через токен CAPSKIP_CLIENT и типизирован как единственный метод SDK, который использует сервис, поэтому тест может передать одну функцию, а компилятор всё равно проверит её сигнатуру.
// src/capskip/capskip.service.ts
import { Inject, Injectable } from '@nestjs/common';
import { TimeoutException, type CapSkip } from 'capskip';
import { MODULE_OPTIONS_TOKEN, type CapSkipModuleOptions } from './capskip.options.js';
export const CAPSKIP_CLIENT = Symbol('CAPSKIP_CLIENT');
/** The one SDK method this service calls, so a test double stays small. */
export type TurnstileClient = Pick<CapSkip, 'turnstile'>;
export interface TurnstileToken {
token: string;
/** Submit the token with this User-Agent when CapSkip reports one. */
userAgent?: string;
}
@Injectable()
export class CapSkipService {
constructor(
@Inject(CAPSKIP_CLIENT) private readonly client: TurnstileClient,
@Inject(MODULE_OPTIONS_TOKEN) private readonly options: CapSkipModuleOptions,
) {}
async solveTurnstile(sitekey: string, url: string): Promise<TurnstileToken> {
const seconds = this.options.timeoutSeconds ?? 60;
// The SDK sets no timeout on its HTTP calls and checks its deadline only
// between polls, so a CapSkip that stops answering would hold this call
// forever. The race ends it 6 seconds after the SDK deadline at the latest.
let timer: NodeJS.Timeout | undefined;
const giveUp = new Promise<never>((_, reject) => {
timer = setTimeout(
() => reject(new TimeoutException(`no answer from CapSkip within ${seconds + 6} s`)),
(seconds + 6) * 1000,
);
});
try {
const result = await Promise.race([
this.client.turnstile(sitekey, url, { timeout: seconds }),
giveUp,
]);
if (typeof result.code !== 'string') {
throw new Error('Unexpected CapSkip result for turnstile');
}
return { token: result.code, userAgent: result.userAgent };
} finally {
clearTimeout(timer);
}
}
}Turnstile выбран как пример, потому что его результат содержит User-Agent, который, согласно типам SDK, нужно использовать при отправке токена. Сервис возвращает его вместе с токеном как небольшой объект, а не как исходный результат SDK, у которого поле code типизировано как строка или объект и здесь отвергается, если это не строка. Другие типы устроены так же: добавьте по методу для recaptcha, hcaptcha или mtcaptcha и передавайте в них timeout по причине из шага 3. Поля, которые принимает каждый тип, перечислены в разделе Документация API.
Ошибки SDK как HTTP-статусы
В SDK есть четыре класса исключений, и все они наследуют CapSkipError: ValidationException, NetworkException, ApiException и TimeoutException. ApiException несёт в сообщении только текст ответа CapSkip, без поля code, поэтому преобразование достаёт код ERROR_ из текста сообщения. Сохраните это как src/capskip/capskip.errors.ts.
// src/capskip/capskip.errors.ts
import { Catch, HttpException, HttpStatus, Logger, type ArgumentsHost } from '@nestjs/common';
import { BaseExceptionFilter } from '@nestjs/core';
import {
ApiException,
CapSkipError,
NetworkException,
TimeoutException,
ValidationException,
} from 'capskip';
const BAD_INPUT = /ERROR_(RECAPTCHA_INVALID_(SITEKEY|DOMAIN)|BAD_PARAMETERS|PAGEURL)/;
const BAD_CREDENTIALS = /ERROR_(KEY_DOES_NOT_EXIST|WRONG_USER_KEY|ZERO_BALANCE)/;
export function toHttpException(err: CapSkipError): HttpException {
const code = /ERROR_[A-Z_]+/.exec(err.message)?.[0];
const body = (status: HttpStatus, error: string) => ({
statusCode: status,
error,
code: code ?? err.name,
});
if (err instanceof TimeoutException) {
return new HttpException(body(HttpStatus.GATEWAY_TIMEOUT, 'Solver timeout'), 504);
}
if (err instanceof NetworkException) {
return new HttpException(body(HttpStatus.SERVICE_UNAVAILABLE, 'Solver unreachable'), 503);
}
if (err instanceof ApiException && BAD_INPUT.test(err.message)) {
return new HttpException(body(HttpStatus.BAD_REQUEST, 'Solver refused the task'), 400);
}
if (err instanceof ApiException && code === 'ERROR_CAPTCHA_UNSOLVABLE') {
return new HttpException(body(HttpStatus.UNPROCESSABLE_ENTITY, 'Not solved, retry'), 422);
}
if (err instanceof ValidationException) {
// The SDK refused a task this service built: a bug here, not the caller's.
return new HttpException(body(HttpStatus.INTERNAL_SERVER_ERROR, 'Task refused by the SDK'), 500);
}
// Wrong key, empty balance or anything else: our side of the link, not the caller's.
const error = err instanceof ApiException && BAD_CREDENTIALS.test(err.message)
? 'Solver credentials rejected'
: 'Solver error';
return new HttpException(body(HttpStatus.BAD_GATEWAY, error), 502);
}
@Catch(CapSkipError)
export class CapSkipExceptionFilter extends BaseExceptionFilter {
private readonly logger = new Logger(CapSkipExceptionFilter.name);
override catch(err: CapSkipError, host: ArgumentsHost) {
// The SDK message is the reply text of CapSkip and never holds the key.
this.logger.warn(`${err.name} ${err.message}`);
super.catch(toHttpException(err), host);
}
}Фильтр наследует BaseExceptionFilter и передаёт обработку дальше, по образцу из главы Nest о фильтрах исключений Благодаря этому он работает на любом HTTP-адаптере. Он перехватывает только CapSkipError, пишет одно предупреждение с именем ошибки и сообщением (текстом ответа CapSkip, но никогда не вашим ключом) и не выпускает это исходное сообщение в ответ.
| Что выбросил SDK | HTTP | Почему такой статус |
|---|---|---|
| TimeoutException | 504 | Токен не получен за время таймаута. Сюда же попадает CapSkip, который замолчал между опросами |
| NetworkException | 503 | Не удалось связаться с CapSkip при отправке задания |
| ApiException с ERROR_CAPTCHA_UNSOLVABLE | 422 | Не решено. В документации API CapSkip сказано отправить новое задание |
| ApiException с ERROR_RECAPTCHA_INVALID_SITEKEY, ERROR_RECAPTCHA_INVALID_DOMAIN, ERROR_BAD_PARAMETERS или ERROR_PAGEURL | 400 | Вызывающая сторона прислала sitekey или адрес страницы, которые CapSkip отклоняет |
| ApiException с ERROR_KEY_DOES_NOT_EXIST, ERROR_WRONG_USER_KEY или ERROR_ZERO_BALANCE | 502 | Проблема в собственном ключе вашего сервиса, а не во входных данных вызывающей стороны |
| ValidationException | 500 | SDK отклонил задание, которое собрал этот сервис, а это здесь ошибка |
Любая другая ApiException превращается в 502. Модуль регистрирует фильтр через APP_FILTER, поэтому каждое приложение, которое подключает модуль, получает это преобразование.
Модуль, приложение и контроллер
Сохраните модуль как src/capskip/capskip.module.ts. Он создаёт клиент из параметров в фабричном провайдере, добавляет сервис и регистрирует фильтр.
// src/capskip/capskip.module.ts
import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';
import { CapSkip } from 'capskip';
import { CapSkipExceptionFilter } from './capskip.errors.js';
import {
ConfigurableModuleClass,
MODULE_OPTIONS_TOKEN,
type CapSkipModuleOptions,
} from './capskip.options.js';
import { CAPSKIP_CLIENT, CapSkipService } from './capskip.service.js';
@Module({
providers: [
{
provide: CAPSKIP_CLIENT,
inject: [MODULE_OPTIONS_TOKEN],
useFactory: ({ host, port, apiKey }: CapSkipModuleOptions) =>
new CapSkip({ host, port, apiKey }),
},
CapSkipService,
{ provide: APP_FILTER, useClass: CapSkipExceptionFilter },
],
exports: [CapSkipService],
})
export class CapSkipModule extends ConfigurableModuleClass {}Замените src/app.module.ts следующим блоком. forRootAsync запускает фабрику с тем, что вы перечислите в inject. ConfigModule здесь глобальный, поэтому CapSkipModule находит ConfigService без импорта.
// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { CapSkipModule } from './capskip/capskip.module.js';
import { TurnstileController } from './turnstile.controller.js';
@Module({
imports: [
ConfigModule.forRoot({ isGlobal: true }),
CapSkipModule.forRootAsync({
inject: [ConfigService],
useFactory: (config: ConfigService) => ({
host: config.get<string>('CAPSKIP_HOST', '127.0.0.1'),
port: Number(config.get('CAPSKIP_PORT', 8080)),
apiKey: config.get<string>('CAPSKIP_API_KEY'),
timeoutSeconds: Number(config.get('CAPSKIP_TIMEOUT', 60)),
}),
}),
],
controllers: [TurnstileController],
})
export class AppModule {}Наконец, сохраните src/turnstile.controller.ts. Параметр url определяет, для какой страницы CapSkip решает капчу, так что открытый маршрут позволил бы любому тратить ваш решатель. Проверка по TARGET_HOSTS это минимум: она принимает только https-адреса, обрезает пробелы в списке и отклоняет все запросы, если список пуст или не задан. Поставьте перед ней собственный guard аутентификации.
// src/turnstile.controller.ts
import { BadRequestException, Body, Controller, Post } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { CapSkipService } from './capskip/capskip.service.js';
@Controller('captcha')
export class TurnstileController {
constructor(
private readonly capskip: CapSkipService,
private readonly config: ConfigService,
) {}
@Post('turnstile')
solve(@Body() body: { sitekey?: unknown; url?: unknown }) {
const hosts = this.config
.get<string>('TARGET_HOSTS', '')
.split(',')
.map((host) => host.trim())
.filter(Boolean);
const page =
typeof body.url === 'string' && URL.canParse(body.url) ? new URL(body.url) : null;
if (
typeof body.sitekey !== 'string' ||
!body.sitekey ||
!page ||
page.protocol !== 'https:' ||
!hosts.includes(page.host)
) {
throw new BadRequestException('sitekey or url missing, or host not allowed');
}
return this.capskip.solveTurnstile(body.sitekey, page.href);
}
}Шаг 3: таймаут запроса и дедлайн SDK
Я не задавал таймаут в Nest, и запросы ниже ждали полные 7.8 секунды, так что здесь единственный дедлайн это дедлайн SDK. Он считается в секундах и ведёт себя четырьмя способами, которые важны для ожидающего запроса.
Во-первых, дедлайн проверяется, когда подходит время очередного опроса, а не когда он истекает. SDK опрашивает примерно на 0, 0.25, 0.75, 1.75 и 3.75 секунде, затем на 7.75 и после этого каждые 5 секунд, поэтому таймаут 5 заканчивается примерно на 7.8. Замер на имитации, которая никогда не отвечает, на Node.js 24.22.0 (на 20.11.1 результат совпал в пределах 0.1 секунды во всех четырёх строках):
| Параметр timeout | TimeoutException через |
|---|---|
| 5 секунд | 7.82 секунды |
| 10 секунд | 12.83 секунды |
| 20 секунд | 22.82 секунды |
| 30 секунд | 32.86 секунды |
Поэтому давайте каждому вызывающему и каждому прокси перед сервисом таймаут, равный значению SDK плюс как минимум 5 секунд. Через Nest CAPSKIP_TIMEOUT 5 дал ответ 504 через 7.84 секунды.
Во-вторых, turnstile() использует defaultTimeout клиента, 120 секунд, а не recaptchaTimeout, хотя комментарий в определениях типов SDK относит Turnstile к recaptchaTimeout. При defaultTimeout 3 и recaptchaTimeout 30 вызов закончился через 3.81 секунды; при обратных значениях через 32.87. В исходном коде recaptcha читает recaptchaTimeout, а mtcaptcha defaultTimeout, поэтому сервис передаёт параметр timeout в каждом вызове.
В-третьих, вызывающий, который сдался, не останавливает решение: SDK не принимает AbortSignal, а Nest не отменяет обработчик при разрыве соединения. За клиентом supertest, ушедшим на 3.0 секунде, последовал пятый опрос на 3.79 секунде. Единственный тормоз это короткий таймаут, поэтому CAPSKIP_TIMEOUT остаётся небольшим.
В-четвёртых, и это хуже всего: SDK не задаёт таймаут для своих HTTP-запросов и проверяет дедлайн только между опросами. Если CapSkip принял опрос и не отвечает, потому что ПК уснул или брандмауэр отбрасывает пакеты, дедлайн не проверяется никогда. На имитации, которая так себя вела, SDK с timeout 5 всё ещё ждал через 30 секунд. Поэтому сервис ставит вызов SDK в гонку с собственным таймером, на 6 секунд позже дедлайна SDK: при CAPSKIP_TIMEOUT 5 зависший опрос превратился в 504 через 11.0 секунды. Брошенный вызов SDK остаётся в ожидании, поэтому держите гонку и короткий таймаут вместе.
Шаг 4: тесты для сервиса капчи на NestJS
Модульный тест с имитацией клиента
Сохраните это как src/capskip/capskip.service.spec.ts. Test.createTestingModule собирает модуль из настоящего сервиса и двух простых значений: поддельного клиента и поддельных параметров. Его запускает скрипт npm test из каркаса. Тест также покрывает нестроковый результат и таймер на случай зависшего CapSkip.
// src/capskip/capskip.service.spec.ts
import { HttpException } from '@nestjs/common';
import { Test } from '@nestjs/testing';
import { ApiException, NetworkException, TimeoutException, ValidationException } from 'capskip';
import { toHttpException } from './capskip.errors.js';
import { MODULE_OPTIONS_TOKEN } from './capskip.options.js';
import { CAPSKIP_CLIENT, CapSkipService } from './capskip.service.js';
describe('CapSkipService', () => {
const turnstile = vi.fn();
let service: CapSkipService;
beforeEach(async () => {
turnstile.mockReset();
const moduleRef = await Test.createTestingModule({
providers: [
CapSkipService,
{ provide: CAPSKIP_CLIENT, useValue: { turnstile } },
{ provide: MODULE_OPTIONS_TOKEN, useValue: { timeoutSeconds: 20 } },
],
}).compile();
service = moduleRef.get(CapSkipService);
});
it('passes the timeout and returns token and User-Agent', async () => {
turnstile.mockResolvedValue({ captchaId: '7', code: 'tok', userAgent: 'UA' });
await expect(service.solveTurnstile('0xKEY', 'https://example.com/')).resolves.toEqual({
token: 'tok',
userAgent: 'UA',
});
expect(turnstile).toHaveBeenCalledWith('0xKEY', 'https://example.com/', { timeout: 20 });
});
afterEach(() => vi.useRealTimers());
it('refuses a result whose code is not a string', async () => {
turnstile.mockResolvedValue({ captchaId: '7', code: { token: 'x' } });
await expect(service.solveTurnstile('0xKEY', 'https://example.com/')).rejects.toThrow(
'Unexpected CapSkip result',
);
});
it('gives up 6 seconds after the SDK deadline when CapSkip never answers', async () => {
vi.useFakeTimers();
turnstile.mockReturnValue(new Promise(() => {}));
const outcome = expect(service.solveTurnstile('0xKEY', 'https://example.com/')).rejects.toBeInstanceOf(
TimeoutException,
);
await vi.advanceTimersByTimeAsync(26_000);
await outcome;
});
it.each([
[new TimeoutException('timeout 20 exceeded'), 504],
[new NetworkException('connect ECONNREFUSED'), 503],
[new ApiException('ERROR_CAPTCHA_UNSOLVABLE'), 422],
[new ApiException('ERROR_RECAPTCHA_INVALID_SITEKEY'), 400],
[new ApiException('ERROR_WRONG_USER_KEY'), 502],
[new ValidationException('Unsupported parameters'), 500],
])('maps %s to HTTP %i', (err, status) => {
const mapped = toHttpException(err);
expect(mapped).toBeInstanceOf(HttpException);
expect(mapped.getStatus()).toBe(status);
});
});У контроллера есть собственный spec, src/turnstile.controller.spec.ts, потому что случай с пустым списком не требует запущенного приложения.
// src/turnstile.controller.spec.ts
import { BadRequestException } from '@nestjs/common';
import { TurnstileController } from './turnstile.controller.js';
describe('TurnstileController', () => {
const solveTurnstile = vi.fn().mockResolvedValue({ token: 'tok' });
const controller = (hosts?: string) =>
new TurnstileController(
{ solveTurnstile } as never,
{ get: (_name: string, fallback: string) => hosts ?? fallback } as never,
);
const page = { sitekey: '0xKEY', url: 'https://example.com/login' };
beforeEach(() => solveTurnstile.mockClear());
it.each([undefined, '', ' , '])('refuses every request when TARGET_HOSTS is %j', (hosts) => {
expect(() => controller(hosts).solve(page)).toThrow(BadRequestException);
expect(solveTurnstile).not.toHaveBeenCalled();
});
it('accepts a listed host and passes the parsed address on', async () => {
await controller(' example.com , ').solve(page);
expect(solveTurnstile).toHaveBeenCalledWith('0xKEY', 'https://example.com/login');
});
});E2E-тест против имитации CapSkip
Сервис капчи на NestJS нужно тестировать без живого CapSkip, поэтому эта имитация заменяет in.php и res.php. Она слушает порт 0, так что систему выбирает свободный порт, и записывает всё, что получает. Её ответы и задержки это мои правила, а не поведение настоящего CapSkip. Сохраните её как test/mock-capskip.ts.
// test/mock-capskip.ts
import { createServer } from 'node:http';
import type { AddressInfo } from 'node:net';
// A stand-in for CapSkip's in.php and res.php. Not the real app: the
// delay and the replies below are this file's own rules.
export async function startMock(listenPort = 0) {
const mock = {
port: 0,
solveMs: 0, // how long a task stays "not ready"
submitReply: '', // set to ERROR_... to refuse every submit
pollReply: '', // set to ERROR_... to fail every poll
hangPolls: false, // accept a poll and never answer it
submits: [] as Record<string, string>[],
polls: [] as number[], // Date.now() of each res.php call
close: () => {
server.closeAllConnections();
return new Promise<void>((done) => server.close(() => done()));
},
};
let submittedAt = 0;
const server = createServer((req, res) => {
const url = new URL(req.url!, 'http://mock');
let raw = '';
req.on('data', (chunk) => (raw += chunk));
req.on('end', () => {
if (url.pathname === '/in.php') {
mock.submits.push(Object.fromEntries(new URLSearchParams(raw)));
submittedAt = Date.now();
res.end(mock.submitReply || 'OK|7');
} else if (url.pathname === '/res.php') {
mock.polls.push(Date.now());
if (mock.hangPolls) return;
const waiting = Date.now() - submittedAt < mock.solveMs;
if (mock.pollReply) res.end(JSON.stringify({ status: 0, request: mock.pollReply }));
else if (waiting) res.end(JSON.stringify({ status: 0, request: 'CAPCHA_NOT_READY' }));
else res.end(JSON.stringify({ status: 1, request: '0.mock-token', useragent: 'Mock UA' }));
} else {
res.statusCode = 404;
res.end();
}
});
});
await new Promise<void>((ready) => server.listen(listenPort, '127.0.0.1', ready));
mock.port = (server.address() as AddressInfo).port;
return mock;
}E2E-spec запускает настоящий AppModule, направляет переменные окружения на имитацию и отправляет запросы через supertest. Сохраните его как test/turnstile.e2e-spec.ts и запустите npm run test:e2e. Переменные, уже заданные в окружении, приоритетнее .env, поэтому spec может их переопределять.
// test/turnstile.e2e-spec.ts
import { Logger, type INestApplication } from '@nestjs/common';
import { Test } from '@nestjs/testing';
import request from 'supertest';
import { AppModule } from '../src/app.module.js';
import { startMock } from './mock-capskip.js';
describe('POST /captcha/turnstile', () => {
let app: INestApplication;
let mock: Awaited<ReturnType<typeof startMock>>;
const body = { sitekey: '0xKEY', url: 'https://example.com/login' };
beforeAll(async () => {
mock = await startMock();
process.env.CAPSKIP_HOST = '127.0.0.1';
process.env.CAPSKIP_PORT = String(mock.port);
process.env.CAPSKIP_TIMEOUT = '5';
process.env.TARGET_HOSTS = ' example.com, '; // spaces and a trailing comma are harmless
const moduleRef = await Test.createTestingModule({ imports: [AppModule] }).compile();
app = moduleRef.createNestApplication();
await app.init();
});
afterAll(async () => {
await app.close();
await mock.close();
});
beforeEach(() => {
Object.assign(mock, { solveMs: 0, submitReply: '', pollReply: '', hangPolls: false, submits: [], polls: [] });
});
it('returns the token and sends a turnstile task', async () => {
const res = await request(app.getHttpServer()).post('/captcha/turnstile').send(body).expect(201);
expect(res.body).toEqual({ token: '0.mock-token', userAgent: 'Mock UA' });
expect(mock.submits[0]).toMatchObject({ method: 'turnstile', sitekey: '0xKEY', pageurl: body.url });
});
it('refuses a host that is not on the list, before CapSkip is called', async () => {
await request(app.getHttpServer())
.post('/captcha/turnstile')
.send({ ...body, url: 'https://evil.test/' })
.expect(400);
expect(mock.submits).toHaveLength(0);
});
it.each([
{ sitekey: '0xKEY', url: 'http://example.com/login' },
{ sitekey: '0xKEY', url: 'file:///C:/Windows/win.ini' },
{ sitekey: '0xKEY', url: 'not a url' },
{ sitekey: { a: 1 }, url: 'https://example.com/login' },
{ url: 'https://example.com/login' },
])('refuses %j before CapSkip is called', async (bad) => {
await request(app.getHttpServer()).post('/captcha/turnstile').send(bad).expect(400);
expect(mock.submits).toHaveLength(0);
});
it('maps an unsolvable task to 422 and logs one warning', async () => {
const warn = vi.spyOn(Logger.prototype, 'warn');
mock.pollReply = 'ERROR_CAPTCHA_UNSOLVABLE';
const res = await request(app.getHttpServer()).post('/captcha/turnstile').send(body).expect(422);
expect(res.body).toMatchObject({ code: 'ERROR_CAPTCHA_UNSOLVABLE' });
expect(warn).toHaveBeenCalledWith(expect.stringContaining('ERROR_CAPTCHA_UNSOLVABLE'));
warn.mockRestore();
});
it('maps a refused key to 502', async () => {
mock.submitReply = 'ERROR_WRONG_USER_KEY';
await request(app.getHttpServer()).post('/captcha/turnstile').send(body).expect(502);
});
it('answers 504 after the timeout of 5 seconds, not before it', async () => {
mock.solveMs = 60_000;
const started = Date.now();
await request(app.getHttpServer()).post('/captcha/turnstile').send(body).expect(504);
const seconds = (Date.now() - started) / 1000;
expect(seconds).toBeGreaterThan(5);
expect(seconds).toBeLessThan(9);
}, 15_000);
it('answers 504 when CapSkip accepts a poll and never replies', async () => {
mock.hangPolls = true;
const started = Date.now();
await request(app.getHttpServer()).post('/captcha/turnstile').send(body).expect(504);
const seconds = (Date.now() - started) / 1000;
expect(seconds).toBeGreaterThan(10.5);
expect(seconds).toBeLessThan(13);
}, 20_000);
});Вот результаты на имитации и capskip 1.7.0 в Windows 11:
| Среда выполнения | Модульные тесты | E2E-тесты |
|---|---|---|
| Node.js 24.22.0 | 13 пройдено в 2 файлах | 11 пройдено, около 19 с |
| Node.js 25.2.1 | 13 пройдено в 2 файлах | 11 пройдено, около 19 с |
| Node.js 20.11.1 | Команда создания каркаса и Vitest не работают | Команда создания каркаса и Vitest не работают |
На 20.11.1 команда создания каркаса и Vitest останавливаются с ошибкой, что в node:util нет экспорта styleText, которого в этом выпуске нет.
Запуск на другой машине: Server mode
Сервис Nest редко живёт на том же ПК, где работает CapSkip. Укажите адрес этого ПК в CAPSKIP_HOST, и больше ничего не изменится. CapSkip при этом должен работать в Server mode, который описан в разделе Настройки подключения руководства по настройке, где сказано, что для Server mode CapSkip нужно запускать от имени администратора. SDK говорит по обычному http и отправляет ключ в строке запроса каждого вызова res.php, поэтому держите это соединение в частной сети.
CapSkip открывает свой порт для всех адресов, когда запускается Server mode, поэтому, чтобы ограничить доступ ожидаемыми машинами, добавьте для остальных правило блокировки в брандмауэре Windows и включите API Key Validation, чтобы CAPSKIP_API_KEY что-то значил. Если CapSkip не запущен, отправка завершается с NetworkException (в моём запуске это отказ в соединении на 127.0.0.1), и фильтр отвечает 503. Недостижимый адрес (192.0.2.1) заставил SDK сдаться через 21.1 секунды, поэтому сервис ответил 503 примерно через 21 секунду при таймауте 20; при таймауте 5 гонка дала 504 через 11.0 секунды. Эти запуски шли на имитации и Node.js 24.22.0.
Частые ошибки
| Что вы видите | Причина | Исправить |
|---|---|---|
| Nest can’t resolve dependencies of the CapSkipService, argument Symbol(CAPSKIP_CLIENT) at index [0] | В тестовом модуле указан сервис, но нет токена клиента | Добавьте провайдер для CAPSKIP_CLIENT с поддельным клиентом |
| Nest can’t resolve dependencies of the CONFIGURABLE_MODULE_OPTIONS provider, argument ConfigService | forRootAsync внедряет ConfigService, но ConfigModule не глобальный и не импортирован | Передайте imports с ConfigModule или задайте isGlobal в ConfigModule.forRoot |
TypeError: Cannot read properties of undefined (reading "get") | У фабрики есть параметр config, но у forRootAsync нет списка inject | Добавьте inject с ConfigService |
| Nest can’t resolve dependencies of the Symbol(CAPSKIP_CLIENT) provider, argument CONFIGURABLE_MODULE_OPTIONS | CapSkipModule импортирован без forRoot и forRootAsync | Импортируйте результат одного из этих двух вызовов |
| HTTP 502 с кодом ERROR_WRONG_USER_KEY или ERROR_KEY_DOES_NOT_EXIST | В CapSkip включена API Key Validation. Первый код означает, что ключ отсутствует или пуст, второй что он недействителен | Задайте в CAPSKIP_API_KEY действительный ключ, затем перезапустите сервис |
| HTTP 504 спустя долгое время после того, как вы сдались | SDK продолжает опрашивать до своего дедлайна, либо гонка сдалась из-за молчащего CapSkip | Уменьшите CAPSKIP_TIMEOUT и прочитайте шаг 3 |
Четыре сообщения Nest это настоящая формулировка Nest 12.4.2, как её вывел мой тестовый модуль, в сокращённом виде. Коды ошибок CapSkip перечислены в разделе Документация API.
FAQ
Может ли сервис капчи на NestJS работать на другой машине, чем CapSkip?
Да. Задайте в CAPSKIP_HOST адрес ПК с CapSkip и переключите CapSkip в Server mode. В Server mode CapSkip принимает соединения на всех адресах, поэтому добавьте правило блокировки в брандмауэре Windows для неожиданных машин и включите API Key Validation. Менять код не нужно.
Когда стоит использовать очередь вместо контроллера?
Когда вызывающая сторона не может ждать решения или когда их приходит много сразу. Контроллер держит запрос открытым всё время решения, и это нормально для одного-двух запросов за раз. Обработчик очереди может импортировать тот же CapSkipModule, а эту сторону разбирает руководство по воркеру BullMQ.
Почему сервис возвращает User-Agent вместе с токеном?
В типах SDK сказано, что для Turnstile нужно использовать User-Agent из результата при отправке токена, и он присутствует только тогда, когда CapSkip его сообщает. Сервис передаёт его дальше, чтобы вызывающая сторона могла его отправить.
Сервису капчи на NestJS, который должен пройти Turnstile, нужны три вещи в правильных местах: клиент за токеном, чтобы его можно было подменить, одно место, которое превращает ошибки SDK в статусы, и таймаут на каждом вызове плюс гонка на случай молчания. Решает капчу CapSkip: это безлимитный сервис распознавания капчи на вашем собственном оборудовании, поэтому повтор или упавший прогон тестов никогда не попадает в счёт. О решении остальных типов капчи из Node.js читайте на странице сервиса распознавания капчи для Node.js.
