Merge "SessionManager: Document expectations for storage backend"

includes/DefaultSettings.php

@@ -2730,9 +2730,11 @@ $wgMessageCacheType = CACHE_ANYTHING;
 $wgParserCacheType = CACHE_ANYTHING;
 
 /**
- * The cache type for storing session data.
+ * The cache backend for storing session data.
  *
- * For available types see $wgMainCacheType.
+ * Used by MediaWiki\Session\SessionManager. See $wgMainCacheType for available types.
+ *
+ * See [SessionManager Storage expectations](@ref SessionManager-storage-expectations).
  */
 $wgSessionCacheType = CACHE_ANYTHING;
 

includes/libs/objectcache/RESTBagOStuff.php

@@ -128,6 +128,7 @@ class RESTBagOStuff extends MediumSpecificBagOStuff {
 		$this->url = rtrim( $params['url'], '/' ) . '/';
 
 		// Default config, R+W > N; no locks on reads though; writes go straight to state-machine
+		// TODO: What does this mean^. What is "N"? What state-machine?
 		$this->attrMap[self::ATTR_SYNCWRITES] = self::QOS_SYNCWRITES_QC;
 	}
 

includes/session/SessionManager.php

@@ -46,6 +46,35 @@ use Wikimedia\ObjectFactory;
  *
  * To provide custom session handling, implement a MediaWiki\Session\SessionProvider.
  *
+ * @anchor SessionManager-storage-expectations
+ *
+ * ## Storage expectations
+ *
+ * The SessionManager should be configured with a very fast storage system that is
+ * optimized for holding key-value pairs. It expects:
+ *
+ * - Low latencies. Session data is read or written to during nearly all web requests from
+ *   people that have contributed to or otherwise engaged with the site, including those not
+ *   logged in with a registered account.
+ *
+ * - Locally writable data. The data must be writable from both primary and secondary
+ *   data centres.
+ *
+ * - Locally latest reads. Writes must by default be immediately consistent within
+ *   the local data centre, and visible to other reads from web servers in that data centre.
+ *
+ * - Replication. The data must be eventually consistent across all data centres. Writes
+ *   are either synced to all remote data centres, or locally overwritten by another write
+ *   that is.
+ *
+ * - Support BagOStuff::WRITE_SYNC flag. The data must writable with synchronous replication
+ *   waited for, across all data centres. This is used when resetting or deleting a session,
+ *   which must not be lost or overwritten by earlier or overlapping write actions.
+ *
+ * The SessionManager uses set() and delete() for write operations, which should by default
+ * be synchronous in the local data centre, and replicate asynchronously to any others.
+ * This behaviour can be overridden by the use of the WRITE_SYNC flag.
+ *
  * @ingroup Session
  * @since 1.27
  * @see https://www.mediawiki.org/wiki/Manual:SessionManager_and_AuthManager