Update miscellaneous documentation

Signed-off-by: Cy Rossignol <[email protected]>

Author: cyrossignol

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 Monospice
+Copyright (c) Monospice
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -26,6 +26,7 @@ as needed by the environment. A developer may use a standalone Redis server in
 their local environment, while production environments operate a Redis Sentinel
 set of servers.
 
+
 Contents
 --------
 
@@ -40,11 +41,13 @@ Contents
  - [Override the Standard Redis API][s-override-redis-api]
  - [Executing Redis Commands (RedisSentinel Facade)][s-facade]
      - [Dependency Injection][s-dependency-injection]
+ - [Other Sentinel Considerations][s-considerations]
  - [Testing](#testing)
  - [License](#license)
  - [Appendix: Environment Variables][s-appx-env-vars]
  - [Appendix: Configuration Examples][s-appx-examples]
 
+
 Requirements
 ------------
 
@@ -62,10 +65,11 @@ This Readme assumes prior knowledge of configuring [Redis][redis] for [Redis
 Sentinel][sentinel] and [using Redis with Laravel][laravel-redis-docs] or
 [Lumen][lumen-redis-docs].
 
+
 Installation
 ------------
 
-We're using Laravel, so we'll install through composer, of course!
+We're using Laravel, so we'll install through Composer, of course!
 
 #### For Laravel/Lumen 5.4 and above:
 
@@ -109,6 +113,7 @@ In Lumen, register the service provider in *bootstrap/app.php*:
 $app->register(Monospice\LaravelRedisSentinel\RedisSentinelServiceProvider::class);
 ```
 
+
 Quickstart (TL;DR)
 ------------------
 
@@ -148,6 +153,7 @@ For those that need a quick development Sentinel server cluster, try the
 [*start-cluster.sh*][s-integration-tests] script included with the package's
 testing files.
 
+
 Configuration
 -------------
 
@@ -169,6 +175,7 @@ installation.
 The package continues to support advanced configuration through standard config
 files without requiring changes for existing projects.
 
+
 Environment-Based Configuration
 -------------------------------
 
@@ -265,6 +272,7 @@ file](config/redis-sentinel.php) or the [environment-based configuration
 examples][s-env-config-examples] to better understand how the package uses
 environment variables.
 
+
 Using Standard Configuration Files
 ----------------------------------
 
@@ -277,6 +285,7 @@ default environment-based configuration can provide.
 For this configuration method, we'll modify the following config files:
 
  - *config/database.php* - to define the Redis Sentinel connections
+ - *config/broadcasting.php* - to define the Redis Sentinel broadcaster
  - *config/cache.php* - to define a Redis Sentinel cache store
  - *config/session.php* - to set the Redis Sentinel connection for sessions
  - *config/queue.php* - to define a Redis Sentinel queue connection
@@ -300,7 +309,7 @@ remove the `'redis'` driver config block that ships with Laravel by default.
 
 **Note:** Laravel passes these configuration options to the [Predis][predis]
 client library, so we can include advanced configuration options here if
-needed. See the [Predis Documentation][predis-docs] for more information.
+needed. See the [Predis documentation][predis-docs] for more information.
 
 #### Basic Configuration
 
@@ -371,24 +380,23 @@ for a single connection. The default values are shown below:
     ...
 
     // The default amount of time (in seconds) the client waits before
-    // determining that a connection attempt to a Sentinel server failed
+    // determining that a connection attempt to a Sentinel server failed.
     'sentinel_timeout' => 0.100,
 
-    // The default number of attempts the client tries to contact a Sentinel
-    // server before it determines that it cannot reach all Sentinel servers
-    // in a quorum. A value of 0 instructs the client to throw an exception
-    // after the first failed attempt, while a value of -1 causes the client
-    // to continue to retry connections to Sentinel indefinitely
+    // The default number of attempts to retry a command when the client fails
+    // to connect to a Redis or Sentinel server. A value of 0 instructs the
+    // client to throw an exception after the first failed attempt, while a
+    // value of -1 causes the client to continue to retry commands indefinitely.
     'retry_limit' => 20,
 
-    // The default amount of time (in milliseconds) the client waits before
-    // attempting to contact another Sentinel server if the previous server did
-    // not respond
+    // The default amount of time (in milliseconds) that the client waits before
+    // attempting to contact another Sentinel server or retry a command if the
+    // previous server did not respond.
     'retry_wait' => 1000,
 
     // Instructs the client to query the first reachable Sentinel server for an
     // updated set of Sentinels each time the client needs to establish a
-    // connection with a Redis master or slave server
+    // connection with a Redis master or replica.
     'update_sentinels' => false,
 ],
 ```
@@ -482,6 +490,7 @@ If the application contains a specific connection in the `'redis-sentinel'`
 database configuration for the queue, replace `'connection' => 'default'` with
 its name.
 
+
 Using a Package Configuration File
 ----------------------------------
 
@@ -513,12 +522,13 @@ We can customize the package's [internal config file](config/redis-sentinel.php)
 by copying it into our project's *config/* directory  and changing the values
 as needed. Lumen users may need to create this directory if it doesn't exist.
 
-A custom package config file need only contain the top-level elements that
+A custom package config file needs only to contain the top-level elements that
 developer wishes to customize: in the code shown above, the custom config file
 only overrides the package's default configuration for Redis Sentinel
 connections, so the package will still automatically configure the broadcasting,
 cache, session, and queue services using environment variables.
 
+
 Hybrid Configuration
 --------------------
 
@@ -543,14 +553,15 @@ configuration that it does not explicitly declare, and the main application
 configuration receives the values from both of these that it does not provide
 in a standard config file.
 
+
 Override the Standard Redis API
 -------------------------------
 
 This package adds Redis Sentinel drivers for Laravel's caching, session, and
 queue APIs, and the developer may select which of these to utilize Sentinel
 connections for. However, Laravel also provides [an API][laravel-redis-api-docs]
 for interacting with Redis directly through the `Redis` facade, or through
-`Illuminate\Redis\Database` which we can resolve through the application
+the Redis connection manager which we can resolve through the application
 container (`app('redis')`, dependency injection, etc.).
 
 When installed, this package does not impose the use of Sentinel for all Redis
@@ -587,6 +598,7 @@ service (`app('redis')`, etc) will operate using the Sentinel connections.
 This makes it easier for developers to use a standalone Redis server in their
 local environments and switch to a full Sentinel set of servers in production.
 
+
 Executing Redis Commands (RedisSentinel Facade)
 -------------------------------------------------
 
@@ -661,14 +673,67 @@ public function __construct(Redis $redis)
 }
 ```
 
+
+Other Sentinel Considerations
+-----------------------------
+
+The following sections describe some characteristics to keep in mind when
+working with Sentinel connections.
+
+### Read and Write Operations
+
+To spread load between available resources, the client attempts to execute read
+operations on Redis slave servers when initializing a connection. Commands that
+write data will always execute on the master server.
+
+### Transactions
+
+All commands in a transaction, even read-only commands, execute on the master
+Redis server. When it makes sense to do so, avoid calling read commands within
+a transaction to improve load-balancing.
+
+If a transaction aborts because of a connection failure, the package attempts
+to reconnect and retry the transaction until it exhausts the configured number
+of allowed attempts (`retry_limit`), or until the entire transaction succeeds.
+
+**Important:** Predis provides a specialized MULTI/EXEC abstraction that we can
+obtain by calling `transaction()` with no arguments. This API is *not*
+protected by Sentinel connection failure handling. For high-availability, use
+the Laravel API by passing a closure to `transaction()`.
+
+### Publish/Subscribe
+
+For PUB/SUB messaging, the client publishes messages to the master server. When
+subscribing, the package attempts to connect to a slave server first before
+falling-back to the master. Like with read operations, this helps to distribute
+the load away from the master because messages published to the master propagate
+to each of the slaves.
+
+Applications with long-running subscribers need to extend the timeout of the
+connection or disable it by setting `read_write_timeout` to `0`. Additionally,
+we also need to extend or disable the `timeout` configuration directive on the
+Redis servers that the application subscribes to.
+
+When a subscriber connection fails, the package will attempt to reconnect to
+another server and resume listening for messages. We may want to set the value
+of `retry_limit` to `-1` on connections with long-running subscribers so that
+the client continues to retry forever. Note that a subscriber may miss messages
+published to a channel while re-establishing the connection.
+
+**Important:** Predis provides a PUB/SUB consumer that we can obtain by calling
+`pubSubLoop()` with no arguments. This API is *not* protected by Sentinel
+connection failure handling. For high-availability, use the Laravel API by
+passing a closure to `subscribe()` or `psubscribe()`.
+
+
 Testing
 -------
 
 This package includes a PHPUnit test suite with unit tests for the package's
 classes and an integration test suite for Sentinel-specific functionality and
-known issues. These tests do not verify every Redis command because Predis and
-Laravel both contain full test suites themselves, and because the package code
-simply wraps these libraries.
+compatibility fixes. These tests do not verify every Redis command because
+Predis and Laravel both contain full test suites themselves, and because the
+package code simply wraps these libraries.
 
 ```shell
 $ phpunit --testsuite unit
@@ -733,6 +798,7 @@ $ docker-compose run --rm tests [--testsuite ...]
 Developers can also customize the Compose file by copying *docker-compose.yml*
 to *docker-compose.override.yml*.
 
+
 License
 -------
 
@@ -741,6 +807,7 @@ information.
 
 -------------------------------------------------------------------------------
 
+
 Appendix: Environment Variables
 -------------------------------
 
@@ -865,6 +932,7 @@ when `SESSION_DRIVER` equals `redis-sentinel`. It defaults to the package's
 internal, auto-configured *session* connection when unset unless the
 application configuration already contains a value for `session.connection`.
 
+
 Appendix: Configuration Examples
 --------------------------------
 
@@ -1043,6 +1111,7 @@ Sentinel Documentation][sentinel].
 
 [s-appx-env-vars]: #appendix-environment-variables
 [s-appx-examples]: #appendix-configuration-examples
