Add seed collection admin endpoint

This commit is contained in:
dahyeon committed 2026-07-03 03:27:52 -07:00
1 parent ce00bc84b5
commit 56f10f7c29
3 files changed
+198 -1

No files matched your search

@@ -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<AnalysisRequestAcceptedDto> {
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<string, unknown> {
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<Record<SeedSource, number>> | 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<Record<SeedSource, number>> = {};
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<void> {
const actualToken = this.extractBearerToken(request);
if (!actualToken) {
throw new UnauthorizedException('Admin token is required.');
}
let expectedToken: string;
try {
expectedToken = await this.secretService.get<string>('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);
}
}
+71
View File
@@ -24,6 +24,7 @@ describe('AppController (e2e)', () => {
let app: INestApplication<App>;
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([
[
+13
View File
@@ -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 <ADMIN_API_TOKEN>`. 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 해소)