From 56f10f7c2912282f7e3809389236d5f8baef808e Mon Sep 17 00:00:00 2001 From: dahyeon Date: Fri, 3 Jul 2026 03:27:52 -0700 Subject: [PATCH] Add seed collection admin endpoint --- .../modules/analysis/analysis.controller.ts | 115 +++++++++++++++++- apps/api/test/app.e2e-spec.ts | 71 +++++++++++ docs/PLAN.md | 13 ++ 3 files changed, 198 insertions(+), 1 deletion(-) diff --git a/apps/api/src/modules/analysis/analysis.controller.ts b/apps/api/src/modules/analysis/analysis.controller.ts index a246b82..464b6c0 100644 --- a/apps/api/src/modules/analysis/analysis.controller.ts +++ b/apps/api/src/modules/analysis/analysis.controller.ts @@ -8,6 +8,7 @@ import { Post, Query, Req, + UnauthorizedException, } from '@nestjs/common'; import type { AnalysisJobStatusDto, @@ -20,6 +21,8 @@ import { toRegionalRoute, type RiotPlatformRoute, } from '../riot/riot.types'; +import { SecretService } from '../global/secret/secret.service'; +import { SEED_SOURCES, type SeedSource } from '../global/database/schemas'; import { AnalysisQueueService } from './analysis-queue.service'; import { DEFAULT_ANALYSIS_MATCH_COUNT, @@ -28,8 +31,14 @@ import { } from './analysis.constants'; import { AnalysisReadService } from './analysis-read.service'; import { AnalysisRequestThrottleService } from './analysis-request-throttle.service'; -import type { UserAnalysisJobData } from './analysis.types'; +import type { + SeedCollectionJobData, + UserAnalysisJobData, +} from './analysis.types'; import type { Request } from 'express'; +import { createHash, timingSafeEqual } from 'node:crypto'; + +const MAX_ADMIN_SEED_COLLECTION_SOURCE_LIMIT = 200; @Controller() export class AnalysisController { @@ -37,6 +46,7 @@ export class AnalysisController { private readonly analysisQueueService: AnalysisQueueService, private readonly analysisReadService: AnalysisReadService, private readonly analysisRequestThrottleService: AnalysisRequestThrottleService, + private readonly secretService: SecretService, ) {} @Post('analysis/request') @@ -52,6 +62,18 @@ export class AnalysisController { return this.analysisQueueService.enqueueUserAnalysis(data); } + @Post('admin/seed-collection/request') + @HttpCode(202) + public async requestSeedCollection( + @Body() body: unknown, + @Req() request: Request, + ): Promise { + await this.assertAdminRequest(request); + return this.analysisQueueService.enqueueSeedCollection( + this.parseSeedCollectionRequest(body), + ); + } + @Get('analysis/jobs/:jobId') public async getJobStatus( @Param('jobId') jobId: string, @@ -105,6 +127,19 @@ export class AnalysisController { }; } + private parseSeedCollectionRequest(body: unknown): SeedCollectionJobData { + const record = body === undefined ? {} : this.requireRecord(body); + const platformRoute = this.parsePlatformRoute(record.platform ?? 'kr'); + const queueId = this.parseSeedCollectionQueueId(record.queueId); + const sourceLimits = this.parseSeedSourceLimits(record.sourceLimits); + + return { + platformRoute, + queueId, + ...(sourceLimits ? { sourceLimits } : {}), + }; + } + private requireRecord(value: unknown): Record { if (typeof value !== 'object' || value === null || Array.isArray(value)) { throw new BadRequestException('Request body must be an object.'); @@ -165,6 +200,18 @@ export class AnalysisController { return queueId; } + private parseSeedCollectionQueueId(value: unknown): number { + if (value === undefined) return 420; + if ( + typeof value !== 'number' || + !Number.isInteger(value) || + value !== 420 + ) { + throw new BadRequestException('queueId is unsupported.'); + } + return value; + } + private parseSimilarPlayersLimit(value?: string): number { if (value === undefined) return 10; const limit = Number(value); @@ -174,7 +221,73 @@ export class AnalysisController { return Math.min(limit, 10); } + private parseSeedSourceLimits( + value: unknown, + ): Partial> | undefined { + if (value === undefined) { + return undefined; + } + if (typeof value !== 'object' || value === null || Array.isArray(value)) { + throw new BadRequestException('sourceLimits must be an object.'); + } + + const sourceLimits: Partial> = {}; + for (const [source, limit] of Object.entries(value)) { + if (!SEED_SOURCES.includes(source as SeedSource)) { + throw new BadRequestException(`sourceLimits.${source} is unsupported.`); + } + if ( + typeof limit !== 'number' || + !Number.isInteger(limit) || + limit < 0 || + limit > MAX_ADMIN_SEED_COLLECTION_SOURCE_LIMIT + ) { + throw new BadRequestException( + `sourceLimits.${source} must be an integer between 0 and ${MAX_ADMIN_SEED_COLLECTION_SOURCE_LIMIT}.`, + ); + } + sourceLimits[source as SeedSource] = limit; + } + + return sourceLimits; + } + private resolveClientKey(request: Request): string { return request.ip || request.socket.remoteAddress || 'unknown-client'; } + + private async assertAdminRequest(request: Request): Promise { + const actualToken = this.extractBearerToken(request); + if (!actualToken) { + throw new UnauthorizedException('Admin token is required.'); + } + + let expectedToken: string; + try { + expectedToken = await this.secretService.get('ADMIN_API_TOKEN'); + } catch { + throw new UnauthorizedException('Admin token is not configured.'); + } + + if (!this.secureTokenEquals(actualToken, expectedToken)) { + throw new UnauthorizedException('Admin token is invalid.'); + } + } + + private extractBearerToken(request: Request): string | null { + const authorization = request.headers.authorization; + if (!authorization) return null; + const match = authorization.match(/^Bearer\s+(.+)$/i); + return match ? match[1]?.trim() || null : null; + } + + private secureTokenEquals( + actualToken: string, + expectedToken: string, + ): boolean { + if (expectedToken.length === 0) return false; + const actualHash = createHash('sha256').update(actualToken).digest(); + const expectedHash = createHash('sha256').update(expectedToken).digest(); + return timingSafeEqual(actualHash, expectedHash); + } } diff --git a/apps/api/test/app.e2e-spec.ts b/apps/api/test/app.e2e-spec.ts index 86388f0..1a08c69 100644 --- a/apps/api/test/app.e2e-spec.ts +++ b/apps/api/test/app.e2e-spec.ts @@ -24,6 +24,7 @@ describe('AppController (e2e)', () => { let app: INestApplication; let analysisQueueService: { enqueueUserAnalysis: jest.Mock; + enqueueSeedCollection: jest.Mock; }; let similarPlayerService: { findSimilarPlayers: jest.Mock; @@ -43,6 +44,7 @@ describe('AppController (e2e)', () => { beforeEach(async () => { analysisQueueService = { enqueueUserAnalysis: jest.fn(), + enqueueSeedCollection: jest.fn(), }; similarPlayerService = { findSimilarPlayers: jest.fn(), @@ -65,6 +67,9 @@ describe('AppController (e2e)', () => { if (key === 'REDIS_URL') { return Promise.resolve('redis://localhost:6379/0'); } + if (key === 'ADMIN_API_TOKEN') { + return Promise.resolve('admin-token'); + } return Promise.resolve(''); }), ready: jest.fn().mockResolvedValue(undefined), @@ -198,6 +203,72 @@ describe('AppController (e2e)', () => { .expect(429); }); + it('/api/admin/seed-collection/request (POST) validates admin token and enqueues seed collection', async () => { + analysisQueueService.enqueueSeedCollection.mockResolvedValue({ + jobId: 'seed-job-1', + status: 'queued', + }); + + await request(app.getHttpServer()) + .post('/api/admin/seed-collection/request') + .set('Authorization', 'Bearer admin-token') + .send({ + platform: 'kr', + sourceLimits: { + challenger: 0, + grandmaster: 25, + master: 0, + }, + }) + .expect(202) + .expect({ + jobId: 'seed-job-1', + status: 'queued', + }); + + expect(analysisQueueService.enqueueSeedCollection).toHaveBeenCalledWith({ + platformRoute: 'kr', + queueId: 420, + sourceLimits: { + challenger: 0, + grandmaster: 25, + master: 0, + }, + }); + }); + + it('/api/admin/seed-collection/request (POST) rejects missing admin token', async () => { + await request(app.getHttpServer()) + .post('/api/admin/seed-collection/request') + .send({ + sourceLimits: { + grandmaster: 25, + }, + }) + .expect(401); + + expect(analysisQueueService.enqueueSeedCollection).not.toHaveBeenCalled(); + }); + + it.each([ + ['unsupported source', { sourceLimits: { diamond: 10 } }], + ['negative source limit', { sourceLimits: { grandmaster: -1 } }], + ['fractional source limit', { sourceLimits: { grandmaster: 1.5 } }], + ['oversized source limit', { sourceLimits: { grandmaster: 201 } }], + ['unsupported queue', { queueId: 440 }], + ])( + '/api/admin/seed-collection/request (POST) rejects %s', + async (_label, body) => { + await request(app.getHttpServer()) + .post('/api/admin/seed-collection/request') + .set('Authorization', 'Bearer admin-token') + .send(body) + .expect(400); + + expect(analysisQueueService.enqueueSeedCollection).not.toHaveBeenCalled(); + }, + ); + it('/api/analysis/jobs/:jobId (GET) returns job statuses', async () => { const records = new Map([ [ diff --git a/docs/PLAN.md b/docs/PLAN.md index 4f82ede..bba7110 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -70,6 +70,7 @@ web (Riot ID 입력) - `RIOT_API_KEY` — Riot 개발자 포털 development key - `MONGODB_CONNECTION_STRING` — Atlas 클러스터 SRV 연결 문자열 - `REDIS_URL` (또는 기존 `REDIS_ENDPOINT`/`REDIS_PASSWORD / REDIS_USERID` 조합 — `RedisModule`이 둘 다 지원) +- `ADMIN_API_TOKEN` — 운영용 백그라운드 잡 enqueue endpoint 보호용 bearer token - `MONGODB_AUTO_INDEX=true` (dev만 — 스키마 선언 인덱스 자동 생성. prod는 인덱스 수동 생성) 로컬 인프라: MongoDB는 Atlas를 그대로 사용하므로 로컬 컨테이너 불필요. Redis가 로컬에 없으면 `compose.dev.yaml`(redis 단일 서비스)을 추가해 사용한다. @@ -771,6 +772,18 @@ DB 스키마가 이 단계를 미리 견디도록 상세화한 스펙이다. 구 - `account`에 `isSeed: true`, `seedSource`(challenger/grandmaster/master), `seedAddedAt`, `lastSeedCollectedAt` 기록 - 별도 저우선순위 BullMQ 큐 `seed-collection`(concurrency 1)로 수집. 유저 분석 잡(`analysis`)이 항상 우선하도록 rate limiter를 공유 - seed 유저도 **동일한 파이프라인**(stage 3~5)으로 `player_match_feature`/`player_profile` 생성 — 별도 코드 경로를 만들지 않는다 +- 운영 트리거: `POST /api/admin/seed-collection/request` with `Authorization: Bearer `. body 예시: + ```json + { + "platform": "kr", + "sourceLimits": { + "challenger": 0, + "grandmaster": 50, + "master": 0 + } + } + ``` + `sourceLimits`를 생략하면 challenger/grandmaster/master 각각 기본 50명, 특정 source를 끄려면 명시적으로 `0`을 보낸다. - **스토리지 예산 주의**: timeline 원본은 경기당 약 2MB(실측 2.3MB)라 seed 수집(중복 제거 후 수천 경기)이면 수 GB로 Atlas M0(512MB)를 초과한다. MVP 1~2(개인 계정 수십 경기)는 M0로 충분하지만, **MVP 3 착수 전에 ① 클러스터 상향 또는 ② feature 추출 완료 후 `riot_match.timeline` 원본 삭제(derived만 보존) 정책을 결정**해야 한다. ②를 대비해 재계산 잡은 timeline 부재를 결측으로 처리하도록 이미 설계되어 있다(§11.9) ### 12.2 Percentile 정규화 도입 (§5.3 TODO 해소)