feat: Redis-backed payment cursor with distributed lock and Horizon rate-limit backoff

[nonsobethel0-dev]

Closes #7

What changed

• RedisService / RedisModule (src/redis/) — global ioredis connection with exponential reconnect strategy and graceful shutdown
• PaymentCursorService (src/payments/payment-cursor.service.ts) — durable cursor persistence using a Lua CAS script (no double-flush races), a 50-entry checkpoint log for safe rollback on restart, and a SET-NX-EX distributed lock so only one pod polls Horizon at a time
• PaymentDetectorService — injected PaymentCursorService; cursor flushed to Redis every PERSIST_EVERY=10 operations; distributed lock renewed each poll cycle; 429 and 5xx HTTP errors trigger separate backoff intervals and durations; rateLimitRemaining < 10 triggers the 429 backoff path preemptively
• StellarService — added getPaymentsPage() returning Horizon rate-limit headers alongside records, and getHttpStatusFromError() for clean AxiosError unwrapping
• payments.module.ts — registers PaymentCursorService as a provider
• app.module.ts — imports RedisModule (marked @Global(), available app-wide)
• package.json — adds ioredis@^5.3.2 (runtime) and ioredis-mock@^8.9.0 (test)
• .env.example — documents REDIS_URL and PLATFORM_RECEIVING_ACCOUNT

Why

The old detector kept the cursor in memory only — a pod restart or crash silently skipped all payments processed since the last in-memory cursor update. Under horizontal scaling, multiple pods also raced against the same Horizon account stream. This change makes the cursor durable and the poller single-leader.

How to test

• Start Redis locally (docker run -p 6379:6379 redis:alpine)
• Set REDIS_URL=redis://localhost:6379 and PLATFORM_RECEIVING_ACCOUNT=<testnet address> in .env
• Run npm install then npm run dev — look for Redis connected and Restored cursor log lines
• Kill and restart the server — confirm the cursor resumes from the last persisted token, not from now
• Run the unit tests: npm test -- payment-cursor.spec — all 18 cases should pass via ioredis-mock

[oomokaro1]

Hi @nonsobethel0-dev! The implementation looks solid — nice work on the CAS cursor, checkpoint rollback, and distributed lock. CI is failing because npm ci can't find the new dependencies in the lock file.

Fix: Run this locally and commit the updated lock file:

npm install
git add package-lock.json
git commit -m "chore: update package-lock.json for ioredis dependencies"
git push

The package.json adds ioredis, ioredis-mock, and their types, but package-lock.json wasn't included in the commit. npm ci requires them to be in sync.

[oomokaro1]

Hi @nonsobethel0-dev! The implementation is solid — cursor persistence, distributed lock, Lua CAS, checkpoint rollback, and backoff logic all look correct and match the issue requirements.

CI blocker: package-lock.json is out of sync. Fix:

npm install
git add package-lock.json
git commit -m "chore: update package-lock.json for ioredis dependencies"
git push

Missing test scenarios (the issue explicitly asks for these):

1. Rate limit handling test — simulate a 429 response from Horizon and verify the backoff kicks in (poll interval changes to 10s, resets after 1 minute)

2. Crash recovery simulation — simulate a crash mid-processing (e.g. process 3 ops, then stop), restart, and verify the cursor rolls back to the last checkpoint

3. Integration test — a full flow: store cursor → process payments → persist → restart → verify cursor restores correctly from Redis

These are listed in the issue under "Testing" requirements. The current 18 unit tests cover the service methods well, but the issue specifically calls out these scenarios.

[nonsobethel0-dev]

Fixed the CI failure — npm ci was erroring because ioredis, ioredis-mock, and their transitive deps were added to package.json but package-lock.json was never updated alongside them. Regenerated the lock file and pushed. CI should be green now.

[oomokaro1]

LGTM. All previous feedback addressed — lock file included, crash recovery and backoff tests added, integration tests cover persist-and-restore cycles. One minor note: @types/ioredis is unnecessary since ioredis v5 ships its own types, but it won't break anything.