Poll-Based Projector System #237

New issue

Closed

opened 2025-12-28 19:56:33 -08:00 by jwilger · 1 comment

jwilger commented

2025-12-28 19:56:33 -08:00

(Migrated from github.com)

Implements the poll-based projector system per ARCHITECTURE.md v2.7.

Overview

This epic covers the complete projector infrastructure for EventCore:

Poll-based event consumption - Projectors control when to fetch events, apply them transactionally, and checkpoint atomically
Checkpoint persistence - Subscriptions table tracks (subscription_name, last_position, updated_at) for resumable projections
Distributed coordination - PostgreSQL session-scoped advisory locks on dedicated connections (NOT pooled)
Contract test suite - Verify backend implementations conform to expected behavior

Coordination Model

Subscriptions Table → WHERE did we process up to?
Advisory Lock → WHO is processing right now?
Dedicated Connection → Connection lifetime = lock lifetime

When a projector process crashes or exits, the connection closes and the lock releases automatically.

Acceptance Criteria

Projectors can poll events and checkpoint progress
Checkpoint store persists position atomically
ProjectorCoordinator trait with try_acquire() (#239)
Contract tests verify coordination semantics (#239)
run_projection(projector, &backend) free function (#258)
Backends implement EventReader + CheckpointStore + ProjectorCoordinator (#258)
Leadership acquired at start, held for duration (#258)
Integration test verifies coordination behavior (#258)

Implements the poll-based projector system per ARCHITECTURE.md v2.7. ### Overview This epic covers the complete projector infrastructure for EventCore: - **Poll-based event consumption** - Projectors control when to fetch events, apply them transactionally, and checkpoint atomically - **Checkpoint persistence** - Subscriptions table tracks `(subscription_name, last_position, updated_at)` for resumable projections - **Distributed coordination** - PostgreSQL session-scoped advisory locks on dedicated connections (NOT pooled) - **Contract test suite** - Verify backend implementations conform to expected behavior ### Coordination Model ``` Subscriptions Table → WHERE did we process up to? Advisory Lock → WHO is processing right now? Dedicated Connection → Connection lifetime = lock lifetime ``` When a projector process crashes or exits, the connection closes and the lock releases automatically. ### Acceptance Criteria - [x] Projectors can poll events and checkpoint progress - [x] Checkpoint store persists position atomically - [x] `ProjectorCoordinator` trait with `try_acquire()` (#239) - [x] Contract tests verify coordination semantics (#239) - [x] `run_projection(projector, &backend)` free function (#258) - [x] Backends implement `EventReader + CheckpointStore + ProjectorCoordinator` (#258) - [x] Leadership acquired at start, held for duration (#258) - [x] Integration test verifies coordination behavior (#258)

jwilger commented

2026-01-01 08:14:32 -08:00

(Migrated from github.com)

Closed prematurely.