Service NestJS CAPTCHA: Module yang Memecahkan Turnstile

Kebanyakan pencarian tentang NestJS captcha bertujuan melindungi situs Nest dengan captcha. Panduan ini membahas arah sebaliknya: service Anda harus melewati widget Cloudflare Turnstile di halaman yang boleh Anda otomatisasi, dan service itu membutuhkan token. Anda membungkus paket capskip dalam dynamic module, mengubah error-nya menjadi status HTTP, lalu mengujinya dengan Vitest dan supertest. Pemecahan CAPTCHA dilakukan oleh pemecah Turnstile CapSkip yang berjalan di PC Windows milik Anda, tanpa biaya per pemecahan. Tidak ada antrean yang terlibat; untuk pemecahan yang memang perlu antrean, lihat panduan worker BullMQ.
Apa yang Anda butuhkan
- CapSkip di PC Windows Anda. Alamat tempat CapSkip mendengarkan diatur di bagian pengaturan koneksi pada panduan penyiapan: Local mode menjaganya tetap di 127.0.0.1, dan Server mode membukanya ke jaringan Anda.
- Node.js 24.15 atau lebih baru pada jalur 24, atau 26. Generator scaffold meminta 22.22.3, 24.15 atau 26, Vite 8 dan bundler-nya meminta 20.19 atau 22.12, dan Nest 12 sendiri meminta 20. Saya menjalankan proyek ini, dari scaffold sampai pengujian, di 24.22.0 dan 25.2.1, dengan npm menampilkan peringatan engine untuk @nestjs/schematics. Di 20.11.1 perintah scaffold dan Vitest gagal.
- Nest 12 (di sini 12.4.2) dengan @nestjs/config 12.1.1 dan capskip 1.7.0. Scaffold-nya hanya ESM (path import berakhiran .js) dan menguji dengan Vitest, jadi mock-nya berupa vi.fn.
Setiap eksekusi di bawah ini memakai mock in.php dan res.php buatan saya, ditambah paket capskip 1.7.0 yang asli. Tidak ada task yang sampai ke CapSkip asli, jadi saya tidak menyebutkan waktu pemecahan, dan setiap penundaan serta balasan adalah aturan dari mock.
Langkah 1: buat proyek dan pengaturannya
Jalankan ini di PowerShell. Perintah ini membuat scaffold aplikasi, menginstal dua paket, menghapus empat file contoh yang digantikan oleh tata letak baru, dan membuat folder untuk module.
# 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
Jalankan blok berikut di folder proyek. Blok ini menulis .env dan .gitignore tanpa editor, sehingga file tidak bisa terlanjur bernama .env.txt. Scaffold yang dibuat tanpa git tidak punya .gitignore, dan .env akan berisi key Anda, jadi daftarkan di sana sebelum pertama kali memakai git. SDK tidak membaca environment variable sendiri, jadi factory di Step 2 yang membacanya. CAPSKIP_API_KEY hanya berpengaruh bila API Key Validation aktif di CapSkip; jika dikosongkan, SDK mengirim key 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
Step 2: membangun module
Opsi, dijelaskan sekali saja
Simpan blok berikut sebagai src/capskip/capskip.options.ts. Nest menyediakan ConfigurableModuleBuilder yang menghasilkan method statis forRoot dan forRootAsync serta sebuah injection token untuk opsinya. Argumen extras menambahkan flag isGlobal yang tetap berada di module, di luar opsi. Builder ini dijelaskan di bab Nest dynamic modules.
// 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();Service, dengan client di balik sebuah token
Simpan ini sebagai src/capskip/capskip.service.ts. Client SDK tidak dibuat di dalam service. Client itu masuk lewat token CAPSKIP_CLIENT, bertipe satu method SDK yang dipakai service, sehingga sebuah test cukup memberikan satu fungsi dan compiler tetap memeriksa signature-nya.
// 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 dipakai sebagai contoh karena hasilnya membawa User-Agent yang menurut tipe SDK harus dipakai saat Anda mengirim token. Service mengembalikannya bersama token dalam sebuah objek kecil, bukan sebagai hasil mentah SDK, yang field code-nya bertipe string atau objek dan di sini ditolak bila bukan string. Tipe lain mengikuti bentuk yang sama: tambahkan satu method untuk masing-masing recaptcha, hcaptcha atau mtcaptcha, dengan meneruskan timeout, karena alasan di Step 3. Field yang diterima tiap tipe ada di Dokumentasi API.
Error SDK sebagai status HTTP
SDK punya empat kelas exception, semuanya turunan CapSkipError: ValidationException, NetworkException, ApiException dan TimeoutException. ApiException hanya membawa teks balasan CapSkip sebagai message-nya, tanpa field code, jadi pemetaan membaca kode ERROR_ dari message tersebut. Simpan ini sebagai 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);
}
}Filter ini memperluas BaseExceptionFilter dan mendelegasikan, pola yang diperlihatkan oleh bab Nest exception filter dan karena itu berfungsi di adapter HTTP apa pun. Filter hanya menangkap CapSkipError, mencatat satu peringatan berisi nama error dan message-nya (teks balasan CapSkip, tidak pernah key Anda) dan menjaga message mentah itu tetap di luar respons.
| Yang dilemparkan SDK | HTTP | Mengapa status itu |
|---|---|---|
| TimeoutException | 504 | Tidak ada token dalam batas timeout. CapSkip yang diam di antara polling juga berakhir di sini |
| NetworkException | 503 | CapSkip tidak bisa dijangkau saat task dikirim |
| ApiException dengan ERROR_CAPTCHA_UNSOLVABLE | 422 | Tidak terpecahkan. Dokumentasi API CapSkip menyarankan untuk mengirim task baru |
| ApiException dengan ERROR_RECAPTCHA_INVALID_SITEKEY, ERROR_RECAPTCHA_INVALID_DOMAIN, ERROR_BAD_PARAMETERS atau ERROR_PAGEURL | 400 | Pemanggil mengirim sitekey atau alamat halaman yang ditolak CapSkip |
| ApiException dengan ERROR_KEY_DOES_NOT_EXIST, ERROR_WRONG_USER_KEY atau ERROR_ZERO_BALANCE | 502 | Masalahnya ada pada key milik service Anda sendiri, bukan pada input dari pemanggil |
| ValidationException | 500 | SDK menolak sebuah task yang dibuat service ini, yang berarti ada bug di sini |
ApiException lainnya menjadi 502. Module mendaftarkan filter dengan APP_FILTER, jadi setiap aplikasi yang mengimpor module ini mendapat pemetaannya.
Module, aplikasi, dan sebuah controller
Simpan module sebagai src/capskip/capskip.module.ts. Module ini membuat client dari opsi di dalam sebuah factory provider, menambahkan service, dan mendaftarkan filter.
// 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 {}Ganti src/app.module.ts dengan blok berikut. forRootAsync menjalankan factory dengan apa pun yang Anda daftarkan di inject. ConfigModule di sini bersifat global, jadi CapSkipModule menemukan ConfigService tanpa mengimpornya.
// 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 {}Terakhir, simpan src/turnstile.controller.ts. url menentukan halaman mana yang dipecahkan CapSkip, jadi route yang terbuka akan membiarkan siapa pun memakai solver Anda. Pemeriksaan terhadap TARGET_HOSTS adalah syarat minimum: hanya menerima alamat https, merapikan daftarnya, dan menolak setiap permintaan bila daftar kosong atau tidak diatur. Pasang guard autentikasi Anda sendiri di depannya.
// 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);
}
}Step 3: timeout permintaan dan tenggat SDK
Saya tidak mengatur timeout di Nest, dan permintaan di bawah ini menunggu penuh selama 7.8 detik, jadi tenggat SDK adalah satu-satunya di sini. Tenggat dihitung dalam detik dan berperilaku dengan empat cara yang penting bagi permintaan yang sedang menunggu.
Pertama, tenggat diperiksa saat polling berikutnya jatuh tempo, bukan saat tenggat terlewati. SDK melakukan polling pada sekitar 0, 0.25, 0.75, 1.75 dan 3.75 detik, lalu pada 7.75 dan setiap 5 detik setelahnya, jadi timeout 5 berakhir pada sekitar 7.8. Diukur terhadap mock yang tidak pernah menjawab, di Node.js 24.22.0 (20.11.1 cocok dalam selisih 0.1 detik pada keempat baris):
| Opsi timeout | TimeoutException setelah |
|---|---|
| 5 detik | 7.82 detik |
| 10 detik | 12.83 detik |
| 20 detik | 22.82 detik |
| 30 detik | 32.86 detik |
Jadi berikan kepada setiap pemanggil, dan setiap proxy di depannya, timeout sebesar nilai SDK ditambah sedikitnya 5 detik. Lewat Nest, CAPSKIP_TIMEOUT 5 dijawab 504 setelah 7.84 detik.
Kedua, turnstile() memakai defaultTimeout milik client, 120 detik, bukan recaptchaTimeout, padahal sebuah komentar di definisi tipe SDK mencantumkan Turnstile di bawah recaptchaTimeout. Dengan defaultTimeout 3 dan recaptchaTimeout 30, prosesnya berakhir setelah 3.81 detik; ketika ditukar, setelah 32.87. Di source, recaptcha membaca recaptchaTimeout dan mtcaptcha membaca defaultTimeout, jadi service meneruskan opsi timeout pada setiap panggilan.
Ketiga, pemanggil yang menyerah tidak menghentikan pemecahan: SDK tidak menerima AbortSignal dan Nest tidak membatalkan handler saat koneksi terputus. Client supertest yang pergi pada 3.0 detik tetap diikuti polling kelima pada 3.79 detik. Timeout yang pendek adalah satu-satunya rem, jadi CAPSKIP_TIMEOUT dijaga tetap kecil.
Keempat, dan yang terburuk: SDK tidak mengatur timeout pada permintaan HTTP-nya dan memeriksa tenggat hanya di antara polling. Jika CapSkip menerima sebuah polling dan tidak pernah membalas, karena PC tertidur atau firewall menjatuhkan paket, tenggat tidak pernah diperiksa. Terhadap mock yang berbuat begitu, SDK dengan timeout 5 masih tertunda setelah 30 detik. Maka service mengadu panggilan SDK dengan timer-nya sendiri (race), 6 detik setelah tenggat SDK: dengan CAPSKIP_TIMEOUT 5, polling yang menggantung menjadi 504 setelah 11.0 detik. Panggilan SDK yang ditinggalkan tetap tertunda, jadi pertahankan race dan timeout pendek bersama-sama.
Step 4: pengujian untuk service NestJS captcha
Unit test dengan client yang di-mock
Simpan ini sebagai src/capskip/capskip.service.spec.ts. Test.createTestingModule membuat module dari service asli dan dua nilai biasa: client palsu dan opsi palsu. Skrip npm test dari scaffold menjalankannya. Test ini juga mencakup hasil non-string dan timer CapSkip yang menggantung.
// 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);
});
});Controller mendapat spec tersendiri, src/turnstile.controller.spec.ts, karena kasus daftar kosong tidak membutuhkan aplikasi yang berjalan.
// 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');
});
});Test e2e terhadap mock CapSkip
Service NestJS captcha sebaiknya diuji tanpa CapSkip yang hidup, jadi mock ini menggantikan in.php dan res.php. Mock mendengarkan di port 0, sehingga sistem memilih port yang kosong, dan mencatat apa yang diterimanya. Balasan dan penundaannya adalah aturan saya, bukan perilaku CapSkip yang asli. Simpan sebagai 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;
}Spec e2e menjalankan AppModule yang asli, mengarahkan environment variable ke mock, dan mengirim permintaan dengan supertest. Simpan sebagai test/turnstile.e2e-spec.ts dan jalankan npm run test:e2e. Variabel yang sudah ada di environment menang atas .env, sehingga spec bisa menimpanya.
// 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);
});Berikut hasilnya, dengan mock dan capskip 1.7.0, di Windows 11:
| Runtime | Unit test | E2E test |
|---|---|---|
| Node.js 24.22.0 | 13 lulus di 2 file | 11 lulus, sekitar 19 detik |
| Node.js 25.2.1 | 13 lulus di 2 file | 11 lulus, sekitar 19 detik |
| Node.js 20.11.1 | Perintah scaffold dan Vitest gagal | Perintah scaffold dan Vitest gagal |
Di 20.11.1 perintah scaffold dan Vitest berhenti dengan error bahwa node:util tidak punya export bernama styleText, yang tidak disediakan oleh rilis tersebut.
Menjalankannya di mesin lain: Server mode
Service Nest jarang berada di PC yang menjalankan CapSkip. Taruh alamat PC itu di CAPSKIP_HOST dan tidak ada hal lain yang berubah. CapSkip lalu harus dalam Server mode, seperti dijelaskan di pengaturan koneksi pada panduan penyiapan, yang menyebutkan bahwa Server mode mengharuskan CapSkip berjalan sebagai administrator. SDK berbicara dengan http biasa dan mengirim key di query string setiap panggilan res.php, jadi jaga koneksi itu tetap di jaringan privat.
CapSkip membuka port-nya untuk semua alamat saat Server mode dimulai, jadi untuk membatasinya pada mesin yang Anda harapkan, tambahkan aturan blokir Windows Firewall untuk yang lain, dan aktifkan API Key Validation agar CAPSKIP_API_KEY ada artinya. Jika CapSkip tidak berjalan, pengiriman gagal dengan NetworkException (koneksi ditolak di 127.0.0.1 pada eksekusi saya) dan filter menjawab 503. Alamat yang tidak bisa dirutekan (192.0.2.1) membuat SDK menyerah setelah 21.1 detik, sehingga service menjawab 503 setelah sekitar 21 detik dengan timeout 20; dengan timeout 5, race menjawab 504 setelah 11.0 detik. Eksekusi ini memakai mock dan Node.js 24.22.0.
Kesalahan umum
| Apa yang Anda lihat | Penyebab | Perbaiki |
|---|---|---|
| Nest can’t resolve dependencies of the CapSkipService, argument Symbol(CAPSKIP_CLIENT) at index [0] | Sebuah test module mendaftarkan service tetapi tidak token client-nya | Tambahkan provider untuk CAPSKIP_CLIENT dengan sebuah fake |
| Nest can’t resolve dependencies of the CONFIGURABLE_MODULE_OPTIONS provider, argument ConfigService | forRootAsync menyuntikkan ConfigService, tetapi ConfigModule tidak global dan tidak diimpor | Teruskan imports dengan ConfigModule, atau atur isGlobal di ConfigModule.forRoot |
TypeError: Cannot read properties of undefined (reading "get") | Factory punya parameter config tetapi forRootAsync tidak punya daftar inject | Tambahkan inject dengan ConfigService |
| Nest can’t resolve dependencies of the Symbol(CAPSKIP_CLIENT) provider, argument CONFIGURABLE_MODULE_OPTIONS | CapSkipModule diimpor polos, tanpa forRoot atau forRootAsync | Impor hasil dari salah satu dari dua panggilan itu |
| HTTP 502 dengan code ERROR_WRONG_USER_KEY atau ERROR_KEY_DOES_NOT_EXIST | API Key Validation aktif di CapSkip. Code pertama berarti key tidak ada atau kosong, code kedua berarti key tidak valid | Atur CAPSKIP_API_KEY ke key yang valid, lalu mulai ulang service |
| HTTP 504 lama setelah Anda menyerah | SDK terus melakukan polling sampai tenggatnya sendiri, atau race menyerah terhadap CapSkip yang diam | Turunkan CAPSKIP_TIMEOUT dan baca Step 3 |
Keempat message Nest adalah kata-kata asli Nest 12.4.2 seperti dicetak oleh test module saya, dengan sedikit dipersingkat. Kode error CapSkip tercantum di Dokumentasi API.
FAQ
Bisakah service NestJS captcha berjalan di mesin yang berbeda dari CapSkip?
Bisa. Atur CAPSKIP_HOST ke alamat PC CapSkip dan alihkan CapSkip ke Server mode. Server mode membuat CapSkip menerima koneksi di semua alamat, jadi tambahkan aturan blokir Windows Firewall untuk mesin yang tidak Anda harapkan dan aktifkan API Key Validation. Tidak perlu mengubah kode.
Kapan saya sebaiknya memakai queue, bukan controller?
Saat pemanggil tidak bisa menunggu sebuah pemecahan, atau saat banyak yang datang bersamaan. Controller menahan permintaan terbuka selama seluruh pemecahan, yang tidak masalah untuk satu atau dua sekaligus. Queue processor bisa mengimpor CapSkipModule yang sama, dan panduan worker BullMQ membahas sisi itu.
Mengapa service mengembalikan User-Agent di samping token?
Tipe SDK menyebutkan bahwa untuk Turnstile, User-Agent pada hasilnya adalah yang harus dipakai saat Anda mengirim token, dan nilai itu ada hanya bila CapSkip melaporkannya. Service meneruskannya agar pemanggil bisa mengirimnya.
Service NestJS captcha yang harus melewati Turnstile membutuhkan tiga hal di tempat yang tepat: client di balik sebuah token agar bisa dipalsukan, satu tempat yang mengubah error SDK menjadi status, dan timeout pada setiap panggilan ditambah race untuk kasus yang diam. CapSkip adalah pemecah captcha tanpa batas yang berjalan di perangkat milik Anda, jadi percobaan ulang atau eksekusi test yang gagal tidak pernah muncul di tagihan. Pemecahan jenis CAPTCHA lain dari Node.js dibahas di halaman pemecah CAPTCHA Node.js.