+[s-considerations]: #other-sentinel-considerations
 [s-dependency-injection]: #dependency-injection
 [s-dev-vs-prod-example]: #development-vs-production
 [s-env-config]: #environment-based-configuration

src/Connections/PredisConnection.php

@@ -216,6 +216,9 @@ public function transaction(callable $callback = null)
      * @param callable $callback The operation to execute.
      *
      * @return mixed The result of the first successful attempt.
+     *
+     * @throws CommunicationException After exhausting the allowed number of
+     * attempts to reconnect.
      */
     protected function retryOnFailure(callable $callback)
     {
@@ -275,6 +278,9 @@ protected function getMaster()
      * if the connection does not include any slaves.
      *
      * @return Client The client instance for the selected slave.
+     *
+     * @throws RuntimeException When the client cannot reach any replicas
+     * (and the master if $fallbackToMaster is TRUE).
      */
     protected function getRandomSlave($fallbackToMaster = true)
     {

src/Contracts/Factory.php

@@ -4,6 +4,15 @@
 
 use Illuminate\Contracts\Redis\Factory as RedisFactoryContract;
 
+/**
+ * Executes Redis commands using Sentinel connections.
+ *
+ * @category Package
+ * @package  Monospice\LaravelRedisSentinel
+ * @author   Cy Rossignol <[email protected]>
+ * @license  See LICENSE file
+ * @link     https://github.com/monospice/laravel-redis-sentinel-drivers
+ */
 interface Factory extends RedisFactoryContract
 {
 }