Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 144
0.00% covered (danger)
0.00%
0 / 12
CRAP
0.00% covered (danger)
0.00%
0 / 1
RedisConnectionPool
0.00% covered (danger)
0.00%
0 / 144
0.00% covered (danger)
0.00%
0 / 12
3306
0.00% covered (danger)
0.00%
0 / 1
 __construct
0.00% covered (danger)
0.00%
0 / 20
0.00% covered (danger)
0.00%
0 / 1
56
 setLogger
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 applyDefaultConfig
0.00% covered (danger)
0.00%
0 / 9
0.00% covered (danger)
0.00%
0 / 1
30
 singleton
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 1
6
 destroySingletons
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 getConnection
0.00% covered (danger)
0.00%
0 / 65
0.00% covered (danger)
0.00%
0 / 1
342
 freeConnection
0.00% covered (danger)
0.00%
0 / 8
0.00% covered (danger)
0.00%
0 / 1
20
 closeExcessIdleConections
0.00% covered (danger)
0.00%
0 / 8
0.00% covered (danger)
0.00%
0 / 1
42
 handleError
0.00% covered (danger)
0.00%
0 / 13
0.00% covered (danger)
0.00%
0 / 1
20
 reauthenticateConnection
0.00% covered (danger)
0.00%
0 / 7
0.00% covered (danger)
0.00%
0 / 1
12
 resetTimeout
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
6
 __destruct
