Repository navigation
Add opt-in LISTEN/NOTIFY long polling - #41
Conversation
There was a problem hiding this comment.
🔵 Needs a closer look
Unresolved wakeup gaps and schema-wide listener recovery require fixes and PostgreSQL-backed human validation.
2 open issues
What changed in this PR
Adds opt-in notification-driven long polling to the PostgreSQL provider while preserving short polling by default.
Changes:
- Adds listener recovery, bounded timer tracking, and long-poll configuration.
- Installs disabled notification triggers with explicit schema-wide activation.
- Adds integration coverage, CI validation, and operational documentation.
| File | Description |
|---|---|
| tests/postgres_provider_test.rs | Enables validation in either polling mode. |
| tests/long_poll_tests.rs | Adds integration tests and an idle-query benchmark. |
| src/provider.rs | Integrates configuration and long-poll fetches. |
| src/notifier.rs | Implements listeners, timers, recovery, and waiting. |
| src/migrations.rs | Adds notification activation and verification. |
| src/lib.rs | Exports and documents long-poll configuration. |
| README.md | Documents usage and operational limitations. |
| migrations/README.md | Documents activation and test commands. |
| migrations/0027_diff.md | Records migration changes. |
| migrations/0027_add_long_poll_notifications.sql | Installs disabled triggers and updates cleanup. |
| docs/migration-policy.md | Explains activation and compatibility. |
| CHANGELOG.md | Records the unreleased feature. |
| Cargo.toml | Raises the SQLx minimum to 0.8.3. |
| .github/workflows/test.yml | Runs validation with long polling enabled. |
Review effort: Balanced
52557ef to
e2fba14
Compare
e2fba14 to
60a2bb9
Compare
Match #51's associated load_migrations and parse_version functions, including the failed-unlock regression added by #41. This keeps the standalone branch buildable and avoids E0599 when the prerequisite changes are combined. Retain b33a3f2's connection-reuse behavior without changing pool sizing or tuning for the upstream barrier-based test. Addresses review item 41-N11. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Todd J. Green (tjgreen42)
left a comment
There was a problem hiding this comment.
Review by GPT-6.1 Sol.
No actionable findings in this revision. Reviewed listener startup/reconnection, wakeup registration and deferred-work deadlines, schema-wide trigger activation, polling fallback, shutdown, and migration compatibility. The earlier lost-wakeup/recovery concerns are addressed. The documented SQLx limitation around unbounded graceful pool.close() on a wedged listener is not a hang in provider/runtime drop, which aborts the listener without awaiting cleanup.
Scope: static review at 20dffa7, including the relevant SQLx cleanup behavior. No local PostgreSQL integration tests were run; local nextest compilation was blocked by the available Rust 1.88 toolchain versus a resolved dependency requiring Rust 1.89.
|
GPT-6.1 Sol: Please refresh the PR description to match the current branch. It still says the PR is a draft, but it is marked ready for review. Please also mention the later hardening: lease-expiry hints; read-only timer scans with 200 ms server-side timeouts; single-flight scans retained across watchdog wakeups and reconnects; and fresh catch-up scans of both queues after reconnect. The operational warning should explicitly include notification costs for successful claims, lease-changing renewals, and session-lease writes. The migration 0030 and prerequisite release-order notes still appear current. |
|
Thom Chiovoloni (@thomcc-work) Are we planning to add the capability to migrate from a pre-existing |
Todd J. Green (tjgreen42)
left a comment
There was a problem hiding this comment.
This looks good, strictly an improvement on duroxide-pg-opt in several respects. Nice job. What's left before we can turn it on by default? (Stress-testing to make sure notifications don't get out of hand under high load?)
Short polling leaves workers idle between fetches. Use notifications and bounded visibility timers as wake-up hints, and keep the existing queue predicates and locks authoritative. If the listener or a timer scan stalls, polling can still recover ready work. Install disabled triggers in migration 0030, after the pruning and worker-ordering migrations. Activate them only on explicit request. Run the existing provider validations against both polling modes without registering the runtime checks twice. Source-Commit: 9c80e42 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
9c80e42 to
e294b2f
Compare

Summary
Adds opt-in PostgreSQL LISTEN/NOTIFY long polling for orchestration and activity work, adapted from
duroxide-pg-opt. The goal is to reduce empty-queue queries and polling-induced latency while preserving existing queue eligibility, locking, and acknowledgment rules. Existing constructors continue to use short polling by default.The same configuration is supported for Entra-authenticated connections. SQLx 0.8.3 or later is required for explicit listener reconnect handling; native-TLS configuration is unchanged.
The provider and its stress harness use the published Duroxide 0.2.0 dependency. Applications that depend directly on
duroxideshould use the 0.2 series with this provider.Waiting and recovery
READ ONLYtransactions with 200 ms server-side lock and statement timeouts. Server-cancelled scans roll back and return their connections to the pool instead of accumulating blocked backends.Notifications remain hints: database predicates and locks determine whether work can actually be claimed.
Migration and activation
Landing order: #32, then #51, then #41. This top layer adds
0030after the timestamp/pruning migrations (0027and0028) and the worker-progress migration (0029). Deploy the ordered sequence together; a ledger that skips a predecessor is rejected. Follow #32's fully drained upgrade when coming from before0027.The lower layers supply the Duroxide 0.2.0 bump, duplicate-acknowledgement validation, and deferred-worker ordering. This layer exercises the same validations with long polling enabled; it does not duplicate their registrations.
Migration
0030installs six disabled notification triggers covering both queues and session leases. Notifications are activated schema-wide only by construction with bothMigrationPolicy::ApplyAlland long polling enabled.VerifyOnlyperforms no DDL and requires prior activation. Disabling an individual provider’s listener does not disable shared triggers.Migration and activation transactions use 250 ms lock timeouts and jittered retries for deadlocks and lock contention, with a ten-second retry budget. Failed attempts roll back without advancing the ledger. Migration errors retain the database message and SQLSTATE source. Connections are preserved for reuse only after successful migration and confirmed advisory-lock release; errors and cancellation close them.
The cleanup function preserves migration
0028’s batched-pruning cleanup. Disposable databases that ran an earlier draft of this PR as migration0027must be recreated. Older binaries still reject unknown migration versions even when notifications are disabled. This does not convert databases using the incompatibleduroxide-pg-optmigration history.Operational considerations
PREPARE TRANSACTION. Activated queue and session-lease writes are therefore incompatible with PostgreSQL two-phase commit.Validation
The provider suite runs with short and long polling. It now uses the released lock-expiration test from microsoft/duroxide#76: the checks start at the first successful claim, not at a task-start barrier. No lease duration or expiry margin was changed. The new duplicate-ack validation checks that retrying an already-committed activity acknowledgment fails permanently, with exactly one completion queued and the worker item removed.
With migrations
0027through0030together, the deferred-worker validation exercises session and non-session work in both polling modes. The shared validation factory cleans up every schema it creates.