NestJS CAPTCHA Servisi: Turnstile Çözen Bir Modül

nestjs captcha - NestJS CAPTCHA Service: A Module That Solves Turnstile

NestJS captcha arayanların çoğu, bir Nest sitesini captcha ile korumak ister. Bu kılavuz ters yönü anlatır: sizin bir servisiniz, otomatikleştirmenize izin verilen bir sayfadaki Cloudflare Turnstile widget’ını geçmek zorunda ve bunun için bir token’a ihtiyaç duyuyor. capskip paketini bir dynamic module içine sarar, hatalarını HTTP durum kodlarına çevirir ve Vitest ile supertest kullanarak test edersiniz. Çözme işini CapSkip Turnstile çözücü üstlenir; sahibi olduğunuz bir Windows bilgisayarında çalışır ve çözüm başına ücret almaz. Kuyruk kullanılmaz; kuyruğa ait çözümler şurada ele alınır: BullMQ worker kılavuzu.

Neye ihtiyacınız var

  • Windows bilgisayarınızdaki CapSkip. Hangi adresi dinleyeceği bağlantı ayarları bölümünde seçilir; bu bölüm şu kılavuzda yer alır: kurulum kılavuzu: Local mode onu 127.0.0.1 üzerinde tutar, Server mode ise ağınıza açar.
  • Node.js 24 hattında 24.15 veya daha yenisi ya da 26. Scaffold üreticisi 22.22.3, 24.15 veya 26 ister; Vite 8 ve paketleyicisi 20.19 veya 22.12, Nest 12’nin kendisi ise 20 ister. Projeyi scaffold’dan testlere kadar 24.22.0 ve 25.2.1 üzerinde çalıştırdım; orada npm, @nestjs/schematics için bir engine uyarısı yazdırdı. 20.11.1 üzerinde scaffold komutu ve Vitest hata verir.
  • Nest 12 (burada 12.4.2), @nestjs/config 12.1.1 ve capskip 1.7.0. Scaffold yalnızca ESM kullanır (import yolları .js ile biter) ve Vitest ile test eder; bu yüzden mock’lar vi.fn olur.

Aşağıdaki her çalıştırmada kendi yazdığım bir in.php ve res.php mock’unu ve gerçek capskip 1.7.0 paketini kullandım. Hiçbir görev gerçek bir CapSkip’e ulaşmadı; bu yüzden bir çözüm süresi vermiyorum ve her gecikme ile yanıt mock’un kuralıdır.

1. Adım: projeyi ve ayarları oluşturun

Bunu PowerShell’de çalıştırın. Uygulamanın scaffold’ını oluşturur, iki paketi kurar, yeni düzenin yerine geçtiği dört örnek dosyayı siler ve modül için klasörü yaratır.

# 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

Sonraki bloğu proje klasöründe çalıştırın. .env ve .gitignore dosyalarını bir düzenleyici kullanmadan yazar; böylece dosyanın adı .env.txt olarak kalamaz. git olmadan oluşturulan bir scaffold’da .gitignore yoktur ve .env anahtarınızı tutacaktır; bu yüzden git’i ilk kullanmadan önce onu oraya ekleyin. SDK ortam değişkenlerinin hiçbirini kendisi okumaz; bu yüzden 2. Adım’daki factory bunları okur. CAPSKIP_API_KEY yalnızca CapSkip’te API Key Validation açıksa önem taşır; verilmezse SDK capskip anahtarını gönderir.

# 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. Adım: modülü oluşturun

Seçenekler, tek seferde anlatılır

Sonraki bloğu src/capskip/capskip.options.ts olarak kaydedin. Nest, statik forRoot ve forRootAsync metotlarını ve seçenekler için bir injection token’ı üreten bir ConfigurableModuleBuilder ile gelir. extras argümanı, seçeneklerin dışında, modülde kalan bir isGlobal bayrağı ekler. Builder şurada anlatılır: Nest dynamic modules bölümü.

// 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();

Servis ve token arkasındaki istemci

Bunu src/capskip/capskip.service.ts olarak kaydedin. SDK istemcisi servisin içinde oluşturulmaz. CAPSKIP_CLIENT token’ı üzerinden gelir ve servisin kullandığı tek SDK metodu olarak tiplenir; böylece bir test tek bir fonksiyon verebilir ve derleyici imzayı yine denetler.

// 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);
    }
  }
}

Örnek olarak Turnstile seçildi, çünkü sonucu, SDK tiplerinin token’ı gönderirken kullanmanızı söylediği bir User-Agent taşır. Servis bunu token ile birlikte, ham SDK sonucu olarak değil küçük bir nesne olarak döndürür; ham sonucun code alanı string ya da nesne olarak tiplenmiştir ve string değilse burada reddedilir. Diğer türler aynı biçimi izler: 3. Adım’daki nedenden dolayı timeout’u vererek recaptcha, hcaptcha veya mtcaptcha için birer metot ekleyin. Her türün aldığı alanlar şurada: API belgeleri.

