Event Subscription Design Specification - `gameEvents`

This document provides a detailed architectural overview of the gameEvents event subscription within the leaderboard service. It covers the subscription’s transport configuration, topic definitions, authorization model, and payload transformations.

Subscription Overview

Description: Subscribes to gameplay events so the leaderboard can update ELO ratings, player stats, and rankings when games are completed.

Transport: websocket Clients connect via Socket.IO at namespace /events/gameEvents for long-lived bidirectional subscriptions. Ideal for dashboards, live tickers, and collaborative interfaces.
Namespace: /events/gameEvents

Topics

This subscription exposes 1 Kafka topic to connected clients:

`gameCompleted`

Fires when a chess game is updated (status changes to completed/terminated). Used to trigger ELO recalculation and leaderboard rank updates for both players.

Kafka Topic: wechess-gameplay-service-game-updated
DataObject: playerStats
Access Level: Inherited from DataObject configuration

Excluded Fields

The following fields are stripped from the payload before sending to clients: invitationCode

Authorization

The subscription uses a layered authorization model that controls which users can connect and which topics they receive:

Absolute Roles

Users with roles administrator bypass all authorization checks and receive all topics without filtering.

Event Filter Script

Evaluated for each incoming Kafka event before delivery. Returns false to skip the event for the user:

data.result != null && (data.status == 'completed' || data.status == 'terminated')

Context variables: session, topicName, dataObjectName, data

Client Integration

WebSocket Connection (Socket.IO)

import { io } from 'socket.io-client';

const socket = io('/events/gameEvents', {
  auth: { token: 'your-jwt-token' }
});

// Subscribe to specific topics
socket.on('gameCompleted', (data) => {
  console.log('gameCompleted event:', data);
});


socket.on('connect', () => console.log('Connected to gameEvents'));
socket.on('disconnect', () => console.log('Disconnected from gameEvents'));

This document was generated from the event subscription configuration and should be kept in sync with design changes.

Event Subscription Design Specification - gameEvents