GeezerVison

Summary

Adds native multi-host support to RedisSentinel via a new hosts constructor option, eliminating the need for userland workarounds such as namoshek/laravel-redis-sentinel for the Sentinel discovery portion of the problem.

Partially addresses #2819. Related prior discussion: #2132.

API

$sentinel = new RedisSentinel([
    'hosts' => [
        ['host' => '10.0.0.1', 'port' => 26379],
        ['host' => '10.0.0.2', 'port' => 26379],
        ['host' => '10.0.0.3', 'port' => 26379],
    ],
    'connectTimeout' => 0.1,
    'auth' => 'secret',
]);

// Auto-falls-back to the next Sentinel on network failure.
$master = $sentinel->getMasterAddrByName('mymaster');

Semantics

• Zero BC risk. When hosts is not provided, RedisSentinel behaves exactly as before.
• Sticky connection. First reachable host is used for all subsequent calls. current_host_idx advances only on failure.
• One command-level retry per call. Inside sentinel_try_next_host, a bounded linear scan iterates remaining hosts; at most one command re-execution.
• Skipped hosts stay skipped for the instance lifetime.
• Network error detection inspects RedisSock state (status, stream) — no exception message parsing.
• Validation errors (empty hosts, missing host, wrong types, >1024 entries) throw RedisException, consistent with the rest of phpredis.
• Exhaustion throws RedisException mentioning the host count and last attempted endpoint.

Not in this PR (deferred)

To keep scope reviewable, the following are deferred to a follow-up:

• Auto-reconnect of Redis (not RedisSentinel) connections on master failover
• Configurable retry policy (retryAttempts, retryDelay)
• Command-level retry on the Redis class driven by Sentinel re-query

The supporting infrastructure introduced here (RedisSock->sentinel_hosts, sentinel_try_next_host) is reusable for that follow-up.

Implementation notes

• Host list is stored on RedisSock as three new fields (sentinel_hosts, sentinel_hosts_count, sentinel_current_host_idx). sentinel_host_entry is forward-declared in common.h with the full struct in sentinel_library.h. This avoids touching shared layout in redis_object / Redis / RedisCluster.
• All 11 RedisSentinel methods wrap their REDIS_PROCESS_KW_CMD call in a SENTINEL_METHOD macro that implements the retry. No-op when hosts == NULL (single-host usage is identical to today).
• Exception handling is careful to clear EG(exception) between per-host connection attempts so a failing intermediate host does not leak state into a successful retry.
• Built and tested against PHP 8.1–8.4; follows the existing REDIS_THROW_EXCEPTION / zend_throw_exception_ex(redis_exception_ce, …) convention rather than zend_value_error / zend_type_error (which are PHP 8+ only).

Testing

• 17 integration tests in tests/RedisSentinelMultiHostTest.php (covers construction, fallback, validation, sticky behavior, bounded retries, DoS guard).
• Docker-compose cluster in tests/sentinel-multihost/ (1 master + 2 replicas + 3 Sentinels). See the README.md in that directory for local usage.
• New CI job sentinel-multihost in .github/workflows/ci.yml runs the integration tests across PHP 8.1–8.4.
• Tests mark themselves skipped when the Sentinel env is unreachable, so existing local runs are unaffected.
• Valgrind verified: zero new leaks across 200 iterations × all paths (baseline leak count unchanged).

Open questions

Happy to adjust any of these based on maintainer preference:

1. Option naming — hosts as a top-level option vs. allowing host to accept string|array. I went with a separate option to avoid type ambiguity for static analyzers; the alternative is a few-line change if preferred.
2. Retry configurability — currently "exhaust remaining list, at most one retry per command call". Should retryAttempts / retryDelay be added in this PR, or is that more appropriate for the Phase 2 follow-up?
3. Host rehydration — skipped hosts are permanently skipped for the instance lifetime. Periodic revisit (or reset-on-demand) could be added if real usage shows demand.
4. Phase 2 shape — should Redis auto-reconnect via Sentinel live on the existing Redis class or in a new wrapper (e.g. RedisSentinelPool)? Not in scope here, but worth flagging early for discussion.

Opened as Draft to invite design discussion before marking ready for review.