0.00% covered (danger)
0.00%
0 / 5
0.00% covered (danger)
0.00%
0 / 1
20
1<?php
2/**
3 * Redis client connection pooling manager.
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
19 *
20 * @file
21 * @defgroup Redis Redis
22 */
23
24use Psr\Log\LoggerAwareInterface;
25use Psr\Log\LoggerInterface;
26use Psr\Log\NullLogger;
27
28/**
29 * Helper class to manage Redis connections.
30 *
31 * This can be used to get handle wrappers that free the handle when the wrapper
32 * leaves scope. The maximum number of free handles (connections) is configurable.
33 * This provides an easy way to cache connection handles that may also have state,
34 * such as a handle does between multi() and exec(), and without hoarding connections.
35 * The wrappers use PHP magic methods so that calling functions on them calls the
36 * function of the actual Redis object handle.
37 *
38 * @ingroup Redis
39 * @since 1.21
40 */
41class RedisConnectionPool implements LoggerAwareInterface {
42    /** @var int Connection timeout in seconds */
43    protected $connectTimeout;
44    /** @var string Read timeout in seconds */
45    protected $readTimeout;
46    /** @var string Plaintext auth password */
47    protected $password;
48    /** @var bool Whether connections persist */
49    protected $persistent;
50    /** @var int Serializer to use (Redis::SERIALIZER_*) */
51    protected $serializer;
52    /** @var string ID for persistent connections */
53    protected $id;
54
55    /** @var int Current idle pool size */
56    protected $idlePoolSize = 0;
57
58    /**
59     * @var array (server name => ((connection info array),...)
60     * @phan-var array<string,array{conn:Redis,free:bool}[]>
61     */
62    protected $connections = [];
63    /** @var array (server name => UNIX timestamp) */
64    protected $downServers = [];
65
66    /** @var array (pool ID => RedisConnectionPool) */
67    protected static $instances = [];
68
69    /** integer; seconds to cache servers as "down". */
70    private const SERVER_DOWN_TTL = 30;
71
72    /**
73     * @var LoggerInterface
74     */
75    protected $logger;
76
77    /**
78     * @param array $options
79     * @param string $id
80     * @throws Exception
81     */
82    protected function __construct( array $options, $id ) {
83        if ( !class_exists( Redis::class ) ) {
84            throw new RuntimeException(
85                __CLASS__ . ' requires a Redis client library. ' .
86                'See https://www.mediawiki.org/wiki/Redis#Setup' );
87        }
88        $this->logger = $options['logger'] ?? new NullLogger();
89        $this->connectTimeout = $options['connectTimeout'];
90        $this->readTimeout = $options['readTimeout'];
91        $this->persistent = $options['persistent'];
92        $this->password = $options['password'];
93        if ( !isset( $options['serializer'] ) || $options['serializer'] === 'php' ) {
94            $this->serializer = Redis::SERIALIZER_PHP;
95        } elseif ( $options['serializer'] === 'igbinary' ) {
96            if ( !defined( 'Redis::SERIALIZER_IGBINARY' ) ) {
97                throw new InvalidArgumentException(
98                    __CLASS__ . ': configured serializer "igbinary" not available' );
99            }
100            $this->serializer = Redis::SERIALIZER_IGBINARY;
101        } elseif ( $options['serializer'] === 'none' ) {
102            $this->serializer = Redis::SERIALIZER_NONE;
103        } else {
104            throw new InvalidArgumentException( "Invalid serializer specified." );
105        }
106        $this->id = $id;
107    }
108
109    public function setLogger( LoggerInterface $logger ) {
110        $this->logger = $logger;
111    }
112
113    /**
114     * @param array $options
115     * @return array
116     */
117    protected static function applyDefaultConfig( array $options ) {
118        if ( !isset( $options['connectTimeout'] ) ) {
119            $options['connectTimeout'] = 1;
120        }
121        if ( !isset( $options['readTimeout'] ) ) {
122            $options['readTimeout'] = 1;
123        }
124        if ( !isset( $options['persistent'] ) ) {
125            $options['persistent'] = false;
126        }
127        if ( !isset( $options['password'] ) ) {
128            $options['password'] = null;
129        }
130
131        return $options;
132    }
133
134    /**
135     * @param array $options
136     * $options include:
137     *   - connectTimeout : The timeout for new connections, in seconds.
138     *                      Optional, default is 1 second.
139     *   - readTimeout    : The timeout for operation reads, in seconds.
140     *                      Commands like BLPOP can fail if told to wait longer than this.
141     *                      Optional, default is 1 second.
142     *   - persistent     : Set this to true to allow connections to persist across
143     *                      multiple web requests. False by default.
144     *   - password       : The authentication password, will be sent to Redis in clear text.
145     *                      Optional, if it is unspecified, no AUTH command will be sent.
146     *   - serializer     : Set to "php", "igbinary", or "none". Default is "php".
147     * @return RedisConnectionPool
148     */
149    public static function singleton( array $options ) {
150        $options = self::applyDefaultConfig( $options );
151        // Map the options to a unique hash...
152        ksort( $options ); // normalize to avoid pool fragmentation
153        $id = sha1( serialize( $options ) );
154        // Initialize the object at the hash as needed...
155        if ( !isset( self::$instances[$id] ) ) {
156            self::$instances[$id] = new self( $options, $id );
157        }
158
159        return self::$instances[$id];
160    }
161
162    /**
163     * Destroy all singleton() instances
164     * @since 1.27
165     */
166    public static function destroySingletons() {
167        self::$instances = [];
168    }
169
170    /**
171     * Get a connection to a redis server. Based on code in RedisBagOStuff.php.
172     *
173     * @param string $server A hostname/port combination or the absolute path of a UNIX socket.
174     *                       If a hostname is specified but no port, port 6379 will be used.
175     * @param LoggerInterface|null $logger PSR-3 logger instance. [optional]
176     * @return RedisConnRef|Redis|false Returns false on failure
177     * @throws InvalidArgumentException
178     */
179    public function getConnection( $server, LoggerInterface $logger = null ) {
180        // The above @return also documents 'Redis' for convenience with IDEs.
181        // RedisConnRef uses PHP magic methods, which wouldn't be recognised.
182
183        $logger = $logger ?: $this->logger;
184        // Check the listing "dead" servers which have had a connection errors.
185        // Servers are marked dead for a limited period of time, to
186        // avoid excessive overhead from repeated connection timeouts.
187        if ( isset( $this->downServers[$server] ) ) {
188            $now = time();
189            if ( $now > $this->downServers[$server] ) {
190                // Dead time expired
191                unset( $this->downServers[$server] );
192            } else {
193                // Server is dead
194                $logger->debug(
195                    'Server "{redis_server}" is marked down for another ' .
196                    ( $this->downServers[$server] - $now ) . ' seconds',
197                    [ 'redis_server' => $server ]
198                );
199
200                return false;
201            }
202        }
203
204        // Check if a connection is already free for use
205        if ( isset( $this->connections[$server] ) ) {
206            foreach ( $this->connections[$server] as &$connection ) {
207                if ( $connection['free'] ) {
208                    $connection['free'] = false;
209                    --$this->idlePoolSize;
210
211                    return new RedisConnRef(
212                        $this, $server, $connection['conn'], $logger
213                    );
214                }
215            }
216        }
217
218        if ( !$server ) {
219            throw new InvalidArgumentException(
220                __CLASS__ . ": invalid configured server \"$server\"" );
221        } elseif ( substr( $server, 0, 1 ) === '/' ) {
222            // UNIX domain socket
223            // These are required by the redis extension to start with a slash, but
224            // we still need to set the port to a special value to make it work.
225            $host = $server;
226            $port = 0;
227        } else {
228            // TCP connection
229            if ( preg_match( '/^\[(.+)\]:(\d+)$/', $server, $m ) ) {
230                // (ip, port)
231                [ $host, $port ] = [ $m[1], (int)$m[2] ];
232            } elseif ( preg_match( '/^((?:[\w]+\:\/\/)?[^:]+):(\d+)$/', $server, $m ) ) {
233                // (ip, uri or path, port)
234                [ $host, $port ] = [ $m[1], (int)$m[2] ];
235                if (
236                    substr( $host, 0, 6 ) === 'tls://'
237                    && version_compare( phpversion( 'redis' ), '5.0.0' ) < 0
238                ) {
239                    throw new RuntimeException(
240                        'A newer version of the Redis client library is required to use TLS. ' .
241                        'See https://www.mediawiki.org/wiki/Redis#Setup' );
242                }
243            } else {
244                // (ip or path, port)
245                [ $host, $port ] = [ $server, 6379 ];
246            }
247        }
248
249        $conn = new Redis();
250        try {
251            if ( $this->persistent ) {
252                $result = $conn->pconnect( $host, $port, $this->connectTimeout, $this->id );
253            } else {
254                $result = $conn->connect( $host, $port, $this->connectTimeout );
255            }
256            if ( !$result ) {
257                $logger->error(
258                    'Could not connect to server "{redis_server}"',
259                    [ 'redis_server' => $server ]
260                );
261                // Mark server down for some time to avoid further timeouts
262                $this->downServers[$server] = time() + self::SERVER_DOWN_TTL;
263
264                return false;
265            }
266            if ( ( $this->password !== null ) && !$conn->auth( $this->password ) ) {
267                $logger->error(
268                    'Authentication error connecting to "{redis_server}"',
269                    [ 'redis_server' => $server ]
270                );
271            }
272        } catch ( RedisException $e ) {
273            $this->downServers[$server] = time() + self::SERVER_DOWN_TTL;
274            $logger->error(
275                'Redis exception connecting to "{redis_server}"',
276                [
277                    'redis_server' => $server,
278                    'exception' => $e,
279                ]
280            );
281
282            return false;
283        }
284
285        $conn->setOption( Redis::OPT_READ_TIMEOUT, $this->readTimeout );
286        $conn->setOption( Redis::OPT_SERIALIZER, $this->serializer );
287        $this->connections[$server][] = [ 'conn' => $conn, 'free' => false ];
288
289        return new RedisConnRef( $this, $server, $conn, $logger );
290    }
291
292    /**
293     * Mark a connection to a server as free to return to the pool
294     *
295     * @param string $server
296     * @param Redis $conn
297     * @return bool
298     */
299    public function freeConnection( $server, Redis $conn ) {
300        $found = false;
301
302        foreach ( $this->connections[$server] as &$connection ) {
303            if ( $connection['conn'] === $conn && !$connection['free'] ) {
304                $connection['free'] = true;
305                ++$this->idlePoolSize;
306                break;
307            }
308        }
309
310        $this->closeExcessIdleConections();
311
312        return $found;
313    }
314
315    /**
316     * Close any extra idle connections if there are more than the limit
317     */
318    protected function closeExcessIdleConections() {
319        if ( $this->idlePoolSize <= count( $this->connections ) ) {
320            return; // nothing to do (no more connections than servers)
321        }
322
323        foreach ( $this->connections as &$serverConnections ) {
324            foreach ( $serverConnections as $key => &$connection ) {
325                if ( $connection['free'] ) {
326                    unset( $serverConnections[$key] );
327                    if ( --$this->idlePoolSize <= count( $this->connections ) ) {
328                        return; // done (no more connections than servers)
329                    }
330                }
331            }
332        }
333    }
334
335    /**
336     * The redis extension throws an exception in response to various read, write
337     * and protocol errors. Sometimes it also closes the connection, sometimes
338     * not. The safest response for us is to explicitly destroy the connection
339     * object and let it be reopened during the next request.
340     *
341     * @param RedisConnRef $cref
342     * @param RedisException $e
343     */
344    public function handleError( RedisConnRef $cref, RedisException $e ) {
345        $server = $cref->getServer();
346        $this->logger->error(
347            'Redis exception on server "{redis_server}"',
348            [
349                'redis_server' => $server,
350                'exception' => $e,
351            ]
352        );
353        foreach ( $this->connections[$server] as $key => $connection ) {
354            if ( $cref->isConnIdentical( $connection['conn'] ) ) {
355                $this->idlePoolSize -= $connection['free'] ? 1 : 0;
356                unset( $this->connections[$server][$key] );
357                break;
358            }
359        }
360    }
361
362    /**
363     * Re-send an AUTH request to the redis server (useful after disconnects).
364     *
365     * This works around an upstream bug in phpredis. phpredis hides disconnects by transparently
366     * reconnecting, but it neglects to re-authenticate the new connection. To the user of the
367     * phpredis client API this manifests as a seemingly random tendency of connections to lose
368     * their authentication status.
369     *
370     * This method is for internal use only.
371     *
372     * @see https://github.com/nicolasff/phpredis/issues/403
373     *
374     * @param string $server
375     * @param Redis $conn
376     * @return bool Success
377     */
378    public function reauthenticateConnection( $server, Redis $conn ) {
379        if ( $this->password !== null && !$conn->auth( $this->password ) ) {
380            $this->logger->error(
381                'Authentication error connecting to "{redis_server}"',
382                [ 'redis_server' => $server ]
383            );
384
385            return false;
386        }
387
388        return true;
389    }
390
391    /**
392     * Adjust or reset the connection handle read timeout value
393     *
394     * @param Redis $conn
395     * @param int|null $timeout Optional
396     */
397    public function resetTimeout( Redis $conn, $timeout = null ) {
398        $conn->setOption( Redis::OPT_READ_TIMEOUT, $timeout ?: $this->readTimeout );
399    }
400
401    /**
402     * Make sure connections are closed
403     */
404    public function __destruct() {
405        foreach ( $this->connections as &$serverConnections ) {
406            foreach ( $serverConnections as &$connection ) {
407                try {
408                    /** @var Redis $conn */
409                    $conn = $connection['conn'];
410                    $conn->close();
411                } catch ( RedisException $e ) {
412                    // The destructor can be called on shutdown when random parts of the system
413                    // have been destructed already, causing weird errors. Ignore them.
414                }
415            }
416        }
417    }
418}