feat: redesign auction engine with redis sot

This commit is contained in:
dahyeon committed 2026-06-23 03:16:04 -07:00
1 parent 737702d78c
commit e8bb20d988
75 files changed
+12737 -542

No files matched your search

@@ -0,0 +1,377 @@
import { AuctionRedisService } from './auction-redis.service';
import { AuctionRedisCommandService } from './auction-redis-command.service';
import { AUCTION_APPLY_TRANSITION_SCRIPT } from './auction-redis.apply-transition';
import { AUCTION_BID_SCRIPT } from './auction-redis.bid';
import { AUCTION_EXPIRE_PREPARE_SCRIPT } from './auction-redis.expire-prepare';
import { AUCTION_RESERVE_ACTION_REQUEST_SCRIPT } from './auction-redis.reserve-action';
import { AUCTION_HYDRATE_STATE_SCRIPT } from './auction-redis.state';
function makeService(reply: unknown) {
const auctionRedisService = {
evalScript: jest.fn().mockResolvedValue(reply),
} as unknown as jest.Mocked<AuctionRedisService>;
return {
auctionRedisService,
service: new AuctionRedisCommandService(auctionRedisService),
};
}
describe('AuctionRedisCommandService', () => {
it('executes BID script and parses successful reply', async () => {
const { service, auctionRedisService } = makeService([
'OK',
'bid-1',
'9',
'1000',
'120',
'2',
'31000',
'{"bidPointAmount":120}',
]);
await expect(
service.placeBid('match-1', {
bidderTeamIndex: 2,
bidPointAmount: 120,
bidRequestId: 'bid-1',
bidderUserId: 'captain-2',
clientObservedAuctionLifecycleId: 'life-1',
clientObservedCurrentBidRoundPlayerUserId: 'player-1',
maximumAuctionTeamMemberCount: 5,
maximumStoredAuctionBidHistoryCount: 200,
maximumStoredBidRequestResultCount: 100,
matchId: 'match-1',
minimumBidPointReservePerRemainingAuctionTeamMemberSlot: 10,
minimumBidRequestResultReplayWindowMS: 60_000,
}),
).resolves.toEqual({
auctionBidHistoryEntry: { bidPointAmount: 120 },
bidRequestId: 'bid-1',
currentHighestBidderTeamIndex: 2,
currentHighestBidPointAmount: 120,
currentBidRoundDeadlineTimestampMS: 31_000,
currentServerTimestampMS: 1_000,
ok: true,
revision: 9,
});
expect(auctionRedisService.evalScript).toHaveBeenCalledWith(
AUCTION_BID_SCRIPT,
expect.arrayContaining(['auction:match-1:liveAuctionState']),
expect.arrayContaining(['match-1', '2', '120']),
);
});
it('parses BID rejected reply', async () => {
const { service } = makeService([
'REJECTED',
'TOO_LOW',
'bid-1',
'1000',
]);
await expect(
service.placeBid('match-1', {
bidderTeamIndex: 2,
bidPointAmount: 120,
bidRequestId: 'bid-1',
bidderUserId: 'captain-2',
clientObservedAuctionLifecycleId: 'life-1',
clientObservedCurrentBidRoundPlayerUserId: 'player-1',
maximumAuctionTeamMemberCount: 5,
maximumStoredAuctionBidHistoryCount: 200,
maximumStoredBidRequestResultCount: 100,
matchId: 'match-1',
minimumBidPointReservePerRemainingAuctionTeamMemberSlot: 10,
minimumBidRequestResultReplayWindowMS: 60_000,
}),
).resolves.toEqual({
bidRequestId: 'bid-1',
code: 'TOO_LOW',
currentServerTimestampMS: 1000,
rejected: true,
});
});
it('executes reserve action request and parses lease metadata', async () => {
const { service, auctionRedisService } = makeService([
'RESERVED',
'life-1:request-1',
'transition-1',
'',
'2',
'1',
'1000',
]);
await expect(
service.reserveActionRequest('match-1', {
auctionActionRequestId: 'request-1',
auctionActionType: 'sold',
auctionStateTransitionId: 'transition-1',
clientObservedAuctionLifecycleId: 'life-1',
clientObservedPhase: 'bidding',
clientObservedRevision: 8,
leaseDurationMS: 10_000,
maximumStoredAuctionActionRequestResultCount: 100,
minimumAuctionActionRequestResultReplayWindowMS: 60_000,
processingOwnerToken: 'owner-1',
}),
).resolves.toEqual({
actionRequestScopeKey: 'life-1:request-1',
auctionStateTransitionId: 'transition-1',
currentServerTimestampMS: 1000,
newAuctionLifecycleId: '',
observedProcessingLeaseVersion: 2,
reserved: true,
wasLeaseExpired: true,
});
expect(auctionRedisService.evalScript).toHaveBeenCalledWith(
AUCTION_RESERVE_ACTION_REQUEST_SCRIPT,
expect.arrayContaining(['auction:match-1:auctionActionRequestResults']),
expect.arrayContaining(['life-1', 'request-1', 'sold']),
);
});
it('parses reserve action request replay refetch metadata', async () => {
const { service } = makeService([
'REPLAY',
'applied',
'life-1:request-1',
'11',
'',
'transition-1',
'',
'2',
'3000',
'',
'1',
]);
await expect(
service.reserveActionRequest('match-1', {
auctionActionRequestId: 'request-1',
auctionActionType: 'sold',
auctionStateTransitionId: 'transition-1',
clientObservedAuctionLifecycleId: 'life-1',
clientObservedPhase: 'bidding',
clientObservedRevision: 8,
leaseDurationMS: 10_000,
maximumStoredAuctionActionRequestResultCount: 100,
minimumAuctionActionRequestResultReplayWindowMS: 60_000,
processingOwnerToken: 'owner-1',
}),
).resolves.toEqual({
actionRequestScopeKey: 'life-1:request-1',
currentServerTimestampMS: 3000,
isReplay: true,
requiresRefetch: true,
replayStatus: 'applied',
revision: 11,
});
});
it('executes apply transition and parses successful reply', async () => {
const { service, auctionRedisService } = makeService([
'OK',
'transition-1',
'11',
'2000',
]);
await expect(
service.applyTransition('match-1', {
afterAuctionStructureStateJson: '{"auctionTeams":[]}',
auctionHistorySequence: 5,
auctionLifecycleId: 'life-1',
auctionStateTransitionId: 'transition-1',
broadcastStateRevision: 11,
deadline: { mode: 'remove' },
durabilityPayloadJson: '{"auctionStateTransitionId":"transition-1"}',
expectedPhase: 'bidding',
expectedRevision: 10,
liveStatePatch: { phase: 'sold' },
matchId: 'match-1',
shouldBroadcastState: true,
}),
).resolves.toEqual({
auctionStateTransitionId: 'transition-1',
currentServerTimestampMS: 2000,
ok: true,
revision: 11,
});
expect(auctionRedisService.evalScript).toHaveBeenCalledWith(
AUCTION_APPLY_TRANSITION_SCRIPT,
expect.arrayContaining(['auction:match-1:liveAuctionState']),
expect.arrayContaining(['match-1', 'life-1', 'transition-1']),
);
});
it('parses apply transition replay and rejected replies', async () => {
await expect(
makeService(['REPLAY', 'APPLIED', 'transition-1', '2100'])
.service.applyTransition('match-1', {
afterAuctionStructureStateJson: '{}',
auctionHistorySequence: 5,
auctionLifecycleId: 'life-1',
auctionStateTransitionId: 'transition-1',
broadcastStateRevision: 11,
deadline: { mode: 'none' },
durabilityPayloadJson: '{}',
expectedPhase: 'sold',
expectedRevision: 10,
liveStatePatch: {},
matchId: 'match-1',
shouldBroadcastState: false,
}),
).resolves.toEqual({
auctionStateTransitionId: 'transition-1',
currentServerTimestampMS: 2100,
isReplay: true,
replayStatus: 'APPLIED',
});
await expect(
makeService(['REJECTED', 'CONFLICT', 'transition-1', '2200'])
.service.applyTransition('match-1', {
afterAuctionStructureStateJson: '{}',
auctionHistorySequence: 5,
auctionLifecycleId: 'life-1',
auctionStateTransitionId: 'transition-1',
broadcastStateRevision: 11,
deadline: { mode: 'none' },
durabilityPayloadJson: '{}',
expectedPhase: 'sold',
expectedRevision: 10,
liveStatePatch: {},
matchId: 'match-1',
shouldBroadcastState: false,
}),
).resolves.toEqual({
auctionStateTransitionId: 'transition-1',
code: 'CONFLICT',
currentServerTimestampMS: 2200,
rejected: true,
});
});
it('executes expire prepare and parses expiry decisions', async () => {
const { service, auctionRedisService } = makeService([
'OK',
'sold',
'expire-1',
'12',
'3000',
]);
await expect(
service.expirePrepare('match-1', {
auctionStateTransitionId: 'expire-1',
bidRoundExpiryRetryDelayMS: 3000,
matchId: 'match-1',
}),
).resolves.toEqual({
auctionStateTransitionId: 'expire-1',
bidRoundExpiryDecision: 'sold',
currentServerTimestampMS: 3000,
isReplay: undefined,
ok: true,
revision: 12,
});
expect(auctionRedisService.evalScript).toHaveBeenCalledWith(
AUCTION_EXPIRE_PREPARE_SCRIPT,
expect.arrayContaining(['auction:match-1:liveAuctionState']),
expect.arrayContaining(['match-1', 'expire-1']),
);
});
it('parses expire prepare replay and noop replies', async () => {
await expect(
makeService(['REPLAY', 'passed', 'expire-1', '12', '3100'])
.service.expirePrepare('match-1', {
auctionStateTransitionId: 'expire-1',
bidRoundExpiryRetryDelayMS: 3000,
matchId: 'match-1',
}),
).resolves.toMatchObject({
auctionStateTransitionId: 'expire-1',
bidRoundExpiryDecision: 'passed',
currentServerTimestampMS: 3100,
isReplay: true,
ok: true,
revision: 12,
});
await expect(
makeService(['NOOP', 'NOT_DUE', '3200']).service.expirePrepare(
'match-1',
{
auctionStateTransitionId: 'expire-1',
bidRoundExpiryRetryDelayMS: 3000,
matchId: 'match-1',
},
),
).resolves.toEqual({
code: 'NOT_DUE',
currentServerTimestampMS: 3200,
noop: true,
});
});
it('executes hydrate state and parses hydrate/noop replies', async () => {
const { service, auctionRedisService } = makeService(['OK', '7', '4000']);
await expect(
service.hydrateState('match-1', {
auctionHistorySequence: 3,
auctionLifecycleId: 'life-1',
maximumBidRoundDurationSeconds: 30,
matchId: 'match-1',
phase: 'presenting',
revision: 6,
structureStateJson: '{"auctionTeams":[]}',
}),
).resolves.toEqual({
currentServerTimestampMS: 4000,
hydrated: true,
revision: 7,
});
expect(auctionRedisService.evalScript).toHaveBeenCalledWith(
AUCTION_HYDRATE_STATE_SCRIPT,
expect.arrayContaining(['auction:match-1:liveAuctionState']),
expect.arrayContaining(['match-1', 'life-1', '6']),
);
await expect(
makeService(['NOOP', '8', '4100']).service.hydrateState('match-1', {
auctionHistorySequence: 3,
auctionLifecycleId: 'life-1',
maximumBidRoundDurationSeconds: 30,
matchId: 'match-1',
phase: 'presenting',
revision: 6,
structureStateJson: '{}',
}),
).resolves.toEqual({
currentServerTimestampMS: 4100,
noop: true,
revision: 8,
});
await expect(
makeService(['REJECTED', 'INVALID_PATCH_ARITY', '4200'])
.service.hydrateState('match-1', {
auctionHistorySequence: 3,
auctionLifecycleId: 'life-1',
maximumBidRoundDurationSeconds: 30,
matchId: 'match-1',
phase: 'presenting',
revision: 6,
structureStateJson: '{}',
}),
).resolves.toEqual({
code: 'INVALID_PATCH_ARITY',
currentServerTimestampMS: 4200,
rejected: true,
});
});
});
@@ -0,0 +1,375 @@
import { Injectable } from '@nestjs/common';
import {
type AuctionApplyTransitionScriptInput,
buildAuctionApplyTransitionScriptInvocation,
} from './auction-redis.apply-transition';
import {
type AuctionBidScriptInput,
buildAuctionBidScriptInvocation,
} from './auction-redis.bid';
import {
type AuctionExpirePrepareScriptInput,
buildAuctionExpirePrepareScriptInvocation,
} from './auction-redis.expire-prepare';
import { buildAuctionRedisKeys } from './auction-redis.keys';
import { AuctionRedisService } from './auction-redis.service';
import {
type AuctionReserveActionRequestScriptInput,
buildAuctionReserveActionRequestScriptInvocation,
} from './auction-redis.reserve-action';
import {
type HydrateAuctionStateScriptInput,
buildHydrateAuctionStateScriptInvocation,
} from './auction-redis.state';
export type AuctionBidCommandResult =
| {
auctionBidHistoryEntry: Record<string, unknown>;
bidRequestId: string;
currentBidRoundDeadlineTimestampMS: number;
currentHighestBidderTeamIndex: number;
currentHighestBidPointAmount: number;
currentServerTimestampMS: number;
isReplay?: boolean;
ok: true;
revision: number;
}
| {
bidRequestId: string;
code: string;
currentServerTimestampMS: number;
isReplay?: boolean;
rejected: true;
};
export type AuctionReserveActionRequestCommandResult =
| {
actionRequestScopeKey: string;
auctionStateTransitionId: string;
currentServerTimestampMS: number;
newAuctionLifecycleId: string;
observedProcessingLeaseVersion: number;
reserved: true;
wasLeaseExpired: boolean;
}
| {
actionRequestScopeKey: string;
code: string;
currentServerTimestampMS: number;
rejected: true;
}
| {
actionRequestScopeKey: string;
currentServerTimestampMS: number;
isReplay: true;
requiresRefetch?: boolean;
replayStatus: string;
responseJson?: string;
revision?: number;
};
export type AuctionApplyTransitionCommandResult =
| {
auctionStateTransitionId: string;
currentServerTimestampMS: number;
ok: true;
revision: number;
}
| {
auctionStateTransitionId: string;
currentServerTimestampMS: number;
isReplay: true;
replayStatus: string;
}
| {
auctionStateTransitionId: string;
code: string;
currentServerTimestampMS: number;
rejected: true;
};
export type AuctionExpirePrepareCommandResult =
| {
auctionStateTransitionId: string;
bidRoundExpiryDecision: 'passed' | 'sold';
currentServerTimestampMS: number;
isReplay?: boolean;
ok: true;
revision: number;
}
| {
code: string;
currentServerTimestampMS: number;
noop: true;
};
export type AuctionHydrateStateCommandResult =
| {
currentServerTimestampMS: number;
hydrated: true;
revision: number;
}
| {
currentServerTimestampMS: number;
noop: true;
revision: number;
}
| {
code: string;
currentServerTimestampMS: number;
rejected: true;
};
@Injectable()
export class AuctionRedisCommandService {
constructor(private readonly auctionRedisService: AuctionRedisService) {}
public async placeBid(
matchId: string,
input: AuctionBidScriptInput,
): Promise<AuctionBidCommandResult> {
const invocation = buildAuctionBidScriptInvocation(
buildAuctionRedisKeys(matchId),
input,
);
const reply = await this.auctionRedisService.evalScript<unknown[]>(
invocation.script,
invocation.keys,
invocation.values,
);
return parseBidCommandReply(reply);
}
public async reserveActionRequest(
matchId: string,
input: AuctionReserveActionRequestScriptInput,
): Promise<AuctionReserveActionRequestCommandResult> {
const invocation = buildAuctionReserveActionRequestScriptInvocation(
buildAuctionRedisKeys(matchId),
input,
);
const reply = await this.auctionRedisService.evalScript<unknown[]>(
invocation.script,
invocation.keys,
invocation.values,
);
return parseReserveActionRequestReply(reply);
}
public async applyTransition(
matchId: string,
input: AuctionApplyTransitionScriptInput,
): Promise<AuctionApplyTransitionCommandResult> {
const invocation = buildAuctionApplyTransitionScriptInvocation(
buildAuctionRedisKeys(matchId),
input,
);
const reply = await this.auctionRedisService.evalScript<unknown[]>(
invocation.script,
invocation.keys,
invocation.values,
);
return parseApplyTransitionReply(reply);
}
public async expirePrepare(
matchId: string,
input: AuctionExpirePrepareScriptInput,
): Promise<AuctionExpirePrepareCommandResult> {
const invocation = buildAuctionExpirePrepareScriptInvocation(
buildAuctionRedisKeys(matchId),
input,
);
const reply = await this.auctionRedisService.evalScript<unknown[]>(
invocation.script,
invocation.keys,
invocation.values,
);
return parseExpirePrepareReply(reply);
}
public async hydrateState(
matchId: string,
input: HydrateAuctionStateScriptInput,
): Promise<AuctionHydrateStateCommandResult> {
const invocation = buildHydrateAuctionStateScriptInvocation(
buildAuctionRedisKeys(matchId),
input,
);
const reply = await this.auctionRedisService.evalScript<unknown[]>(
invocation.script,
invocation.keys,
invocation.values,
);
return parseHydrateStateReply(reply);
}
}
function parseBidCommandReply(reply: unknown[]): AuctionBidCommandResult {
const values = reply.map(String);
const kind = values[0];
if (kind === 'OK') {
return {
auctionBidHistoryEntry: JSON.parse(values[7] || '{}') as Record<
string,
unknown
>,
bidRequestId: values[1],
currentBidRoundDeadlineTimestampMS: numberValue(values[6]),
currentHighestBidderTeamIndex: numberValue(values[5]),
currentHighestBidPointAmount: numberValue(values[4]),
currentServerTimestampMS: numberValue(values[3]),
ok: true,
revision: numberValue(values[2]),
};
}
if (kind === 'REPLAY') {
const status = values[1];
if (status === 'ok') {
return {
auctionBidHistoryEntry: JSON.parse(values[8] || '{}') as Record<
string,
unknown
>,
bidRequestId: values[2],
currentBidRoundDeadlineTimestampMS: numberValue(values[7]),
currentHighestBidderTeamIndex: numberValue(values[6]),
currentHighestBidPointAmount: numberValue(values[5]),
currentServerTimestampMS: numberValue(values[9]),
isReplay: true,
ok: true,
revision: numberValue(values[3]),
};
}
return {
bidRequestId: values[2],
code: values[4] || status,
currentServerTimestampMS: numberValue(values[9]),
isReplay: true,
rejected: true,
};
}
return {
bidRequestId: values[2] ?? '',
code: values[1] ?? 'UNKNOWN',
currentServerTimestampMS: numberValue(values[3]),
rejected: true,
};
}
function parseReserveActionRequestReply(
reply: unknown[],
): AuctionReserveActionRequestCommandResult {
const values = reply.map(String);
const kind = values[0];
if (kind === 'RESERVED') {
return {
actionRequestScopeKey: values[1],
auctionStateTransitionId: values[2],
currentServerTimestampMS: numberValue(values[6]),
newAuctionLifecycleId: values[3],
observedProcessingLeaseVersion: numberValue(values[4]),
reserved: true,
wasLeaseExpired: values[5] === '1',
};
}
if (kind === 'REPLAY') {
return {
actionRequestScopeKey: values[2],
currentServerTimestampMS: numberValue(values[8]),
isReplay: true,
requiresRefetch: values[10] === '1' || undefined,
replayStatus: values[1],
responseJson: values[9] || undefined,
revision: values[3] ? numberValue(values[3]) : undefined,
};
}
return {
actionRequestScopeKey: values[2] ?? '',
code: values[1] ?? 'UNKNOWN',
currentServerTimestampMS: numberValue(values[3]),
rejected: true,
};
}
function parseApplyTransitionReply(
reply: unknown[],
): AuctionApplyTransitionCommandResult {
const values = reply.map(String);
const kind = values[0];
if (kind === 'OK') {
return {
auctionStateTransitionId: values[1],
currentServerTimestampMS: numberValue(values[3]),
ok: true,
revision: numberValue(values[2]),
};
}
if (kind === 'REPLAY') {
return {
auctionStateTransitionId: values[2],
currentServerTimestampMS: numberValue(values[3]),
isReplay: true,
replayStatus: values[1],
};
}
return {
auctionStateTransitionId: values[2] ?? '',
code: values[1] ?? 'UNKNOWN',
currentServerTimestampMS: numberValue(values[3]),
rejected: true,
};
}
function parseExpirePrepareReply(
reply: unknown[],
): AuctionExpirePrepareCommandResult {
const values = reply.map(String);
const kind = values[0];
if (kind === 'OK' || kind === 'REPLAY') {
return {
auctionStateTransitionId: values[2],
bidRoundExpiryDecision:
values[1] === 'sold' || values[1] === 'passed' ? values[1] : 'passed',
currentServerTimestampMS: numberValue(values[4]),
isReplay: kind === 'REPLAY' || undefined,
ok: true,
revision: numberValue(values[3]),
};
}
return {
code: values[1] ?? 'UNKNOWN',
currentServerTimestampMS: numberValue(values[2]),
noop: true,
};
}
function parseHydrateStateReply(
reply: unknown[],
): AuctionHydrateStateCommandResult {
const values = reply.map(String);
if (values[0] === 'OK') {
return {
currentServerTimestampMS: numberValue(values[2]),
hydrated: true,
revision: numberValue(values[1]),
};
}
if (values[0] === 'REJECTED') {
return {
code: values[1] ?? 'UNKNOWN',
currentServerTimestampMS: numberValue(values[2]),
rejected: true,
};
}
return {
currentServerTimestampMS: numberValue(values[2]),
noop: true,
revision: numberValue(values[1]),
};
}
function numberValue(value: string | undefined): number {
const parsed = Number(value);
return Number.isFinite(parsed) ? parsed : 0;
}
@@ -0,0 +1,152 @@
import mongoose from 'mongoose';
import {
buildAuctionRedisLiveStatePatchFromStructure,
buildAuctionRedisStructureState,
convertLegacyAuctionTeamsToRedisTeams,
} from './auction-redis-projection';
describe('auction redis projection helpers', () => {
it('converts legacy auction team fields to redis-v1 names', () => {
const captainUserId = new mongoose.Types.ObjectId();
const memberUserId = new mongoose.Types.ObjectId();
expect(
convertLegacyAuctionTeamsToRedisTeams([
{
teamIndex: 1,
captainUserId,
points: 970,
members: [
{
userId: memberUserId,
assignedPosition: 'ADC',
cost: 30,
},
],
},
]),
).toEqual([
{
teamIndex: 1,
captainUserId,
remainingBidPointAmount: 970,
members: [
{
userId: memberUserId,
assignedPosition: 'ADC',
memberAcquisitionBidPointAmount: 30,
},
],
},
]);
});
it('builds the redis structure state with only structure/config fields', () => {
const captainUserId = new mongoose.Types.ObjectId();
const playerUserId = new mongoose.Types.ObjectId();
expect(
buildAuctionRedisStructureState({
auctionPlayerOrder: [
{
userId: playerUserId,
puuid: 'puuid',
gameName: 'Player',
tagLine: 'KR1',
profileIconId: 1,
preferredPositions: [{ position: 'MID', priority: 1 }],
tiers: [],
tierHistory: [],
masteries: [],
passCount: 0,
},
],
auctionTeams: [
{
teamIndex: 1,
captainUserId,
remainingBidPointAmount: 1000,
members: [],
},
],
bidRoundExtensionSeconds: 5,
currentAuctionPlayerOrderIndex: 0,
currentAuctionRound: 1,
initialTeamBidPointAmount: 1000,
manualTopTierAuctionPriorityUserIds: [],
maximumBidRoundDurationSeconds: 30,
passedAuctionPlayerQueue: [],
topTierAuctionPriorityThreshold: 'NONE',
}),
).toMatchObject({
auctionPlayerOrder: [expect.objectContaining({ userId: playerUserId })],
auctionTeams: [
expect.objectContaining({
captainUserId,
remainingBidPointAmount: 1000,
teamIndex: 1,
}),
],
bidRoundExtensionSeconds: 5,
currentAuctionPlayerOrderIndex: 0,
currentAuctionRound: 1,
initialTeamBidPointAmount: 1000,
maximumBidRoundDurationSeconds: 30,
passedAuctionPlayerQueue: [],
topTierAuctionPriorityThreshold: 'NONE',
});
});
it('builds live state patch required by BID Lua', () => {
const captainUserId = new mongoose.Types.ObjectId();
const playerUserId = new mongoose.Types.ObjectId();
expect(
buildAuctionRedisLiveStatePatchFromStructure({
auctionPlayerOrder: [
{
userId: playerUserId,
puuid: 'puuid',
gameName: 'Player',
tagLine: 'KR1',
profileIconId: 1,
preferredPositions: [{ position: 'MID', priority: 1 }],
tiers: [],
tierHistory: [],
masteries: [],
passCount: 0,
},
],
auctionTeams: [
{
teamIndex: 2,
captainUserId,
remainingBidPointAmount: 970,
members: [
{
userId: new mongoose.Types.ObjectId(),
assignedPosition: 'ADC',
memberAcquisitionBidPointAmount: 30,
},
],
},
],
bidRoundExtensionSeconds: 5,
currentAuctionPlayerOrderIndex: 0,
currentAuctionRound: 1,
initialTeamBidPointAmount: 1000,
manualTopTierAuctionPriorityUserIds: [],
maximumBidRoundDurationSeconds: 30,
passedAuctionPlayerQueue: [],
topTierAuctionPriorityThreshold: 'NONE',
}),
).toEqual({
bidRoundExtensionSeconds: 5,
currentAuctionPlayerOrderIndex: 0,
currentBidRoundPlayerUserId: playerUserId.toString(),
maximumBidRoundDurationSeconds: 30,
'team:2:assignedAuctionTeamMemberCount': 2,
'team:2:remainingBidPointAmount': 970,
});
});
});
@@ -0,0 +1,92 @@
import type {
AuctionPlayerSnapshot,
AuctionTeam,
AuctionTopTierThreshold,
RedisAuctionTeam,
} from '../../global/database/schema';
import type mongoose from 'mongoose';
export interface AuctionRedisStructureStateInput {
auctionPlayerOrder: AuctionPlayerSnapshot[];
auctionTeams: RedisAuctionTeam[];
bidRoundExtensionSeconds: number;
currentAuctionPlayerOrderIndex: number;
currentAuctionRound: number;
initialTeamBidPointAmount: number;
manualTopTierAuctionPriorityUserIds: mongoose.Types.ObjectId[];
maximumBidRoundDurationSeconds: number;
passedAuctionPlayerQueue: AuctionPlayerSnapshot[];
topTierAuctionPriorityThreshold: AuctionTopTierThreshold;
}
export function convertLegacyAuctionTeamsToRedisTeams(
teams: AuctionTeam[],
): RedisAuctionTeam[] {
return teams.map((team) => ({
teamIndex: team.teamIndex,
captainUserId: team.captainUserId,
remainingBidPointAmount: team.points,
members: team.members.map((member) => ({
userId: member.userId,
assignedPosition: member.assignedPosition,
memberAcquisitionBidPointAmount: member.cost,
})),
}));
}
export function buildAuctionRedisStructureState(
input: AuctionRedisStructureStateInput,
): Record<string, unknown> {
return {
auctionPlayerOrder: input.auctionPlayerOrder,
auctionTeams: input.auctionTeams,
bidRoundExtensionSeconds: input.bidRoundExtensionSeconds,
currentAuctionPlayerOrderIndex: input.currentAuctionPlayerOrderIndex,
currentAuctionRound: input.currentAuctionRound,
initialTeamBidPointAmount: input.initialTeamBidPointAmount,
manualTopTierAuctionPriorityUserIds:
input.manualTopTierAuctionPriorityUserIds,
maximumBidRoundDurationSeconds: input.maximumBidRoundDurationSeconds,
passedAuctionPlayerQueue: input.passedAuctionPlayerQueue,
topTierAuctionPriorityThreshold: input.topTierAuctionPriorityThreshold,
};
}
export function buildAuctionRedisLiveStatePatchFromStructure(
input: AuctionRedisStructureStateInput,
): Record<string, string | number> {
const patch: Record<string, string | number> = {
bidRoundExtensionSeconds: input.bidRoundExtensionSeconds,
currentAuctionPlayerOrderIndex: input.currentAuctionPlayerOrderIndex,
maximumBidRoundDurationSeconds: input.maximumBidRoundDurationSeconds,
};
const currentPlayer =
input.auctionPlayerOrder[input.currentAuctionPlayerOrderIndex];
if (currentPlayer) {
patch.currentBidRoundPlayerUserId = currentPlayer.userId.toString();
}
for (const team of input.auctionTeams) {
patch[`team:${team.teamIndex}:remainingBidPointAmount`] =
team.remainingBidPointAmount;
patch[`team:${team.teamIndex}:assignedAuctionTeamMemberCount`] =
countAuctionTeamMembersIncludingCaptain(team);
}
return patch;
}
export function stringifyAuctionRedisStructureState(
input: AuctionRedisStructureStateInput,
): string {
return JSON.stringify(buildAuctionRedisStructureState(input));
}
function countAuctionTeamMembersIncludingCaptain(team: RedisAuctionTeam): number {
const userIds = new Set<string>([team.captainUserId.toString()]);
for (const member of team.members) {
userIds.add(member.userId.toString());
}
return userIds.size;
}
@@ -0,0 +1,160 @@
import { AuctionRedisService } from './auction-redis.service';
import { AuctionRedisStateReaderService } from './auction-redis-state-reader.service';
function makeService(commandReplies: unknown[], currentServerTimestampMS = 1000) {
const sendCommand = jest
.fn()
.mockImplementation(() => Promise.resolve(commandReplies.shift()));
const auctionRedisService = {
getCurrentRedisTimestampMS: jest
.fn()
.mockResolvedValue(currentServerTimestampMS),
raw: jest.fn().mockReturnValue({ sendCommand }),
} as unknown as jest.Mocked<AuctionRedisService>;
return {
auctionRedisService,
sendCommand,
service: new AuctionRedisStateReaderService(auctionRedisService),
};
}
describe('AuctionRedisStateReaderService', () => {
it('reads live state identity', async () => {
const { service, sendCommand } = makeService([['life-1', '7']]);
await expect(service.readLiveStateIdentity('match-1')).resolves.toEqual({
auctionLifecycleId: 'life-1',
revision: 7,
});
expect(sendCommand).toHaveBeenCalledWith([
'HMGET',
'auction:match-1:liveAuctionState',
'auctionLifecycleId',
'revision',
]);
});
it('returns null when live state identity is missing', async () => {
const { service } = makeService([[null, null]]);
await expect(service.readLiveStateIdentity('match-1')).resolves.toBeNull();
});
it('assembles a public auction view from Redis state', async () => {
const { service, sendCommand } = makeService([
[
'auctionLifecycleId',
'life-1',
'phase',
'expiring',
'revision',
'8',
'currentHighestBidPointAmount',
'100',
'currentHighestBidderTeamIndex',
'2',
'team:2:remainingBidPointAmount',
'900',
'bidRoundExpiryDecision',
'sold',
],
'{"auctionTeams":[{"teamIndex":1}]}',
['{"bidPointAmount":100,"bidderTeamIndex":2}'],
]);
const view = await service.readAuctionStateView('match-1', {
shouldForceAuctionStateResync: true,
});
expect(view).toMatchObject({
auctionBidHistory: [{ bidPointAmount: 100, bidderTeamIndex: 2 }],
auctionLifecycleId: 'life-1',
auctionTeams: [{ teamIndex: 1 }],
canPlaceBidInCurrentBidRound: false,
currentHighestBidderTeamIndex: 2,
currentHighestBidPointAmount: 100,
currentServerTimestampMS: 1000,
isAuctionStateTransitionInProgress: true,
phase: 'bidding',
revision: 8,
shouldForceAuctionStateResync: true,
});
expect(view).not.toHaveProperty('team:2:remainingBidPointAmount');
expect(view).not.toHaveProperty('bidRoundExpiryDecision');
expect(sendCommand).toHaveBeenNthCalledWith(1, [
'HGETALL',
'auction:match-1:liveAuctionState',
]);
expect(sendCommand).toHaveBeenNthCalledWith(2, [
'GET',
'auction:match-1:auctionStructureState',
]);
expect(sendCommand).toHaveBeenNthCalledWith(3, [
'LRANGE',
'auction:match-1:auctionBidHistory',
'0',
'-1',
]);
});
it('assembles state when HGETALL returns an object', async () => {
const { service } = makeService([
{
auctionLifecycleId: 'life-1',
phase: 'presenting',
revision: '3',
},
'{"auctionTeams":[]}',
[],
]);
await expect(service.readAuctionStateView('match-1')).resolves.toMatchObject({
auctionLifecycleId: 'life-1',
auctionTeams: [],
phase: 'presenting',
revision: 3,
});
});
it('can expose internal live fields for server-side expiry completion', async () => {
const { service } = makeService([
{
auctionLifecycleId: 'life-1',
bidRoundExpiryDecision: 'sold',
phase: 'expiring',
revision: '4',
'team:1:remainingBidPointAmount': '900',
},
'{"auctionTeams":[]}',
[],
]);
await expect(
service.readAuctionStateView('match-1', {
includeInternalLiveStateFields: true,
}),
).resolves.toMatchObject({
bidRoundExpiryDecision: 'sold',
redisInternalPhase: 'expiring',
'team:1:remainingBidPointAmount': '900',
});
});
it('returns null when live or structure state is absent', async () => {
await expect(
makeService([[], '{"auctionTeams":[]}', []]).service.readAuctionStateView(
'match-1',
),
).resolves.toBeNull();
await expect(
makeService([
{ auctionLifecycleId: 'life-1', phase: 'presenting', revision: '1' },
null,
[],
]).service.readAuctionStateView('match-1'),
).resolves.toBeNull();
});
});
@@ -0,0 +1,155 @@
import { Injectable } from '@nestjs/common';
import { buildAuctionRedisKeys } from './auction-redis.keys';
import { AuctionRedisService } from './auction-redis.service';
import { assembleAuctionViewFromRedisState } from './auction-redis.state';
const NUMERIC_LIVE_STATE_FIELDS = new Set([
'bidRoundExpiryPlayerOrderIndex',
'bidRoundExpiryRevision',
'bidRoundExpiryWinningBidPointAmount',
'bidRoundExpiryWinningBidderTeamIndex',
'currentAuctionHistorySequence',
'currentAuctionPlayerOrderIndex',
'currentBidRoundDeadlineTimestampMS',
'currentHighestBidPointAmount',
'currentHighestBidderTeamIndex',
'matchSideEffectRevision',
'revision',
]);
export interface AuctionRedisLiveStateIdentity {
auctionLifecycleId?: string;
revision?: number;
}
export interface AuctionRedisStateViewReadOptions {
includeInternalLiveStateFields?: boolean;
shouldForceAuctionStateResync?: boolean;
}
@Injectable()
export class AuctionRedisStateReaderService {
constructor(private readonly auctionRedisService: AuctionRedisService) {}
public async readLiveStateIdentity(
matchId: string,
): Promise<AuctionRedisLiveStateIdentity | null> {
const keys = buildAuctionRedisKeys(matchId);
const reply = await this.auctionRedisService.raw().sendCommand([
'HMGET',
keys.liveStateKey,
'auctionLifecycleId',
'revision',
]);
if (!Array.isArray(reply)) return null;
const auctionLifecycleId =
typeof reply[0] === 'string' && reply[0] ? reply[0] : undefined;
const revision =
typeof reply[1] === 'string' || typeof reply[1] === 'number'
? Number(reply[1])
: Number.NaN;
if (!auctionLifecycleId && !Number.isFinite(revision)) return null;
return {
auctionLifecycleId,
revision: Number.isFinite(revision) ? revision : undefined,
};
}
public async readAuctionStateView(
matchId: string,
options: AuctionRedisStateViewReadOptions = {},
): Promise<Record<string, unknown> | null> {
const keys = buildAuctionRedisKeys(matchId);
const [currentServerTimestampMS, liveReply, structureStateJson, bidEntries] =
await Promise.all([
this.auctionRedisService.getCurrentRedisTimestampMS(),
this.auctionRedisService.raw().sendCommand(['HGETALL', keys.liveStateKey]),
this.auctionRedisService.raw().sendCommand(['GET', keys.structureStateKey]),
this.auctionRedisService.raw().sendCommand([
'LRANGE',
keys.bidHistoryKey,
'0',
'-1',
]),
]);
const liveState = parseHashReply(liveReply, {
includeInternalLiveStateFields:
options.includeInternalLiveStateFields ?? false,
});
if (!liveState) return null;
if (
typeof liveState.auctionLifecycleId !== 'string' ||
typeof liveState.phase !== 'string' ||
typeof liveState.revision !== 'number'
) {
return null;
}
if (typeof structureStateJson !== 'string' || !structureStateJson) {
return null;
}
const view = assembleAuctionViewFromRedisState({
auctionBidHistoryEntries: Array.isArray(bidEntries)
? bidEntries.map(String)
: [],
currentServerTimestampMS,
liveState: liveState as Record<string, unknown> & {
auctionLifecycleId: string;
phase: string;
revision: number;
},
shouldForceAuctionStateResync: options.shouldForceAuctionStateResync,
structureState: JSON.parse(structureStateJson) as Record<string, unknown>,
});
if (options.includeInternalLiveStateFields) {
view.redisInternalPhase = liveState.phase;
}
return view;
}
}
function parseHashReply(
reply: unknown,
options: { includeInternalLiveStateFields?: boolean } = {},
): Record<string, unknown> | null {
if (!reply) return null;
if (Array.isArray(reply)) {
if (reply.length === 0) return null;
const entries: [string, unknown][] = [];
for (let index = 0; index < reply.length; index += 2) {
entries.push([String(reply[index]), reply[index + 1]]);
}
return parseHashEntries(entries, options);
}
if (typeof reply === 'object') {
const entries = Object.entries(reply as Record<string, unknown>);
if (entries.length === 0) return null;
return parseHashEntries(entries, options);
}
return null;
}
function parseHashEntries(
entries: [string, unknown][],
options: { includeInternalLiveStateFields?: boolean } = {},
): Record<string, unknown> {
const result: Record<string, unknown> = {};
for (const [field, rawValue] of entries) {
if (!options.includeInternalLiveStateFields && isInternalLiveStateField(field)) {
continue;
}
const value = String(rawValue);
if (NUMERIC_LIVE_STATE_FIELDS.has(field)) {
const parsed = Number(value);
result[field] = Number.isFinite(parsed) ? parsed : 0;
continue;
}
result[field] = value;
}
return result;
}
function isInternalLiveStateField(field: string): boolean {
return field.startsWith('team:') || field.startsWith('bidRoundExpiry');
}
@@ -0,0 +1,113 @@
import { buildAuctionRedisKeys } from './auction-redis.keys';
import {
AUCTION_APPLY_TRANSITION_SCRIPT,
buildAuctionApplyTransitionScriptInvocation,
} from './auction-redis.apply-transition';
describe('auction apply transition redis script contract', () => {
it('builds APPLY_TRANSITION keys and values in a stable order', () => {
const keys = buildAuctionRedisKeys('match-1');
const invocation = buildAuctionApplyTransitionScriptInvocation(keys, {
actionRequest: {
observedProcessingLeaseVersion: 3,
processingOwnerToken: 'owner-1',
scopeKey: 'life-1:request-1',
},
afterAuctionStructureStateJson: '{"auctionTeams":[]}',
auctionHistorySequence: 4,
auctionLifecycleId: 'life-1',
auctionStateTransitionId: 'transition-1',
broadcastStateRevision: 9,
deadline: { durationSeconds: 30, mode: 'set-relative' },
durabilityPayloadJson: '{"revision":9}',
expectedCurrentAuctionPlayerOrderIndex: 2,
expectedCurrentBidRoundPlayerUserId: 'player-1',
expectedAuctionHistorySequence: 3,
expectedPhase: 'bidding',
expectedRevision: 8,
liveStatePatch: {
currentAuctionHistorySequence: 4,
phase: 'sold',
},
matchId: 'match-1',
shouldBroadcastState: true,
});
expect(invocation.script).toBe(AUCTION_APPLY_TRANSITION_SCRIPT);
expect(invocation.keys).toEqual([
'auction:match-1:liveAuctionState',
'auction:match-1:auctionStructureState',
'auction:match-1:appliedAuctionStateTransitionIds',
'auction:match-1:durability:transition-1',
'auction:auctionDurabilityRetryQueue',
'auction:match-1:auctionActionRequestResults',
'auction:match-1:auctionActionRequestResultOrder',
'auction:match-1:auctionBidHistory',
'auction:match-1:bidRequestResults',
'auction:match-1:bidRequestResultOrder',
'auction:bidRoundDeadlineQueue',
]);
expect(invocation.values.slice(0, 19)).toEqual([
'match-1',
'life-1',
'transition-1',
'8',
'3',
'bidding',
'player-1',
'2',
'{"auctionTeams":[]}',
'4',
'{"revision":9}',
'1',
'9',
'set-relative',
'30',
'0',
'life-1:request-1',
'owner-1',
'3',
]);
expect(invocation.values.slice(19)).toEqual([
'2',
'currentAuctionHistorySequence',
'4',
'phase',
'sold',
]);
});
it('keeps critical atomicity guards in Lua', () => {
expect(AUCTION_APPLY_TRANSITION_SCRIPT.lua).toContain("redis.call('TIME')");
expect(AUCTION_APPLY_TRANSITION_SCRIPT.lua).toContain(
'ACTION_REQUEST_LEASE_VERSION_MISMATCH',
);
expect(AUCTION_APPLY_TRANSITION_SCRIPT.lua).toContain(
'ACTION_REQUEST_TRANSITION_MISMATCH',
);
expect(AUCTION_APPLY_TRANSITION_SCRIPT.lua).toContain(
'INVALID_PATCH_ARITY',
);
expect(AUCTION_APPLY_TRANSITION_SCRIPT.lua).toContain(
'shouldBroadcastState',
);
expect(AUCTION_APPLY_TRANSITION_SCRIPT.lua).toContain(
"redis.call('SADD'",
);
expect(AUCTION_APPLY_TRANSITION_SCRIPT.lua).toContain(
"redis.call('HINCRBY'",
);
expect(AUCTION_APPLY_TRANSITION_SCRIPT.lua).toContain(
'currentAuctionHistorySequence',
);
expect(AUCTION_APPLY_TRANSITION_SCRIPT.lua).toContain(
'storeValidatedActionRequestRejection',
);
expect(AUCTION_APPLY_TRANSITION_SCRIPT.lua).toContain(
"actionRequestPrefix .. 'status'",
);
expect(AUCTION_APPLY_TRANSITION_SCRIPT.lua).toContain(
"actionRequestPrefix .. 'requiresRefetch'",
);
});
});
@@ -0,0 +1,325 @@
import type { AuctionRedisKeys } from './auction-redis.keys';
import { defineAuctionRedisScript } from './auction-redis.scripts';
export type ApplyTransitionDeadlineInput =
| { mode: 'none' }
| { mode: 'remove' }
| { durationSeconds: number; mode: 'set-relative' };
export interface ApplyTransitionActionRequestInput {
observedProcessingLeaseVersion: number;
processingOwnerToken: string;
scopeKey: string;
}
export interface AuctionApplyTransitionScriptInput {
actionRequest?: ApplyTransitionActionRequestInput;
afterAuctionStructureStateJson: string;
auctionHistorySequence: number;
auctionLifecycleId: string;
auctionStateTransitionId: string;
broadcastStateRevision: number;
deadline: ApplyTransitionDeadlineInput;
durabilityPayloadJson: string;
expectedCurrentAuctionPlayerOrderIndex?: number;
expectedCurrentBidRoundPlayerUserId?: string;
expectedAuctionHistorySequence?: number;
expectedPhase: string;
expectedRevision: number;
liveStatePatch: Record<string, string | number | boolean | null | undefined>;
matchId: string;
shouldBroadcastState: boolean;
shouldResetBidRuntime?: boolean;
}
export interface AuctionApplyTransitionScriptInvocation {
keys: string[];
script: typeof AUCTION_APPLY_TRANSITION_SCRIPT;
values: string[];
}
function stringifyRedisValue(value: string | number | boolean | null): string {
if (typeof value === 'boolean') return value ? '1' : '0';
if (value === null) return '';
return String(value);
}
function flattenLiveStatePatch(
liveStatePatch: AuctionApplyTransitionScriptInput['liveStatePatch'],
): string[] {
return Object.entries(liveStatePatch)
.filter(([, value]) => value !== undefined)
.sort(([a], [b]) => a.localeCompare(b))
.flatMap(([key, value]) => [
key,
stringifyRedisValue(value as string | number | boolean | null),
]);
}
export function buildAuctionApplyTransitionScriptInvocation(
keys: AuctionRedisKeys,
input: AuctionApplyTransitionScriptInput,
): AuctionApplyTransitionScriptInvocation {
const liveStatePatchPairs = flattenLiveStatePatch(input.liveStatePatch);
const deadlineDurationSeconds =
input.deadline.mode === 'set-relative'
? String(input.deadline.durationSeconds)
: '0';
return {
keys: [
keys.liveStateKey,
keys.structureStateKey,
keys.appliedTransitionIdsKey,
keys.durabilityPayloadKey(input.auctionStateTransitionId),
keys.durabilityRetryQueueKey,
keys.actionRequestResultsKey,
keys.actionRequestResultOrderKey,
keys.bidHistoryKey,
keys.bidRequestResultsKey,
keys.bidRequestResultOrderKey,
keys.deadlineQueueKey,
],
script: AUCTION_APPLY_TRANSITION_SCRIPT,
values: [
input.matchId,
input.auctionLifecycleId,
input.auctionStateTransitionId,
String(input.expectedRevision),
String(
input.expectedAuctionHistorySequence ??
input.auctionHistorySequence - 1,
),
input.expectedPhase,
input.expectedCurrentBidRoundPlayerUserId ?? '',
input.expectedCurrentAuctionPlayerOrderIndex === undefined
? ''
: String(input.expectedCurrentAuctionPlayerOrderIndex),
input.afterAuctionStructureStateJson,
String(input.auctionHistorySequence),
input.durabilityPayloadJson,
input.shouldBroadcastState ? '1' : '0',
String(input.broadcastStateRevision),
input.deadline.mode,
deadlineDurationSeconds,
input.shouldResetBidRuntime ? '1' : '0',
input.actionRequest?.scopeKey ?? '',
input.actionRequest?.processingOwnerToken ?? '',
input.actionRequest?.observedProcessingLeaseVersion === undefined
? ''
: String(input.actionRequest.observedProcessingLeaseVersion),
String(liveStatePatchPairs.length / 2),
...liveStatePatchPairs,
],
};
}
export const AUCTION_APPLY_TRANSITION_SCRIPT = defineAuctionRedisScript(
'auction.applyTransition',
`
local liveAuctionStateKey = KEYS[1]
local auctionStructureStateKey = KEYS[2]
local appliedAuctionStateTransitionIdsKey = KEYS[3]
local durabilityPayloadKey = KEYS[4]
local durabilityRetryQueueKey = KEYS[5]
local auctionActionRequestResultsKey = KEYS[6]
local auctionActionRequestResultOrderKey = KEYS[7]
local auctionBidHistoryKey = KEYS[8]
local bidRequestResultsKey = KEYS[9]
local bidRequestResultOrderKey = KEYS[10]
local bidRoundDeadlineQueueKey = KEYS[11]
local matchId = ARGV[1]
local auctionLifecycleId = ARGV[2]
local auctionStateTransitionId = ARGV[3]
local expectedRevision = tonumber(ARGV[4])
local expectedAuctionHistorySequence = tonumber(ARGV[5])
local expectedPhase = ARGV[6]
local expectedCurrentBidRoundPlayerUserId = ARGV[7]
local expectedCurrentAuctionPlayerOrderIndex = ARGV[8]
local afterAuctionStructureStateJson = ARGV[9]
local auctionHistorySequence = tonumber(ARGV[10])
local durabilityPayloadJson = ARGV[11]
local shouldBroadcastState = ARGV[12]
local broadcastStateRevision = tonumber(ARGV[13])
local deadlineMode = ARGV[14]
local deadlineDurationSeconds = tonumber(ARGV[15])
local shouldResetBidRuntime = ARGV[16]
local actionRequestScopeKey = ARGV[17]
local processingOwnerToken = ARGV[18]
local observedProcessingLeaseVersion = ARGV[19]
local liveStatePatchPairCount = tonumber(ARGV[20])
local redisTime = redis.call('TIME')
local currentRedisTimestampMS = (tonumber(redisTime[1]) * 1000) + math.floor(tonumber(redisTime[2]) / 1000)
local validatedActionRequestScopeKey = ''
local function storeValidatedActionRequestRejection(code)
if validatedActionRequestScopeKey == '' then
return
end
local actionRequestPrefix = validatedActionRequestScopeKey .. ':'
redis.call(
'HSET',
auctionActionRequestResultsKey,
actionRequestPrefix .. 'status',
'rejected',
actionRequestPrefix .. 'rejectCode',
code,
actionRequestPrefix .. 'requiresRefetch',
'1',
actionRequestPrefix .. 'responseServerTimestampMS',
tostring(currentRedisTimestampMS)
)
end
local function reject(code)
storeValidatedActionRequestRejection(code)
return {'REJECTED', code, auctionStateTransitionId, tostring(currentRedisTimestampMS)}
end
if not liveStatePatchPairCount then
return reject('INVALID_PATCH_ARITY')
end
if #ARGV ~= 20 + (liveStatePatchPairCount * 2) then
return reject('INVALID_PATCH_ARITY')
end
if not durabilityPayloadJson or durabilityPayloadJson == '' then
return reject('MISSING_DURABILITY_PAYLOAD')
end
if shouldBroadcastState ~= '0' and shouldBroadcastState ~= '1' then
return reject('INVALID_SHOULD_BROADCAST_STATE')
end
if shouldBroadcastState == '1' and not broadcastStateRevision then
return reject('INVALID_BROADCAST_STATE_REVISION')
end
if deadlineMode ~= 'none' and deadlineMode ~= 'remove' and deadlineMode ~= 'set-relative' then
return reject('INVALID_DEADLINE_MODE')
end
if deadlineMode == 'set-relative' and (not deadlineDurationSeconds or deadlineDurationSeconds <= 0) then
return reject('INVALID_DEADLINE_DURATION')
end
if actionRequestScopeKey ~= '' then
local actionRequestPrefix = actionRequestScopeKey .. ':'
local storedTransitionId = redis.call('HGET', auctionActionRequestResultsKey, actionRequestPrefix .. 'auctionStateTransitionId')
if not storedTransitionId then
return reject('ACTION_REQUEST_NOT_RESERVED')
end
if storedTransitionId ~= auctionStateTransitionId then
return reject('ACTION_REQUEST_TRANSITION_MISMATCH')
end
local storedOwnerToken = redis.call('HGET', auctionActionRequestResultsKey, actionRequestPrefix .. 'processingOwnerToken')
local leaseExpiresAtTimestampMS = tonumber(redis.call('HGET', auctionActionRequestResultsKey, actionRequestPrefix .. 'processingLeaseExpiresAtTimestampMS') or '0')
if leaseExpiresAtTimestampMS <= currentRedisTimestampMS then
return reject('ACTION_REQUEST_LEASE_EXPIRED')
end
if storedOwnerToken ~= processingOwnerToken then
return reject('ACTION_REQUEST_IN_PROGRESS')
end
local storedLeaseVersion = redis.call('HGET', auctionActionRequestResultsKey, actionRequestPrefix .. 'processingLeaseVersion') or ''
if storedLeaseVersion ~= observedProcessingLeaseVersion then
return reject('ACTION_REQUEST_LEASE_VERSION_MISMATCH')
end
validatedActionRequestScopeKey = actionRequestScopeKey
end
local currentRevision = tonumber(redis.call('HGET', liveAuctionStateKey, 'revision') or '-1')
if currentRevision ~= expectedRevision then
return reject('CONFLICT')
end
local currentAuctionHistorySequence = tonumber(redis.call('HGET', liveAuctionStateKey, 'currentAuctionHistorySequence') or '-1')
if currentAuctionHistorySequence ~= expectedAuctionHistorySequence then
return reject('CONFLICT')
end
if redis.call('HGET', liveAuctionStateKey, 'auctionLifecycleId') ~= auctionLifecycleId then
return reject('CONFLICT')
end
if redis.call('HGET', liveAuctionStateKey, 'phase') ~= expectedPhase then
return reject('CONFLICT')
end
if expectedCurrentBidRoundPlayerUserId ~= '' and redis.call('HGET', liveAuctionStateKey, 'currentBidRoundPlayerUserId') ~= expectedCurrentBidRoundPlayerUserId then
return reject('CONFLICT')
end
if expectedCurrentAuctionPlayerOrderIndex ~= '' and redis.call('HGET', liveAuctionStateKey, 'currentAuctionPlayerOrderIndex') ~= expectedCurrentAuctionPlayerOrderIndex then
return reject('CONFLICT')
end
local transitionDedupeMember = auctionLifecycleId .. ':' .. auctionStateTransitionId
if redis.call('SISMEMBER', appliedAuctionStateTransitionIdsKey, transitionDedupeMember) == 1 then
return {'REPLAY', 'APPLIED', auctionStateTransitionId, tostring(currentRedisTimestampMS)}
end
local newRevision = redis.call('HINCRBY', liveAuctionStateKey, 'revision', 1)
redis.call('SET', auctionStructureStateKey, afterAuctionStructureStateJson)
local hsetArgs = {
liveAuctionStateKey,
'auctionLifecycleId',
auctionLifecycleId,
'currentAuctionHistorySequence',
tostring(auctionHistorySequence),
'lastAppliedAuctionStateTransitionId',
auctionStateTransitionId
}
local patchIndex = 21
for i = 1, liveStatePatchPairCount do
table.insert(hsetArgs, ARGV[patchIndex])
table.insert(hsetArgs, ARGV[patchIndex + 1])
patchIndex = patchIndex + 2
end
redis.call('HSET', unpack(hsetArgs))
if deadlineMode == 'set-relative' then
local currentBidRoundDeadlineTimestampMS = currentRedisTimestampMS + (deadlineDurationSeconds * 1000)
redis.call('HSET', liveAuctionStateKey, 'currentBidRoundDeadlineTimestampMS', tostring(currentBidRoundDeadlineTimestampMS))
redis.call('ZADD', bidRoundDeadlineQueueKey, currentBidRoundDeadlineTimestampMS, matchId)
elseif deadlineMode == 'remove' then
redis.call('ZREM', bidRoundDeadlineQueueKey, matchId)
end
if shouldResetBidRuntime == '1' then
redis.call('DEL', auctionBidHistoryKey, bidRequestResultsKey, bidRequestResultOrderKey)
end
redis.call('SADD', appliedAuctionStateTransitionIdsKey, transitionDedupeMember)
redis.call(
'HSET',
durabilityPayloadKey,
'payloadJson',
durabilityPayloadJson,
'preparedAtRedisTimestampMS',
tostring(currentRedisTimestampMS),
'committedAtRedisTimestampMS',
tostring(currentRedisTimestampMS),
'auctionLifecycleId',
auctionLifecycleId,
'revision',
tostring(newRevision),
'shouldBroadcastState',
shouldBroadcastState,
'broadcastStateRevision',
tostring(broadcastStateRevision)
)
redis.call('ZADD', durabilityRetryQueueKey, currentRedisTimestampMS, durabilityPayloadKey)
if actionRequestScopeKey ~= '' then
local actionRequestPrefix = actionRequestScopeKey .. ':'
redis.call(
'HSET',
auctionActionRequestResultsKey,
actionRequestPrefix .. 'status',
'applied',
actionRequestPrefix .. 'revision',
tostring(newRevision),
actionRequestPrefix .. 'requiresRefetch',
'1',
actionRequestPrefix .. 'responseServerTimestampMS',
tostring(currentRedisTimestampMS)
)
redis.call('RPUSH', auctionActionRequestResultOrderKey, actionRequestScopeKey)
end
return {'OK', auctionStateTransitionId, tostring(newRevision), tostring(currentRedisTimestampMS)}
`,
);
@@ -0,0 +1,72 @@
import { buildAuctionRedisKeys } from './auction-redis.keys';
import {
AUCTION_BID_SCRIPT,
buildAuctionBidScriptInvocation,
buildBidRequestPayloadFingerprint,
} from './auction-redis.bid';
describe('auction bid redis script contract', () => {
it('builds the BID script KEYS and ARGV in the documented order', () => {
const keys = buildAuctionRedisKeys('match-1');
const invocation = buildAuctionBidScriptInvocation(keys, {
bidderTeamIndex: 2,
bidPointAmount: 120,
bidRequestId: 'bid-1',
bidderUserId: 'captain-2',
clientObservedAuctionLifecycleId: 'life-1',
clientObservedCurrentBidRoundPlayerUserId: 'player-1',
maximumAuctionTeamMemberCount: 5,
maximumStoredAuctionBidHistoryCount: 200,
maximumStoredBidRequestResultCount: 100,
matchId: 'match-1',
minimumBidPointReservePerRemainingAuctionTeamMemberSlot: 10,
minimumBidRequestResultReplayWindowMS: 60_000,
});
expect(invocation.script).toBe(AUCTION_BID_SCRIPT);
expect(invocation.keys).toEqual([
'auction:match-1:liveAuctionState',
'auction:match-1:auctionBidHistory',
'auction:match-1:bidRequestResults',
'auction:match-1:bidRequestResultOrder',
'auction:bidRoundDeadlineQueue',
]);
expect(invocation.values).toEqual([
'match-1',
'2',
'120',
'5',
'10',
'bid-1',
'captain-2',
'life-1',
'player-1',
'match-1|life-1|player-1|2|120',
'100',
'60000',
'200',
]);
});
it('keeps bid fingerprints stable and timestamp-free', () => {
expect(
buildBidRequestPayloadFingerprint({
bidderTeamIndex: 2,
bidPointAmount: 120,
clientObservedAuctionLifecycleId: 'life-1',
clientObservedCurrentBidRoundPlayerUserId: 'player-1',
matchId: 'match-1',
}),
).toBe('match-1|life-1|player-1|2|120');
});
it('uses Redis TIME and scalar hash fields rather than JSON parsing', () => {
expect(AUCTION_BID_SCRIPT.lua).toContain("redis.call('TIME')");
expect(AUCTION_BID_SCRIPT.lua).toContain("redis.call('HINCRBY'");
expect(AUCTION_BID_SCRIPT.lua).toContain('BID_REQUEST_RESULT_LIMIT');
expect(AUCTION_BID_SCRIPT.lua).toContain(
'currentHighestBidPointAmount',
);
expect(AUCTION_BID_SCRIPT.lua).not.toContain('cjson.decode');
});
});
@@ -0,0 +1,310 @@
import type { AuctionRedisKeys } from './auction-redis.keys';
import { defineAuctionRedisScript } from './auction-redis.scripts';
export interface AuctionBidScriptInput {
bidderTeamIndex: number;
bidPointAmount: number;
bidRequestId: string;
bidderUserId: string;
clientObservedAuctionLifecycleId: string;
clientObservedCurrentBidRoundPlayerUserId: string;
maximumAuctionTeamMemberCount: number;
maximumStoredAuctionBidHistoryCount: number;
maximumStoredBidRequestResultCount: number;
matchId: string;
minimumBidPointReservePerRemainingAuctionTeamMemberSlot: number;
minimumBidRequestResultReplayWindowMS: number;
}
export interface AuctionBidScriptInvocation {
keys: string[];
script: typeof AUCTION_BID_SCRIPT;
values: string[];
}
const BID_RESULT_HASH_SUFFIXES = [
'fingerprint',
'status',
'revision',
'rejectCode',
'currentHighestBidPointAmount',
'currentHighestBidderTeamIndex',
'currentBidRoundDeadlineTimestampMS',
'auctionBidHistoryEntryJson',
'responseServerTimestampMS',
'createdAtTimestampMS',
] as const;
export function buildBidRequestPayloadFingerprint(params: {
bidderTeamIndex: number;
bidPointAmount: number;
clientObservedAuctionLifecycleId: string;
clientObservedCurrentBidRoundPlayerUserId: string;
matchId: string;
}): string {
return [
params.matchId,
params.clientObservedAuctionLifecycleId,
params.clientObservedCurrentBidRoundPlayerUserId,
params.bidderTeamIndex,
params.bidPointAmount,
].join('|');
}
export function buildAuctionBidScriptInvocation(
keys: AuctionRedisKeys,
input: AuctionBidScriptInput,
): AuctionBidScriptInvocation {
return {
keys: [
keys.liveStateKey,
keys.bidHistoryKey,
keys.bidRequestResultsKey,
keys.bidRequestResultOrderKey,
keys.deadlineQueueKey,
],
script: AUCTION_BID_SCRIPT,
values: [
input.matchId,
String(input.bidderTeamIndex),
String(input.bidPointAmount),
String(input.maximumAuctionTeamMemberCount),
String(input.minimumBidPointReservePerRemainingAuctionTeamMemberSlot),
input.bidRequestId,
input.bidderUserId,
input.clientObservedAuctionLifecycleId,
input.clientObservedCurrentBidRoundPlayerUserId,
buildBidRequestPayloadFingerprint(input),
String(input.maximumStoredBidRequestResultCount),
String(input.minimumBidRequestResultReplayWindowMS),
String(input.maximumStoredAuctionBidHistoryCount),
],
};
}
export const AUCTION_BID_SCRIPT = defineAuctionRedisScript(
'auction.bid',
`
local liveAuctionStateKey = KEYS[1]
local auctionBidHistoryKey = KEYS[2]
local bidRequestResultsKey = KEYS[3]
local bidRequestResultOrderKey = KEYS[4]
local bidRoundDeadlineQueueKey = KEYS[5]
local matchId = ARGV[1]
local bidderTeamIndex = ARGV[2]
local bidPointAmount = tonumber(ARGV[3])
local maximumAuctionTeamMemberCount = tonumber(ARGV[4])
local minimumBidPointReservePerRemainingAuctionTeamMemberSlot = tonumber(ARGV[5])
local bidRequestId = ARGV[6]
local bidderUserId = ARGV[7]
local clientObservedAuctionLifecycleId = ARGV[8]
local clientObservedCurrentBidRoundPlayerUserId = ARGV[9]
local bidRequestPayloadFingerprint = ARGV[10]
local maximumStoredBidRequestResultCount = tonumber(ARGV[11])
local minimumBidRequestResultReplayWindowMS = tonumber(ARGV[12])
local maximumStoredAuctionBidHistoryCount = tonumber(ARGV[13])
local redisTime = redis.call('TIME')
local currentRedisTimestampMS = (tonumber(redisTime[1]) * 1000) + math.floor(tonumber(redisTime[2]) / 1000)
local function requestField(suffix)
return bidRequestId .. ':' .. suffix
end
local function hdelBidRequest(requestId)
redis.call(
'HDEL',
bidRequestResultsKey,
requestId .. ':fingerprint',
requestId .. ':status',
requestId .. ':revision',
requestId .. ':rejectCode',
requestId .. ':currentHighestBidPointAmount',
requestId .. ':currentHighestBidderTeamIndex',
requestId .. ':currentBidRoundDeadlineTimestampMS',
requestId .. ':auctionBidHistoryEntryJson',
requestId .. ':responseServerTimestampMS',
requestId .. ':createdAtTimestampMS'
)
end
local function trimOldBidRequestResults()
while redis.call('LLEN', bidRequestResultOrderKey) >= maximumStoredBidRequestResultCount do
local oldestBidRequestId = redis.call('LINDEX', bidRequestResultOrderKey, 0)
if not oldestBidRequestId then
return
end
local createdAtTimestampMS = tonumber(redis.call('HGET', bidRequestResultsKey, oldestBidRequestId .. ':createdAtTimestampMS') or '0')
if createdAtTimestampMS > currentRedisTimestampMS - minimumBidRequestResultReplayWindowMS then
return
end
redis.call('LPOP', bidRequestResultOrderKey)
hdelBidRequest(oldestBidRequestId)
end
end
local function replayExistingRequest()
local status = redis.call('HGET', bidRequestResultsKey, requestField('status')) or ''
return {
'REPLAY',
status,
bidRequestId,
redis.call('HGET', bidRequestResultsKey, requestField('revision')) or '',
redis.call('HGET', bidRequestResultsKey, requestField('rejectCode')) or '',
redis.call('HGET', bidRequestResultsKey, requestField('currentHighestBidPointAmount')) or '',
redis.call('HGET', bidRequestResultsKey, requestField('currentHighestBidderTeamIndex')) or '',
redis.call('HGET', bidRequestResultsKey, requestField('currentBidRoundDeadlineTimestampMS')) or '',
redis.call('HGET', bidRequestResultsKey, requestField('auctionBidHistoryEntryJson')) or '',
redis.call('HGET', bidRequestResultsKey, requestField('responseServerTimestampMS')) or tostring(currentRedisTimestampMS)
}
end
local existingFingerprint = redis.call('HGET', bidRequestResultsKey, requestField('fingerprint'))
if existingFingerprint then
if existingFingerprint ~= bidRequestPayloadFingerprint then
return {'REJECTED', 'DUPLICATE_REQUEST_CONFLICT', bidRequestId, tostring(currentRedisTimestampMS)}
end
return replayExistingRequest()
end
trimOldBidRequestResults()
if redis.call('LLEN', bidRequestResultOrderKey) >= maximumStoredBidRequestResultCount then
return {'REJECTED', 'BID_REQUEST_RESULT_LIMIT', bidRequestId, tostring(currentRedisTimestampMS)}
end
local function storeRejectedRequest(rejectCode)
redis.call(
'HSET',
bidRequestResultsKey,
requestField('fingerprint'),
bidRequestPayloadFingerprint,
requestField('status'),
'rejected',
requestField('rejectCode'),
rejectCode,
requestField('responseServerTimestampMS'),
tostring(currentRedisTimestampMS),
requestField('createdAtTimestampMS'),
tostring(currentRedisTimestampMS)
)
redis.call('RPUSH', bidRequestResultOrderKey, bidRequestId)
return {'REJECTED', rejectCode, bidRequestId, tostring(currentRedisTimestampMS)}
end
local phase = redis.call('HGET', liveAuctionStateKey, 'phase')
if phase ~= 'bidding' then
return storeRejectedRequest('PHASE')
end
local auctionLifecycleId = redis.call('HGET', liveAuctionStateKey, 'auctionLifecycleId')
local currentBidRoundPlayerUserId = redis.call('HGET', liveAuctionStateKey, 'currentBidRoundPlayerUserId')
if auctionLifecycleId ~= clientObservedAuctionLifecycleId or currentBidRoundPlayerUserId ~= clientObservedCurrentBidRoundPlayerUserId then
return storeRejectedRequest('STALE_BID_ROUND')
end
local currentBidRoundDeadlineTimestampMS = tonumber(redis.call('HGET', liveAuctionStateKey, 'currentBidRoundDeadlineTimestampMS') or '0')
if currentBidRoundDeadlineTimestampMS <= currentRedisTimestampMS then
return storeRejectedRequest('EXPIRED')
end
local currentHighestBidPointAmount = tonumber(redis.call('HGET', liveAuctionStateKey, 'currentHighestBidPointAmount') or '0')
if bidPointAmount <= currentHighestBidPointAmount then
return storeRejectedRequest('TOO_LOW')
end
local remainingBidPointAmountField = 'team:' .. bidderTeamIndex .. ':remainingBidPointAmount'
local assignedAuctionTeamMemberCountField = 'team:' .. bidderTeamIndex .. ':assignedAuctionTeamMemberCount'
local remainingBidPointAmountRaw = redis.call('HGET', liveAuctionStateKey, remainingBidPointAmountField)
if not remainingBidPointAmountRaw then
return storeRejectedRequest('UNKNOWN_TEAM')
end
local assignedAuctionTeamMemberCount = tonumber(redis.call('HGET', liveAuctionStateKey, assignedAuctionTeamMemberCountField) or '0')
if assignedAuctionTeamMemberCount >= maximumAuctionTeamMemberCount then
return storeRejectedRequest('FULL')
end
local remainingBidPointAmount = tonumber(remainingBidPointAmountRaw)
local remainingSlotsAfterBid = maximumAuctionTeamMemberCount - assignedAuctionTeamMemberCount - 1
local requiredReserveAfterBid = remainingSlotsAfterBid * minimumBidPointReservePerRemainingAuctionTeamMemberSlot
if bidPointAmount + requiredReserveAfterBid > remainingBidPointAmount then
return storeRejectedRequest('INSUFFICIENT')
end
if redis.call('LLEN', auctionBidHistoryKey) >= maximumStoredAuctionBidHistoryCount then
return storeRejectedRequest('BID_HISTORY_LIMIT')
end
local maximumBidRoundDurationSeconds = tonumber(redis.call('HGET', liveAuctionStateKey, 'maximumBidRoundDurationSeconds') or '0')
local bidRoundExtensionSeconds = tonumber(redis.call('HGET', liveAuctionStateKey, 'bidRoundExtensionSeconds') or '0')
local remainingBidRoundTimeMS = currentBidRoundDeadlineTimestampMS - currentRedisTimestampMS
local nextRemainingBidRoundTimeMS = remainingBidRoundTimeMS
local bidRoundExtensionMS = bidRoundExtensionSeconds * 1000
local maximumBidRoundDurationMS = maximumBidRoundDurationSeconds * 1000
if nextRemainingBidRoundTimeMS < bidRoundExtensionMS then
nextRemainingBidRoundTimeMS = bidRoundExtensionMS
end
if nextRemainingBidRoundTimeMS > maximumBidRoundDurationMS then
nextRemainingBidRoundTimeMS = maximumBidRoundDurationMS
end
local nextBidRoundDeadlineTimestampMS = currentRedisTimestampMS + nextRemainingBidRoundTimeMS
local revision = redis.call('HINCRBY', liveAuctionStateKey, 'revision', 1)
local auctionBidHistoryEntryJson =
'{"bidderTeamIndex":' .. bidderTeamIndex ..
',"bidPointAmount":' .. tostring(bidPointAmount) ..
',"bidderUserId":"' .. bidderUserId ..
'","bidPlacedAtTimestampMS":' .. tostring(currentRedisTimestampMS) ..
'}'
redis.call('RPUSH', auctionBidHistoryKey, auctionBidHistoryEntryJson)
redis.call(
'HSET',
liveAuctionStateKey,
'currentHighestBidPointAmount',
tostring(bidPointAmount),
'currentHighestBidderTeamIndex',
bidderTeamIndex,
'currentBidRoundDeadlineTimestampMS',
tostring(nextBidRoundDeadlineTimestampMS)
)
redis.call('ZADD', bidRoundDeadlineQueueKey, nextBidRoundDeadlineTimestampMS, matchId)
redis.call(
'HSET',
bidRequestResultsKey,
requestField('fingerprint'),
bidRequestPayloadFingerprint,
requestField('status'),
'ok',
requestField('revision'),
tostring(revision),
requestField('currentHighestBidPointAmount'),
tostring(bidPointAmount),
requestField('currentHighestBidderTeamIndex'),
bidderTeamIndex,
requestField('currentBidRoundDeadlineTimestampMS'),
tostring(nextBidRoundDeadlineTimestampMS),
requestField('auctionBidHistoryEntryJson'),
auctionBidHistoryEntryJson,
requestField('responseServerTimestampMS'),
tostring(currentRedisTimestampMS),
requestField('createdAtTimestampMS'),
tostring(currentRedisTimestampMS)
)
redis.call('RPUSH', bidRequestResultOrderKey, bidRequestId)
return {
'OK',
bidRequestId,
tostring(revision),
tostring(currentRedisTimestampMS),
tostring(bidPointAmount),
bidderTeamIndex,
tostring(nextBidRoundDeadlineTimestampMS),
auctionBidHistoryEntryJson
}
`,
);
export const BID_RESULT_HASH_FIELD_SUFFIXES = BID_RESULT_HASH_SUFFIXES;
@@ -0,0 +1 @@
export const AUCTION_REDIS_CLIENT = Symbol('AUCTION_REDIS_CLIENT');
@@ -0,0 +1,38 @@
import { buildAuctionRedisKeys } from './auction-redis.keys';
import {
AUCTION_EXPIRE_PREPARE_SCRIPT,
buildAuctionExpirePrepareScriptInvocation,
} from './auction-redis.expire-prepare';
describe('auction expire prepare redis script contract', () => {
it('builds EXPIRE_PREPARE keys and values', () => {
const invocation = buildAuctionExpirePrepareScriptInvocation(
buildAuctionRedisKeys('match-1'),
{
auctionStateTransitionId: 'expire-1',
bidRoundExpiryRetryDelayMS: 3_000,
matchId: 'match-1',
},
);
expect(invocation.script).toBe(AUCTION_EXPIRE_PREPARE_SCRIPT);
expect(invocation.keys).toEqual([
'auction:match-1:liveAuctionState',
'auction:bidRoundDeadlineQueue',
]);
expect(invocation.values).toEqual(['match-1', 'expire-1', '3000']);
});
it('freezes expiry context with Redis TIME and expiring phase', () => {
expect(AUCTION_EXPIRE_PREPARE_SCRIPT.lua).toContain("redis.call('TIME')");
expect(AUCTION_EXPIRE_PREPARE_SCRIPT.lua).toContain("'phase'");
expect(AUCTION_EXPIRE_PREPARE_SCRIPT.lua).toContain("'expiring'");
expect(AUCTION_EXPIRE_PREPARE_SCRIPT.lua).toContain(
'bidRoundExpiryRevision',
);
expect(AUCTION_EXPIRE_PREPARE_SCRIPT.lua).toContain(
'bidRoundExpiryWinningBidderTeamIndex',
);
expect(AUCTION_EXPIRE_PREPARE_SCRIPT.lua).toContain("'ZADD'");
});
});
@@ -0,0 +1,107 @@
import type { AuctionRedisKeys } from './auction-redis.keys';
import { defineAuctionRedisScript } from './auction-redis.scripts';
export interface AuctionExpirePrepareScriptInput {
auctionStateTransitionId: string;
bidRoundExpiryRetryDelayMS: number;
matchId: string;
}
export interface AuctionExpirePrepareScriptInvocation {
keys: string[];
script: typeof AUCTION_EXPIRE_PREPARE_SCRIPT;
values: string[];
}
export function buildAuctionExpirePrepareScriptInvocation(
keys: AuctionRedisKeys,
input: AuctionExpirePrepareScriptInput,
): AuctionExpirePrepareScriptInvocation {
return {
keys: [keys.liveStateKey, keys.deadlineQueueKey],
script: AUCTION_EXPIRE_PREPARE_SCRIPT,
values: [
input.matchId,
input.auctionStateTransitionId,
String(input.bidRoundExpiryRetryDelayMS),
],
};
}
export const AUCTION_EXPIRE_PREPARE_SCRIPT = defineAuctionRedisScript(
'auction.expirePrepare',
`
local liveAuctionStateKey = KEYS[1]
local bidRoundDeadlineQueueKey = KEYS[2]
local matchId = ARGV[1]
local auctionStateTransitionId = ARGV[2]
local bidRoundExpiryRetryDelayMS = tonumber(ARGV[3])
local redisTime = redis.call('TIME')
local currentRedisTimestampMS = (tonumber(redisTime[1]) * 1000) + math.floor(tonumber(redisTime[2]) / 1000)
local phase = redis.call('HGET', liveAuctionStateKey, 'phase')
if phase == 'expiring' then
return {
'REPLAY',
redis.call('HGET', liveAuctionStateKey, 'bidRoundExpiryDecision') or '',
redis.call('HGET', liveAuctionStateKey, 'bidRoundExpiryAuctionStateTransitionId') or '',
redis.call('HGET', liveAuctionStateKey, 'bidRoundExpiryRevision') or '',
tostring(currentRedisTimestampMS)
}
end
if phase ~= 'bidding' then
redis.call('ZREM', bidRoundDeadlineQueueKey, matchId)
return {'NOOP', 'PHASE', tostring(currentRedisTimestampMS)}
end
local currentBidRoundDeadlineTimestampMS = tonumber(redis.call('HGET', liveAuctionStateKey, 'currentBidRoundDeadlineTimestampMS') or '0')
if currentBidRoundDeadlineTimestampMS > currentRedisTimestampMS then
return {'NOOP', 'NOT_DUE', tostring(currentRedisTimestampMS)}
end
local currentHighestBidPointAmount = tonumber(redis.call('HGET', liveAuctionStateKey, 'currentHighestBidPointAmount') or '0')
local currentHighestBidderTeamIndex = redis.call('HGET', liveAuctionStateKey, 'currentHighestBidderTeamIndex') or '-1'
local bidRoundExpiryDecision = 'passed'
if currentHighestBidPointAmount > 0 then
bidRoundExpiryDecision = 'sold'
end
local revision = redis.call('HINCRBY', liveAuctionStateKey, 'revision', 1)
redis.call(
'HSET',
liveAuctionStateKey,
'phase',
'expiring',
'bidRoundExpiryDecision',
bidRoundExpiryDecision,
'bidRoundExpiryAuctionStateTransitionId',
auctionStateTransitionId,
'bidRoundExpiryPlayerUserId',
redis.call('HGET', liveAuctionStateKey, 'currentBidRoundPlayerUserId') or '',
'bidRoundExpiryPlayerOrderIndex',
redis.call('HGET', liveAuctionStateKey, 'currentAuctionPlayerOrderIndex') or '',
'bidRoundExpiryWinningBidPointAmount',
tostring(currentHighestBidPointAmount),
'bidRoundExpiryWinningBidderTeamIndex',
currentHighestBidderTeamIndex,
'bidRoundExpiryRevision',
tostring(revision)
)
redis.call(
'ZADD',
bidRoundDeadlineQueueKey,
currentRedisTimestampMS + bidRoundExpiryRetryDelayMS,
matchId
)
return {
'OK',
bidRoundExpiryDecision,
auctionStateTransitionId,
tostring(revision),
tostring(currentRedisTimestampMS)
}
`,
);
@@ -0,0 +1,29 @@
import { buildAuctionRedisKeys } from './auction-redis.keys';
describe('auction redis keys', () => {
it('builds lifecycle-safe key names from match id', () => {
expect(buildAuctionRedisKeys('match-1')).toMatchObject({
actionRequestResultOrderKey: 'auction:match-1:auctionActionRequestResultOrder',
actionRequestResultsKey: 'auction:match-1:auctionActionRequestResults',
appliedTransitionIdsKey: 'auction:match-1:appliedAuctionStateTransitionIds',
bidHistoryKey: 'auction:match-1:auctionBidHistory',
bidRequestResultOrderKey: 'auction:match-1:bidRequestResultOrder',
bidRequestResultsKey: 'auction:match-1:bidRequestResults',
deadlineQueueKey: 'auction:bidRoundDeadlineQueue',
durabilityDeadLetterQueueKey: 'auction:auctionDurabilityDeadLetterQueue',
durabilityPayloadKeyPrefix: 'auction:match-1:durability:',
durabilityRetryQueueKey: 'auction:auctionDurabilityRetryQueue',
liveStateKey: 'auction:match-1:liveAuctionState',
rehydrateLockKey: 'auction:match-1:rehydrateLock',
stateTransitionLockKey: 'auction:match-1:auctionStateTransitionLock',
structureStateKey: 'auction:match-1:auctionStructureState',
});
});
it('builds transition durability payload keys', () => {
const keys = buildAuctionRedisKeys('match-1');
expect(keys.durabilityPayloadKey('transition-1')).toBe(
'auction:match-1:durability:transition-1',
);
});
});
@@ -0,0 +1,47 @@
export const AUCTION_BID_ROUND_DEADLINE_QUEUE_KEY =
'auction:bidRoundDeadlineQueue';
export const AUCTION_DURABILITY_RETRY_QUEUE_KEY =
'auction:auctionDurabilityRetryQueue';
export const AUCTION_DURABILITY_DEAD_LETTER_QUEUE_KEY =
'auction:auctionDurabilityDeadLetterQueue';
export interface AuctionRedisKeys {
actionRequestResultOrderKey: string;
actionRequestResultsKey: string;
appliedTransitionIdsKey: string;
bidHistoryKey: string;
bidRequestResultOrderKey: string;
bidRequestResultsKey: string;
deadlineQueueKey: string;
durabilityDeadLetterQueueKey: string;
durabilityPayloadKey: (auctionStateTransitionId: string) => string;
durabilityPayloadKeyPrefix: string;
durabilityRetryQueueKey: string;
liveStateKey: string;
rehydrateLockKey: string;
stateTransitionLockKey: string;
structureStateKey: string;
}
export function buildAuctionRedisKeys(matchId: string): AuctionRedisKeys {
const prefix = `auction:${matchId}`;
const durabilityPayloadKeyPrefix = `${prefix}:durability:`;
return {
actionRequestResultOrderKey: `${prefix}:auctionActionRequestResultOrder`,
actionRequestResultsKey: `${prefix}:auctionActionRequestResults`,
appliedTransitionIdsKey: `${prefix}:appliedAuctionStateTransitionIds`,
bidHistoryKey: `${prefix}:auctionBidHistory`,
bidRequestResultOrderKey: `${prefix}:bidRequestResultOrder`,
bidRequestResultsKey: `${prefix}:bidRequestResults`,
deadlineQueueKey: AUCTION_BID_ROUND_DEADLINE_QUEUE_KEY,
durabilityDeadLetterQueueKey: AUCTION_DURABILITY_DEAD_LETTER_QUEUE_KEY,
durabilityPayloadKey: (auctionStateTransitionId: string) =>
`${durabilityPayloadKeyPrefix}${auctionStateTransitionId}`,
durabilityPayloadKeyPrefix,
durabilityRetryQueueKey: AUCTION_DURABILITY_RETRY_QUEUE_KEY,
liveStateKey: `${prefix}:liveAuctionState`,
rehydrateLockKey: `${prefix}:rehydrateLock`,
stateTransitionLockKey: `${prefix}:auctionStateTransitionLock`,
structureStateKey: `${prefix}:auctionStructureState`,
};
}
@@ -0,0 +1,100 @@
import { Logger, Module } from '@nestjs/common';
import { createClient } from 'redis';
import { SecretModule } from '../../global/secret/secret.module';
import { SecretService } from '../../global/secret/secret.service';
import {
assertDistinctRedisInstances,
resolveRedisClientOptions,
} from '../../global/redis/redis.config';
import { AUCTION_REDIS_CLIENT } from './auction-redis.constants';
import {
AuctionRedisService,
type AuctionRedisClient,
} from './auction-redis.service';
import { AuctionRedisCommandService } from './auction-redis-command.service';
import { AuctionRedisStateReaderService } from './auction-redis-state-reader.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: AUCTION_REDIS_CLIENT,
inject: [SecretService],
useFactory: async (
secretService: SecretService,
): Promise<AuctionRedisClient> => {
await secretService.ready();
const [
redisUrl,
redisEndpoint,
auctionRedisUrl,
auctionRedisEndpoint,
auctionRedisUsername,
auctionRedisPassword,
] = await Promise.all([
readFirstSecret(secretService, ['REDIS_URL', 'GARNET_URL']),
readFirstSecret(secretService, ['REDIS_ENDPOINT', 'GARNET_ENDPOINT']),
readFirstSecret(secretService, ['AUCTION_REDIS_URL']),
readFirstSecret(secretService, ['AUCTION_REDIS_ENDPOINT']),
readFirstSecret(secretService, [
'AUCTION_REDIS_USERNAME',
'AUCTION_REDIS_USERID',
]),
readFirstSecret(secretService, ['AUCTION_REDIS_PASSWORD']),
]);
const redisOptions = resolveRedisClientOptions({
endpoint: redisEndpoint,
endpointEnvName: 'REDIS_ENDPOINT',
url: redisUrl,
urlEnvName: 'REDIS_URL',
});
const auctionRedisOptions = resolveRedisClientOptions({
endpoint: auctionRedisEndpoint,
endpointEnvName: 'AUCTION_REDIS_ENDPOINT',
password: auctionRedisPassword,
url: auctionRedisUrl,
urlEnvName: 'AUCTION_REDIS_URL',
username: auctionRedisUsername,
});
assertDistinctRedisInstances(redisOptions.url, auctionRedisOptions.url);
const logger = new Logger('AuctionRedisClient');
const client = createClient(auctionRedisOptions);
client.on('error', (error) => {
logger.error(
`Auction Redis client error: ${error?.message ?? error}`,
);
});
await client.connect();
logger.log('Auction Redis connected');
return client;
},
},
AuctionRedisService,
AuctionRedisCommandService,
AuctionRedisStateReaderService,
],
exports: [
AuctionRedisService,
AuctionRedisCommandService,
AuctionRedisStateReaderService,
AUCTION_REDIS_CLIENT,
],
})
export class AuctionRedisModule {}
@@ -0,0 +1,77 @@
import { buildAuctionRedisKeys } from './auction-redis.keys';
import {
AUCTION_RESERVE_ACTION_REQUEST_SCRIPT,
buildActionRequestPayloadFingerprint,
buildAuctionReserveActionRequestScriptInvocation,
} from './auction-redis.reserve-action';
describe('auction reserve action request redis script contract', () => {
it('builds RESERVE_AUCTION_ACTION_REQUEST keys and values', () => {
const invocation = buildAuctionReserveActionRequestScriptInvocation(
buildAuctionRedisKeys('match-1'),
{
auctionActionRequestId: 'request-1',
auctionActionType: 'sold',
auctionStateTransitionId: 'transition-1',
clientObservedAuctionLifecycleId: 'life-1',
clientObservedPhase: 'bidding',
clientObservedRevision: 8,
leaseDurationMS: 10_000,
maximumStoredAuctionActionRequestResultCount: 100,
minimumAuctionActionRequestResultReplayWindowMS: 60_000,
newAuctionLifecycleId: undefined,
processingOwnerToken: 'owner-1',
},
);
expect(invocation.script).toBe(AUCTION_RESERVE_ACTION_REQUEST_SCRIPT);
expect(invocation.keys).toEqual([
'auction:match-1:auctionActionRequestResults',
'auction:match-1:auctionActionRequestResultOrder',
]);
expect(invocation.values).toEqual([
'life-1',
'request-1',
'sold',
'transition-1',
'',
'owner-1',
'10000',
'100',
'60000',
'life-1|request-1|sold|8|bidding||',
]);
});
it('builds stable action request fingerprints', () => {
expect(
buildActionRequestPayloadFingerprint({
auctionActionRequestId: 'request-1',
auctionActionType: 'next',
clientObservedAuctionLifecycleId: 'life-1',
clientObservedCurrentAuctionPlayerOrderIndex: 3,
clientObservedCurrentBidRoundPlayerUserId: 'player-1',
clientObservedPhase: 'sold',
clientObservedRevision: 9,
}),
).toBe('life-1|request-1|next|9|sold|player-1|3');
});
it('keeps lease version and replay guards in Lua', () => {
expect(AUCTION_RESERVE_ACTION_REQUEST_SCRIPT.lua).toContain(
"redis.call('TIME')",
);
expect(AUCTION_RESERVE_ACTION_REQUEST_SCRIPT.lua).toContain(
'processingLeaseVersion',
);
expect(AUCTION_RESERVE_ACTION_REQUEST_SCRIPT.lua).toContain(
'ACTION_REQUEST_IN_PROGRESS',
);
expect(AUCTION_RESERVE_ACTION_REQUEST_SCRIPT.lua).toContain(
'ACTION_REQUEST_RESULT_LIMIT',
);
expect(AUCTION_RESERVE_ACTION_REQUEST_SCRIPT.lua).toContain(
'DUPLICATE_ACTION_REQUEST_CONFLICT',
);
});
});
@@ -0,0 +1,233 @@
import type { AuctionRedisKeys } from './auction-redis.keys';
import { defineAuctionRedisScript } from './auction-redis.scripts';
export interface AuctionReserveActionRequestScriptInput {
auctionActionRequestId: string;
auctionActionType: string;
auctionStateTransitionId: string;
clientObservedAuctionLifecycleId: string;
clientObservedCurrentAuctionPlayerOrderIndex?: number;
clientObservedCurrentBidRoundPlayerUserId?: string;
clientObservedPhase: string;
clientObservedRevision: number;
leaseDurationMS: number;
maximumStoredAuctionActionRequestResultCount: number;
minimumAuctionActionRequestResultReplayWindowMS: number;
newAuctionLifecycleId?: string;
processingOwnerToken: string;
}
export interface AuctionReserveActionRequestScriptInvocation {
keys: string[];
script: typeof AUCTION_RESERVE_ACTION_REQUEST_SCRIPT;
values: string[];
}
export function buildActionRequestPayloadFingerprint(params: {
auctionActionRequestId: string;
auctionActionType: string;
clientObservedAuctionLifecycleId: string;
clientObservedCurrentAuctionPlayerOrderIndex?: number;
clientObservedCurrentBidRoundPlayerUserId?: string;
clientObservedPhase: string;
clientObservedRevision: number;
}): string {
return [
params.clientObservedAuctionLifecycleId,
params.auctionActionRequestId,
params.auctionActionType,
params.clientObservedRevision,
params.clientObservedPhase,
params.clientObservedCurrentBidRoundPlayerUserId ?? '',
params.clientObservedCurrentAuctionPlayerOrderIndex ?? '',
].join('|');
}
export function buildAuctionReserveActionRequestScriptInvocation(
keys: AuctionRedisKeys,
input: AuctionReserveActionRequestScriptInput,
): AuctionReserveActionRequestScriptInvocation {
return {
keys: [keys.actionRequestResultsKey, keys.actionRequestResultOrderKey],
script: AUCTION_RESERVE_ACTION_REQUEST_SCRIPT,
values: [
input.clientObservedAuctionLifecycleId,
input.auctionActionRequestId,
input.auctionActionType,
input.auctionStateTransitionId,
input.newAuctionLifecycleId ?? '',
input.processingOwnerToken,
String(input.leaseDurationMS),
String(input.maximumStoredAuctionActionRequestResultCount),
String(input.minimumAuctionActionRequestResultReplayWindowMS),
buildActionRequestPayloadFingerprint(input),
],
};
}
export const AUCTION_RESERVE_ACTION_REQUEST_SCRIPT = defineAuctionRedisScript(
'auction.reserveActionRequest',
`
local auctionActionRequestResultsKey = KEYS[1]
local auctionActionRequestResultOrderKey = KEYS[2]
local clientObservedAuctionLifecycleId = ARGV[1]
local auctionActionRequestId = ARGV[2]
local auctionActionType = ARGV[3]
local auctionStateTransitionId = ARGV[4]
local newAuctionLifecycleId = ARGV[5]
local processingOwnerToken = ARGV[6]
local leaseDurationMS = tonumber(ARGV[7])
local maximumStoredAuctionActionRequestResultCount = tonumber(ARGV[8])
local minimumAuctionActionRequestResultReplayWindowMS = tonumber(ARGV[9])
local actionRequestPayloadFingerprint = ARGV[10]
local redisTime = redis.call('TIME')
local currentRedisTimestampMS = (tonumber(redisTime[1]) * 1000) + math.floor(tonumber(redisTime[2]) / 1000)
local actionRequestScopeKey = clientObservedAuctionLifecycleId .. ':' .. auctionActionRequestId
local function requestField(suffix)
return actionRequestScopeKey .. ':' .. suffix
end
local function hdelActionRequest(scopeKey)
redis.call(
'HDEL',
auctionActionRequestResultsKey,
scopeKey .. ':fingerprint',
scopeKey .. ':status',
scopeKey .. ':revision',
scopeKey .. ':rejectCode',
scopeKey .. ':auctionActionType',
scopeKey .. ':auctionStateTransitionId',
scopeKey .. ':newAuctionLifecycleId',
scopeKey .. ':processingOwnerToken',
scopeKey .. ':processingLeaseExpiresAtTimestampMS',
scopeKey .. ':processingLeaseVersion',
scopeKey .. ':responseServerTimestampMS',
scopeKey .. ':responseJson',
scopeKey .. ':requiresRefetch',
scopeKey .. ':createdAtTimestampMS'
)
end
local function trimOldActionRequestResults()
while redis.call('LLEN', auctionActionRequestResultOrderKey) >= maximumStoredAuctionActionRequestResultCount do
local oldestActionRequestScopeKey = redis.call('LINDEX', auctionActionRequestResultOrderKey, 0)
if not oldestActionRequestScopeKey then
return
end
local createdAtTimestampMS = tonumber(redis.call('HGET', auctionActionRequestResultsKey, oldestActionRequestScopeKey .. ':createdAtTimestampMS') or '0')
if createdAtTimestampMS > currentRedisTimestampMS - minimumAuctionActionRequestResultReplayWindowMS then
return
end
redis.call('LPOP', auctionActionRequestResultOrderKey)
hdelActionRequest(oldestActionRequestScopeKey)
end
end
local existingFingerprint = redis.call('HGET', auctionActionRequestResultsKey, requestField('fingerprint'))
if existingFingerprint then
if existingFingerprint ~= actionRequestPayloadFingerprint then
return {'REJECTED', 'DUPLICATE_ACTION_REQUEST_CONFLICT', actionRequestScopeKey, tostring(currentRedisTimestampMS)}
end
local status = redis.call('HGET', auctionActionRequestResultsKey, requestField('status')) or ''
if status == 'applied' or status == 'rejected' then
return {
'REPLAY',
status,
actionRequestScopeKey,
redis.call('HGET', auctionActionRequestResultsKey, requestField('revision')) or '',
redis.call('HGET', auctionActionRequestResultsKey, requestField('rejectCode')) or '',
redis.call('HGET', auctionActionRequestResultsKey, requestField('auctionStateTransitionId')) or '',
redis.call('HGET', auctionActionRequestResultsKey, requestField('newAuctionLifecycleId')) or '',
redis.call('HGET', auctionActionRequestResultsKey, requestField('processingLeaseVersion')) or '',
redis.call('HGET', auctionActionRequestResultsKey, requestField('responseServerTimestampMS')) or tostring(currentRedisTimestampMS),
redis.call('HGET', auctionActionRequestResultsKey, requestField('responseJson')) or '',
redis.call('HGET', auctionActionRequestResultsKey, requestField('requiresRefetch')) or ''
}
end
local leaseExpiresAtTimestampMS = tonumber(redis.call('HGET', auctionActionRequestResultsKey, requestField('processingLeaseExpiresAtTimestampMS')) or '0')
local storedOwnerToken = redis.call('HGET', auctionActionRequestResultsKey, requestField('processingOwnerToken')) or ''
local storedLeaseVersion = tonumber(redis.call('HGET', auctionActionRequestResultsKey, requestField('processingLeaseVersion')) or '1')
if leaseExpiresAtTimestampMS > currentRedisTimestampMS and storedOwnerToken ~= processingOwnerToken then
return {'REJECTED', 'ACTION_REQUEST_IN_PROGRESS', actionRequestScopeKey, tostring(currentRedisTimestampMS)}
end
local nextLeaseVersion = storedLeaseVersion
local wasLeaseExpired = '0'
if leaseExpiresAtTimestampMS <= currentRedisTimestampMS then
nextLeaseVersion = storedLeaseVersion + 1
wasLeaseExpired = '1'
end
redis.call(
'HSET',
auctionActionRequestResultsKey,
requestField('status'),
'processing',
requestField('processingOwnerToken'),
processingOwnerToken,
requestField('processingLeaseExpiresAtTimestampMS'),
tostring(currentRedisTimestampMS + leaseDurationMS),
requestField('processingLeaseVersion'),
tostring(nextLeaseVersion),
requestField('responseServerTimestampMS'),
tostring(currentRedisTimestampMS)
)
return {
'RESERVED',
actionRequestScopeKey,
redis.call('HGET', auctionActionRequestResultsKey, requestField('auctionStateTransitionId')) or auctionStateTransitionId,
redis.call('HGET', auctionActionRequestResultsKey, requestField('newAuctionLifecycleId')) or '',
tostring(nextLeaseVersion),
wasLeaseExpired,
tostring(currentRedisTimestampMS)
}
end
trimOldActionRequestResults()
if redis.call('LLEN', auctionActionRequestResultOrderKey) >= maximumStoredAuctionActionRequestResultCount then
return {'REJECTED', 'ACTION_REQUEST_RESULT_LIMIT', actionRequestScopeKey, tostring(currentRedisTimestampMS)}
end
redis.call(
'HSET',
auctionActionRequestResultsKey,
requestField('fingerprint'),
actionRequestPayloadFingerprint,
requestField('status'),
'processing',
requestField('auctionActionType'),
auctionActionType,
requestField('auctionStateTransitionId'),
auctionStateTransitionId,
requestField('newAuctionLifecycleId'),
newAuctionLifecycleId,
requestField('processingOwnerToken'),
processingOwnerToken,
requestField('processingLeaseExpiresAtTimestampMS'),
tostring(currentRedisTimestampMS + leaseDurationMS),
requestField('processingLeaseVersion'),
'1',
requestField('responseServerTimestampMS'),
tostring(currentRedisTimestampMS),
requestField('createdAtTimestampMS'),
tostring(currentRedisTimestampMS)
)
redis.call('RPUSH', auctionActionRequestResultOrderKey, actionRequestScopeKey)
return {
'RESERVED',
actionRequestScopeKey,
auctionStateTransitionId,
newAuctionLifecycleId,
'1',
'0',
tostring(currentRedisTimestampMS)
}
`,
);
@@ -0,0 +1,14 @@
import { createHash } from 'crypto';
import { defineAuctionRedisScript } from './auction-redis.scripts';
describe('auction redis scripts', () => {
it('stores normalized Lua and its SHA1', () => {
const script = defineAuctionRedisScript('test', 'return 1\n');
expect(script).toEqual({
lua: 'return 1\n',
name: 'test',
sha: createHash('sha1').update('return 1\n').digest('hex'),
});
});
});
@@ -0,0 +1,18 @@
import { createHash } from 'crypto';
export interface AuctionRedisScriptDefinition {
lua: string;
name: string;
sha: string;
}
export function defineAuctionRedisScript(
name: string,
lua: string,
): AuctionRedisScriptDefinition {
return {
lua,
name,
sha: createHash('sha1').update(lua).digest('hex'),
};
}
@@ -0,0 +1,64 @@
import {
AuctionRedisNoscriptError,
AuctionRedisService,
} from './auction-redis.service';
function makeService(sendCommand: jest.Mock) {
const client = {
destroy: jest.fn(),
quit: jest.fn().mockResolvedValue(undefined),
sendCommand,
};
return new AuctionRedisService(client as never);
}
describe('AuctionRedisService', () => {
it('uses Redis TIME as the timestamp source', async () => {
const service = makeService(jest.fn().mockResolvedValue(['1781700000', '123000']));
await expect(service.getCurrentRedisTimestampMS()).resolves.toBe(
1_781_700_000_123,
);
});
it('loads and retries a script once when EVALSHA returns NOSCRIPT', async () => {
const sendCommand = jest
.fn()
.mockRejectedValueOnce(new AuctionRedisNoscriptError())
.mockResolvedValueOnce('sha-from-redis')
.mockResolvedValueOnce(['ok']);
const service = makeService(sendCommand);
await expect(
service.evalShaWithReload({
keys: ['auction:state:1'],
script: 'return 1',
scriptSha: 'old-sha',
values: ['v1'],
}),
).resolves.toEqual(['ok']);
expect(sendCommand.mock.calls).toEqual([
[['EVALSHA', 'old-sha', '1', 'auction:state:1', 'v1']],
[['SCRIPT', 'LOAD', 'return 1']],
[['EVALSHA', 'sha-from-redis', '1', 'auction:state:1', 'v1']],
]);
});
it('does not reload scripts for non-NOSCRIPT errors', async () => {
const error = new Error('OOM command not allowed');
const sendCommand = jest.fn().mockRejectedValue(error);
const service = makeService(sendCommand);
await expect(
service.evalShaWithReload({
keys: [],
script: 'return 1',
scriptSha: 'sha',
values: [],
}),
).rejects.toBe(error);
expect(sendCommand).toHaveBeenCalledTimes(1);
});
});
@@ -0,0 +1,131 @@
import { Inject, Injectable, OnModuleDestroy } from '@nestjs/common';
import type { createClient } from 'redis';
import { AUCTION_REDIS_CLIENT } from './auction-redis.constants';
import type { AuctionRedisScriptDefinition } from './auction-redis.scripts';
export type AuctionRedisClient = ReturnType<typeof createClient>;
export interface EvalShaWithReloadParams {
keys: string[];
script: string;
scriptSha: string;
values: string[];
}
export class AuctionRedisNoscriptError extends Error {
constructor(message = 'NOSCRIPT No matching script. Please use EVAL.') {
super(message);
this.name = 'AuctionRedisNoscriptError';
}
}
function isNoscriptError(error: unknown): boolean {
if (error instanceof AuctionRedisNoscriptError) return true;
const message =
error instanceof Error ? error.message : typeof error === 'string' ? error : '';
return /\bNOSCRIPT\b/iu.test(message);
}
function buildEvalShaCommand(
scriptSha: string,
keys: string[],
values: string[],
): string[] {
return ['EVALSHA', scriptSha, String(keys.length), ...keys, ...values];
}
function parseRedisTimeReply(reply: unknown): number {
if (Array.isArray(reply) && reply.length >= 2) {
const seconds = Number(reply[0]);
const microseconds = Number(reply[1]);
if (Number.isFinite(seconds) && Number.isFinite(microseconds)) {
return seconds * 1000 + Math.floor(microseconds / 1000);
}
}
throw new Error(`Unexpected Redis TIME reply: ${JSON.stringify(reply)}`);
}
@Injectable()
export class AuctionRedisService implements OnModuleDestroy {
constructor(
@Inject(AUCTION_REDIS_CLIENT)
private readonly client: AuctionRedisClient,
) {}
async onModuleDestroy() {
try {
await this.client.quit();
} catch {
this.client.destroy();
}
}
public raw(): AuctionRedisClient {
return this.client;
}
public async getCurrentRedisTimestampMS(): Promise<number> {
const reply = await this.client.sendCommand(['TIME']);
return parseRedisTimeReply(reply);
}
public async evalShaWithReload<T = unknown>(
params: EvalShaWithReloadParams,
): Promise<T> {
try {
return (await this.client.sendCommand(
buildEvalShaCommand(params.scriptSha, params.keys, params.values),
)) as T;
} catch (error) {
if (!isNoscriptError(error)) throw error;
}
const loadedSha = String(
await this.client.sendCommand(['SCRIPT', 'LOAD', params.script]),
);
return (await this.client.sendCommand(
buildEvalShaCommand(loadedSha, params.keys, params.values),
)) as T;
}
public async evalScript<T = unknown>(
script: AuctionRedisScriptDefinition,
keys: string[],
values: string[],
): Promise<T> {
return this.evalShaWithReload<T>({
keys,
script: script.lua,
scriptSha: script.sha,
values,
});
}
public async acquireTokenLock(
key: string,
token: string,
ttlMS: number,
): Promise<boolean> {
const result = await this.client.sendCommand([
'SET',
key,
token,
'PX',
String(ttlMS),
'NX',
]);
return String(result) === 'OK';
}
public async releaseTokenLock(key: string, token: string): Promise<boolean> {
const result = await this.client.sendCommand([
'EVAL',
'if redis.call("GET", KEYS[1]) == ARGV[1] then return redis.call("DEL", KEYS[1]) else return 0 end',
'1',
key,
token,
]);
return Number(result) === 1;
}
}
@@ -0,0 +1,111 @@
import { buildAuctionRedisKeys } from './auction-redis.keys';
import {
AUCTION_HYDRATE_STATE_SCRIPT,
assembleAuctionViewFromRedisState,
buildHydrateAuctionStateScriptInvocation,
shouldHydrateRedisAuctionState,
} from './auction-redis.state';
describe('auction redis state assembly', () => {
it.each([
{
expected: true,
live: null,
mongo: { auctionLifecycleId: 'life-1', revision: 1 },
},
{
expected: true,
live: { auctionLifecycleId: 'life-1', revision: 1 },
mongo: { auctionLifecycleId: 'life-1', revision: 2 },
},
{
expected: true,
live: { auctionLifecycleId: 'old-life', revision: 2 },
mongo: { auctionLifecycleId: 'new-life', revision: 2 },
},
{
expected: false,
live: { auctionLifecycleId: 'redis-life', revision: 3 },
mongo: { auctionLifecycleId: 'mongo-life', revision: 2 },
},
])('decides rehydrate need: %#', ({ live, mongo, expected }) => {
expect(shouldHydrateRedisAuctionState({ live, mongo })).toBe(expected);
});
it('assembles public view and maps internal expiring phase to bidding', () => {
expect(
assembleAuctionViewFromRedisState({
auctionBidHistoryEntries: ['{"bidPointAmount":100}'],
currentServerTimestampMS: 1_000,
liveState: {
auctionLifecycleId: 'life-1',
currentBidRoundPlayerUserId: 'player-1',
phase: 'expiring',
revision: 3,
},
shouldForceAuctionStateResync: true,
structureState: {
auctionTeams: [],
},
}),
).toMatchObject({
auctionBidHistory: [{ bidPointAmount: 100 }],
auctionLifecycleId: 'life-1',
canPlaceBidInCurrentBidRound: false,
currentBidRoundPlayerUserId: 'player-1',
currentServerTimestampMS: 1000,
isAuctionStateTransitionInProgress: true,
phase: 'bidding',
revision: 3,
shouldForceAuctionStateResync: true,
});
});
it('builds HYDRATE invocation and keeps CAS conditions in Lua', () => {
const invocation = buildHydrateAuctionStateScriptInvocation(
buildAuctionRedisKeys('match-1'),
{
auctionHistorySequence: 4,
auctionLifecycleId: 'life-1',
liveStatePatch: {
'team:1:assignedAuctionTeamMemberCount': 1,
'team:1:remainingBidPointAmount': 1000,
},
maximumBidRoundDurationSeconds: 30,
matchId: 'match-1',
phase: 'bidding',
revision: 7,
structureStateJson: '{"auctionTeams":[]}',
},
);
expect(invocation.script).toBe(AUCTION_HYDRATE_STATE_SCRIPT);
expect(invocation.keys).toEqual([
'auction:match-1:liveAuctionState',
'auction:match-1:auctionStructureState',
'auction:bidRoundDeadlineQueue',
]);
expect(invocation.values).toEqual([
'match-1',
'life-1',
'7',
'bidding',
'4',
'30',
'{"auctionTeams":[]}',
'2',
'team:1:assignedAuctionTeamMemberCount',
'1',
'team:1:remainingBidPointAmount',
'1000',
]);
expect(AUCTION_HYDRATE_STATE_SCRIPT.lua).toContain("redis.call('TIME')");
expect(AUCTION_HYDRATE_STATE_SCRIPT.lua).toContain(
'INVALID_PATCH_ARITY',
);
expect(AUCTION_HYDRATE_STATE_SCRIPT.lua).toContain(
'mongoRevision > redisRevision',
);
expect(AUCTION_HYDRATE_STATE_SCRIPT.lua).toContain("redis.call('ZADD'");
});
});
@@ -0,0 +1,188 @@
import type { AuctionRedisKeys } from './auction-redis.keys';
import { defineAuctionRedisScript } from './auction-redis.scripts';
export interface AuctionRedisRevisionIdentity {
auctionLifecycleId?: string;
revision?: number;
}
export interface ShouldHydrateRedisAuctionStateParams {
live: AuctionRedisRevisionIdentity | null;
mongo: Required<AuctionRedisRevisionIdentity>;
}
export interface AssembleAuctionViewParams {
auctionBidHistoryEntries: string[];
currentServerTimestampMS: number;
liveState: Record<string, unknown> & {
auctionLifecycleId: string;
phase: string;
revision: number;
};
shouldForceAuctionStateResync?: boolean;
structureState: Record<string, unknown>;
}
export interface HydrateAuctionStateScriptInput {
auctionHistorySequence: number;
auctionLifecycleId: string;
liveStatePatch?: Record<string, string | number | boolean | null | undefined>;
maximumBidRoundDurationSeconds: number;
matchId: string;
phase: string;
revision: number;
structureStateJson: string;
}
export interface HydrateAuctionStateScriptInvocation {
keys: string[];
script: typeof AUCTION_HYDRATE_STATE_SCRIPT;
values: string[];
}
function stringifyRedisValue(value: string | number | boolean | null): string {
if (typeof value === 'boolean') return value ? '1' : '0';
if (value === null) return '';
return String(value);
}
function flattenLiveStatePatch(
liveStatePatch: HydrateAuctionStateScriptInput['liveStatePatch'],
): string[] {
return Object.entries(liveStatePatch ?? {})
.filter(([, value]) => value !== undefined)
.sort(([a], [b]) => a.localeCompare(b))
.flatMap(([key, value]) => [
key,
stringifyRedisValue(value as string | number | boolean | null),
]);
}
export function shouldHydrateRedisAuctionState(
params: ShouldHydrateRedisAuctionStateParams,
): boolean {
if (!params.live) return true;
const redisRevision = params.live.revision ?? -1;
const mongoRevision = params.mongo.revision;
if (mongoRevision > redisRevision) return true;
return (
mongoRevision === redisRevision &&
params.mongo.auctionLifecycleId !== params.live.auctionLifecycleId
);
}
export function assembleAuctionViewFromRedisState(
params: AssembleAuctionViewParams,
): Record<string, unknown> {
const isExpiring = params.liveState.phase === 'expiring';
return {
...params.structureState,
...params.liveState,
auctionBidHistory: params.auctionBidHistoryEntries.map((entry) =>
JSON.parse(entry),
),
canPlaceBidInCurrentBidRound: !isExpiring,
currentServerTimestampMS: params.currentServerTimestampMS,
isAuctionStateTransitionInProgress: isExpiring,
phase: isExpiring ? 'bidding' : params.liveState.phase,
shouldForceAuctionStateResync:
params.shouldForceAuctionStateResync || undefined,
};
}
export function buildHydrateAuctionStateScriptInvocation(
keys: AuctionRedisKeys,
input: HydrateAuctionStateScriptInput,
): HydrateAuctionStateScriptInvocation {
const liveStatePatchPairs = flattenLiveStatePatch(input.liveStatePatch);
return {
keys: [keys.liveStateKey, keys.structureStateKey, keys.deadlineQueueKey],
script: AUCTION_HYDRATE_STATE_SCRIPT,
values: [
input.matchId,
input.auctionLifecycleId,
String(input.revision),
input.phase,
String(input.auctionHistorySequence),
String(input.maximumBidRoundDurationSeconds),
input.structureStateJson,
String(liveStatePatchPairs.length / 2),
...liveStatePatchPairs,
],
};
}
export const AUCTION_HYDRATE_STATE_SCRIPT = defineAuctionRedisScript(
'auction.hydrateState',
`
local liveAuctionStateKey = KEYS[1]
local auctionStructureStateKey = KEYS[2]
local bidRoundDeadlineQueueKey = KEYS[3]
local matchId = ARGV[1]
local mongoAuctionLifecycleId = ARGV[2]
local mongoRevision = tonumber(ARGV[3])
local phase = ARGV[4]
local auctionHistorySequence = ARGV[5]
local maximumBidRoundDurationSeconds = tonumber(ARGV[6])
local structureStateJson = ARGV[7]
local liveStatePatchPairCount = tonumber(ARGV[8])
local redisTime = redis.call('TIME')
local currentRedisTimestampMS = (tonumber(redisTime[1]) * 1000) + math.floor(tonumber(redisTime[2]) / 1000)
local redisRevision = tonumber(redis.call('HGET', liveAuctionStateKey, 'revision') or '-1')
local redisAuctionLifecycleId = redis.call('HGET', liveAuctionStateKey, 'auctionLifecycleId')
if not liveStatePatchPairCount or #ARGV ~= 8 + (liveStatePatchPairCount * 2) then
return {'REJECTED', 'INVALID_PATCH_ARITY', tostring(currentRedisTimestampMS)}
end
local shouldHydrate = false
if redisRevision < 0 then
shouldHydrate = true
elseif mongoRevision > redisRevision then
shouldHydrate = true
elseif mongoRevision == redisRevision and mongoAuctionLifecycleId ~= redisAuctionLifecycleId then
shouldHydrate = true
end
if not shouldHydrate then
return {'NOOP', tostring(redisRevision), tostring(currentRedisTimestampMS)}
end
local hydratedRevision = mongoRevision + 1
redis.call('SET', auctionStructureStateKey, structureStateJson)
local hsetArgs = {
liveAuctionStateKey,
'auctionLifecycleId',
mongoAuctionLifecycleId,
'revision',
tostring(hydratedRevision),
'phase',
phase,
'currentAuctionHistorySequence',
auctionHistorySequence,
'currentHighestBidPointAmount',
'0',
'currentHighestBidderTeamIndex',
'-1'
}
local patchIndex = 9
for i = 1, liveStatePatchPairCount do
table.insert(hsetArgs, ARGV[patchIndex])
table.insert(hsetArgs, ARGV[patchIndex + 1])
patchIndex = patchIndex + 2
end
redis.call('HSET', unpack(hsetArgs))
if phase == 'bidding' then
local currentBidRoundDeadlineTimestampMS = currentRedisTimestampMS + (maximumBidRoundDurationSeconds * 1000)
redis.call('HSET', liveAuctionStateKey, 'currentBidRoundDeadlineTimestampMS', tostring(currentBidRoundDeadlineTimestampMS))
redis.call('ZADD', bidRoundDeadlineQueueKey, currentBidRoundDeadlineTimestampMS, matchId)
else
redis.call('ZREM', bidRoundDeadlineQueueKey, matchId)
end
return {'OK', tostring(hydratedRevision), tostring(currentRedisTimestampMS)}
`,
);