Add analysis pipeline
This commit is contained in:
1 parent
256d776131
commit
770c198ccd
20 files changed
+2572
-1
No files matched your search
@@ -20,11 +20,13 @@
|
||||
},
|
||||
"dependencies": {
|
||||
"@infisical/sdk": "^5.0.2",
|
||||
"@nestjs/bullmq": "^11.0.4",
|
||||
"@nestjs/common": "^11.0.1",
|
||||
"@nestjs/config": "^4.0.4",
|
||||
"@nestjs/core": "^11.0.1",
|
||||
"@nestjs/platform-express": "^11.0.1",
|
||||
"@persona-lenz/shared": "workspace:*",
|
||||
"bullmq": "^5.79.2",
|
||||
"mongoose": "^9.7.3",
|
||||
"redis": "^5.12.1",
|
||||
"reflect-metadata": "^0.2.2",
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
import { getQueueToken } from '@nestjs/bullmq';
|
||||
import { Test } from '@nestjs/testing';
|
||||
import { AppModule } from './app.module';
|
||||
import { AnalysisQueueService } from './modules/analysis/analysis-queue.service';
|
||||
import { ANALYSIS_QUEUE_NAME } from './modules/analysis/analysis.constants';
|
||||
import { ConnectionService } from './modules/global/database/connection.service';
|
||||
import { REDIS_CLIENT } from './modules/global/redis/redis.constants';
|
||||
import { SecretService } from './modules/global/secret/secret.service';
|
||||
|
||||
function createSecretServiceStub() {
|
||||
return {
|
||||
get: jest.fn((key: string) => {
|
||||
if (key === 'REDIS_URL')
|
||||
return Promise.resolve('redis://localhost:6379/0');
|
||||
return Promise.resolve('');
|
||||
}),
|
||||
ready: jest.fn().mockResolvedValue(undefined),
|
||||
};
|
||||
}
|
||||
|
||||
describe('AppModule', () => {
|
||||
it('compiles with the analysis queue module wired', async () => {
|
||||
const moduleRef = await Test.createTestingModule({
|
||||
imports: [AppModule],
|
||||
})
|
||||
.overrideProvider(SecretService)
|
||||
.useValue(createSecretServiceStub())
|
||||
.overrideProvider(ConnectionService)
|
||||
.useValue({})
|
||||
.overrideProvider(REDIS_CLIENT)
|
||||
.useValue({
|
||||
destroy: jest.fn(),
|
||||
quit: jest.fn().mockResolvedValue(undefined),
|
||||
})
|
||||
.overrideProvider(getQueueToken(ANALYSIS_QUEUE_NAME))
|
||||
.useValue({
|
||||
add: jest.fn(),
|
||||
})
|
||||
.compile();
|
||||
|
||||
expect(moduleRef.get(AnalysisQueueService)).toBeInstanceOf(
|
||||
AnalysisQueueService,
|
||||
);
|
||||
|
||||
await moduleRef.close();
|
||||
});
|
||||
});
|
||||
@@ -1,10 +1,11 @@
|
||||
import { Module } from '@nestjs/common';
|
||||
import { AppController } from './app.controller';
|
||||
import { AppService } from './app.service';
|
||||
import { AnalysisModule } from './modules/analysis/analysis.module';
|
||||
import { GlobalModule } from './modules/global/global.module';
|
||||
|
||||
@Module({
|
||||
imports: [GlobalModule],
|
||||
imports: [GlobalModule, AnalysisModule],
|
||||
controllers: [AppController],
|
||||
providers: [AppService],
|
||||
})
|
||||
|
||||
@@ -0,0 +1,355 @@
|
||||
import { FEATURE_SCHEMA_VERSION } from '@persona-lenz/shared';
|
||||
import type { ConnectionService } from '../global/database/connection.service';
|
||||
import type { Account } from '../global/database/schemas';
|
||||
import type { RiotApiClient } from '../riot/riot-api.client';
|
||||
import type { UserAnalysisJobData } from './analysis.types';
|
||||
import { FeatureExtractorService } from './feature-extractor.service';
|
||||
import { AnalysisPipelineService } from './analysis-pipeline.service';
|
||||
import { ProfileBuilderService } from './profile-builder.service';
|
||||
|
||||
function createJobData(): UserAnalysisJobData {
|
||||
return {
|
||||
gameName: 'Hide on bush',
|
||||
tagLine: 'KR1',
|
||||
platformRoute: 'kr',
|
||||
regionalRoute: 'asia',
|
||||
queueId: 420,
|
||||
requestedMatchCount: 20,
|
||||
};
|
||||
}
|
||||
|
||||
function createMatchPayload(matchId = 'KR_1') {
|
||||
return {
|
||||
metadata: {
|
||||
matchId,
|
||||
participants: ['target-puuid', 'ally-puuid'],
|
||||
},
|
||||
info: {
|
||||
gameCreation: 1_700_000_000_000,
|
||||
gameDuration: 1800,
|
||||
gameVersion: '26.13.123.456',
|
||||
queueId: 420,
|
||||
participants: [
|
||||
{
|
||||
puuid: 'target-puuid',
|
||||
teamId: 100,
|
||||
teamPosition: 'MIDDLE',
|
||||
championId: 103,
|
||||
kills: 6,
|
||||
deaths: 2,
|
||||
assists: 8,
|
||||
totalDamageDealtToChampions: 24_000,
|
||||
goldEarned: 12_000,
|
||||
totalMinionsKilled: 210,
|
||||
neutralMinionsKilled: 12,
|
||||
visionScore: 24,
|
||||
wardsKilled: 4,
|
||||
detectorWardsPlaced: 3,
|
||||
win: true,
|
||||
challenges: {
|
||||
kda: 7,
|
||||
killParticipation: 0.7,
|
||||
teamDamagePercentage: 0.32,
|
||||
damagePerMinute: 800,
|
||||
goldPerMinute: 400,
|
||||
visionScorePerMinute: 0.8,
|
||||
controlWardsPlaced: 3,
|
||||
soloKills: 2,
|
||||
},
|
||||
},
|
||||
{
|
||||
puuid: 'ally-puuid',
|
||||
teamId: 100,
|
||||
teamPosition: 'JUNGLE',
|
||||
championId: 64,
|
||||
kills: 10,
|
||||
totalDamageDealtToChampions: 30_000,
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
interface ExecQuery<T> {
|
||||
exec: jest.Mock<Promise<T>, []>;
|
||||
}
|
||||
|
||||
type AcknowledgedUpdate = { acknowledged: boolean };
|
||||
type UpdateOneMock = jest.Mock<
|
||||
ExecQuery<AcknowledgedUpdate>,
|
||||
[Record<string, unknown>, Record<string, unknown>, Record<string, unknown>?]
|
||||
>;
|
||||
|
||||
function asRecord(value: unknown): Record<string, unknown> {
|
||||
if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
|
||||
return value as Record<string, unknown>;
|
||||
}
|
||||
return {};
|
||||
}
|
||||
|
||||
function execResolved<T>(value: T): ExecQuery<T> {
|
||||
return { exec: jest.fn<Promise<T>, []>().mockResolvedValue(value) };
|
||||
}
|
||||
|
||||
function leanExecResolved<T>(value: T) {
|
||||
return {
|
||||
lean: jest.fn(() => execResolved(value)),
|
||||
};
|
||||
}
|
||||
|
||||
function createStoredAccount(overrides: Partial<Account> = {}): Account {
|
||||
return {
|
||||
createdAt: new Date('2026-07-01T00:00:00.000Z'),
|
||||
updatedAt: new Date('2026-07-01T00:00:00.000Z'),
|
||||
puuid: 'target-puuid',
|
||||
gameName: 'Hide on bush',
|
||||
tagLine: 'KR1',
|
||||
platformRoute: 'kr',
|
||||
regionalRoute: 'asia',
|
||||
profileIconId: 1,
|
||||
summonerLevel: 500,
|
||||
tiers: [],
|
||||
isSeed: false,
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
interface PipelineHarnessOptions {
|
||||
accountError?: Error;
|
||||
existingMatchRaw?: Record<string, unknown> | null;
|
||||
getMatch?: jest.Mock<Promise<Record<string, unknown>>, [string, string]>;
|
||||
matchIds?: string[];
|
||||
storedAccount?: Account;
|
||||
}
|
||||
|
||||
function createPipelineHarness(options: PipelineHarnessOptions = {}) {
|
||||
const updateAnalysisJob: UpdateOneMock = jest
|
||||
.fn<ExecQuery<AcknowledgedUpdate>, Parameters<UpdateOneMock>>()
|
||||
.mockReturnValue(execResolved({ acknowledged: true }));
|
||||
const findOneAndUpdateAccount = jest
|
||||
.fn()
|
||||
.mockReturnValue(
|
||||
leanExecResolved(options.storedAccount ?? createStoredAccount()),
|
||||
);
|
||||
const updateAccount: UpdateOneMock = jest
|
||||
.fn<ExecQuery<AcknowledgedUpdate>, Parameters<UpdateOneMock>>()
|
||||
.mockReturnValue(execResolved({ acknowledged: true }));
|
||||
const findOneRiotMatch = jest
|
||||
.fn()
|
||||
.mockReturnValue(
|
||||
leanExecResolved(
|
||||
options.existingMatchRaw ? { raw: options.existingMatchRaw } : null,
|
||||
),
|
||||
);
|
||||
const updateRiotMatch: UpdateOneMock = jest
|
||||
.fn<ExecQuery<AcknowledgedUpdate>, Parameters<UpdateOneMock>>()
|
||||
.mockReturnValue(execResolved({ acknowledged: true }));
|
||||
const updatePlayerMatchFeature: UpdateOneMock = jest
|
||||
.fn<ExecQuery<AcknowledgedUpdate>, Parameters<UpdateOneMock>>()
|
||||
.mockReturnValue(execResolved({ acknowledged: true }));
|
||||
const updatePlayerProfile: UpdateOneMock = jest
|
||||
.fn<ExecQuery<AcknowledgedUpdate>, Parameters<UpdateOneMock>>()
|
||||
.mockReturnValue(execResolved({ acknowledged: true }));
|
||||
|
||||
const models = {
|
||||
account: {
|
||||
findOneAndUpdate: findOneAndUpdateAccount,
|
||||
updateOne: updateAccount,
|
||||
},
|
||||
analysisJob: {
|
||||
updateOne: updateAnalysisJob,
|
||||
},
|
||||
playerMatchFeature: {
|
||||
updateOne: updatePlayerMatchFeature,
|
||||
},
|
||||
playerProfile: {
|
||||
updateOne: updatePlayerProfile,
|
||||
},
|
||||
riotMatch: {
|
||||
findOne: findOneRiotMatch,
|
||||
updateOne: updateRiotMatch,
|
||||
},
|
||||
};
|
||||
const connectionService = {
|
||||
getModel: jest.fn((modelKey: keyof typeof models) =>
|
||||
Promise.resolve(models[modelKey]),
|
||||
),
|
||||
} as unknown as ConnectionService;
|
||||
const getAccountByRiotId = options.accountError
|
||||
? jest.fn().mockRejectedValue(options.accountError)
|
||||
: jest.fn().mockResolvedValue({
|
||||
puuid: 'target-puuid',
|
||||
gameName: 'Hide on bush',
|
||||
tagLine: 'KR1',
|
||||
});
|
||||
const getMatch =
|
||||
options.getMatch ??
|
||||
jest
|
||||
.fn<Promise<Record<string, unknown>>, [string, string]>()
|
||||
.mockResolvedValue(createMatchPayload());
|
||||
const riotApiClient = {
|
||||
getAccountByRiotId,
|
||||
getSummonerByPuuid: jest.fn().mockResolvedValue({
|
||||
id: 'summoner-id',
|
||||
puuid: 'target-puuid',
|
||||
profileIconId: 1,
|
||||
summonerLevel: 500,
|
||||
}),
|
||||
getLeagueEntriesByPuuid: jest.fn().mockResolvedValue([]),
|
||||
getMatchIds: jest.fn().mockResolvedValue(options.matchIds ?? ['KR_1']),
|
||||
getMatch,
|
||||
} as unknown as RiotApiClient;
|
||||
|
||||
return {
|
||||
findOneRiotMatch,
|
||||
getMatch,
|
||||
service: new AnalysisPipelineService(
|
||||
connectionService,
|
||||
riotApiClient,
|
||||
new FeatureExtractorService(),
|
||||
new ProfileBuilderService(),
|
||||
),
|
||||
updateAnalysisJob,
|
||||
updatePlayerMatchFeature,
|
||||
updatePlayerProfile,
|
||||
updateRiotMatch,
|
||||
};
|
||||
}
|
||||
|
||||
describe('AnalysisPipelineService', () => {
|
||||
it('fetches missing match details, stores features, builds a profile, and completes the job', async () => {
|
||||
const {
|
||||
findOneRiotMatch,
|
||||
getMatch,
|
||||
service,
|
||||
updateAnalysisJob,
|
||||
updatePlayerMatchFeature,
|
||||
updatePlayerProfile,
|
||||
updateRiotMatch,
|
||||
} = createPipelineHarness();
|
||||
|
||||
await service.processUserAnalysisJob(createJobData(), 'analysis-job-1');
|
||||
|
||||
expect(findOneRiotMatch).toHaveBeenCalledWith({ matchId: 'KR_1' });
|
||||
expect(getMatch).toHaveBeenCalledWith('KR_1', 'asia');
|
||||
|
||||
const riotMatchUpdate = updateRiotMatch.mock.calls[0][1];
|
||||
expect(riotMatchUpdate).toMatchObject({
|
||||
$setOnInsert: {
|
||||
matchId: 'KR_1',
|
||||
queueId: 420,
|
||||
},
|
||||
});
|
||||
|
||||
const playerMatchFeatureUpdate = updatePlayerMatchFeature.mock.calls[0][1];
|
||||
expect(playerMatchFeatureUpdate).toMatchObject({
|
||||
$set: {
|
||||
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
|
||||
matchId: 'KR_1',
|
||||
},
|
||||
});
|
||||
|
||||
const playerProfileUpdate = updatePlayerProfile.mock.calls[0][1];
|
||||
expect(playerProfileUpdate).toMatchObject({
|
||||
$set: {
|
||||
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
|
||||
puuid: 'target-puuid',
|
||||
sampleGameCount: 1,
|
||||
},
|
||||
});
|
||||
|
||||
const completedJobUpdate = updateAnalysisJob.mock.calls.find(
|
||||
([, update]) => asRecord(asRecord(update).$set).status === 'completed',
|
||||
);
|
||||
expect(completedJobUpdate).toBeDefined();
|
||||
expect(asRecord(asRecord(completedJobUpdate?.[1]).$set)).toMatchObject({
|
||||
status: 'completed',
|
||||
stage: 'completed',
|
||||
});
|
||||
});
|
||||
|
||||
it('completes without building a profile when no ranked matches are returned', async () => {
|
||||
const { service, updateAnalysisJob, updatePlayerProfile } =
|
||||
createPipelineHarness({
|
||||
matchIds: [],
|
||||
});
|
||||
|
||||
await service.processUserAnalysisJob(createJobData(), 'analysis-job-1');
|
||||
|
||||
expect(updatePlayerProfile).not.toHaveBeenCalled();
|
||||
const completedJobUpdate = updateAnalysisJob.mock.calls.find(
|
||||
([, update]) => asRecord(asRecord(update).$set).status === 'completed',
|
||||
);
|
||||
expect(completedJobUpdate).toBeDefined();
|
||||
});
|
||||
|
||||
it('uses cached match details without recalling Riot Match-V5', async () => {
|
||||
const { getMatch, service, updatePlayerMatchFeature } =
|
||||
createPipelineHarness({
|
||||
existingMatchRaw: createMatchPayload(),
|
||||
});
|
||||
|
||||
await service.processUserAnalysisJob(createJobData(), 'analysis-job-1');
|
||||
|
||||
expect(getMatch).not.toHaveBeenCalled();
|
||||
expect(updatePlayerMatchFeature).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('skips individual match fetch failures and still builds from successful matches', async () => {
|
||||
const getMatch = jest
|
||||
.fn<Promise<Record<string, unknown>>, [string, string]>()
|
||||
.mockRejectedValueOnce(new Error('temporary upstream failure'))
|
||||
.mockResolvedValueOnce(createMatchPayload('KR_2'));
|
||||
const { service, updatePlayerProfile } = createPipelineHarness({
|
||||
getMatch,
|
||||
matchIds: ['KR_1', 'KR_2'],
|
||||
});
|
||||
|
||||
await service.processUserAnalysisJob(createJobData(), 'analysis-job-1');
|
||||
|
||||
expect(getMatch).toHaveBeenCalledTimes(2);
|
||||
const playerProfileUpdate = updatePlayerProfile.mock.calls[0][1];
|
||||
expect(playerProfileUpdate).toMatchObject({
|
||||
$set: {
|
||||
sampleGameCount: 1,
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it('does not mark the job failed before BullMQ exhausts retries', async () => {
|
||||
const { service, updateAnalysisJob } = createPipelineHarness({
|
||||
accountError: new Error('upstream unavailable'),
|
||||
});
|
||||
|
||||
await expect(
|
||||
service.processUserAnalysisJob(createJobData(), 'analysis-job-1', {
|
||||
isFinalAttempt: false,
|
||||
}),
|
||||
).rejects.toThrow('upstream unavailable');
|
||||
|
||||
const failedJobUpdate = updateAnalysisJob.mock.calls.find(
|
||||
([, update]) => asRecord(asRecord(update).$set).status === 'failed',
|
||||
);
|
||||
expect(failedJobUpdate).toBeUndefined();
|
||||
});
|
||||
|
||||
it('marks the job failed with a public error on the final BullMQ attempt', async () => {
|
||||
const { service, updateAnalysisJob } = createPipelineHarness({
|
||||
accountError: new Error('internal host redis.local refused connection'),
|
||||
});
|
||||
|
||||
await expect(
|
||||
service.processUserAnalysisJob(createJobData(), 'analysis-job-1', {
|
||||
isFinalAttempt: true,
|
||||
}),
|
||||
).rejects.toThrow('internal host redis.local refused connection');
|
||||
|
||||
const failedJobUpdate = updateAnalysisJob.mock.calls.find(
|
||||
([, update]) => asRecord(asRecord(update).$set).status === 'failed',
|
||||
);
|
||||
expect(asRecord(asRecord(failedJobUpdate?.[1]).$set)).toMatchObject({
|
||||
status: 'failed',
|
||||
error: 'Analysis failed during processing.',
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,456 @@
|
||||
import { Injectable, Logger } from '@nestjs/common';
|
||||
import { ConnectionService } from '../global/database/connection.service';
|
||||
import type {
|
||||
Account,
|
||||
AnalysisJobStatus,
|
||||
RiotMatch,
|
||||
TierInfo,
|
||||
} from '../global/database/schemas';
|
||||
import {
|
||||
RiotApiClient,
|
||||
type RiotLeagueEntryDto,
|
||||
} from '../riot/riot-api.client';
|
||||
import {
|
||||
normalizeRequestedMatchCount,
|
||||
USER_ANALYSIS_JOB_NAME,
|
||||
} from './analysis.constants';
|
||||
import type {
|
||||
ExtractedPlayerMatchFeature,
|
||||
UserAnalysisJobData,
|
||||
} from './analysis.types';
|
||||
import { FeatureExtractorService } from './feature-extractor.service';
|
||||
import { ProfileBuilderService } from './profile-builder.service';
|
||||
|
||||
interface MatchRecord {
|
||||
matchId: string;
|
||||
raw: Record<string, unknown>;
|
||||
}
|
||||
|
||||
interface ParsedMatchSummary {
|
||||
gameCreation: number;
|
||||
gameDuration: number;
|
||||
gameVersion?: string;
|
||||
queueId?: number;
|
||||
participantPuuids: string[];
|
||||
}
|
||||
|
||||
function asRecord(value: unknown): Record<string, unknown> {
|
||||
if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
|
||||
return value as Record<string, unknown>;
|
||||
}
|
||||
return {};
|
||||
}
|
||||
|
||||
function asNumber(value: unknown, fallback = 0): number {
|
||||
return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
|
||||
}
|
||||
|
||||
function asString(value: unknown): string | undefined {
|
||||
return typeof value === 'string' ? value : undefined;
|
||||
}
|
||||
|
||||
function asStringArray(value: unknown): string[] {
|
||||
if (!Array.isArray(value)) return [];
|
||||
return value.filter((item): item is string => typeof item === 'string');
|
||||
}
|
||||
|
||||
function errorMessage(error: unknown): string {
|
||||
return error instanceof Error ? error.message : String(error);
|
||||
}
|
||||
|
||||
@Injectable()
|
||||
export class AnalysisPipelineService {
|
||||
private readonly logger = new Logger(AnalysisPipelineService.name);
|
||||
|
||||
constructor(
|
||||
private readonly connectionService: ConnectionService,
|
||||
private readonly riotApiClient: RiotApiClient,
|
||||
private readonly featureExtractorService: FeatureExtractorService,
|
||||
private readonly profileBuilderService: ProfileBuilderService,
|
||||
) {}
|
||||
|
||||
public async processUserAnalysisJob(
|
||||
data: UserAnalysisJobData,
|
||||
jobId: string,
|
||||
options: { isFinalAttempt?: boolean } = {},
|
||||
): Promise<void> {
|
||||
const normalizedData = {
|
||||
...data,
|
||||
requestedMatchCount: normalizeRequestedMatchCount(
|
||||
data.requestedMatchCount,
|
||||
),
|
||||
};
|
||||
|
||||
try {
|
||||
await this.updateJob(jobId, {
|
||||
status: 'processing',
|
||||
stage: 'resolve-account',
|
||||
progress: {
|
||||
fetchedMatches: 0,
|
||||
totalMatches: 0,
|
||||
},
|
||||
});
|
||||
|
||||
const account = await this.resolveAndStoreAccount(normalizedData);
|
||||
await this.updateJob(jobId, {
|
||||
puuid: account.puuid,
|
||||
stage: 'fetch-match-ids',
|
||||
});
|
||||
|
||||
const matchIds = await this.riotApiClient.getMatchIds(account.puuid, {
|
||||
count: normalizedData.requestedMatchCount,
|
||||
queue: normalizedData.queueId,
|
||||
regionalRoute: normalizedData.regionalRoute,
|
||||
});
|
||||
await this.updateJob(jobId, {
|
||||
stage: 'fetch-match-details',
|
||||
progress: {
|
||||
fetchedMatches: 0,
|
||||
totalMatches: matchIds.length,
|
||||
},
|
||||
});
|
||||
|
||||
if (matchIds.length === 0) {
|
||||
await this.completeJob(jobId);
|
||||
return;
|
||||
}
|
||||
|
||||
const matchRecords = await this.fetchAndStoreMatches(
|
||||
matchIds,
|
||||
normalizedData,
|
||||
jobId,
|
||||
);
|
||||
await this.updateJob(jobId, {
|
||||
stage: 'extract-features',
|
||||
});
|
||||
|
||||
const extractedFeatures = await this.extractAndStoreFeatures(
|
||||
matchRecords,
|
||||
account.puuid,
|
||||
normalizedData.queueId,
|
||||
);
|
||||
await this.updateJob(jobId, {
|
||||
stage: 'build-profile',
|
||||
});
|
||||
|
||||
if (extractedFeatures.length > 0) {
|
||||
await this.buildAndStoreProfile(
|
||||
account,
|
||||
normalizedData,
|
||||
extractedFeatures,
|
||||
);
|
||||
}
|
||||
|
||||
await this.completeJob(jobId);
|
||||
} catch (error) {
|
||||
if (options.isFinalAttempt === true) {
|
||||
await this.updateJob(jobId, {
|
||||
status: 'failed',
|
||||
error: this.publicErrorMessage(error),
|
||||
});
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
private async resolveAndStoreAccount(
|
||||
data: UserAnalysisJobData,
|
||||
): Promise<Account> {
|
||||
const account = await this.riotApiClient.getAccountByRiotId(
|
||||
data.gameName,
|
||||
data.tagLine,
|
||||
data.regionalRoute,
|
||||
);
|
||||
const [summoner, tiers] = await Promise.all([
|
||||
this.riotApiClient.getSummonerByPuuid(account.puuid, data.platformRoute),
|
||||
this.riotApiClient.getLeagueEntriesByPuuid(
|
||||
account.puuid,
|
||||
data.platformRoute,
|
||||
),
|
||||
]);
|
||||
const accountModel = await this.connectionService.getModel('account');
|
||||
const tierFetchedAt = new Date();
|
||||
|
||||
const storedAccount = await accountModel
|
||||
.findOneAndUpdate(
|
||||
{ puuid: account.puuid },
|
||||
{
|
||||
$set: {
|
||||
puuid: account.puuid,
|
||||
gameName: account.gameName,
|
||||
tagLine: account.tagLine,
|
||||
platformRoute: data.platformRoute,
|
||||
regionalRoute: data.regionalRoute,
|
||||
profileIconId: summoner.profileIconId,
|
||||
summonerLevel: summoner.summonerLevel,
|
||||
tiers: this.toTierInfo(tiers, tierFetchedAt),
|
||||
tiersFetchedAt: tierFetchedAt,
|
||||
},
|
||||
$setOnInsert: {
|
||||
isSeed: false,
|
||||
},
|
||||
},
|
||||
{
|
||||
new: true,
|
||||
setDefaultsOnInsert: true,
|
||||
upsert: true,
|
||||
},
|
||||
)
|
||||
.lean<Account>()
|
||||
.exec();
|
||||
|
||||
if (!storedAccount) {
|
||||
throw new Error('Failed to store Riot account.');
|
||||
}
|
||||
return storedAccount;
|
||||
}
|
||||
|
||||
private async fetchAndStoreMatches(
|
||||
matchIds: string[],
|
||||
data: UserAnalysisJobData,
|
||||
jobId: string,
|
||||
): Promise<MatchRecord[]> {
|
||||
const matchRecords: MatchRecord[] = [];
|
||||
const riotMatchModel = await this.connectionService.getModel('riotMatch');
|
||||
|
||||
for (const [index, matchId] of matchIds.entries()) {
|
||||
try {
|
||||
const existingMatch = await riotMatchModel
|
||||
.findOne({ matchId })
|
||||
.lean<RiotMatch>()
|
||||
.exec();
|
||||
|
||||
if (existingMatch) {
|
||||
if (this.isEligibleMatch(existingMatch.raw, data.queueId)) {
|
||||
matchRecords.push({ matchId, raw: existingMatch.raw });
|
||||
}
|
||||
} else {
|
||||
const rawMatch = await this.riotApiClient.getMatch(
|
||||
matchId,
|
||||
data.regionalRoute,
|
||||
);
|
||||
await this.storeRiotMatch(matchId, rawMatch);
|
||||
if (this.isEligibleMatch(rawMatch, data.queueId)) {
|
||||
matchRecords.push({ matchId, raw: rawMatch });
|
||||
}
|
||||
}
|
||||
} catch (error) {
|
||||
this.logger.warn(
|
||||
`Skipping matchId="${this.safeLogText(matchId)}" after fetch/store failure: ${this.safeLogText(errorMessage(error))}`,
|
||||
);
|
||||
} finally {
|
||||
await this.updateJob(jobId, {
|
||||
progress: {
|
||||
fetchedMatches: index + 1,
|
||||
totalMatches: matchIds.length,
|
||||
},
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return matchRecords;
|
||||
}
|
||||
|
||||
private async storeRiotMatch(
|
||||
matchId: string,
|
||||
rawMatch: Record<string, unknown>,
|
||||
): Promise<void> {
|
||||
const summary = this.parseMatchSummary(rawMatch);
|
||||
const riotMatchModel = await this.connectionService.getModel('riotMatch');
|
||||
|
||||
await riotMatchModel
|
||||
.updateOne(
|
||||
{ matchId },
|
||||
{
|
||||
$setOnInsert: {
|
||||
matchId,
|
||||
gameCreation: summary.gameCreation,
|
||||
gameDuration: summary.gameDuration,
|
||||
gameVersion: summary.gameVersion,
|
||||
queueId: summary.queueId,
|
||||
participantPuuids: summary.participantPuuids,
|
||||
raw: rawMatch,
|
||||
fetchedAt: new Date(),
|
||||
},
|
||||
},
|
||||
{ upsert: true },
|
||||
)
|
||||
.exec();
|
||||
}
|
||||
|
||||
private async extractAndStoreFeatures(
|
||||
matchRecords: MatchRecord[],
|
||||
puuid: string,
|
||||
queueId: number,
|
||||
): Promise<ExtractedPlayerMatchFeature[]> {
|
||||
const playerMatchFeatureModel =
|
||||
await this.connectionService.getModel('playerMatchFeature');
|
||||
const extractedFeatures: ExtractedPlayerMatchFeature[] = [];
|
||||
|
||||
for (const matchRecord of matchRecords) {
|
||||
try {
|
||||
const feature = this.featureExtractorService.extractPlayerMatchFeature(
|
||||
matchRecord.raw,
|
||||
puuid,
|
||||
);
|
||||
if (feature.queueId !== queueId) continue;
|
||||
|
||||
await playerMatchFeatureModel
|
||||
.updateOne(
|
||||
{ matchId: feature.matchId, puuid: feature.puuid },
|
||||
{ $set: feature },
|
||||
{ upsert: true },
|
||||
)
|
||||
.exec();
|
||||
extractedFeatures.push(feature);
|
||||
} catch (error) {
|
||||
this.logger.warn(
|
||||
`Skipping feature extraction for matchId="${this.safeLogText(matchRecord.matchId)}": ${this.safeLogText(errorMessage(error))}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
return extractedFeatures;
|
||||
}
|
||||
|
||||
private async buildAndStoreProfile(
|
||||
account: Account,
|
||||
data: UserAnalysisJobData,
|
||||
extractedFeatures: ExtractedPlayerMatchFeature[],
|
||||
): Promise<void> {
|
||||
const profile = this.profileBuilderService.buildProfile({
|
||||
features: extractedFeatures,
|
||||
isSeed: account.isSeed,
|
||||
puuid: account.puuid,
|
||||
queueId: data.queueId,
|
||||
});
|
||||
const playerProfileModel =
|
||||
await this.connectionService.getModel('playerProfile');
|
||||
const accountModel = await this.connectionService.getModel('account');
|
||||
const analyzedAt = new Date();
|
||||
|
||||
await playerProfileModel
|
||||
.updateOne(
|
||||
{
|
||||
puuid: account.puuid,
|
||||
queueId: data.queueId,
|
||||
},
|
||||
{ $set: profile },
|
||||
{ upsert: true },
|
||||
)
|
||||
.exec();
|
||||
await accountModel
|
||||
.updateOne(
|
||||
{ puuid: account.puuid },
|
||||
{
|
||||
$set: {
|
||||
lastAnalyzedAt: analyzedAt,
|
||||
},
|
||||
},
|
||||
)
|
||||
.exec();
|
||||
}
|
||||
|
||||
private async completeJob(jobId: string): Promise<void> {
|
||||
await this.updateJob(jobId, {
|
||||
status: 'completed',
|
||||
stage: 'completed',
|
||||
completedAt: new Date(),
|
||||
error: undefined,
|
||||
});
|
||||
}
|
||||
|
||||
private async updateJob(
|
||||
jobId: string,
|
||||
patch: {
|
||||
completedAt?: Date;
|
||||
error?: string;
|
||||
progress?: { fetchedMatches: number; totalMatches: number };
|
||||
puuid?: string;
|
||||
stage?: string;
|
||||
status?: AnalysisJobStatus;
|
||||
},
|
||||
): Promise<void> {
|
||||
const analysisJobModel =
|
||||
await this.connectionService.getModel('analysisJob');
|
||||
const set: Record<string, unknown> = {
|
||||
jobId,
|
||||
jobType: USER_ANALYSIS_JOB_NAME,
|
||||
...patch,
|
||||
};
|
||||
const unset: Record<string, string> = {};
|
||||
if (patch.error === undefined) {
|
||||
delete set.error;
|
||||
}
|
||||
if (patch.status === 'completed') {
|
||||
unset.error = '';
|
||||
}
|
||||
|
||||
await analysisJobModel
|
||||
.updateOne(
|
||||
{ jobId },
|
||||
{
|
||||
$set: set,
|
||||
...(Object.keys(unset).length > 0 ? { $unset: unset } : {}),
|
||||
},
|
||||
)
|
||||
.exec();
|
||||
}
|
||||
|
||||
private isEligibleMatch(
|
||||
rawMatch: Record<string, unknown>,
|
||||
queueId: number,
|
||||
): boolean {
|
||||
const info = asRecord(rawMatch.info);
|
||||
return (
|
||||
asNumber(info.queueId) === queueId && asNumber(info.gameDuration) >= 300
|
||||
);
|
||||
}
|
||||
|
||||
private parseMatchSummary(
|
||||
rawMatch: Record<string, unknown>,
|
||||
): ParsedMatchSummary {
|
||||
const metadata = asRecord(rawMatch.metadata);
|
||||
const info = asRecord(rawMatch.info);
|
||||
return {
|
||||
gameCreation: asNumber(info.gameCreation),
|
||||
gameDuration: asNumber(info.gameDuration),
|
||||
gameVersion: asString(info.gameVersion),
|
||||
queueId:
|
||||
typeof info.queueId === 'number' && Number.isFinite(info.queueId)
|
||||
? info.queueId
|
||||
: undefined,
|
||||
participantPuuids: asStringArray(metadata.participants),
|
||||
};
|
||||
}
|
||||
|
||||
private toTierInfo(
|
||||
entries: RiotLeagueEntryDto[],
|
||||
fetchedAt: Date,
|
||||
): TierInfo[] {
|
||||
return entries.map((entry) => ({
|
||||
queueType: entry.queueType,
|
||||
tier: entry.tier,
|
||||
rank: entry.rank,
|
||||
leaguePoints: entry.leaguePoints,
|
||||
wins: entry.wins,
|
||||
losses: entry.losses,
|
||||
fetchedAt,
|
||||
}));
|
||||
}
|
||||
|
||||
private publicErrorMessage(error: unknown): string {
|
||||
if (
|
||||
error instanceof Error &&
|
||||
(error.name === 'RiotApiKeyError' ||
|
||||
error.message.includes('Riot API key'))
|
||||
) {
|
||||
return 'Riot API key is invalid or expired.';
|
||||
}
|
||||
return 'Analysis failed during processing.';
|
||||
}
|
||||
|
||||
private safeLogText(value: string): string {
|
||||
return value.replace(/[\r\n\t]/gu, ' ').slice(0, 300);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,186 @@
|
||||
import type { AnalysisJob } from '../global/database/schemas';
|
||||
import type { ConnectionService } from '../global/database/connection.service';
|
||||
import type { UserAnalysisJobData } from './analysis.types';
|
||||
import { USER_ANALYSIS_JOB_NAME } from './analysis.constants';
|
||||
import { AnalysisQueueService } from './analysis-queue.service';
|
||||
|
||||
function createJobData(
|
||||
overrides: Partial<UserAnalysisJobData> = {},
|
||||
): UserAnalysisJobData {
|
||||
return {
|
||||
gameName: 'Hide on bush',
|
||||
tagLine: 'KR1',
|
||||
platformRoute: 'kr',
|
||||
regionalRoute: 'asia',
|
||||
queueId: 420,
|
||||
requestedMatchCount: 20,
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
function createFindOneChain(
|
||||
result: Pick<AnalysisJob, 'jobId' | 'status'> | null,
|
||||
) {
|
||||
const exec = jest
|
||||
.fn<Promise<Pick<AnalysisJob, 'jobId' | 'status'> | null>, []>()
|
||||
.mockResolvedValue(result);
|
||||
const lean = jest.fn(() => ({ exec }));
|
||||
const sort = jest.fn(() => ({ lean }));
|
||||
return {
|
||||
chain: { sort },
|
||||
exec,
|
||||
lean,
|
||||
sort,
|
||||
};
|
||||
}
|
||||
|
||||
describe('AnalysisQueueService', () => {
|
||||
it('creates an analysis job document and enqueues a BullMQ job', async () => {
|
||||
const add = jest.fn().mockResolvedValue({ id: 'job-from-bull' });
|
||||
const findOneChain = createFindOneChain(null);
|
||||
const create = jest.fn().mockResolvedValue({});
|
||||
const updateOne = jest.fn(() => ({
|
||||
exec: jest.fn().mockResolvedValue({}),
|
||||
}));
|
||||
const analysisJobModel = {
|
||||
create,
|
||||
findOne: jest.fn(() => findOneChain.chain),
|
||||
updateOne,
|
||||
};
|
||||
const connectionService = {
|
||||
getModel: jest.fn().mockResolvedValue(analysisJobModel),
|
||||
} as unknown as ConnectionService;
|
||||
const service = new AnalysisQueueService(
|
||||
{ add } as never,
|
||||
connectionService,
|
||||
() => 'analysis-job-1',
|
||||
);
|
||||
|
||||
const result = await service.enqueueUserAnalysis(createJobData());
|
||||
|
||||
expect(result).toEqual({ jobId: 'analysis-job-1', status: 'queued' });
|
||||
expect(create).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
jobId: 'analysis-job-1',
|
||||
jobType: USER_ANALYSIS_JOB_NAME,
|
||||
gameName: 'Hide on bush',
|
||||
tagLine: 'KR1',
|
||||
status: 'queued',
|
||||
}),
|
||||
);
|
||||
expect(add).toHaveBeenCalledWith(
|
||||
USER_ANALYSIS_JOB_NAME,
|
||||
createJobData(),
|
||||
expect.objectContaining({
|
||||
attempts: 2,
|
||||
jobId: 'analysis-job-1',
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('returns an existing active job instead of enqueueing a duplicate', async () => {
|
||||
const add = jest.fn();
|
||||
const findOneChain = createFindOneChain({
|
||||
jobId: 'existing-job',
|
||||
status: 'processing',
|
||||
});
|
||||
const analysisJobModel = {
|
||||
create: jest.fn(),
|
||||
findOne: jest.fn(() => findOneChain.chain),
|
||||
};
|
||||
const connectionService = {
|
||||
getModel: jest.fn().mockResolvedValue(analysisJobModel),
|
||||
} as unknown as ConnectionService;
|
||||
const service = new AnalysisQueueService(
|
||||
{ add } as never,
|
||||
connectionService,
|
||||
() => 'new-job',
|
||||
);
|
||||
|
||||
await expect(service.enqueueUserAnalysis(createJobData())).resolves.toEqual(
|
||||
{
|
||||
jobId: 'existing-job',
|
||||
status: 'processing',
|
||||
},
|
||||
);
|
||||
expect(add).not.toHaveBeenCalled();
|
||||
expect(analysisJobModel.create).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('marks the pre-created job failed when BullMQ enqueue fails', async () => {
|
||||
const add = jest.fn().mockRejectedValue(new Error('redis unavailable'));
|
||||
const findOneChain = createFindOneChain(null);
|
||||
const create = jest.fn().mockResolvedValue({});
|
||||
const updateOne = jest.fn(() => ({
|
||||
exec: jest.fn().mockResolvedValue({}),
|
||||
}));
|
||||
const analysisJobModel = {
|
||||
create,
|
||||
findOne: jest.fn(() => findOneChain.chain),
|
||||
updateOne,
|
||||
};
|
||||
const connectionService = {
|
||||
getModel: jest.fn().mockResolvedValue(analysisJobModel),
|
||||
} as unknown as ConnectionService;
|
||||
const service = new AnalysisQueueService(
|
||||
{ add } as never,
|
||||
connectionService,
|
||||
() => 'analysis-job-1',
|
||||
);
|
||||
|
||||
await expect(service.enqueueUserAnalysis(createJobData())).rejects.toThrow(
|
||||
'redis unavailable',
|
||||
);
|
||||
expect(updateOne).toHaveBeenCalledWith(
|
||||
{ jobId: 'analysis-job-1' },
|
||||
{
|
||||
$set: {
|
||||
status: 'failed',
|
||||
stage: 'enqueue',
|
||||
error: 'redis unavailable',
|
||||
},
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
it('serializes identical in-process requests before creating a duplicate job', async () => {
|
||||
const add = jest.fn().mockResolvedValue({ id: 'analysis-job-1' });
|
||||
let activeJob: Pick<AnalysisJob, 'jobId' | 'status'> | null = null;
|
||||
const findOne = jest.fn(() => ({
|
||||
sort: jest.fn(() => ({
|
||||
lean: jest.fn(() => ({
|
||||
exec: jest
|
||||
.fn<Promise<Pick<AnalysisJob, 'jobId' | 'status'> | null>, []>()
|
||||
.mockImplementation(() => Promise.resolve(activeJob)),
|
||||
})),
|
||||
})),
|
||||
}));
|
||||
const create = jest.fn().mockImplementation(() => {
|
||||
activeJob = { jobId: 'analysis-job-1', status: 'queued' };
|
||||
return Promise.resolve({});
|
||||
});
|
||||
const analysisJobModel = {
|
||||
create,
|
||||
findOne,
|
||||
updateOne: jest.fn(),
|
||||
};
|
||||
const connectionService = {
|
||||
getModel: jest.fn().mockResolvedValue(analysisJobModel),
|
||||
} as unknown as ConnectionService;
|
||||
const service = new AnalysisQueueService(
|
||||
{ add } as never,
|
||||
connectionService,
|
||||
() => (create.mock.calls.length === 0 ? 'analysis-job-1' : 'unexpected'),
|
||||
);
|
||||
|
||||
const [firstResult, secondResult] = await Promise.all([
|
||||
service.enqueueUserAnalysis(createJobData()),
|
||||
service.enqueueUserAnalysis(createJobData()),
|
||||
]);
|
||||
|
||||
expect(firstResult).toEqual({ jobId: 'analysis-job-1', status: 'queued' });
|
||||
expect(secondResult).toEqual({ jobId: 'analysis-job-1', status: 'queued' });
|
||||
expect(create).toHaveBeenCalledTimes(1);
|
||||
expect(add).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,159 @@
|
||||
import { InjectQueue } from '@nestjs/bullmq';
|
||||
import { Inject, Injectable } from '@nestjs/common';
|
||||
import type { AnalysisRequestAcceptedDto } from '@persona-lenz/shared';
|
||||
import type { Queue } from 'bullmq';
|
||||
import { randomUUID } from 'node:crypto';
|
||||
import { ConnectionService } from '../global/database/connection.service';
|
||||
import type { AnalysisJob } from '../global/database/schemas';
|
||||
import {
|
||||
ANALYSIS_JOB_ID_FACTORY,
|
||||
ACTIVE_ANALYSIS_JOB_STATUSES,
|
||||
ANALYSIS_QUEUE_NAME,
|
||||
normalizeRequestedMatchCount,
|
||||
USER_ANALYSIS_JOB_NAME,
|
||||
} from './analysis.constants';
|
||||
import type { UserAnalysisJobData } from './analysis.types';
|
||||
|
||||
type JobIdFactory = () => string;
|
||||
type ActiveAnalysisJob = Pick<AnalysisJob, 'jobId'> & {
|
||||
status: Extract<AnalysisJob['status'], 'queued' | 'processing'>;
|
||||
};
|
||||
|
||||
@Injectable()
|
||||
export class AnalysisQueueService {
|
||||
constructor(
|
||||
@InjectQueue(ANALYSIS_QUEUE_NAME)
|
||||
private readonly analysisQueue: Queue<
|
||||
UserAnalysisJobData,
|
||||
void,
|
||||
typeof USER_ANALYSIS_JOB_NAME
|
||||
>,
|
||||
private readonly connectionService: ConnectionService,
|
||||
@Inject(ANALYSIS_JOB_ID_FACTORY)
|
||||
private readonly jobIdFactory: JobIdFactory = randomUUID,
|
||||
) {}
|
||||
|
||||
public async enqueueUserAnalysis(
|
||||
data: UserAnalysisJobData,
|
||||
): Promise<AnalysisRequestAcceptedDto> {
|
||||
const normalizedData = {
|
||||
...data,
|
||||
requestedMatchCount: normalizeRequestedMatchCount(
|
||||
data.requestedMatchCount,
|
||||
),
|
||||
};
|
||||
const duplicateRequestKey = this.duplicateRequestKey(normalizedData);
|
||||
while (this.pendingDuplicateRequestKeys.has(duplicateRequestKey)) {
|
||||
await this.sleep(10);
|
||||
}
|
||||
|
||||
this.pendingDuplicateRequestKeys.add(duplicateRequestKey);
|
||||
try {
|
||||
return await this.enqueueUserAnalysisWithoutDuplicateRequestRace(
|
||||
normalizedData,
|
||||
);
|
||||
} finally {
|
||||
this.pendingDuplicateRequestKeys.delete(duplicateRequestKey);
|
||||
}
|
||||
}
|
||||
|
||||
private readonly pendingDuplicateRequestKeys = new Set<string>();
|
||||
|
||||
private async enqueueUserAnalysisWithoutDuplicateRequestRace(
|
||||
normalizedData: UserAnalysisJobData,
|
||||
): Promise<AnalysisRequestAcceptedDto> {
|
||||
const analysisJobModel =
|
||||
await this.connectionService.getModel('analysisJob');
|
||||
const existingJob = await this.findActiveJob(
|
||||
analysisJobModel,
|
||||
normalizedData,
|
||||
);
|
||||
if (existingJob) {
|
||||
return {
|
||||
jobId: existingJob.jobId,
|
||||
status: existingJob.status,
|
||||
};
|
||||
}
|
||||
|
||||
const jobId = this.jobIdFactory();
|
||||
await analysisJobModel.create({
|
||||
jobId,
|
||||
jobType: USER_ANALYSIS_JOB_NAME,
|
||||
gameName: normalizedData.gameName,
|
||||
tagLine: normalizedData.tagLine,
|
||||
platformRoute: normalizedData.platformRoute,
|
||||
queueId: normalizedData.queueId,
|
||||
requestedMatchCount: normalizedData.requestedMatchCount,
|
||||
status: 'queued',
|
||||
stage: 'queued',
|
||||
progress: {
|
||||
fetchedMatches: 0,
|
||||
totalMatches: 0,
|
||||
},
|
||||
});
|
||||
|
||||
try {
|
||||
await this.analysisQueue.add(USER_ANALYSIS_JOB_NAME, normalizedData, {
|
||||
attempts: 2,
|
||||
backoff: {
|
||||
type: 'exponential',
|
||||
delay: 1_000,
|
||||
},
|
||||
jobId,
|
||||
});
|
||||
} catch (error) {
|
||||
await analysisJobModel
|
||||
.updateOne(
|
||||
{ jobId },
|
||||
{
|
||||
$set: {
|
||||
status: 'failed',
|
||||
stage: 'enqueue',
|
||||
error: this.errorMessage(error),
|
||||
},
|
||||
},
|
||||
)
|
||||
.exec();
|
||||
throw error;
|
||||
}
|
||||
|
||||
return {
|
||||
jobId,
|
||||
status: 'queued',
|
||||
};
|
||||
}
|
||||
|
||||
private async findActiveJob(
|
||||
analysisJobModel: Awaited<ReturnType<ConnectionService['getModel']>>,
|
||||
data: UserAnalysisJobData,
|
||||
): Promise<ActiveAnalysisJob | null> {
|
||||
return analysisJobModel
|
||||
.findOne({
|
||||
gameName: data.gameName,
|
||||
tagLine: data.tagLine,
|
||||
platformRoute: data.platformRoute,
|
||||
queueId: data.queueId,
|
||||
status: { $in: ACTIVE_ANALYSIS_JOB_STATUSES },
|
||||
})
|
||||
.sort({ createdAt: -1 })
|
||||
.lean<ActiveAnalysisJob>()
|
||||
.exec();
|
||||
}
|
||||
|
||||
private errorMessage(error: unknown): string {
|
||||
return error instanceof Error ? error.message : String(error);
|
||||
}
|
||||
|
||||
private duplicateRequestKey(data: UserAnalysisJobData): string {
|
||||
return [
|
||||
data.platformRoute,
|
||||
data.queueId,
|
||||
data.gameName.trim().toLocaleLowerCase(),
|
||||
data.tagLine.trim().toLocaleLowerCase(),
|
||||
].join(':');
|
||||
}
|
||||
|
||||
private async sleep(durationMs: number): Promise<void> {
|
||||
await new Promise((resolve) => setTimeout(resolve, durationMs));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
export const ANALYSIS_QUEUE_NAME = 'analysis';
|
||||
export const USER_ANALYSIS_JOB_NAME = 'user-analysis';
|
||||
export const ANALYSIS_JOB_ID_FACTORY = Symbol('ANALYSIS_JOB_ID_FACTORY');
|
||||
|
||||
export const DEFAULT_ANALYSIS_MATCH_COUNT = 20;
|
||||
export const MAX_ANALYSIS_MATCH_COUNT = 50;
|
||||
|
||||
export const ACTIVE_ANALYSIS_JOB_STATUSES = ['queued', 'processing'] as const;
|
||||
|
||||
export function normalizeRequestedMatchCount(
|
||||
requestedMatchCount: number,
|
||||
): number {
|
||||
if (!Number.isFinite(requestedMatchCount) || requestedMatchCount <= 0) {
|
||||
return DEFAULT_ANALYSIS_MATCH_COUNT;
|
||||
}
|
||||
|
||||
return Math.min(Math.trunc(requestedMatchCount), MAX_ANALYSIS_MATCH_COUNT);
|
||||
}
|
||||
@@ -0,0 +1,49 @@
|
||||
import { BullModule } from '@nestjs/bullmq';
|
||||
import { Module } from '@nestjs/common';
|
||||
import { randomUUID } from 'node:crypto';
|
||||
import { DatabaseModule } from '../global/database/database.module';
|
||||
import { SecretModule } from '../global/secret/secret.module';
|
||||
import { SecretService } from '../global/secret/secret.service';
|
||||
import { RiotModule } from '../riot/riot.module';
|
||||
import { AnalysisQueueService } from './analysis-queue.service';
|
||||
import {
|
||||
ANALYSIS_JOB_ID_FACTORY,
|
||||
ANALYSIS_QUEUE_NAME,
|
||||
} from './analysis.constants';
|
||||
import { AnalysisPipelineService } from './analysis-pipeline.service';
|
||||
import { AnalysisProcessor } from './analysis.processor';
|
||||
import { createBullMqOptions } from './bullmq.config';
|
||||
import { FeatureExtractorService } from './feature-extractor.service';
|
||||
import { ProfileBuilderService } from './profile-builder.service';
|
||||
|
||||
@Module({
|
||||
imports: [
|
||||
SecretModule,
|
||||
DatabaseModule,
|
||||
RiotModule,
|
||||
BullModule.forRootAsync({
|
||||
imports: [SecretModule],
|
||||
inject: [SecretService],
|
||||
useFactory: createBullMqOptions,
|
||||
extraOptions: {
|
||||
manualRegistration: process.env.NODE_ENV === 'test',
|
||||
},
|
||||
}),
|
||||
BullModule.registerQueue({
|
||||
name: ANALYSIS_QUEUE_NAME,
|
||||
}),
|
||||
],
|
||||
providers: [
|
||||
{
|
||||
provide: ANALYSIS_JOB_ID_FACTORY,
|
||||
useValue: randomUUID,
|
||||
},
|
||||
AnalysisQueueService,
|
||||
AnalysisPipelineService,
|
||||
AnalysisProcessor,
|
||||
FeatureExtractorService,
|
||||
ProfileBuilderService,
|
||||
],
|
||||
exports: [AnalysisQueueService, AnalysisPipelineService],
|
||||
})
|
||||
export class AnalysisModule {}
|
||||
@@ -0,0 +1,117 @@
|
||||
import type { Job } from 'bullmq';
|
||||
import { USER_ANALYSIS_JOB_NAME } from './analysis.constants';
|
||||
import type { UserAnalysisJobData } from './analysis.types';
|
||||
import { AnalysisPipelineService } from './analysis-pipeline.service';
|
||||
import { AnalysisProcessor } from './analysis.processor';
|
||||
|
||||
function createJobData(): UserAnalysisJobData {
|
||||
return {
|
||||
gameName: 'Hide on bush',
|
||||
tagLine: 'KR1',
|
||||
platformRoute: 'kr',
|
||||
regionalRoute: 'asia',
|
||||
queueId: 420,
|
||||
requestedMatchCount: 20,
|
||||
};
|
||||
}
|
||||
|
||||
describe('AnalysisProcessor', () => {
|
||||
it('delegates BullMQ jobs to the analysis pipeline', async () => {
|
||||
const processUserAnalysisJob = jest
|
||||
.fn<
|
||||
Promise<void>,
|
||||
[UserAnalysisJobData, string, { isFinalAttempt?: boolean }]
|
||||
>()
|
||||
.mockResolvedValue(undefined);
|
||||
const processor = new AnalysisProcessor({
|
||||
processUserAnalysisJob,
|
||||
} as unknown as AnalysisPipelineService);
|
||||
|
||||
await processor.process({
|
||||
attemptsMade: 1,
|
||||
id: 'analysis-job-1',
|
||||
name: USER_ANALYSIS_JOB_NAME,
|
||||
opts: { attempts: 2 },
|
||||
data: createJobData(),
|
||||
} as Job<unknown>);
|
||||
|
||||
expect(processUserAnalysisJob).toHaveBeenCalledWith(
|
||||
createJobData(),
|
||||
'analysis-job-1',
|
||||
{ isFinalAttempt: true },
|
||||
);
|
||||
});
|
||||
|
||||
it('rejects jobs without a BullMQ id', async () => {
|
||||
const processor = new AnalysisProcessor({
|
||||
processUserAnalysisJob: jest.fn(),
|
||||
} as unknown as AnalysisPipelineService);
|
||||
|
||||
await expect(
|
||||
processor.process({
|
||||
data: createJobData(),
|
||||
name: USER_ANALYSIS_JOB_NAME,
|
||||
} as Job<unknown>),
|
||||
).rejects.toThrow('Analysis job is missing a BullMQ job id.');
|
||||
});
|
||||
|
||||
it('rejects unsupported job names before processing data', async () => {
|
||||
const processUserAnalysisJob = jest.fn();
|
||||
const processor = new AnalysisProcessor({
|
||||
processUserAnalysisJob,
|
||||
} as unknown as AnalysisPipelineService);
|
||||
|
||||
await expect(
|
||||
processor.process({
|
||||
id: 'analysis-job-1',
|
||||
name: 'unexpected',
|
||||
data: createJobData(),
|
||||
} as Job<unknown>),
|
||||
).rejects.toThrow('Unsupported analysis job name "unexpected".');
|
||||
expect(processUserAnalysisJob).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('rejects malformed Redis payloads', async () => {
|
||||
const processUserAnalysisJob = jest.fn();
|
||||
const processor = new AnalysisProcessor({
|
||||
processUserAnalysisJob,
|
||||
} as unknown as AnalysisPipelineService);
|
||||
|
||||
await expect(
|
||||
processor.process({
|
||||
attemptsMade: 0,
|
||||
id: 'analysis-job-1',
|
||||
name: USER_ANALYSIS_JOB_NAME,
|
||||
opts: { attempts: 2 },
|
||||
data: {
|
||||
...createJobData(),
|
||||
regionalRoute: 'americas',
|
||||
},
|
||||
} as Job<unknown>),
|
||||
).rejects.toThrow(
|
||||
'Analysis job regionalRoute does not match platformRoute.',
|
||||
);
|
||||
expect(processUserAnalysisJob).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('normalizes requested match count from valid queue payloads', async () => {
|
||||
const processUserAnalysisJob = jest.fn().mockResolvedValue(undefined);
|
||||
const processor = new AnalysisProcessor({
|
||||
processUserAnalysisJob,
|
||||
} as unknown as AnalysisPipelineService);
|
||||
|
||||
await processor.process({
|
||||
attemptsMade: 0,
|
||||
id: 'analysis-job-1',
|
||||
name: USER_ANALYSIS_JOB_NAME,
|
||||
opts: { attempts: 2 },
|
||||
data: createJobData({ requestedMatchCount: 999 }),
|
||||
} as Job<unknown>);
|
||||
|
||||
expect(processUserAnalysisJob).toHaveBeenCalledWith(
|
||||
createJobData({ requestedMatchCount: 50 }),
|
||||
'analysis-job-1',
|
||||
{ isFinalAttempt: false },
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,127 @@
|
||||
import { Processor, WorkerHost } from '@nestjs/bullmq';
|
||||
import type { Job } from 'bullmq';
|
||||
import {
|
||||
ANALYSIS_QUEUE_NAME,
|
||||
normalizeRequestedMatchCount,
|
||||
USER_ANALYSIS_JOB_NAME,
|
||||
} from './analysis.constants';
|
||||
import { AnalysisPipelineService } from './analysis-pipeline.service';
|
||||
import type { UserAnalysisJobData } from './analysis.types';
|
||||
import {
|
||||
RIOT_PLATFORM_ROUTES,
|
||||
RIOT_REGIONAL_ROUTES,
|
||||
toRegionalRoute,
|
||||
type RiotPlatformRoute,
|
||||
type RiotRegionalRoute,
|
||||
} from '../riot/riot.types';
|
||||
|
||||
@Processor(ANALYSIS_QUEUE_NAME)
|
||||
export class AnalysisProcessor extends WorkerHost {
|
||||
constructor(
|
||||
private readonly analysisPipelineService: AnalysisPipelineService,
|
||||
) {
|
||||
super();
|
||||
}
|
||||
|
||||
public async process(job: Job<unknown>): Promise<void> {
|
||||
if (!job.id) {
|
||||
throw new Error('Analysis job is missing a BullMQ job id.');
|
||||
}
|
||||
if (job.name !== USER_ANALYSIS_JOB_NAME) {
|
||||
throw new Error(`Unsupported analysis job name "${job.name}".`);
|
||||
}
|
||||
|
||||
const data = this.parseUserAnalysisJobData(job.data);
|
||||
await this.analysisPipelineService.processUserAnalysisJob(data, job.id, {
|
||||
isFinalAttempt: this.isFinalAttempt(job),
|
||||
});
|
||||
}
|
||||
|
||||
private parseUserAnalysisJobData(value: unknown): UserAnalysisJobData {
|
||||
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
|
||||
throw new Error('Analysis job data must be an object.');
|
||||
}
|
||||
|
||||
const record = value as Record<string, unknown>;
|
||||
const gameName = this.parseBoundedString(record.gameName, 'gameName', 64);
|
||||
const tagLine = this.parseBoundedString(record.tagLine, 'tagLine', 16);
|
||||
const platformRoute = this.parsePlatformRoute(record.platformRoute);
|
||||
const regionalRoute = this.parseRegionalRoute(record.regionalRoute);
|
||||
if (regionalRoute !== toRegionalRoute(platformRoute)) {
|
||||
throw new Error(
|
||||
'Analysis job regionalRoute does not match platformRoute.',
|
||||
);
|
||||
}
|
||||
|
||||
const queueId = this.parseQueueId(record.queueId);
|
||||
const requestedMatchCount = this.parseRequestedMatchCount(
|
||||
record.requestedMatchCount,
|
||||
);
|
||||
|
||||
return {
|
||||
gameName,
|
||||
tagLine,
|
||||
platformRoute,
|
||||
regionalRoute,
|
||||
queueId,
|
||||
requestedMatchCount,
|
||||
};
|
||||
}
|
||||
|
||||
private parseBoundedString(
|
||||
value: unknown,
|
||||
fieldName: string,
|
||||
maximumLength: number,
|
||||
): string {
|
||||
if (typeof value !== 'string') {
|
||||
throw new Error(`Analysis job ${fieldName} must be a string.`);
|
||||
}
|
||||
const trimmed = value.trim();
|
||||
if (trimmed.length === 0 || trimmed.length > maximumLength) {
|
||||
throw new Error(`Analysis job ${fieldName} is out of range.`);
|
||||
}
|
||||
return trimmed;
|
||||
}
|
||||
|
||||
private parsePlatformRoute(value: unknown): RiotPlatformRoute {
|
||||
if (
|
||||
typeof value !== 'string' ||
|
||||
!RIOT_PLATFORM_ROUTES.includes(value as RiotPlatformRoute)
|
||||
) {
|
||||
throw new Error('Analysis job platformRoute is unsupported.');
|
||||
}
|
||||
return value as RiotPlatformRoute;
|
||||
}
|
||||
|
||||
private parseRegionalRoute(value: unknown): RiotRegionalRoute {
|
||||
if (
|
||||
typeof value !== 'string' ||
|
||||
!RIOT_REGIONAL_ROUTES.includes(value as RiotRegionalRoute)
|
||||
) {
|
||||
throw new Error('Analysis job regionalRoute is unsupported.');
|
||||
}
|
||||
return value as RiotRegionalRoute;
|
||||
}
|
||||
|
||||
private parseQueueId(value: unknown): number {
|
||||
if (value !== 420) {
|
||||
throw new Error('Analysis job queueId is unsupported.');
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
private parseRequestedMatchCount(value: unknown): number {
|
||||
if (typeof value !== 'number' || !Number.isFinite(value)) {
|
||||
throw new Error('Analysis job requestedMatchCount must be finite.');
|
||||
}
|
||||
return normalizeRequestedMatchCount(value);
|
||||
}
|
||||
|
||||
private isFinalAttempt(job: Job<unknown>): boolean {
|
||||
const attempts =
|
||||
typeof job.opts?.attempts === 'number' && job.opts.attempts > 0
|
||||
? job.opts.attempts
|
||||
: 1;
|
||||
return job.attemptsMade + 1 >= attempts;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,52 @@
|
||||
import type { Role } from '@persona-lenz/shared';
|
||||
import type { TeamPositionOrUnknown } from '../global/database/schemas';
|
||||
import type { RiotPlatformRoute, RiotRegionalRoute } from '../riot/riot.types';
|
||||
|
||||
export interface UserAnalysisJobData {
|
||||
gameName: string;
|
||||
tagLine: string;
|
||||
platformRoute: RiotPlatformRoute;
|
||||
regionalRoute: RiotRegionalRoute;
|
||||
queueId: number;
|
||||
requestedMatchCount: number;
|
||||
}
|
||||
|
||||
export interface ExtractedPlayerMatchFeature {
|
||||
matchId: string;
|
||||
puuid: string;
|
||||
queueId: number;
|
||||
role: TeamPositionOrUnknown;
|
||||
championId: number;
|
||||
gameCreation: number;
|
||||
gameDurationSec: number;
|
||||
win: boolean;
|
||||
patch: string;
|
||||
features: Record<string, number>;
|
||||
normalized: Record<string, number>;
|
||||
vector: number[];
|
||||
featureSchemaVersion: number;
|
||||
normalizationMethod: 'registry-baseline';
|
||||
confidence: number;
|
||||
timelineProcessed: false;
|
||||
}
|
||||
|
||||
export interface BuiltPlayerProfile {
|
||||
puuid: string;
|
||||
queueId: number;
|
||||
mainRole: Role;
|
||||
roleDistribution: Partial<Record<Role, number>>;
|
||||
sampleGameCount: number;
|
||||
championPool: Array<{
|
||||
championId: number;
|
||||
games: number;
|
||||
wins: number;
|
||||
}>;
|
||||
profile: Record<string, number>;
|
||||
vector: number[];
|
||||
featureSchemaVersion: number;
|
||||
normalizationMethod: 'registry-baseline';
|
||||
confidence: number;
|
||||
patches: string[];
|
||||
lastMatchAt?: Date;
|
||||
isSeed: boolean;
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
import {
|
||||
createBullMqOptions,
|
||||
resolveBullMqRedisConnection,
|
||||
} from './bullmq.config';
|
||||
|
||||
describe('BullMQ config', () => {
|
||||
it('parses redis URLs into BullMQ connection options', () => {
|
||||
expect(
|
||||
resolveBullMqRedisConnection('redis://worker:secret@redis.local:6380/2'),
|
||||
).toMatchObject({
|
||||
host: 'redis.local',
|
||||
port: 6380,
|
||||
username: 'worker',
|
||||
password: 'secret',
|
||||
db: 2,
|
||||
maxRetriesPerRequest: null,
|
||||
});
|
||||
});
|
||||
|
||||
it('enables TLS for rediss URLs', () => {
|
||||
expect(resolveBullMqRedisConnection('rediss://redis.local')).toMatchObject({
|
||||
host: 'redis.local',
|
||||
port: 6379,
|
||||
tls: {},
|
||||
});
|
||||
});
|
||||
|
||||
it('rejects malformed Redis URLs without an explicit host', () => {
|
||||
expect(() => resolveBullMqRedisConnection('redis:///0')).toThrow(
|
||||
'REDIS_URL must include a hostname.',
|
||||
);
|
||||
});
|
||||
|
||||
it('creates root options from SecretService without exposing secrets', async () => {
|
||||
const secretService = {
|
||||
get: jest
|
||||
.fn<Promise<string>, [string]>()
|
||||
.mockResolvedValue('redis://localhost:6379/0'),
|
||||
};
|
||||
|
||||
await expect(createBullMqOptions(secretService)).resolves.toMatchObject({
|
||||
connection: {
|
||||
host: 'localhost',
|
||||
port: 6379,
|
||||
db: 0,
|
||||
maxRetriesPerRequest: null,
|
||||
},
|
||||
defaultJobOptions: {
|
||||
attempts: 2,
|
||||
},
|
||||
});
|
||||
expect(secretService.get).toHaveBeenCalledWith('REDIS_URL');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,73 @@
|
||||
import type { BullRootModuleOptions } from '@nestjs/bullmq';
|
||||
import type { QueueOptions } from 'bullmq';
|
||||
import type { SecretService } from '../global/secret/secret.service';
|
||||
|
||||
export type BullMqConnectionOptions = NonNullable<QueueOptions['connection']>;
|
||||
|
||||
function parseRedisDatabase(pathname: string): number {
|
||||
const trimmedPath = pathname.replace(/^\/+/u, '');
|
||||
if (!trimmedPath) return 0;
|
||||
|
||||
const database = Number(trimmedPath);
|
||||
if (!Number.isInteger(database) || database < 0) {
|
||||
throw new Error('REDIS_URL must include a non-negative integer database.');
|
||||
}
|
||||
return database;
|
||||
}
|
||||
|
||||
export function resolveBullMqRedisConnection(
|
||||
redisUrl: string,
|
||||
): BullMqConnectionOptions {
|
||||
const parsedUrl = new URL(redisUrl);
|
||||
if (parsedUrl.protocol !== 'redis:' && parsedUrl.protocol !== 'rediss:') {
|
||||
throw new Error('REDIS_URL must use redis:// or rediss://.');
|
||||
}
|
||||
|
||||
if (!parsedUrl.hostname) {
|
||||
throw new Error('REDIS_URL must include a hostname.');
|
||||
}
|
||||
|
||||
const connection: BullMqConnectionOptions = {
|
||||
host: parsedUrl.hostname,
|
||||
port: parsedUrl.port ? Number(parsedUrl.port) : 6379,
|
||||
db: parseRedisDatabase(parsedUrl.pathname),
|
||||
maxRetriesPerRequest: null,
|
||||
};
|
||||
|
||||
if (parsedUrl.username) {
|
||||
connection.username = decodeURIComponent(parsedUrl.username);
|
||||
}
|
||||
if (parsedUrl.password) {
|
||||
connection.password = decodeURIComponent(parsedUrl.password);
|
||||
}
|
||||
if (parsedUrl.protocol === 'rediss:') {
|
||||
connection.tls = {};
|
||||
}
|
||||
|
||||
return connection;
|
||||
}
|
||||
|
||||
export async function createBullMqOptions(
|
||||
secretService: Pick<SecretService, 'get'>,
|
||||
): Promise<BullRootModuleOptions> {
|
||||
const redisUrl = await secretService.get<string>('REDIS_URL');
|
||||
|
||||
return {
|
||||
connection: resolveBullMqRedisConnection(redisUrl),
|
||||
defaultJobOptions: {
|
||||
attempts: 2,
|
||||
backoff: {
|
||||
type: 'exponential',
|
||||
delay: 1_000,
|
||||
},
|
||||
removeOnComplete: {
|
||||
age: 86_400,
|
||||
count: 1_000,
|
||||
},
|
||||
removeOnFail: {
|
||||
age: 604_800,
|
||||
count: 5_000,
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,187 @@
|
||||
import { FEATURE_SCHEMA_VERSION, METRICS } from '@persona-lenz/shared';
|
||||
import { FeatureExtractorService } from './feature-extractor.service';
|
||||
|
||||
function createMatchPayload(overrides: Record<string, unknown> = {}) {
|
||||
const currentPlayer = {
|
||||
puuid: 'target-puuid',
|
||||
teamId: 100,
|
||||
teamPosition: 'MIDDLE',
|
||||
championId: 103,
|
||||
kills: 6,
|
||||
deaths: 2,
|
||||
assists: 8,
|
||||
totalDamageDealtToChampions: 24_000,
|
||||
goldEarned: 12_000,
|
||||
totalMinionsKilled: 210,
|
||||
neutralMinionsKilled: 12,
|
||||
visionScore: 24,
|
||||
wardsKilled: 4,
|
||||
detectorWardsPlaced: 3,
|
||||
win: true,
|
||||
challenges: {
|
||||
kda: 7,
|
||||
killParticipation: 0.7,
|
||||
teamDamagePercentage: 0.32,
|
||||
damagePerMinute: 800,
|
||||
goldPerMinute: 400,
|
||||
visionScorePerMinute: 0.8,
|
||||
controlWardsPlaced: 3,
|
||||
dragonTakedowns: 1,
|
||||
baronTakedowns: 1,
|
||||
riftHeraldTakedowns: 0,
|
||||
soloKills: 2,
|
||||
},
|
||||
};
|
||||
|
||||
return {
|
||||
metadata: {
|
||||
matchId: 'KR_1',
|
||||
participants: ['target-puuid', 'ally-puuid', 'enemy-puuid'],
|
||||
},
|
||||
info: {
|
||||
gameCreation: 1_700_000_000_000,
|
||||
gameDuration: 1800,
|
||||
gameVersion: '26.13.123.456',
|
||||
queueId: 420,
|
||||
participants: [
|
||||
currentPlayer,
|
||||
{
|
||||
puuid: 'ally-puuid',
|
||||
teamId: 100,
|
||||
teamPosition: 'JUNGLE',
|
||||
championId: 64,
|
||||
kills: 10,
|
||||
totalDamageDealtToChampions: 30_000,
|
||||
},
|
||||
{
|
||||
puuid: 'enemy-puuid',
|
||||
teamId: 200,
|
||||
teamPosition: 'MIDDLE',
|
||||
championId: 134,
|
||||
kills: 4,
|
||||
totalDamageDealtToChampions: 16_000,
|
||||
},
|
||||
],
|
||||
...overrides,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
describe('FeatureExtractorService', () => {
|
||||
const service = new FeatureExtractorService();
|
||||
|
||||
it('extracts MVP 1 raw metrics and vector values in registry order', () => {
|
||||
const feature = service.extractPlayerMatchFeature(
|
||||
createMatchPayload(),
|
||||
'target-puuid',
|
||||
);
|
||||
|
||||
expect(feature.matchId).toBe('KR_1');
|
||||
expect(feature.role).toBe('MIDDLE');
|
||||
expect(feature.patch).toBe('26.13');
|
||||
expect(feature.features).toMatchObject({
|
||||
kda: 7,
|
||||
killParticipation: 0.7,
|
||||
damageShare: 0.32,
|
||||
damagePerMin: 800,
|
||||
goldPerMin: 400,
|
||||
csPerMin: 7.4,
|
||||
visionScorePerMin: 0.8,
|
||||
wardsKilledPerMin: 4 / 30,
|
||||
controlWardsPlaced: 3,
|
||||
deathsPerMin: 2 / 30,
|
||||
objectiveParticipation: 2,
|
||||
soloKills: 2,
|
||||
});
|
||||
expect(feature.vector).toEqual(
|
||||
METRICS.map((metric) => feature.normalized[metric.id]),
|
||||
);
|
||||
expect(feature.vector).toHaveLength(12);
|
||||
expect(feature.featureSchemaVersion).toBe(FEATURE_SCHEMA_VERSION);
|
||||
expect(feature.confidence).toBe(1);
|
||||
});
|
||||
|
||||
it('falls back to manual calculations when challenges are missing', () => {
|
||||
const payload = createMatchPayload({
|
||||
participants: [
|
||||
{
|
||||
puuid: 'target-puuid',
|
||||
teamId: 100,
|
||||
teamPosition: 'MIDDLE',
|
||||
championId: 103,
|
||||
kills: 6,
|
||||
deaths: 2,
|
||||
assists: 8,
|
||||
totalDamageDealtToChampions: 24_000,
|
||||
goldEarned: 12_000,
|
||||
totalMinionsKilled: 210,
|
||||
neutralMinionsKilled: 12,
|
||||
visionScore: 24,
|
||||
wardsKilled: 4,
|
||||
detectorWardsPlaced: 3,
|
||||
win: true,
|
||||
},
|
||||
{
|
||||
puuid: 'ally-puuid',
|
||||
teamId: 100,
|
||||
teamPosition: 'JUNGLE',
|
||||
championId: 64,
|
||||
kills: 14,
|
||||
totalDamageDealtToChampions: 36_000,
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
const feature = service.extractPlayerMatchFeature(payload, 'target-puuid');
|
||||
|
||||
expect(feature.features.kda).toBe(7);
|
||||
expect(feature.features.killParticipation).toBe(0.7);
|
||||
expect(feature.features.damageShare).toBe(0.4);
|
||||
expect(feature.features.damagePerMin).toBe(800);
|
||||
expect(feature.features.goldPerMin).toBe(400);
|
||||
expect(feature.features.controlWardsPlaced).toBe(3);
|
||||
expect(feature.features.objectiveParticipation).toBe(0);
|
||||
expect(feature.features.soloKills).toBe(0);
|
||||
});
|
||||
|
||||
it('marks unknown roles and short games with lower confidence', () => {
|
||||
const payload = createMatchPayload({
|
||||
gameDuration: 900,
|
||||
participants: [
|
||||
{
|
||||
puuid: 'target-puuid',
|
||||
teamId: 100,
|
||||
teamPosition: '',
|
||||
championId: 103,
|
||||
kills: 1,
|
||||
deaths: 2,
|
||||
assists: 1,
|
||||
totalDamageDealtToChampions: 5_000,
|
||||
goldEarned: 6_000,
|
||||
totalMinionsKilled: 100,
|
||||
neutralMinionsKilled: 0,
|
||||
visionScore: 10,
|
||||
wardsKilled: 1,
|
||||
detectorWardsPlaced: 0,
|
||||
win: false,
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
const feature = service.extractPlayerMatchFeature(payload, 'target-puuid');
|
||||
|
||||
expect(feature.role).toBe('UNKNOWN');
|
||||
expect(feature.confidence).toBe(0.5);
|
||||
});
|
||||
|
||||
it('marks known-role short games with short-game confidence only', () => {
|
||||
const payload = createMatchPayload({
|
||||
gameDuration: 900,
|
||||
});
|
||||
|
||||
const feature = service.extractPlayerMatchFeature(payload, 'target-puuid');
|
||||
|
||||
expect(feature.role).toBe('MIDDLE');
|
||||
expect(feature.confidence).toBe(0.8);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,218 @@
|
||||
import {
|
||||
FEATURE_SCHEMA_VERSION,
|
||||
METRICS,
|
||||
type MetricDefinition,
|
||||
type Role,
|
||||
} from '@persona-lenz/shared';
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import type { TeamPositionOrUnknown } from '../global/database/schemas';
|
||||
import type { ExtractedPlayerMatchFeature } from './analysis.types';
|
||||
|
||||
interface MatchParticipant {
|
||||
assists?: number;
|
||||
challenges?: Record<string, unknown>;
|
||||
championId?: number;
|
||||
deaths?: number;
|
||||
detectorWardsPlaced?: number;
|
||||
goldEarned?: number;
|
||||
kills?: number;
|
||||
neutralMinionsKilled?: number;
|
||||
puuid?: string;
|
||||
teamId?: number;
|
||||
teamPosition?: string;
|
||||
totalDamageDealtToChampions?: number;
|
||||
totalMinionsKilled?: number;
|
||||
visionScore?: number;
|
||||
wardsKilled?: number;
|
||||
win?: boolean;
|
||||
}
|
||||
|
||||
interface MatchInfo {
|
||||
gameCreation?: number;
|
||||
gameDuration?: number;
|
||||
gameVersion?: string;
|
||||
participants?: MatchParticipant[];
|
||||
queueId?: number;
|
||||
}
|
||||
|
||||
interface MatchPayload {
|
||||
info?: MatchInfo;
|
||||
metadata?: {
|
||||
matchId?: string;
|
||||
};
|
||||
}
|
||||
|
||||
const TEAM_POSITIONS = new Set<Role>([
|
||||
'TOP',
|
||||
'JUNGLE',
|
||||
'MIDDLE',
|
||||
'BOTTOM',
|
||||
'UTILITY',
|
||||
]);
|
||||
|
||||
function asRecord(value: unknown): Record<string, unknown> {
|
||||
if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
|
||||
return value as Record<string, unknown>;
|
||||
}
|
||||
return {};
|
||||
}
|
||||
|
||||
function asNumber(value: unknown, fallback = 0): number {
|
||||
return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
|
||||
}
|
||||
|
||||
function fromChallenge(
|
||||
challenges: Record<string, unknown>,
|
||||
key: string,
|
||||
): number | undefined {
|
||||
const value = challenges[key];
|
||||
return typeof value === 'number' && Number.isFinite(value)
|
||||
? value
|
||||
: undefined;
|
||||
}
|
||||
|
||||
function ratio(numerator: number, denominator: number): number {
|
||||
if (denominator <= 0) return 0;
|
||||
return numerator / denominator;
|
||||
}
|
||||
|
||||
function normalizeMetric(
|
||||
metric: MetricDefinition,
|
||||
role: Role,
|
||||
rawValue: number,
|
||||
): number {
|
||||
const baseline = metric.baseline?.[role];
|
||||
if (!baseline) return Math.max(0, Math.min(1, rawValue));
|
||||
return Math.max(
|
||||
0,
|
||||
Math.min(1, (rawValue - baseline.min) / (baseline.max - baseline.min)),
|
||||
);
|
||||
}
|
||||
|
||||
function resolveRole(teamPosition: string | undefined): TeamPositionOrUnknown {
|
||||
return TEAM_POSITIONS.has(teamPosition as Role)
|
||||
? (teamPosition as Role)
|
||||
: 'UNKNOWN';
|
||||
}
|
||||
|
||||
function resolveNormalizationRole(role: TeamPositionOrUnknown): Role {
|
||||
return role === 'UNKNOWN' ? 'MIDDLE' : role;
|
||||
}
|
||||
|
||||
function resolvePatch(gameVersion: string | undefined): string {
|
||||
const [major, minor] = (gameVersion ?? 'unknown').split('.');
|
||||
if (!major || !minor) return 'unknown';
|
||||
return `${major}.${minor}`;
|
||||
}
|
||||
|
||||
@Injectable()
|
||||
export class FeatureExtractorService {
|
||||
public extractPlayerMatchFeature(
|
||||
rawMatch: Record<string, unknown>,
|
||||
puuid: string,
|
||||
): ExtractedPlayerMatchFeature {
|
||||
const payload = rawMatch as MatchPayload;
|
||||
const info = payload.info ?? {};
|
||||
const participants = info.participants ?? [];
|
||||
const participant = participants.find(
|
||||
(candidate) => candidate.puuid === puuid,
|
||||
);
|
||||
|
||||
if (!participant) {
|
||||
throw new Error(`Participant not found for puuid="${puuid}".`);
|
||||
}
|
||||
|
||||
const gameDurationSec = asNumber(info.gameDuration);
|
||||
const gameMinutes = Math.max(gameDurationSec / 60, 1);
|
||||
const teamId = participant.teamId;
|
||||
const teamParticipants = participants.filter(
|
||||
(candidate) => candidate.teamId === teamId,
|
||||
);
|
||||
const teamKills = teamParticipants.reduce(
|
||||
(sum, candidate) => sum + asNumber(candidate.kills),
|
||||
0,
|
||||
);
|
||||
const teamDamage = teamParticipants.reduce(
|
||||
(sum, candidate) => sum + asNumber(candidate.totalDamageDealtToChampions),
|
||||
0,
|
||||
);
|
||||
|
||||
const challenges = asRecord(participant.challenges);
|
||||
const kills = asNumber(participant.kills);
|
||||
const deaths = asNumber(participant.deaths);
|
||||
const assists = asNumber(participant.assists);
|
||||
const damage = asNumber(participant.totalDamageDealtToChampions);
|
||||
const gold = asNumber(participant.goldEarned);
|
||||
const minions =
|
||||
asNumber(participant.totalMinionsKilled) +
|
||||
asNumber(participant.neutralMinionsKilled);
|
||||
|
||||
const features: Record<string, number> = {
|
||||
kda:
|
||||
fromChallenge(challenges, 'kda') ??
|
||||
(kills + assists) / Math.max(deaths, 1),
|
||||
killParticipation:
|
||||
fromChallenge(challenges, 'killParticipation') ??
|
||||
ratio(kills + assists, teamKills),
|
||||
damageShare:
|
||||
fromChallenge(challenges, 'teamDamagePercentage') ??
|
||||
ratio(damage, teamDamage),
|
||||
damagePerMin:
|
||||
fromChallenge(challenges, 'damagePerMinute') ?? damage / gameMinutes,
|
||||
goldPerMin:
|
||||
fromChallenge(challenges, 'goldPerMinute') ?? gold / gameMinutes,
|
||||
csPerMin: minions / gameMinutes,
|
||||
visionScorePerMin:
|
||||
fromChallenge(challenges, 'visionScorePerMinute') ??
|
||||
asNumber(participant.visionScore) / gameMinutes,
|
||||
wardsKilledPerMin: asNumber(participant.wardsKilled) / gameMinutes,
|
||||
controlWardsPlaced:
|
||||
fromChallenge(challenges, 'controlWardsPlaced') ??
|
||||
asNumber(participant.detectorWardsPlaced),
|
||||
deathsPerMin: deaths / gameMinutes,
|
||||
objectiveParticipation:
|
||||
asNumber(challenges.dragonTakedowns) +
|
||||
asNumber(challenges.baronTakedowns) +
|
||||
asNumber(challenges.riftHeraldTakedowns),
|
||||
soloKills: fromChallenge(challenges, 'soloKills') ?? 0,
|
||||
};
|
||||
|
||||
const role = resolveRole(participant.teamPosition);
|
||||
const normalizationRole = resolveNormalizationRole(role);
|
||||
const normalized = Object.fromEntries(
|
||||
METRICS.map((metric) => [
|
||||
metric.id,
|
||||
normalizeMetric(metric, normalizationRole, features[metric.id] ?? 0),
|
||||
]),
|
||||
);
|
||||
|
||||
return {
|
||||
matchId: payload.metadata?.matchId ?? '',
|
||||
puuid,
|
||||
queueId: asNumber(info.queueId),
|
||||
role,
|
||||
championId: asNumber(participant.championId),
|
||||
gameCreation: asNumber(info.gameCreation),
|
||||
gameDurationSec,
|
||||
win: participant.win === true,
|
||||
patch: resolvePatch(info.gameVersion),
|
||||
features,
|
||||
normalized,
|
||||
vector: METRICS.map((metric) => normalized[metric.id]),
|
||||
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
|
||||
normalizationMethod: 'registry-baseline',
|
||||
confidence: this.resolveConfidence(role, gameDurationSec),
|
||||
timelineProcessed: false,
|
||||
};
|
||||
}
|
||||
|
||||
private resolveConfidence(
|
||||
role: TeamPositionOrUnknown,
|
||||
gameDurationSec: number,
|
||||
): number {
|
||||
let confidence = 1;
|
||||
if (role === 'UNKNOWN') confidence = Math.min(confidence, 0.5);
|
||||
if (gameDurationSec < 1200) confidence = Math.min(confidence, 0.8);
|
||||
return confidence;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,109 @@
|
||||
import { FEATURE_SCHEMA_VERSION, METRICS } from '@persona-lenz/shared';
|
||||
import type { PlayerMatchFeature } from '../global/database/schemas';
|
||||
import { ProfileBuilderService } from './profile-builder.service';
|
||||
|
||||
function createFeature(
|
||||
overrides: Partial<PlayerMatchFeature> = {},
|
||||
): PlayerMatchFeature {
|
||||
const normalized = Object.fromEntries(
|
||||
METRICS.map((metric) => [metric.id, 0.5]),
|
||||
);
|
||||
|
||||
return {
|
||||
createdAt: new Date('2026-07-01T00:00:00.000Z'),
|
||||
updatedAt: new Date('2026-07-01T00:00:00.000Z'),
|
||||
matchId: 'KR_1',
|
||||
puuid: 'target-puuid',
|
||||
queueId: 420,
|
||||
role: 'MIDDLE',
|
||||
championId: 103,
|
||||
gameCreation: 1_700_000_000_000,
|
||||
gameDurationSec: 1800,
|
||||
win: true,
|
||||
patch: '26.13',
|
||||
features: {},
|
||||
normalized,
|
||||
vector: METRICS.map((metric) => normalized[metric.id]),
|
||||
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
|
||||
normalizationMethod: 'registry-baseline',
|
||||
confidence: 1,
|
||||
timelineProcessed: false,
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe('ProfileBuilderService', () => {
|
||||
const service = new ProfileBuilderService();
|
||||
|
||||
it('builds a confidence-weighted profile in registry vector order', () => {
|
||||
const firstNormalized = Object.fromEntries(
|
||||
METRICS.map((metric, index) => [metric.id, 0.8 - index * 0.01]),
|
||||
);
|
||||
const secondNormalized = Object.fromEntries(
|
||||
METRICS.map((metric, index) => [metric.id, 0.2 + index * 0.01]),
|
||||
);
|
||||
const firstFeature = createFeature({
|
||||
matchId: 'KR_1',
|
||||
role: 'MIDDLE',
|
||||
championId: 103,
|
||||
win: true,
|
||||
normalized: firstNormalized,
|
||||
confidence: 1,
|
||||
patch: '26.13',
|
||||
gameCreation: 1_700_000_000_000,
|
||||
});
|
||||
firstFeature.vector = METRICS.map(
|
||||
(metric) => firstFeature.normalized[metric.id],
|
||||
);
|
||||
|
||||
const secondFeature = createFeature({
|
||||
matchId: 'KR_2',
|
||||
role: 'BOTTOM',
|
||||
championId: 22,
|
||||
win: false,
|
||||
normalized: secondNormalized,
|
||||
confidence: 0.5,
|
||||
patch: '26.14',
|
||||
gameCreation: 1_700_100_000_000,
|
||||
});
|
||||
secondFeature.vector = METRICS.map(
|
||||
(metric) => secondFeature.normalized[metric.id],
|
||||
);
|
||||
|
||||
const profile = service.buildProfile({
|
||||
features: [firstFeature, secondFeature],
|
||||
isSeed: false,
|
||||
puuid: 'target-puuid',
|
||||
queueId: 420,
|
||||
});
|
||||
|
||||
expect(profile.mainRole).toBe('MIDDLE');
|
||||
expect(profile.sampleGameCount).toBe(2);
|
||||
for (const metric of METRICS) {
|
||||
expect(profile.profile[metric.id]).toBeCloseTo(
|
||||
(firstNormalized[metric.id] + secondNormalized[metric.id] * 0.5) / 1.5,
|
||||
);
|
||||
}
|
||||
expect(profile.vector).toEqual(
|
||||
METRICS.map((metric) => profile.profile[metric.id]),
|
||||
);
|
||||
expect(profile.championPool).toEqual([
|
||||
{ championId: 103, games: 1, wins: 1 },
|
||||
{ championId: 22, games: 1, wins: 0 },
|
||||
]);
|
||||
expect(profile.patches).toEqual(['26.13', '26.14']);
|
||||
expect(profile.lastMatchAt).toEqual(new Date(1_700_100_000_000));
|
||||
expect(profile.confidence).toBeCloseTo(0.3);
|
||||
});
|
||||
|
||||
it('throws when no features are available', () => {
|
||||
expect(() =>
|
||||
service.buildProfile({
|
||||
features: [],
|
||||
isSeed: false,
|
||||
puuid: 'target-puuid',
|
||||
queueId: 420,
|
||||
}),
|
||||
).toThrow('Cannot build a profile without match features.');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,137 @@
|
||||
import {
|
||||
FEATURE_SCHEMA_VERSION,
|
||||
METRICS,
|
||||
type Role,
|
||||
} from '@persona-lenz/shared';
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import type { PlayerMatchFeature } from '../global/database/schemas';
|
||||
import type { BuiltPlayerProfile } from './analysis.types';
|
||||
|
||||
type ProfileSourceFeature = Pick<
|
||||
PlayerMatchFeature,
|
||||
| 'championId'
|
||||
| 'confidence'
|
||||
| 'gameCreation'
|
||||
| 'normalized'
|
||||
| 'patch'
|
||||
| 'role'
|
||||
| 'win'
|
||||
>;
|
||||
|
||||
export interface BuildProfileParams {
|
||||
features: ProfileSourceFeature[];
|
||||
isSeed: boolean;
|
||||
puuid: string;
|
||||
queueId: number;
|
||||
}
|
||||
|
||||
const ROLE_ORDER: Role[] = ['TOP', 'JUNGLE', 'MIDDLE', 'BOTTOM', 'UTILITY'];
|
||||
|
||||
function isRole(value: string): value is Role {
|
||||
return ROLE_ORDER.includes(value as Role);
|
||||
}
|
||||
|
||||
@Injectable()
|
||||
export class ProfileBuilderService {
|
||||
public buildProfile(params: BuildProfileParams): BuiltPlayerProfile {
|
||||
if (params.features.length === 0) {
|
||||
throw new Error('Cannot build a profile without match features.');
|
||||
}
|
||||
|
||||
const totalConfidence = params.features.reduce(
|
||||
(sum, feature) => sum + feature.confidence,
|
||||
0,
|
||||
);
|
||||
const safeTotalConfidence = Math.max(totalConfidence, Number.EPSILON);
|
||||
|
||||
const profile = Object.fromEntries(
|
||||
METRICS.map((metric) => [
|
||||
metric.id,
|
||||
params.features.reduce(
|
||||
(sum, feature) =>
|
||||
sum + (feature.normalized[metric.id] ?? 0) * feature.confidence,
|
||||
0,
|
||||
) / safeTotalConfidence,
|
||||
]),
|
||||
);
|
||||
|
||||
const roleCounts = new Map<Role, number>();
|
||||
const championPool = new Map<
|
||||
number,
|
||||
{ championId: number; games: number; wins: number }
|
||||
>();
|
||||
|
||||
for (const feature of params.features) {
|
||||
if (isRole(feature.role)) {
|
||||
roleCounts.set(feature.role, (roleCounts.get(feature.role) ?? 0) + 1);
|
||||
}
|
||||
|
||||
const championEntry = championPool.get(feature.championId) ?? {
|
||||
championId: feature.championId,
|
||||
games: 0,
|
||||
wins: 0,
|
||||
};
|
||||
championEntry.games += 1;
|
||||
if (feature.win) championEntry.wins += 1;
|
||||
championPool.set(feature.championId, championEntry);
|
||||
}
|
||||
|
||||
const knownRoleGameCount = [...roleCounts.values()].reduce(
|
||||
(sum, count) => sum + count,
|
||||
0,
|
||||
);
|
||||
const roleDistribution = Object.fromEntries(
|
||||
[...roleCounts.entries()].map(([role, count]) => [
|
||||
role,
|
||||
count / Math.max(knownRoleGameCount, 1),
|
||||
]),
|
||||
) as Partial<Record<Role, number>>;
|
||||
|
||||
const averageConfidence = totalConfidence / params.features.length;
|
||||
const sampleSizeConfidenceMultiplier = Math.min(
|
||||
params.features.length / 5,
|
||||
1,
|
||||
);
|
||||
|
||||
return {
|
||||
puuid: params.puuid,
|
||||
queueId: params.queueId,
|
||||
mainRole: this.resolveMainRole(roleCounts),
|
||||
roleDistribution,
|
||||
sampleGameCount: params.features.length,
|
||||
championPool: [...championPool.values()].sort(
|
||||
(left, right) =>
|
||||
right.games - left.games ||
|
||||
right.wins - left.wins ||
|
||||
left.championId - right.championId,
|
||||
),
|
||||
profile,
|
||||
vector: METRICS.map((metric) => profile[metric.id]),
|
||||
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
|
||||
normalizationMethod: 'registry-baseline',
|
||||
confidence: averageConfidence * sampleSizeConfidenceMultiplier,
|
||||
patches: [
|
||||
...new Set(params.features.map((feature) => feature.patch)),
|
||||
].sort(),
|
||||
lastMatchAt: new Date(
|
||||
Math.max(...params.features.map((feature) => feature.gameCreation)),
|
||||
),
|
||||
isSeed: params.isSeed,
|
||||
};
|
||||
}
|
||||
|
||||
private resolveMainRole(roleCounts: Map<Role, number>): Role {
|
||||
let selectedRole: Role = 'MIDDLE';
|
||||
let selectedCount = -1;
|
||||
|
||||
for (const role of ROLE_ORDER) {
|
||||
const count = roleCounts.get(role) ?? 0;
|
||||
if (count > selectedCount) {
|
||||
selectedRole = role;
|
||||
selectedCount = count;
|
||||
}
|
||||
}
|
||||
|
||||
return selectedRole;
|
||||
}
|
||||
}
|
||||
@@ -1,11 +1,14 @@
|
||||
import { getQueueToken } from '@nestjs/bullmq';
|
||||
import { Test, TestingModule } from '@nestjs/testing';
|
||||
import { INestApplication } from '@nestjs/common';
|
||||
import request from 'supertest';
|
||||
import { App } from 'supertest/types';
|
||||
import { configureApp } from './../src/app.setup';
|
||||
import { AppModule } from './../src/app.module';
|
||||
import { ANALYSIS_QUEUE_NAME } from './../src/modules/analysis/analysis.constants';
|
||||
import { ConnectionService } from './../src/modules/global/database/connection.service';
|
||||
import { REDIS_CLIENT } from './../src/modules/global/redis/redis.constants';
|
||||
import { SecretService } from './../src/modules/global/secret/secret.service';
|
||||
|
||||
describe('AppController (e2e)', () => {
|
||||
let app: INestApplication<App>;
|
||||
@@ -16,11 +19,25 @@ describe('AppController (e2e)', () => {
|
||||
})
|
||||
.overrideProvider(ConnectionService)
|
||||
.useValue({})
|
||||
.overrideProvider(SecretService)
|
||||
.useValue({
|
||||
get: jest.fn((key: string) => {
|
||||
if (key === 'REDIS_URL') {
|
||||
return Promise.resolve('redis://localhost:6379/0');
|
||||
}
|
||||
return Promise.resolve('');
|
||||
}),
|
||||
ready: jest.fn().mockResolvedValue(undefined),
|
||||
})
|
||||
.overrideProvider(REDIS_CLIENT)
|
||||
.useValue({
|
||||
destroy: jest.fn(),
|
||||
quit: jest.fn().mockResolvedValue(undefined),
|
||||
})
|
||||
.overrideProvider(getQueueToken(ANALYSIS_QUEUE_NAME))
|
||||
.useValue({
|
||||
add: jest.fn(),
|
||||
})
|
||||
.compile();
|
||||
|
||||
app = moduleFixture.createNestApplication();
|
||||
|
||||
Reference in new issue
Block a user