Add data infrastructure modules

This commit is contained in:
dahyeon committed 2026-07-02 13:35:34 -07:00
1 parent b4196c6afe
commit 4115646d66
60 files changed
+9642 -2

No files matched your search

+2
View File
@@ -25,6 +25,8 @@
"@nestjs/core": "^11.0.1",
"@nestjs/platform-express": "^11.0.1",
"@persona-lenz/shared": "workspace:*",
"mongoose": "^9.7.3",
"redis": "^5.12.1",
"reflect-metadata": "^0.2.2",
"rxjs": "^7.8.1",
"yaml": "^2.9.0"
@@ -0,0 +1,65 @@
import {
resolveMongoAppName,
resolveMongoConnectionOptions,
resolveMongoDbName,
} from './connection.service';
describe('resolveMongoDbName', () => {
it('uses production database only for prod', () => {
expect(resolveMongoDbName('prod')).toBe('persona-lenz');
});
it('uses isolated databases for non-production environments', () => {
expect(resolveMongoDbName('dev')).toBe('persona-lenz-dev');
expect(resolveMongoDbName('staging')).toBe('persona-lenz-staging');
expect(resolveMongoDbName('')).toBe('persona-lenz-dev');
expect(resolveMongoDbName('local')).toBe('persona-lenz-dev');
});
});
describe('resolveMongoAppName', () => {
it('identifies api environment and process for MongoDB connection tracking', () => {
expect(resolveMongoAppName('staging', 1234)).toBe(
'persona-lenz-api:staging:1234',
);
});
it('uses dev as the fallback environment label', () => {
expect(resolveMongoAppName('', 1234)).toBe('persona-lenz-api:dev:1234');
});
});
describe('resolveMongoConnectionOptions', () => {
it('disables automatic collection and index creation by default', () => {
expect(
resolveMongoConnectionOptions(
'persona-lenz-dev',
'persona-lenz-api:dev:1',
),
).toEqual({
dbName: 'persona-lenz-dev',
appName: 'persona-lenz-api:dev:1',
minPoolSize: 10,
maxPoolSize: 20,
autoIndex: false,
autoCreate: false,
});
});
it('enables automatic index creation when explicitly requested', () => {
expect(
resolveMongoConnectionOptions(
'persona-lenz-staging',
'persona-lenz-api:staging:1',
'true',
),
).toEqual({
dbName: 'persona-lenz-staging',
appName: 'persona-lenz-api:staging:1',
minPoolSize: 10,
maxPoolSize: 20,
autoIndex: true,
autoCreate: false,
});
});
});
@@ -0,0 +1,137 @@
import { Injectable, Logger, Scope, OnModuleInit } from '@nestjs/common';
import mongoose from 'mongoose';
import { SecretService } from '../secret/secret.service';
import { modelDefinitions, ModelTypes } from './schemas';
export function resolveMongoDbName(nodeEnv = process.env.NODE_ENV): string {
if (nodeEnv === 'prod') return 'persona-lenz';
if (nodeEnv === 'staging') return 'persona-lenz-staging';
return 'persona-lenz-dev';
}
export function resolveMongoAppName(
nodeEnv = process.env.NODE_ENV,
pid = process.pid,
): string {
return `persona-lenz-api:${nodeEnv || 'dev'}:${pid}`;
}
export function resolveMongoConnectionOptions(
dbName: string,
appName: string,
mongoAutoIndex = process.env.MONGODB_AUTO_INDEX,
): mongoose.ConnectOptions {
const shouldEnableMongoAutoIndex =
mongoAutoIndex?.trim().toLowerCase() === 'true';
return {
dbName,
appName,
minPoolSize: 10,
maxPoolSize: 20,
autoIndex: shouldEnableMongoAutoIndex,
autoCreate: false,
};
}
@Injectable({ scope: Scope.DEFAULT })
export class ConnectionService implements OnModuleInit {
private readonly logger = new Logger(ConnectionService.name);
private connection: mongoose.Connection | null = null;
constructor(private readonly secretService: SecretService) {}
private models: Map<string, mongoose.Model<any>> | null = null;
public async getConnection(): Promise<mongoose.Connection> {
if (
this.connection !== null &&
this.connection.readyState === mongoose.ConnectionStates.connected
) {
return this.connection;
}
const connectionString = await this.secretService.get(
'MONGODB_CONNECTION_STRING',
);
const dbName = resolveMongoDbName();
const appName = resolveMongoAppName();
const connectionOptions = resolveMongoConnectionOptions(dbName, appName);
const defaultConnection = await mongoose
.createConnection(connectionString, connectionOptions)
.asPromise();
this.connection = defaultConnection;
this.logger.log(
`MongoDB connection created. dbName=${dbName} appName=${appName} autoIndex=${
connectionOptions.autoIndex === true
}`,
);
return this.connection;
}
public async getModel<K extends keyof ModelTypes>(
modelKey: K,
): Promise<mongoose.Model<ModelTypes[K]>> {
if (this.models)
return this.models.get(modelKey) as mongoose.Model<ModelTypes[K]>;
const models = new Map<string, mongoose.Model<any>>();
const connection = await this.getConnection();
modelDefinitions.forEach((modelDefinition) => {
// 이미 생성된 경우 컴파일 스킵.
if (
Object.prototype.hasOwnProperty.call(
connection.models,
modelDefinition.name,
)
) {
models.set(
modelDefinition.name,
connection.models[modelDefinition.name],
);
} else {
models.set(
modelDefinition.name,
connection.model(
modelDefinition.name,
modelDefinition.schema,
modelDefinition.collectionName,
),
);
}
});
this.models = models;
return models.get(modelKey) as mongoose.Model<ModelTypes[K]>;
}
public async createSession(
options?: mongoose.ClientSessionOptions,
): Promise<mongoose.ClientSession | undefined> {
try {
const connection = await this.getConnection();
const session = await connection.startSession(options);
return session;
} catch (error) {
this.logError('Failed to start MongoDB session', error);
}
}
public async onModuleInit() {
await this.getConnection().catch((error: unknown) => {
this.logError('Failed to initialize MongoDB connection', error);
});
}
public async onModuleDestroy() {
await this.connection?.close();
}
private logError(message: string, error: unknown): void {
this.logger.error(
`${message}: ${error instanceof Error ? error.message : String(error)}`,
error instanceof Error ? error.stack : undefined,
);
}
}
@@ -0,0 +1,9 @@
import { Module } from '@nestjs/common';
import { ConnectionService } from './connection.service';
@Module({
imports: [],
providers: [ConnectionService],
exports: [ConnectionService],
})
export class DatabaseModule {}
@@ -0,0 +1,71 @@
import { HydratedDocument, Schema } from 'mongoose';
import type {
RiotPlatformRoute,
RiotRegionalRoute,
} from '../../../riot/riot.types';
import { MongooseTimestamps, TierInfo, TierInfoSubSchema } from './common';
/** 고티어 seed 계정이 어느 리그 목록에서 수집됐는지 (MVP 3) */
export type SeedSource = 'challenger' | 'grandmaster' | 'master';
export const SEED_SOURCES: SeedSource[] = [
'challenger',
'grandmaster',
'master',
];
/**
* Riot 계정. 분석을 요청한 유저와 고티어 seed 유저를 모두 이 컬렉션으로 관리한다.
* primary key는 puuid (Riot ID는 변경될 수 있음).
*/
export interface Account extends MongooseTimestamps {
puuid: string;
gameName: string;
tagLine: string;
platformRoute: RiotPlatformRoute;
regionalRoute: RiotRegionalRoute;
profileIconId: number;
summonerLevel: number;
tiers: TierInfo[]; // league-v4 결과. queueType별 최신 스냅샷
tiersFetchedAt?: Date;
matchIdsFetchedAt?: Date;
lastAnalyzedAt?: Date;
// ---- MVP 3: 고티어 seed pool ----
isSeed: boolean;
seedSource?: SeedSource;
seedAddedAt?: Date;
lastSeedCollectedAt?: Date; // seed 수집 스케줄러가 다음 수집 대상 선정에 사용
}
export const AccountSchema = new Schema<Account>(
{
puuid: { type: String, required: true },
gameName: { type: String, required: true },
tagLine: { type: String, required: true },
platformRoute: { type: String, required: true, default: 'kr' },
regionalRoute: { type: String, required: true, default: 'asia' },
profileIconId: { type: Number, required: true, default: 0 },
summonerLevel: { type: Number, required: true, default: 0 },
tiers: { type: [TierInfoSubSchema], required: true, default: [] },
tiersFetchedAt: { type: Date },
matchIdsFetchedAt: { type: Date },
lastAnalyzedAt: { type: Date },
isSeed: { type: Boolean, required: true, default: false },
seedSource: { type: String, enum: SEED_SOURCES },
seedAddedAt: { type: Date },
lastSeedCollectedAt: { type: Date },
},
{
timestamps: true,
collection: 'account',
},
);
AccountSchema.index({ puuid: 1 }, { unique: true });
AccountSchema.index({ gameName: 1, tagLine: 1 });
AccountSchema.index({ isSeed: 1, lastSeedCollectedAt: 1 });
export type AccountDocument = HydratedDocument<Account>;
@@ -0,0 +1,101 @@
import { HydratedDocument, Schema } from 'mongoose';
import type { RiotPlatformRoute } from '../../../riot/riot.types';
import { MongooseTimestamps } from './common';
/**
* - user-analysis: 유저 분석 요청 (MVP 1)
* - feature-recompute: featureSchemaVersion/정규화 변경에 따른 재계산 (MVP 2, docs/PLAN.md §11.4)
* - seed-collection: 고티어 seed 유저 수집 (MVP 3, §12.1)
* - baseline-computation: metric_baseline 분위값 계산 (MVP 3, §12.2)
*/
export type AnalysisJobType =
| 'user-analysis'
| 'feature-recompute'
| 'seed-collection'
| 'baseline-computation';
export const ANALYSIS_JOB_TYPES: AnalysisJobType[] = [
'user-analysis',
'feature-recompute',
'seed-collection',
'baseline-computation',
];
export type AnalysisJobStatus =
'queued' | 'processing' | 'completed' | 'failed';
export const ANALYSIS_JOB_STATUSES: AnalysisJobStatus[] = [
'queued',
'processing',
'completed',
'failed',
];
export interface AnalysisJobProgress {
fetchedMatches: number;
totalMatches: number;
}
const AnalysisJobProgressSubSchema = new Schema<AnalysisJobProgress>(
{
fetchedMatches: { type: Number, required: true, default: 0 },
totalMatches: { type: Number, required: true, default: 0 },
},
{ _id: false },
);
export interface AnalysisJob extends MongooseTimestamps {
jobId: string; // BullMQ job id와 동일하게 사용
jobType: AnalysisJobType;
puuid?: string; // user-analysis는 resolve-account 후 채움. seed-collection은 처음부터
gameName?: string; // user-analysis에서만 사용
tagLine?: string;
platformRoute: RiotPlatformRoute;
queueId: number;
requestedMatchCount: number;
status: AnalysisJobStatus;
stage?: string; // 'resolve-account' | 'fetch-match-ids' | ...
progress: AnalysisJobProgress;
error?: string;
completedAt?: Date;
}
export const AnalysisJobSchema = new Schema<AnalysisJob>(
{
jobId: { type: String, required: true },
jobType: {
type: String,
enum: ANALYSIS_JOB_TYPES,
required: true,
default: 'user-analysis',
},
puuid: { type: String },
gameName: { type: String },
tagLine: { type: String },
platformRoute: { type: String, required: true, default: 'kr' },
queueId: { type: Number, required: true, default: 420 },
requestedMatchCount: { type: Number, required: true, default: 20 },
status: {
type: String,
enum: ANALYSIS_JOB_STATUSES,
required: true,
default: 'queued',
},
stage: { type: String },
progress: {
type: AnalysisJobProgressSubSchema,
required: true,
default: () => ({ fetchedMatches: 0, totalMatches: 0 }),
},
error: { type: String },
completedAt: { type: Date },
},
{
timestamps: true,
collection: 'analysis_job',
},
);
AnalysisJobSchema.index({ jobId: 1 }, { unique: true });
AnalysisJobSchema.index({ puuid: 1, status: 1 });
AnalysisJobSchema.index({ jobType: 1, status: 1, createdAt: -1 });
export type AnalysisJobDocument = HydratedDocument<AnalysisJob>;
@@ -0,0 +1,53 @@
import { HydratedDocument, Schema } from 'mongoose';
import { MongooseTimestamps, TEAM_POSITIONS, TeamPosition } from './common';
export type ChampionStyleSource = 'manual-taxonomy' | 'derived-from-matches';
export const CHAMPION_STYLE_SOURCES: ChampionStyleSource[] = [
'manual-taxonomy',
'derived-from-matches',
];
/**
* 챔피언 스타일 벡터 (MVP 4). 초기엔 수동 taxonomy로 채우고,
* 이후 seed 유저 match data 기반(derived-from-matches)으로 교체한다.
*/
export interface ChampionStyleProfile extends MongooseTimestamps {
championId: number;
role: TeamPosition;
patch: string; // '26.13' 또는 'ALL'
source: ChampionStyleSource;
style: Record<string, number>; // metricId → 0~1
vector: number[];
featureSchemaVersion: number;
sampleGameCount?: number; // derived-from-matches일 때만
}
export const ChampionStyleProfileSchema = new Schema<ChampionStyleProfile>(
{
championId: { type: Number, required: true },
role: { type: String, enum: TEAM_POSITIONS, required: true },
patch: { type: String, required: true, default: 'ALL' },
source: {
type: String,
enum: CHAMPION_STYLE_SOURCES,
required: true,
default: 'manual-taxonomy',
},
style: { type: Schema.Types.Mixed, required: true, default: () => ({}) },
vector: { type: [Number], required: true, default: [] },
featureSchemaVersion: { type: Number, required: true },
sampleGameCount: { type: Number },
},
{
timestamps: true,
collection: 'champion_style_profile',
},
);
ChampionStyleProfileSchema.index(
{ championId: 1, role: 1, patch: 1, featureSchemaVersion: 1 },
{ unique: true },
);
export type ChampionStyleProfileDocument =
HydratedDocument<ChampionStyleProfile>;
@@ -0,0 +1,61 @@
import { Schema } from 'mongoose';
export interface MongooseTimestamps {
createdAt: Date;
updatedAt: Date;
}
/** Match-V5 participant.teamPosition 값 */
export type TeamPosition = 'TOP' | 'JUNGLE' | 'MIDDLE' | 'BOTTOM' | 'UTILITY';
export const TEAM_POSITIONS: TeamPosition[] = [
'TOP',
'JUNGLE',
'MIDDLE',
'BOTTOM',
'UTILITY',
];
/**
* teamPosition이 비어 있는 비정상 게임을 위한 확장 타입.
* 이 값이 저장되면 해당 feature의 confidence를 감점한다.
*/
export type TeamPositionOrUnknown = TeamPosition | 'UNKNOWN';
export const TEAM_POSITIONS_OR_UNKNOWN: TeamPositionOrUnknown[] = [
...TEAM_POSITIONS,
'UNKNOWN',
];
/**
* 정규화 방식 버전.
* - registry-baseline: feature registry의 role별 min-max clipping (MVP 1, cold start fallback)
* - population-percentile: metric_baseline 분위값 기반 percentile rank (MVP 3)
*/
export type NormalizationMethod = 'registry-baseline' | 'population-percentile';
export const NORMALIZATION_METHODS: NormalizationMethod[] = [
'registry-baseline',
'population-percentile',
];
/** League-V4 랭크 스냅샷 (queueType별 최신) */
export interface TierInfo {
queueType: string; // RANKED_SOLO_5x5, RANKED_FLEX_SR 등
tier: string; // IRON, BRONZE, ..., CHALLENGER
rank: string; // I | II | III | IV (Master+는 빈 문자열)
leaguePoints: number;
wins: number;
losses: number;
fetchedAt: Date; // Riot API로부터 조회된 시각
}
export const TierInfoSubSchema = new Schema<TierInfo>(
{
queueType: { type: String, required: true },
tier: { type: String, required: true },
rank: { type: String, required: true, default: '' },
leaguePoints: { type: Number, required: true, default: 0 },
wins: { type: Number, required: true, default: 0 },
losses: { type: Number, required: true, default: 0 },
fetchedAt: { type: Date, required: true, default: Date.now },
},
{ _id: false },
);
@@ -0,0 +1,82 @@
import { modelDefinitions } from './index';
const EXPECTED_MODEL_NAMES = [
'account',
'riotMatch',
'playerMatchFeature',
'playerProfile',
'analysisJob',
'metricBaseline',
'recommendation',
'championStyleProfile',
];
describe('modelDefinitions registry', () => {
it('registers every expected model exactly once', () => {
const names = modelDefinitions.map((definition) => definition.name);
expect(names.sort()).toEqual([...EXPECTED_MODEL_NAMES].sort());
expect(new Set(names).size).toBe(names.length);
});
it('uses unique snake_case singular collection names', () => {
const collectionNames = modelDefinitions.map(
(definition) => definition.collectionName,
);
expect(new Set(collectionNames).size).toBe(collectionNames.length);
for (const collectionName of collectionNames) {
expect(collectionName).toMatch(/^[a-z][a-z_]*[a-z]$/);
}
});
it('keeps collectionName in sync with each schema collection option', () => {
for (const definition of modelDefinitions) {
expect(definition.schema.get('collection')).toBe(
definition.collectionName,
);
}
});
it('enables timestamps on every schema', () => {
for (const definition of modelDefinitions) {
expect(definition.schema.get('timestamps')).toBe(true);
}
});
it('declares the unique indexes the pipeline depends on', () => {
const uniqueIndexesByModelName: Record<string, Record<string, number>> = {
account: { puuid: 1 },
riotMatch: { matchId: 1 },
playerMatchFeature: { matchId: 1, puuid: 1 },
playerProfile: { puuid: 1, queueId: 1 },
analysisJob: { jobId: 1 },
metricBaseline: {
metricId: 1,
role: 1,
cohort: 1,
patch: 1,
featureSchemaVersion: 1,
},
championStyleProfile: {
championId: 1,
role: 1,
patch: 1,
featureSchemaVersion: 1,
},
};
for (const [modelName, expectedKeys] of Object.entries(
uniqueIndexesByModelName,
)) {
const definition = modelDefinitions.find(
(candidate) => candidate.name === modelName,
);
expect(definition).toBeDefined();
const uniqueIndexes = definition!.schema
.indexes()
.filter(([, indexOptions]) => indexOptions?.unique === true)
.map(([indexKeys]) => indexKeys);
expect(uniqueIndexes).toContainEqual(expectedKeys);
}
});
});
@@ -0,0 +1,77 @@
import { ModelDefinition } from '../types';
import { Account, AccountSchema } from './account.schema';
import { AnalysisJob, AnalysisJobSchema } from './analysis-job.schema';
import {
ChampionStyleProfile,
ChampionStyleProfileSchema,
} from './champion-style-profile.schema';
import { MetricBaseline, MetricBaselineSchema } from './metric-baseline.schema';
import {
PlayerMatchFeature,
PlayerMatchFeatureSchema,
} from './player-match-feature.schema';
import { PlayerProfile, PlayerProfileSchema } from './player-profile.schema';
import { Recommendation, RecommendationSchema } from './recommendation.schema';
import { RiotMatch, RiotMatchSchema } from './riot-match.schema';
export * from './common';
export * from './account.schema';
export * from './analysis-job.schema';
export * from './champion-style-profile.schema';
export * from './metric-baseline.schema';
export * from './player-match-feature.schema';
export * from './player-profile.schema';
export * from './recommendation.schema';
export * from './riot-match.schema';
/**
* 새 컬렉션 추가 절차:
* 1. schemas/에 <collection>.schema.ts 생성 (interface + Schema + index 콜로케이션)
* 2. 여기 modelDefinitions와 ModelTypes에 등록
* 3. schemas/index.spec.ts의 기대 목록 갱신
*/
export const modelDefinitions: ModelDefinition[] = [
{ name: 'account', schema: AccountSchema, collectionName: 'account' },
{ name: 'riotMatch', schema: RiotMatchSchema, collectionName: 'riot_match' },
{
name: 'playerMatchFeature',
schema: PlayerMatchFeatureSchema,
collectionName: 'player_match_feature',
},
{
name: 'playerProfile',
schema: PlayerProfileSchema,
collectionName: 'player_profile',
},
{
name: 'analysisJob',
schema: AnalysisJobSchema,
collectionName: 'analysis_job',
},
{
name: 'metricBaseline',
schema: MetricBaselineSchema,
collectionName: 'metric_baseline',
},
{
name: 'recommendation',
schema: RecommendationSchema,
collectionName: 'recommendation',
},
{
name: 'championStyleProfile',
schema: ChampionStyleProfileSchema,
collectionName: 'champion_style_profile',
},
];
export interface ModelTypes {
account: Account;
riotMatch: RiotMatch;
playerMatchFeature: PlayerMatchFeature;
playerProfile: PlayerProfile;
analysisJob: AnalysisJob;
metricBaseline: MetricBaseline;
recommendation: Recommendation;
championStyleProfile: ChampionStyleProfile;
}
@@ -0,0 +1,50 @@
import { HydratedDocument, Schema } from 'mongoose';
import { MongooseTimestamps, TEAM_POSITIONS, TeamPosition } from './common';
export type BaselineCohort = 'MASTER_PLUS' | 'ALL';
export const BASELINE_COHORTS: BaselineCohort[] = ['MASTER_PLUS', 'ALL'];
/**
* metricId × role × cohort × patch 조합별 인구 분위값 (MVP 3, docs/PLAN.md §12.2).
* 정규화 v2(population-percentile)의 근거 데이터. baseline-computation 잡이 생성한다.
*/
export interface MetricBaseline extends MongooseTimestamps {
metricId: string;
role: TeamPosition;
cohort: BaselineCohort;
patch: string; // '26.13' 또는 'ALL'
featureSchemaVersion: number;
sampleCount: number;
/** p5~p95, 5% 간격 19개 분위값. 정규화 = 선형 보간 percentile rank */
percentileBreakpoints: number[];
computedAt: Date;
}
export const MetricBaselineSchema = new Schema<MetricBaseline>(
{
metricId: { type: String, required: true },
role: { type: String, enum: TEAM_POSITIONS, required: true },
cohort: {
type: String,
enum: BASELINE_COHORTS,
required: true,
default: 'MASTER_PLUS',
},
patch: { type: String, required: true, default: 'ALL' },
featureSchemaVersion: { type: Number, required: true },
sampleCount: { type: Number, required: true, default: 0 },
percentileBreakpoints: { type: [Number], required: true, default: [] },
computedAt: { type: Date, required: true, default: Date.now },
},
{
timestamps: true,
collection: 'metric_baseline',
},
);
MetricBaselineSchema.index(
{ metricId: 1, role: 1, cohort: 1, patch: 1, featureSchemaVersion: 1 },
{ unique: true },
);
export type MetricBaselineDocument = HydratedDocument<MetricBaseline>;
@@ -0,0 +1,105 @@
import { HydratedDocument, Schema } from 'mongoose';
import {
MongooseTimestamps,
NORMALIZATION_METHODS,
NormalizationMethod,
TEAM_POSITIONS_OR_UNKNOWN,
TeamPositionOrUnknown,
} from './common';
/** diff 지표(goldDiffAt10 등)의 비교 대상이 된 라인 상대 (MVP 2) */
export interface LaneOpponentRef {
puuid: string;
championId: number;
}
const LaneOpponentRefSubSchema = new Schema<LaneOpponentRef>(
{
puuid: { type: String, required: true },
championId: { type: Number, required: true },
},
{ _id: false },
);
/**
* 매치 1건 × 플레이어 1명의 feature 계산 결과.
* metricId 목록/순서/정규화 baseline은 packages/shared의 feature registry가 단일 진실 공급원이다.
*/
export interface PlayerMatchFeature extends MongooseTimestamps {
matchId: string;
puuid: string;
queueId: number;
role: TeamPositionOrUnknown; // participant.teamPosition. 빈 값이면 'UNKNOWN' + confidence 감점
championId: number;
gameCreation: number;
gameDurationSec: number;
win: boolean;
patch: string; // gameVersion 앞 두 마디. 예: '26.13'
features: Record<string, number>; // metricId → 정규화 전 raw 값
normalized: Record<string, number>; // metricId → 0~1 정규화 값
vector: number[]; // registry 순서대로 normalized 값
featureSchemaVersion: number;
normalizationMethod: NormalizationMethod;
confidence: number; // 0~1. remake/짧은 게임/role 불명 시 감점
// ---- MVP 2: timeline ----
timelineProcessed: boolean; // timeline 지표 반영 여부. 재계산 잡의 대상 식별
laneOpponent?: LaneOpponentRef;
derived?: Record<string, unknown>; // 스칼라가 아닌 파생물: deathEvents[{t,x,y,zone}] 등
}
export const PlayerMatchFeatureSchema = new Schema<PlayerMatchFeature>(
{
matchId: { type: String, required: true },
puuid: { type: String, required: true },
queueId: { type: Number, required: true },
role: {
type: String,
enum: TEAM_POSITIONS_OR_UNKNOWN,
required: true,
default: 'UNKNOWN',
},
championId: { type: Number, required: true },
gameCreation: { type: Number, required: true },
gameDurationSec: { type: Number, required: true },
win: { type: Boolean, required: true },
patch: { type: String, required: true },
features: { type: Schema.Types.Mixed, required: true, default: () => ({}) },
normalized: {
type: Schema.Types.Mixed,
required: true,
default: () => ({}),
},
vector: { type: [Number], required: true, default: [] },
featureSchemaVersion: { type: Number, required: true },
normalizationMethod: {
type: String,
enum: NORMALIZATION_METHODS,
required: true,
default: 'registry-baseline',
},
confidence: { type: Number, required: true, default: 1 },
timelineProcessed: { type: Boolean, required: true, default: false },
laneOpponent: { type: LaneOpponentRefSubSchema },
derived: { type: Schema.Types.Mixed },
},
{
timestamps: true,
collection: 'player_match_feature',
},
);
PlayerMatchFeatureSchema.index({ matchId: 1, puuid: 1 }, { unique: true });
PlayerMatchFeatureSchema.index({ puuid: 1, queueId: 1, gameCreation: -1 });
// 재계산 잡(feature-recompute)의 대상 스캔용
PlayerMatchFeatureSchema.index({
featureSchemaVersion: 1,
timelineProcessed: 1,
});
// baseline 계산(baseline-computation)의 cohort 집계용
PlayerMatchFeatureSchema.index({ role: 1, patch: 1, gameCreation: -1 });
export type PlayerMatchFeatureDocument = HydratedDocument<PlayerMatchFeature>;
@@ -0,0 +1,113 @@
import { HydratedDocument, Schema } from 'mongoose';
import {
MongooseTimestamps,
NORMALIZATION_METHODS,
NormalizationMethod,
TEAM_POSITIONS,
TeamPosition,
} from './common';
export interface ChampionPoolEntry {
championId: number;
games: number;
wins: number;
}
const ChampionPoolEntrySubSchema = new Schema<ChampionPoolEntry>(
{
championId: { type: Number, required: true },
games: { type: Number, required: true, default: 0 },
wins: { type: Number, required: true, default: 0 },
},
{ _id: false },
);
const RoleDistributionSubSchema = new Schema<
Partial<Record<TeamPosition, number>>
>(
{
TOP: { type: Number },
JUNGLE: { type: Number },
MIDDLE: { type: Number },
BOTTOM: { type: Number },
UTILITY: { type: Number },
},
{ _id: false },
);
/**
* 최근 N게임을 집계한 플레이어 프로필. Atlas Vector Search의 검색 대상 컬렉션.
*
* $vectorSearch는 같은 컬렉션의 필드로만 filter할 수 있으므로,
* 검색 필터에 필요한 값(tier, isSeed 등)을 profile build 시점에 account에서 비정규화해 저장한다.
* Vector Search 인덱스 정의는 docs/PLAN.md §12.3 (MVP 3에서 생성).
*/
export interface PlayerProfile extends MongooseTimestamps {
puuid: string;
queueId: number; // MVP 1은 420(솔로랭크) 고정
mainRole: TeamPosition;
roleDistribution: Partial<Record<TeamPosition, number>>; // 게임 수 비율 0~1
sampleGameCount: number;
championPool: ChampionPoolEntry[]; // games 내림차순. re-rank의 championPoolSim에 사용
profile: Record<string, number>; // metricId → 집계된 0~1 값
vector: number[];
featureSchemaVersion: number;
normalizationMethod: NormalizationMethod;
confidence: number;
patches: string[]; // 집계에 포함된 패치 목록
lastMatchAt?: Date; // 집계에 포함된 가장 최근 게임 시각. recency re-rank용
// ---- MVP 3: $vectorSearch filter용 비정규화 (build 시점 account.tiers에서 복사) ----
tier?: string; // RANKED_SOLO_5x5 기준. 'MASTER' 등
division?: string; // 'I'~'IV' (Master+는 없음)
leaguePoints?: number;
isSeed: boolean;
}
export const PlayerProfileSchema = new Schema<PlayerProfile>(
{
puuid: { type: String, required: true },
queueId: { type: Number, required: true },
mainRole: { type: String, enum: TEAM_POSITIONS, required: true },
roleDistribution: {
type: RoleDistributionSubSchema,
required: true,
default: () => ({}),
},
sampleGameCount: { type: Number, required: true },
championPool: {
type: [ChampionPoolEntrySubSchema],
required: true,
default: [],
},
profile: { type: Schema.Types.Mixed, required: true, default: () => ({}) },
vector: { type: [Number], required: true, default: [] },
featureSchemaVersion: { type: Number, required: true },
normalizationMethod: {
type: String,
enum: NORMALIZATION_METHODS,
required: true,
default: 'registry-baseline',
},
confidence: { type: Number, required: true, default: 1 },
patches: { type: [String], required: true, default: [] },
lastMatchAt: { type: Date },
tier: { type: String },
division: { type: String },
leaguePoints: { type: Number },
isSeed: { type: Boolean, required: true, default: false },
},
{
timestamps: true,
collection: 'player_profile',
},
);
PlayerProfileSchema.index({ puuid: 1, queueId: 1 }, { unique: true });
// 운영 조회용 (멘토 검색 자체는 Atlas Vector Search 인덱스 사용)
PlayerProfileSchema.index({ isSeed: 1, mainRole: 1, tier: 1 });
export type PlayerProfileDocument = HydratedDocument<PlayerProfile>;
@@ -0,0 +1,51 @@
import { HydratedDocument, Schema } from 'mongoose';
import { MongooseTimestamps } from './common';
/**
* - mentor-match: 유사 고티어 유저 Top-K (MVP 3)
* - champion-recommendation: Fit/Growth/Stretch 챔피언 추천 (MVP 4)
* - llm-feedback: LLM 생성 피드백 (MVP 5)
*/
export type RecommendationType =
'mentor-match' | 'champion-recommendation' | 'llm-feedback';
export const RECOMMENDATION_TYPES: RecommendationType[] = [
'mentor-match',
'champion-recommendation',
'llm-feedback',
];
/**
* 추천/피드백 결과 캐시. 프로필이 갱신되면(profileUpdatedAt 비교) stale로 보고 재계산한다.
* result/evidence의 type별 구조는 packages/shared의 DTO로 정의한다.
*/
export interface Recommendation extends MongooseTimestamps {
puuid: string;
queueId: number;
type: RecommendationType;
featureSchemaVersion: number;
profileUpdatedAt: Date; // 어떤 프로필 기준으로 생성됐는지
result: Record<string, unknown>;
evidence: Record<string, unknown>; // 근거 지표 스냅샷. LLM 입력·UI 근거 표시에 사용
generatedAt: Date;
}
export const RecommendationSchema = new Schema<Recommendation>(
{
puuid: { type: String, required: true },
queueId: { type: Number, required: true },
type: { type: String, enum: RECOMMENDATION_TYPES, required: true },
featureSchemaVersion: { type: Number, required: true },
profileUpdatedAt: { type: Date, required: true },
result: { type: Schema.Types.Mixed, required: true, default: () => ({}) },
evidence: { type: Schema.Types.Mixed, required: true, default: () => ({}) },
generatedAt: { type: Date, required: true, default: Date.now },
},
{
timestamps: true,
collection: 'recommendation',
},
);
RecommendationSchema.index({ puuid: 1, queueId: 1, type: 1, generatedAt: -1 });
export type RecommendationDocument = HydratedDocument<Recommendation>;
@@ -0,0 +1,44 @@
import { HydratedDocument, Schema } from 'mongoose';
import { MongooseTimestamps } from './common';
/**
* Riot Match-V5 원본 아카이브. 같은 matchId는 절대 재수집하지 않는다 (rate limit 보호).
* timeline은 MVP 2에서 채워진다.
*/
export interface RiotMatch extends MongooseTimestamps {
matchId: string; // 예: KR_7123456789
gameCreation: number;
gameDuration: number;
gameVersion?: string;
queueId?: number;
participantPuuids: string[];
raw: Record<string, unknown>; // Match-V5 원본 응답 전체
timeline?: Record<string, unknown>; // Match-V5 timeline 원본 응답 전체 (MVP 2)
timelineFetchedAt?: Date;
fetchedAt: Date;
}
export const RiotMatchSchema = new Schema<RiotMatch>(
{
matchId: { type: String, required: true },
gameCreation: { type: Number, required: true, default: 0 },
gameDuration: { type: Number, required: true, default: 0 },
gameVersion: { type: String },
queueId: { type: Number },
participantPuuids: { type: [String], required: true, default: [] },
raw: { type: Schema.Types.Mixed, required: true, default: () => ({}) },
timeline: { type: Schema.Types.Mixed },
timelineFetchedAt: { type: Date },
fetchedAt: { type: Date, required: true, default: Date.now },
},
{
timestamps: true,
collection: 'riot_match',
},
);
RiotMatchSchema.index({ matchId: 1 }, { unique: true });
RiotMatchSchema.index({ participantPuuids: 1, gameCreation: -1 });
RiotMatchSchema.index({ participantPuuids: 1, queueId: 1, gameCreation: -1 });
export type RiotMatchDocument = HydratedDocument<RiotMatch>;
@@ -0,0 +1,9 @@
import mongoose from 'mongoose';
export interface ModelDefinition {
/** ConnectionService.getModel()에서 쓰는 모델 키 (camelCase) */
name: string;
schema: mongoose.Schema<any>;
/** MongoDB 컬렉션 이름 (snake_case 단수). 스키마의 collection 옵션과 반드시 일치시킨다 */
collectionName: string;
}
+3 -2
View File
@@ -1,10 +1,11 @@
import { Module, Global } from '@nestjs/common';
import { DatabaseModule } from './database/database.module';
import { SecretModule } from './secret/secret.module';
@Global()
@Module({
imports: [SecretModule],
imports: [SecretModule, DatabaseModule],
providers: [],
exports: [SecretModule],
exports: [SecretModule, DatabaseModule],
})
export class GlobalModule {}
@@ -0,0 +1,121 @@
import { DistributedLockService } from './distributed-lock.service';
import { RedisService } from './redis.service';
function createService(sendCommand: jest.Mock) {
const redisService = {
raw: jest.fn().mockReturnValue({ sendCommand }),
} as unknown as RedisService;
return new DistributedLockService(redisService);
}
describe('DistributedLockService', () => {
it('acquires a lock with a token and millisecond expiration', async () => {
const sendCommand = jest.fn().mockResolvedValue('OK');
const service = createService(sendCommand);
const lockOwnership = await service.acquireLock({
lockKey: 'distributed-lock:test',
lockOwnershipToken: 'owner-token',
lockExpirationDurationMilliseconds: 30_000,
});
expect(lockOwnership).toEqual({
lockKey: 'distributed-lock:test',
lockOwnershipToken: 'owner-token',
lockExpirationDurationMilliseconds: 30_000,
});
expect(sendCommand).toHaveBeenCalledWith([
'SET',
'distributed-lock:test',
'owner-token',
'NX',
'PX',
'30000',
]);
});
it('returns null when another owner already holds the lock', async () => {
const sendCommand = jest.fn().mockResolvedValue(null);
const service = createService(sendCommand);
await expect(
service.acquireLock({
lockKey: 'distributed-lock:test',
lockExpirationDurationMilliseconds: 30_000,
}),
).resolves.toBeNull();
});
it('releases a lock only when the ownership token matches', async () => {
const sendCommand = jest.fn().mockResolvedValue(1);
const service = createService(sendCommand);
await expect(
service.releaseLockIfOwned({
lockKey: 'distributed-lock:test',
lockOwnershipToken: 'owner-token',
lockExpirationDurationMilliseconds: 30_000,
}),
).resolves.toBe(true);
expect(sendCommand).toHaveBeenCalledWith([
'EVAL',
expect.stringContaining('redis.call("GET", KEYS[1]) == ARGV[1]'),
'1',
'distributed-lock:test',
'owner-token',
]);
});
it('extends a lock only when the ownership token matches', async () => {
const sendCommand = jest.fn().mockResolvedValue(1);
const service = createService(sendCommand);
await expect(
service.extendLockIfOwned(
{
lockKey: 'distributed-lock:test',
lockOwnershipToken: 'owner-token',
lockExpirationDurationMilliseconds: 30_000,
},
45_000,
),
).resolves.toBe(true);
expect(sendCommand).toHaveBeenCalledWith([
'EVAL',
expect.stringContaining('PEXPIRE'),
'1',
'distributed-lock:test',
'owner-token',
'45000',
]);
});
it('runs the operation and releases the lock afterward', async () => {
const sendCommand = jest
.fn()
.mockResolvedValueOnce('OK')
.mockResolvedValueOnce(1);
const service = createService(sendCommand);
const operation = jest.fn().mockResolvedValue('done');
await expect(
service.runWithLock(
{
lockKey: 'distributed-lock:test',
lockExpirationDurationMilliseconds: 30_000,
},
operation,
),
).resolves.toBe('done');
expect(operation).toHaveBeenCalledWith(
expect.objectContaining({
lockKey: 'distributed-lock:test',
lockExpirationDurationMilliseconds: 30_000,
}),
);
expect(sendCommand).toHaveBeenCalledTimes(2);
});
});
@@ -0,0 +1,203 @@
import { Injectable, Logger } from '@nestjs/common';
import { randomUUID } from 'crypto';
import { RedisService } from './redis.service';
const RELEASE_LOCK_IF_OWNED_SCRIPT = `
if redis.call("GET", KEYS[1]) == ARGV[1] then
return redis.call("DEL", KEYS[1])
end
return 0
`;
const EXTEND_LOCK_IF_OWNED_SCRIPT = `
if redis.call("GET", KEYS[1]) == ARGV[1] then
return redis.call("PEXPIRE", KEYS[1], ARGV[2])
end
return 0
`;
export interface DistributedLockOwnership {
lockKey: string;
lockOwnershipToken: string;
lockExpirationDurationMilliseconds: number;
}
export interface AcquireDistributedLockOptions {
lockKey: string;
lockExpirationDurationMilliseconds: number;
lockOwnershipToken?: string;
}
export interface RunWithDistributedLockOptions {
lockKey: string;
lockExpirationDurationMilliseconds: number;
lockAcquireTimeoutMilliseconds?: number;
lockRetryDelayMilliseconds?: number;
}
export interface RunWithRenewedDistributedLockOptions extends RunWithDistributedLockOptions {
lockRenewalIntervalMilliseconds: number;
}
@Injectable()
export class DistributedLockService {
private readonly logger = new Logger(DistributedLockService.name);
constructor(private readonly redisService: RedisService) {}
public async acquireLock(
options: AcquireDistributedLockOptions,
): Promise<DistributedLockOwnership | null> {
this.assertPositiveDuration(
options.lockExpirationDurationMilliseconds,
'lockExpirationDurationMilliseconds',
);
const lockOwnershipToken = options.lockOwnershipToken ?? randomUUID();
const result = await this.redisService
.raw()
.sendCommand([
'SET',
options.lockKey,
lockOwnershipToken,
'NX',
'PX',
String(options.lockExpirationDurationMilliseconds),
]);
// SET NX 응답은 런타임에 'OK' 또는 null이지만 redis 타입 정의(ReplyUnion)에는 string이 없다
if ((result as unknown) !== 'OK') return null;
return {
lockKey: options.lockKey,
lockOwnershipToken,
lockExpirationDurationMilliseconds:
options.lockExpirationDurationMilliseconds,
};
}
public async releaseLockIfOwned(
lockOwnership: DistributedLockOwnership,
): Promise<boolean> {
const result = await this.redisService
.raw()
.sendCommand([
'EVAL',
RELEASE_LOCK_IF_OWNED_SCRIPT,
'1',
lockOwnership.lockKey,
lockOwnership.lockOwnershipToken,
]);
return Number(result) === 1;
}
public async extendLockIfOwned(
lockOwnership: DistributedLockOwnership,
lockExpirationDurationMilliseconds = lockOwnership.lockExpirationDurationMilliseconds,
): Promise<boolean> {
this.assertPositiveDuration(
lockExpirationDurationMilliseconds,
'lockExpirationDurationMilliseconds',
);
const result = await this.redisService
.raw()
.sendCommand([
'EVAL',
EXTEND_LOCK_IF_OWNED_SCRIPT,
'1',
lockOwnership.lockKey,
lockOwnership.lockOwnershipToken,
String(lockExpirationDurationMilliseconds),
]);
return Number(result) === 1;
}
public async runWithLock<TResult>(
options: RunWithDistributedLockOptions,
operation: (lockOwnership: DistributedLockOwnership) => Promise<TResult>,
): Promise<TResult | null> {
const lockOwnership = await this.acquireLockWithRetry(options);
if (!lockOwnership) return null;
try {
return await operation(lockOwnership);
} finally {
await this.releaseLockIfOwned(lockOwnership).catch((error: unknown) => {
this.logger.warn(
`Failed to release distributed lock ${lockOwnership.lockKey}: ${
error instanceof Error ? error.message : String(error)
}`,
);
});
}
}
public async runWithRenewedLock<TResult>(
options: RunWithRenewedDistributedLockOptions,
operation: (lockOwnership: DistributedLockOwnership) => Promise<TResult>,
): Promise<TResult | null> {
this.assertPositiveDuration(
options.lockRenewalIntervalMilliseconds,
'lockRenewalIntervalMilliseconds',
);
const lockOwnership = await this.acquireLockWithRetry(options);
if (!lockOwnership) return null;
const lockRenewalTimer = setInterval(() => {
void this.extendLockIfOwned(lockOwnership).then((wasExtended) => {
if (wasExtended) return;
this.logger.warn(
`Lost distributed lock ownership before operation finished: ${lockOwnership.lockKey}`,
);
});
}, options.lockRenewalIntervalMilliseconds);
lockRenewalTimer.unref?.();
try {
return await operation(lockOwnership);
} finally {
clearInterval(lockRenewalTimer);
await this.releaseLockIfOwned(lockOwnership).catch((error: unknown) => {
this.logger.warn(
`Failed to release distributed lock ${lockOwnership.lockKey}: ${
error instanceof Error ? error.message : String(error)
}`,
);
});
}
}
private async acquireLockWithRetry(
options: RunWithDistributedLockOptions,
): Promise<DistributedLockOwnership | null> {
const lockAcquireTimeoutMilliseconds =
options.lockAcquireTimeoutMilliseconds ?? 0;
const lockRetryDelayMilliseconds =
options.lockRetryDelayMilliseconds ?? 100;
const acquisitionStartedAtTimestampMilliseconds = Date.now();
while (true) {
const lockOwnership = await this.acquireLock(options);
if (lockOwnership) return lockOwnership;
if (lockAcquireTimeoutMilliseconds <= 0) return null;
const elapsedMilliseconds =
Date.now() - acquisitionStartedAtTimestampMilliseconds;
if (elapsedMilliseconds >= lockAcquireTimeoutMilliseconds) return null;
await this.sleep(
Math.min(lockRetryDelayMilliseconds, lockAcquireTimeoutMilliseconds),
);
}
}
private assertPositiveDuration(value: number, fieldName: string): void {
if (Number.isFinite(value) && value > 0) return;
throw new Error(`${fieldName} must be a positive finite number.`);
}
private sleep(durationMilliseconds: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, durationMilliseconds));
}
}
@@ -0,0 +1,59 @@
import {
assertDistinctRedisInstances,
normalizeRedisUrl,
resolveRedisClientOptions,
} from './redis.config';
describe('redis.config', () => {
it('normalizes host:port endpoints into redis URLs', () => {
expect(normalizeRedisUrl('127.0.0.1:6379', 'REDIS_ENDPOINT')).toBe(
'redis://127.0.0.1:6379',
);
expect(normalizeRedisUrl('rediss://cache.example.com:6380')).toBe(
'rediss://cache.example.com:6380',
);
});
it('throws a clear error for empty endpoints', () => {
expect(() => normalizeRedisUrl(' ', 'REDIS_ENDPOINT')).toThrow(
'REDIS_ENDPOINT cannot be empty',
);
});
it('keeps credentials optional when resolving client options', () => {
expect(
resolveRedisClientOptions({
endpoint: 'redis.internal:6379',
username: '',
password: undefined,
endpointEnvName: 'REDIS_ENDPOINT',
}),
).toEqual({
url: 'redis://redis.internal:6379',
});
});
it('rejects auction Redis when it points at the same physical Redis instance', () => {
expect(() =>
assertDistinctRedisInstances(
'redis://cache.internal:6379/0',
'redis://cache.internal:6379/1',
),
).toThrow('AUCTION_REDIS must use a separate Redis instance');
});
it('allows different Redis hosts or ports', () => {
expect(() =>
assertDistinctRedisInstances(
'redis://cache.internal:6379',
'redis://auction.internal:6379',
),
).not.toThrow();
expect(() =>
assertDistinctRedisInstances(
'redis://cache.internal:6379',
'redis://cache.internal:6380',
),
).not.toThrow();
});
});
@@ -0,0 +1,77 @@
export interface RedisClientOptions {
password?: string;
url: string;
username?: string;
}
export interface ResolveRedisClientOptionsParams {
endpoint?: string;
endpointEnvName?: string;
password?: string;
url?: string;
urlEnvName?: string;
username?: string;
}
function trimOptional(value: string | undefined): string | undefined {
const trimmed = value?.trim();
return trimmed ? trimmed : undefined;
}
export function normalizeRedisUrl(
endpointOrUrl: string,
envName = 'REDIS_URL',
): string {
const trimmed = endpointOrUrl.trim();
if (!trimmed) {
throw new Error(`${envName} cannot be empty`);
}
if (/^redis(s)?:\/\//iu.test(trimmed)) {
return trimmed;
}
return `redis://${trimmed}`;
}
export function resolveRedisClientOptions(
params: ResolveRedisClientOptionsParams,
): RedisClientOptions {
const url = trimOptional(params.url);
const endpoint = trimOptional(params.endpoint);
const selectedEndpoint = url ?? endpoint;
const selectedEnvName = url
? (params.urlEnvName ?? 'REDIS_URL')
: (params.endpointEnvName ?? 'REDIS_ENDPOINT');
if (!selectedEndpoint) {
throw new Error(`${selectedEnvName} cannot be empty`);
}
const options: RedisClientOptions = {
url: normalizeRedisUrl(selectedEndpoint, selectedEnvName),
};
const username = trimOptional(params.username);
const password = trimOptional(params.password);
if (username) options.username = username;
if (password) options.password = password;
return options;
}
function parseRedisInstanceIdentity(redisUrl: string): string {
const url = new URL(normalizeRedisUrl(redisUrl));
const hostname = url.hostname.toLowerCase();
const port = url.port || '6379';
return `${hostname}:${port}`;
}
export function assertDistinctRedisInstances(
redisUrl: string,
auctionRedisUrl: string,
): void {
const redisIdentity = parseRedisInstanceIdentity(redisUrl);
const auctionRedisIdentity = parseRedisInstanceIdentity(auctionRedisUrl);
if (redisIdentity === auctionRedisIdentity) {
throw new Error(
'AUCTION_REDIS must use a separate Redis instance from REDIS because auction Redis is a live state source of truth.',
);
}
}
@@ -0,0 +1 @@
export const REDIS_CLIENT = Symbol('REDIS_CLIENT');
@@ -0,0 +1,74 @@
import { Logger, Module } from '@nestjs/common';
import { createClient } from 'redis';
import { SecretModule } from '../secret/secret.module';
import { SecretService } from '../secret/secret.service';
import { REDIS_CLIENT } from './redis.constants';
import { resolveRedisClientOptions } from './redis.config';
import { DistributedLockService } from './distributed-lock.service';
import { RedisService, type RedisClient } from './redis.service';
async function readFirstSecret(
secretService: SecretService,
keys: string[],
): Promise<string | undefined> {
for (const key of keys) {
const value = await secretService.get<string>(key, '');
const trimmed = value.trim();
if (trimmed) return trimmed;
}
return undefined;
}
@Module({
imports: [SecretModule],
providers: [
{
provide: REDIS_CLIENT,
inject: [SecretService],
useFactory: async (
secretService: SecretService,
): Promise<RedisClient> => {
await secretService.ready();
const [url, endpoint, username, password] = await Promise.all([
readFirstSecret(secretService, ['REDIS_URL', 'GARNET_URL']),
readFirstSecret(secretService, ['REDIS_ENDPOINT', 'GARNET_ENDPOINT']),
readFirstSecret(secretService, [
'REDIS_USERNAME',
'REDIS_USERID',
'GARNET_USERNAME',
'GARNET_USERID',
]),
readFirstSecret(secretService, ['REDIS_PASSWORD', 'GARNET_PASSWORD']),
]);
const logger = new Logger('RedisClient');
const client = createClient(
resolveRedisClientOptions({
endpoint,
endpointEnvName: 'REDIS_ENDPOINT',
password,
url,
urlEnvName: 'REDIS_URL',
username,
}),
);
client.on('error', (error: unknown) => {
logger.error(
`Redis client error: ${error instanceof Error ? error.message : String(error)}`,
);
});
await client.connect();
logger.log('Redis connected');
return client;
},
},
RedisService,
DistributedLockService,
],
exports: [RedisService, DistributedLockService, REDIS_CLIENT],
})
export class RedisModule {}
@@ -0,0 +1,54 @@
import { RedisService } from './redis.service';
function createRedisService(client: Record<string, unknown>) {
return new RedisService(client as never);
}
describe('RedisService stream pending recovery', () => {
it('normalizes XAUTOCLAIM array replies into stream entries', async () => {
const sendCommand = jest
.fn()
.mockResolvedValue([
'0-0',
[
[
'1700000000000-0',
['job', '{"kind":"poll-tournament-result"}', 'source', 'test'],
],
],
]);
const service = createRedisService({ sendCommand });
await expect(
service.claimStalePendingStreamMessages({
key: 'riot:queue:high',
group: 'riot-refresh-worker',
consumer: 'worker-1',
stalePendingMessageMinimumIdleMilliseconds: 1_800_000,
count: 1,
}),
).resolves.toEqual({
nextStartId: '0-0',
messages: [
{
id: '1700000000000-0',
message: {
job: '{"kind":"poll-tournament-result"}',
source: 'test',
},
},
],
});
expect(sendCommand).toHaveBeenCalledWith([
'XAUTOCLAIM',
'riot:queue:high',
'riot-refresh-worker',
'worker-1',
'1800000',
'0-0',
'COUNT',
'1',
]);
});
});
@@ -0,0 +1,304 @@
import { Inject, Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
import type { createClient } from 'redis';
import { REDIS_CLIENT } from './redis.constants';
export type RedisClient = ReturnType<typeof createClient>;
export interface StreamEntry {
deliveriesCounter?: number;
id: string;
message: Record<string, string>;
millisElapsedFromDelivery?: number;
}
export interface StreamReadResult {
messages: StreamEntry[];
name: string;
}
export interface ClaimStalePendingStreamMessagesResult {
messages: StreamEntry[];
nextStartId: string;
}
interface RawStreamMessage {
deliveriesCounter?: number;
id: string;
message: unknown;
millisElapsedFromDelivery?: number;
}
interface RawStreamReadResult {
messages: RawStreamMessage[];
name: string;
}
function stringifyStreamValue(value: unknown): string {
if (typeof value === 'string') return value;
if (value === null || value === undefined) return '';
if (typeof value === 'number' || typeof value === 'boolean') {
return String(value);
}
if (value instanceof Buffer) return value.toString();
return JSON.stringify(value) ?? '';
}
function normalizeStreamFields(fields: unknown): Record<string, string> {
if (Array.isArray(fields)) {
const normalized: Record<string, string> = {};
for (let index = 0; index < fields.length; index += 2) {
const key: unknown = fields[index];
if (key === undefined) continue;
const value: unknown = fields[index + 1];
normalized[stringifyStreamValue(key)] = stringifyStreamValue(value);
}
return normalized;
}
if (fields instanceof Map) {
return Object.fromEntries(
[...fields.entries()].map(([key, value]) => [String(key), String(value)]),
);
}
if (typeof fields === 'object' && fields !== null) {
return Object.fromEntries(
Object.entries(fields as Record<string, unknown>).map(([key, value]) => [
key,
String(value),
]),
);
}
return {};
}
@Injectable()
export class RedisService implements OnModuleDestroy {
private readonly logger = new Logger(RedisService.name);
constructor(@Inject(REDIS_CLIENT) private readonly client: RedisClient) {}
async onModuleDestroy() {
try {
await this.client.quit();
} catch {
this.client.destroy();
}
}
public raw(): RedisClient {
return this.client;
}
public async getJson<T>(key: string): Promise<T | null> {
const raw = await this.client.get(key);
if (!raw) return null;
try {
return JSON.parse(raw) as T;
} catch (err) {
this.logger.warn(
`Failed to JSON.parse cached value for key="${key}": ${
(err as Error)?.message ?? err
}`,
);
return null;
}
}
public async setJson(
key: string,
value: unknown,
ttlSeconds?: number,
): Promise<void> {
const serialized = JSON.stringify(value);
if (ttlSeconds && ttlSeconds > 0) {
await this.client.set(key, serialized, { EX: ttlSeconds });
return;
}
await this.client.set(key, serialized);
}
public async getString(key: string): Promise<string | null> {
return this.client.get(key);
}
public async setString(
key: string,
value: string,
ttlSeconds?: number,
): Promise<void> {
if (ttlSeconds && ttlSeconds > 0) {
await this.client.set(key, value, { EX: ttlSeconds });
return;
}
await this.client.set(key, value);
}
public async setStringIfAbsent(
key: string,
value: string,
ttlSeconds?: number,
): Promise<boolean> {
const options: { EX?: number; NX: true } = { NX: true };
if (ttlSeconds && ttlSeconds > 0) options.EX = ttlSeconds;
const result = await this.client.set(key, value, options);
return result === 'OK';
}
public async delete(key: string): Promise<number> {
return this.client.del(key);
}
public async appendStream(
key: string,
fields: Record<string, string>,
options?: { maxLen?: number },
): Promise<string> {
const trimOptions =
options?.maxLen && options.maxLen > 0
? {
TRIM: {
strategy: 'MAXLEN' as const,
strategyModifier: '~' as const,
threshold: options.maxLen,
},
}
: undefined;
return this.client.xAdd(key, '*', fields, trimOptions);
}
public async createConsumerGroup(
key: string,
group: string,
startId = '$',
): Promise<void> {
await this.client.xGroupCreate(key, group, startId, { MKSTREAM: true });
}
public async readGroup(
key: string,
group: string,
consumer: string,
startId: string,
options?: { blockMs?: number; count?: number },
): Promise<StreamReadResult[] | null> {
const readOptions: { BLOCK?: number; COUNT?: number } = {};
if (options?.blockMs !== undefined) readOptions.BLOCK = options.blockMs;
if (options?.count !== undefined) readOptions.COUNT = options.count;
const reply = await this.client.xReadGroup(
group,
consumer,
{ key, id: startId },
readOptions,
);
if (!reply) return null;
return (reply as RawStreamReadResult[]).map((stream) => ({
name: String(stream.name),
messages: stream.messages.map((message) => ({
deliveriesCounter:
typeof message.deliveriesCounter === 'number'
? message.deliveriesCounter
: undefined,
id: String(message.id),
message: normalizeStreamFields(message.message),
millisElapsedFromDelivery:
typeof message.millisElapsedFromDelivery === 'number'
? message.millisElapsedFromDelivery
: undefined,
})),
}));
}
public async claimStalePendingStreamMessages(options: {
key: string;
group: string;
consumer: string;
stalePendingMessageMinimumIdleMilliseconds: number;
startId?: string;
count?: number;
}): Promise<ClaimStalePendingStreamMessagesResult> {
const response = (await this.client.sendCommand([
'XAUTOCLAIM',
options.key,
options.group,
options.consumer,
String(options.stalePendingMessageMinimumIdleMilliseconds),
options.startId ?? '0-0',
'COUNT',
String(options.count ?? 1),
])) as unknown;
const responseItems = Array.isArray(response) ? response : [];
const rawMessages = Array.isArray(responseItems[1]) ? responseItems[1] : [];
return {
nextStartId: String(responseItems[0] ?? '0-0'),
messages: rawMessages
.map((rawMessage) => this.normalizeClaimedStreamMessage(rawMessage))
.filter((message): message is StreamEntry => Boolean(message)),
};
}
public async acknowledgeStream(
key: string,
group: string,
ids: string | string[],
): Promise<number> {
return this.client.xAck(key, group, ids);
}
public async deleteStreamEntries(
key: string,
ids: string | string[],
): Promise<number> {
return this.client.xDel(key, ids);
}
public async streamLength(key: string): Promise<number> {
return this.client.xLen(key);
}
public async publish(channel: string, message: string): Promise<number> {
return this.client.publish(channel, message);
}
private normalizeClaimedStreamMessage(
rawMessage: unknown,
): StreamEntry | null {
if (Array.isArray(rawMessage)) {
const [id, fields] = rawMessage as unknown[];
if (id === undefined) return null;
return {
id: stringifyStreamValue(id),
message: normalizeStreamFields(fields),
};
}
if (
typeof rawMessage === 'object' &&
rawMessage !== null &&
'id' in rawMessage
) {
const message = rawMessage as RawStreamMessage;
return {
deliveriesCounter:
typeof message.deliveriesCounter === 'number'
? message.deliveriesCounter
: undefined,
id: String(message.id),
message: normalizeStreamFields(message.message),
millisElapsedFromDelivery:
typeof message.millisElapsedFromDelivery === 'number'
? message.millisElapsedFromDelivery
: undefined,
};
}
return null;
}
}
+51
View File
@@ -0,0 +1,51 @@
// Riot API 라우팅 타입.
// endpoint별로 platform route(kr 등)와 regional route(asia 등)를 구분해서 사용한다.
// 실제 endpoint가 어느 route를 쓰는지는 Riot Developer Portal API Reference 기준으로 확인할 것.
// - Account-V1 / Match-V5: regional route
// - Summoner-V4 / League-V4: platform route
export type RiotPlatformRoute =
| 'kr'
| 'jp1'
| 'na1'
| 'br1'
| 'la1'
| 'la2'
| 'euw1'
| 'eun1'
| 'tr1'
| 'ru'
| 'me1'
| 'oc1'
| 'sg2'
| 'tw2'
| 'vn2';
export type RiotRegionalRoute = 'americas' | 'asia' | 'europe' | 'sea';
export const PLATFORM_TO_REGIONAL_ROUTE: Record<
RiotPlatformRoute,
RiotRegionalRoute
> = {
kr: 'asia',
jp1: 'asia',
na1: 'americas',
br1: 'americas',
la1: 'americas',
la2: 'americas',
euw1: 'europe',
eun1: 'europe',
tr1: 'europe',
ru: 'europe',
me1: 'europe',
oc1: 'sea',
sg2: 'sea',
tw2: 'sea',
vn2: 'sea',
};
export function toRegionalRoute(
platformRoute: RiotPlatformRoute,
): RiotRegionalRoute {
return PLATFORM_TO_REGIONAL_ROUTE[platformRoute];
}