SDK hataları HTTP durum kodları olarak

SDK’nın hepsi CapSkipError’ı genişleten dört exception sınıfı vardır: ValidationException, NetworkException, ApiException ve TimeoutException. Bir ApiException, mesajı olarak yalnızca CapSkip’in yanıt metnini taşır ve code alanı yoktur; bu yüzden eşleme ERROR_ kodunu mesajın içinden okur. Bunu src/capskip/capskip.errors.ts olarak kaydedin.

// 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);
  }
}

Filtre BaseExceptionFilter’ı genişletir ve işi ona devreder; bu, her HTTP adaptöründe çalışması için Nest exception filter bölümünün gösterdiği kalıptır. Yalnızca CapSkipError’ı yakalar, hata adı ve mesajıyla tek bir uyarı loglar (CapSkip’in yanıt metni, anahtarınız asla) ve bu ham mesajı yanıtın dışında tutar.

SDK’nın verdiği hataHTTPBu durum kodu neden
TimeoutException504Zaman aşımı içinde token gelmedi. Yoklamalar arasında sessizleşen bir CapSkip de burada biter
NetworkException503Görev gönderilirken CapSkip’e ulaşılamadı
ERROR_CAPTCHA_UNSOLVABLE içeren ApiException422Çözülemedi. CapSkip API belgeleri yeni bir görev göndermeyi söyler
ApiException ile ERROR_RECAPTCHA_INVALID_SITEKEY, ERROR_RECAPTCHA_INVALID_DOMAIN, ERROR_BAD_PARAMETERS veya ERROR_PAGEURL400Çağıran, CapSkip’in reddettiği bir sitekey veya sayfa adresi gönderdi
ApiException ile ERROR_KEY_DOES_NOT_EXIST, ERROR_WRONG_USER_KEY veya ERROR_ZERO_BALANCE502Sorun, çağıranın girdisi değil, servisinizin kendi anahtarıdır
ValidationException500SDK, bu servisin oluşturduğu bir görevi reddetti; bu burada bir hatadır

Diğer her ApiException 502 olur. Modül filtreyi APP_FILTER ile kaydeder; bu yüzden modülü içe aktaran her uygulama eşlemeyi alır.

Modül, uygulama ve bir controller

Modülü src/capskip/capskip.module.ts olarak kaydedin. İstemciyi, bir factory provider içinde seçeneklerden oluşturur, servisi ekler ve filtreyi kaydeder.

// 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 dosyasını sonraki blokla değiştirin. forRootAsync, factory’yi inject içinde listelediğiniz her şeyle çalıştırır. ConfigModule burada global olduğu için CapSkipModule, onu içe aktarmadan ConfigService’i bulur.

// 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 {}

Son olarak src/turnstile.controller.ts dosyasını kaydedin. CapSkip’in hangi sayfa için çözeceğine url karar verir; bu yüzden açık bir route, herkesin çözücünüzü harcamasına izin verirdi. TARGET_HOSTS denetimi asgari önlemdir: yalnızca https adreslerini kabul eder, listeyi kırpar ve liste boş ya da tanımsızsa her isteği reddeder. Önüne kendi kimlik doğrulama guard’ınızı koyun.

// 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. Adım: istek timeout’u ve SDK süre sınırı

Nest’te hiçbir timeout ayarlamadım ve aşağıdaki istekler tam 7,8 saniye boyunca bekledi; yani burada tek süre sınırı SDK’nınkidir. Saniye cinsinden sayılır ve bekleyen bir istek için önemli olan dört biçimde davranır.

Birincisi, süre sınırı sona erdiğinde değil, bir sonraki yoklama vakti geldiğinde denetlenir. SDK yaklaşık 0; 0,25; 0,75; 1,75 ve 3,75 saniyede yoklar, sonra 7,75’te ve bundan sonra her 5 saniyede bir; bu yüzden 5’lik bir timeout yaklaşık 7,8’de biter. Hiç yanıt vermeyen bir mock’a karşı, Node.js 24.22.0 üzerinde ölçüldü (20.11.1, dört satırın hepsinde 0,1 saniye içinde uyuştu):

Timeout seçeneğiTimeoutException şu sürede
5 saniye7,82 saniye
10 saniye12,83 saniye
20 saniye22,82 saniye
30 saniye32,86 saniye

Bu yüzden her çağırana ve öndeki her proxy’ye, SDK değeri artı en az 5 saniyelik bir timeout verin. Nest üzerinden CAPSKIP_TIMEOUT 5, 7,84 saniye sonra 504 döndürdü.

