PROGRAMMING PROJECT · DEFERRED
Scalable coordination for classroom demos
Design a designated demo coordinator that can absorb high-volume classroom sessions without changing how ordinary TaraSec nodes report incidents.
When this project is needed
The current Demo 2 design can remain in place. Start this project only if measured demo traffic, status polling or evidence correlation becomes a meaningful load on operational database servers.
TaraSec can configure up to three database servers. One of them may be explicitly designated as the demo coordinator; it must not be assumed to be “server 3”.
Core principle
Node A, Node B and the standard gateway remain demo-unaware. Node B reports every observed incident through the normal reporting path to all configured database servers. The gateway uses the normal confession path to identify the true unit behind NAT.
Only the designated coordinator knows that a registered session is a demo and correlates its ordinary evidence.
Required data flow
- The app registers a demo session with the configured coordinator and receives an opaque session key.
- The app uses that same coordinator and key for all later status calls. A session must not move between coordinators.
- Node B reports the incident normally, including the observed gateway address and translated source port, to all configured database servers.
- The standard gateway matches the translated port against local conntrack/unit-port state and confesses the responsible unit through the existing protocol.
- The coordinator correlates Node A evidence, Node B evidence and the confession with the active demo session.
- After the full sequence is validated, the coordinator may send an authenticated demo-clearance message to peer database servers so replicated demo evidence can be cleared centrally.
Programming scope
- Add explicit coordinator configuration and health/fail-safe behavior.
- Implement durable session registration, opaque keys, expiry and idempotent status reads.
- Build correlation using source address, translated port, destination and time window without special Node B behavior.
- Design authenticated, replay-resistant clearance between database servers.
- Add metrics for request rate, queue depth, correlation latency, database load and rejected clearances.
- Create concurrent classroom load tests and failure tests.
Safety constraints
- Never classify traffic as a demo merely because it reaches a demo node.
- Never clear unrelated, older or independently confirmed infection evidence.
- Clearance must reference a validated session and the exact correlated evidence/unit.
- Session keys must not appear in logs and must be stored hashed where practical.
- If the coordinator is unavailable, ordinary reporting and confession must continue.
- Do not silently fail over an active app session to a server that lacks its state.
Deliverables
- A short architecture decision record comparing the current design with a dedicated coordinator.
- A protocol and database schema for session correlation and peer clearance.
- A working implementation behind a feature flag, with migration and rollback instructions.
- Automated unit, integration, replay, concurrency and overload tests.
- An operations dashboard or report that proves whether the coordinator reduces load on normal database servers.
- Documentation explaining why nodes and gateways remain demo-unaware.
Acceptance criteria
A classroom-sized concurrent test must complete without losing ordinary incident reports. Each valid demo is attributed to the correct unit through report plus confession. Repeated events are idempotent. Invalid, expired or replayed keys and clearance messages are rejected. Real evidence cannot be cleared by a demo session, and ordinary TaraSec protection continues when the coordinator is stopped.
Non-goal: this project must not introduce demo-specific credentials, branches or reporting rules into Node B or the standard gateway.
Suggested background
Backend programming, SQL transactions and indexing, authenticated APIs, distributed-system failure modes, Linux networking, NAT/conntrack and performance testing.