comunidadhll/ai/tasks/pending/TASK-158-current-match-realtime-transport.md

id, title, status, type, team, supporting_teams, roadmap_item, priority

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-158	Current match realtime transport	pending	backend	Backend Senior	Frontend Senior	foundation	high

TASK-158 - Current match realtime transport

Goal

Implement a real-time or near-real-time update strategy for the current-match page, prioritizing the kill feed and then current match metadata/player stats.

Background

The current-match page currently refreshes through polling. In frontend/assets/js/partida-actual.js, the current interval is:

CURRENT_MATCH_POLL_INTERVAL_MS = 30 * 1000

The user explicitly rejected this behavior:

• "He dicho que se actualice en vivo y no cada 20 segundos"

The page should behave much closer to real time, especially for the kill feed. A 20/30-second refresh is too slow for a live combat screen.

Current endpoints:

• GET /api/current-match?server=...
• GET /api/current-match/kills?server=...
• GET /api/current-match/players?server=...

Files to Read First

• AGENTS.md
• ai/repo-context.md
• ai/architecture-index.md
• frontend/assets/js/partida-actual.js
• backend/app/routes.py
• backend/app/rcon_admin_log_storage.py

Inspect the current frontend refresh flow, current-match route payloads, kill feed read model, trusted server validation, and recent AdminLog materialization cadence before changing code.

Expected Files to Modify

Allowed changes:

• backend/app/routes.py
• backend/app/payloads.py
• backend/app/rcon_admin_log_storage.py
• backend helper/read-model files if needed
• frontend/assets/js/partida-actual.js
• frontend/partida-actual.html if needed
• focused tests

Constraints - DO NOT BREAK

• Do not query RCON directly from the frontend.
• Do not expose raw AdminLog lines.
• Do not fabricate events.
• Do not show stale kills as live kills.
• Do not depend on server #03.
• Do not break existing REST endpoints.
• Do not break historical pages or historical match detail pages.
• Keep trusted server validation.
• Keep current public scoreboard URLs without /games.
• Avoid overloading the backend/RCON/AdminLog pipeline.
• Commit and push after implementation.

Implementation Requirements

1. RCA first

• Document current update flow in TASK done notes.
• Confirm which parts are safe to update at high frequency:
  • kill feed
  • player stats
  • match metadata/scoreboard
• Identify whether the backend has access to sufficiently fresh AdminLog data without calling RCON per browser poll.

2. Preferred transport

Evaluate and implement the safest available option:

• Server-Sent Events (SSE) endpoint for live kill events, OR
• short polling for killfeed every 1-2 seconds with ETag/since cursor/last_event_id, OR
• another minimal transport that gives near-real-time updates without duplicating events.

Prefer SSE if it is simple and safe in the current backend stack.

If SSE is not appropriate, implement short polling with cursor semantics.

3. Kill feed endpoint behavior

Add support for incremental fetching:

• since_event_id or since timestamp/server_time
• limit
• server slug
• trusted server validation

The endpoint must return only new events where possible.

4. Frontend behavior

• Remove dependency on a 20/30-second interval for kill feed updates.
• Kill feed should update in near-real-time.
• Avoid overlapping requests.
• Preserve event_id deduplication.
• Do not re-render the whole panel if no new events arrived.
• Keep a capped event buffer.

5. Match metadata and player stats

• These do not need to update every second.
• Keep a slower safe refresh for scoreboard/player stats if needed, for example 10-30 seconds.
• The kill feed must be faster than metadata refresh.

6. Failure/reconnect

• If SSE is used, implement reconnect behavior.
• If short polling is used, handle transient errors without breaking the page.
• Show a small stale/error state only when needed.

7. Backend load

• Do not query expensive RCON calls per browser every second.
• Prefer reading already persisted/recent AdminLog materialized data.
• If a live AdminLog ingestion cadence is insufficient, document it instead of hiding the limitation.

Validation

Run:

• python -m compileall backend/app
• focused backend tests if added/updated
• node --check frontend/assets/js/partida-actual.js
• git diff --check

Before completing the task also confirm that git diff --name-only matches the expected scope.

Manual Verification Steps

• Rebuild backend and frontend.
• Open http://localhost:8080/partida-actual.html?server=comunidad-hispana-01.
• Open http://localhost:8080/partida-actual.html?server=comunidad-hispana-02.
• During an active match, verify new kill events appear without waiting 20/30 seconds.
• Verify repeated updates do not duplicate events.
• Verify no raw AdminLog lines appear.
• Verify stale events are not displayed as live.
• Verify metadata/scoreboard remains stable and does not flicker.
• Verify backend logs do not show excessive RCON/API pressure.

Expected Outcome

The current-match kill feed updates in near-real-time, without depending on the existing 30-second page refresh cycle.

Outcome

Document the RCA, transport decision, validation performed, load/freshness limitations, and any follow-up task that should be created instead of expanding this task.

Change Budget

• Prefer fewer than 5 modified files.
• Prefer changes under 200 lines when feasible.
• Split the work into follow-up tasks if limits are exceeded.