İkincisi, turnstile() recaptchaTimeout’u değil, istemcinin defaultTimeout değerini, yani 120 saniyeyi kullanır; oysa SDK tip tanımlarındaki bir yorum Turnstile’ı recaptchaTimeout altında sayar. defaultTimeout 3 ve recaptchaTimeout 30 iken 3,81 saniye sonra bitti; yer değiştirince 32,87 sonra. Kaynakta recaptcha, recaptchaTimeout’u okur; mtcaptcha ise defaultTimeout’u. Bu yüzden servis her çağrıda timeout seçeneğini kendisi verir.

Üçüncüsü, vazgeçen bir çağıran çözümü durdurmaz: SDK bir AbortSignal almaz ve Nest, bağlantı koptuğunda bir handler’ı iptal etmez. 3,0 saniyede ayrılan bir supertest istemcisinin ardından 3,79 saniyede beşinci bir yoklama geldi. Tek fren kısa bir timeout’tur; bu yüzden CAPSKIP_TIMEOUT küçük kalır.

Dördüncüsü ve en kötüsü: SDK HTTP isteklerine timeout koymaz ve süre sınırını yalnızca yoklamalar arasında denetler. CapSkip bir yoklamayı kabul edip hiç yanıt vermezse, çünkü bilgisayar uyudu ya da bir güvenlik duvarı paketleri düşürüyor, süre sınırı hiç denetlenmez. Bunu yapan bir mock’a karşı, timeout 5 olan SDK 30 saniye sonra hâlâ beklemedeydi. Bu yüzden servis, SDK çağrısını kendi zamanlayıcısıyla yarıştırır; zamanlayıcı SDK süre sınırından 6 saniye sonradır: CAPSKIP_TIMEOUT 5 iken takılan yoklama 11,0 saniye sonra 504 oldu. Bırakılan SDK çağrısı beklemede kalır; bu yüzden yarışı ve kısa bir timeout’u birlikte tutun.

4. Adım: NestJS captcha servisi için testler

Mock bir istemciyle birim testi

Bunu src/capskip/capskip.service.spec.ts olarak kaydedin. Test.createTestingModule, gerçek servisten ve iki düz değerden (sahte bir istemci ve sahte seçenekler) bir modül kurar. Scaffold’ın npm test script’i onu çalıştırır. String olmayan bir sonucu ve takılan CapSkip zamanlayıcısını da kapsar.

// 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’ın kendi spec’i vardır, src/turnstile.controller.spec.ts, çünkü boş liste durumu çalışan bir uygulama gerektirmez.

// 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');
  });
});

Mock bir CapSkip’e karşı e2e testi

Bir NestJS captcha servisi canlı bir CapSkip olmadan test edilmelidir; bu yüzden bu mock, in.php ve res.php yerine geçer. 0 numaralı portu dinler, yani sistem boş bir port seçer, ve aldığı her şeyi kaydeder. Yanıtları ve gecikmeleri benim kurallarımdır, gerçek bir CapSkip’in davranışı değil. Bunu test/mock-capskip.ts olarak kaydedin.

// 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’i gerçek AppModule’ü başlatır, ortam değişkenlerini mock’a yönlendirir ve istekleri supertest ile gönderir. Bunu test/turnstile.e2e-spec.ts olarak kaydedin ve npm run test:e2e çalıştırın. Ortamda zaten bulunan değişkenler .env’e üstün gelir; bu yüzden spec bunları geçersiz kılabilir.

// 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);
});

Sonuçlar şöyle; mock ve capskip 1.7.0 ile, Windows 11 üzerinde:

Çalışma zamanıBirim testleriE2E testleri
Node.js 24.22.02 dosyada 13 geçti11 geçti, yaklaşık 19 sn
Node.js 25.2.12 dosyada 13 geçti11 geçti, yaklaşık 19 sn
Node.js 20.11.1Scaffold komutu ve Vitest hata verirScaffold komutu ve Vitest hata verir

20.11.1 üzerinde scaffold komutu ve Vitest, o sürümün sağlamadığı node:util içinde styleText adlı bir export bulunmadığını söyleyen bir hatayla durur.

Başka bir makinede çalıştırmak: Server mode

Bir Nest servisi nadiren CapSkip’i çalıştıran bilgisayarda durur. O bilgisayarın adresini CAPSKIP_HOST içine yazın, başka hiçbir şey değişmez. CapSkip bu durumda Server mode’da olmalıdır; bu, kurulum kılavuzunun bağlantı ayarları bölümünde anlatılır ve orada Server mode için CapSkip’in yönetici olarak çalışması gerektiği söylenir. SDK düz http konuşur ve anahtarı her res.php çağrısının sorgu dizesinde gönderir; bu yüzden o bağlantıyı özel bir ağda tutun.

Server mode başladığında CapSkip portunu her adrese açar; bu yüzden onu beklediğiniz makinelerle sınırlamak için diğerleri için bir Windows Firewall engelleme kuralı ekleyin ve CAPSKIP_API_KEY bir anlam taşısın diye API Key Validation’ı açın. CapSkip çalışmıyorsa gönderim bir NetworkException ile başarısız olur (benim çalıştırmamda 127.0.0.1 üzerinde reddedilen bir bağlantı) ve filtre 503 döndürür. Yönlendirilemeyen bir adres (192.0.2.1), SDK’nın 21,1 saniye sonra pes etmesine yol açtı; bu yüzden timeout 20 iken servis yaklaşık 21 saniye sonra 503 döndürdü; timeout 5 iken yarış 11,0 saniye sonra 504 döndürdü. Bu çalıştırmalarda mock ve Node.js 24.22.0 kullanıldı.

Yaygın hatalar

GördüğünüzNedenDüzeltme
Nest can’t resolve dependencies of the CapSkipService, argument Symbol(CAPSKIP_CLIENT) at index [0]Bir test modülü servisi listeliyor ama client token’ını listelemiyorCAPSKIP_CLIENT için sahte bir değerle bir provider ekleyin
Nest can’t resolve dependencies of the CONFIGURABLE_MODULE_OPTIONS provider, argument ConfigServiceforRootAsync ConfigService’i enjekte eder, ama ConfigModule ne global ne de içe aktarılmışConfigModule ile imports verin ya da ConfigModule.forRoot içinde isGlobal ayarlayın
TypeError: Cannot read properties of undefined (reading "get")Factory’nin bir config parametresi var ama forRootAsync’te inject listesi yokConfigService ile inject ekleyin
Nest can’t resolve dependencies of the Symbol(CAPSKIP_CLIENT) provider, argument CONFIGURABLE_MODULE_OPTIONSCapSkipModule, forRoot veya forRootAsync olmadan çıplak olarak içe aktarılmışBu iki çağrıdan birinin sonucunu içe aktarın
ERROR_WRONG_USER_KEY veya ERROR_KEY_DOES_NOT_EXIST kodlu HTTP 502CapSkip’te API Key Validation açık. İlk kod anahtarın eksik veya boş olduğu, ikincisi geçersiz olduğu anlamına gelirCAPSKIP_API_KEY değerini geçerli bir anahtara ayarlayın, sonra servisi yeniden başlatın
Siz vazgeçtikten çok sonra HTTP 504SDK kendi süre sınırına kadar yoklamaya devam eder ya da yarış, sessiz bir CapSkip’ten vazgeçmiştirCAPSKIP_TIMEOUT değerini düşürün ve 3. Adım’ı okuyun

Dört Nest mesajı, test modülümün yazdırdığı gibi Nest 12.4.2’nin gerçek ifadesidir; kısaltılmıştır. CapSkip hata kodları şurada listelenir: API belgeleri.

FAQ

Bir NestJS captcha servisi, CapSkip’ten farklı bir makinede çalışabilir mi?

Evet. CAPSKIP_HOST değerini CapSkip bilgisayarının adresine ayarlayın ve CapSkip’i Server mode’a geçirin. Server mode, CapSkip’in her adresten bağlantı kabul etmesini sağlar; bu yüzden beklemediğiniz makineler için bir Windows Firewall engelleme kuralı ekleyin ve API Key Validation’ı açın. Kodda değişiklik gerekmez.

Controller yerine ne zaman kuyruk kullanmalıyım?

Çağıran bir çözümü bekleyemediğinde ya da çok sayıda çözüm aynı anda geldiğinde. Bir controller, isteği çözümün tamamı boyunca açık tutar; bu, aynı anda bir ya da iki istek için sorun değildir. Bir kuyruk işlemcisi aynı CapSkipModule’ü içe aktarabilir ve bu tarafı BullMQ worker kılavuzu anlatır.

Servis neden token’ın yanında bir User-Agent döndürüyor?

SDK tipleri, Turnstile için sonucun User-Agent değerinin token’ı gönderirken kullanılacak değer olduğunu söyler ve bu değer yalnızca CapSkip bir tane bildirirse bulunur. Servis, çağıranın gönderebilmesi için onu iletir.

Turnstile’ı geçmesi gereken bir NestJS captcha servisinin üç şeyi doğru yerde olmalıdır: sahte olabilmesi için token arkasındaki istemci, SDK hatalarını durum kodlarına çeviren tek bir yer ve her çağrıda bir timeout ile sessiz durum için bir yarış. CapSkip, sahibi olduğunuz donanımda çalışan bir sınırsız captcha çözücü olduğu için bir yeniden deneme ya da başarısız bir test çalıştırması faturada asla görünmez. Diğer CAPTCHA türlerini Node.js’ten çözmek için şuraya gidin: Node.js CAPTCHA çözücü sayfasına.