3 * MediaWiki session backend
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.
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.
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
24 namespace MediaWiki\Session
;
27 use Psr\Log\LoggerInterface
;
30 use Wikimedia\AtEase\AtEase
;
33 * This is the actual workhorse for Session.
35 * Most code does not need to use this class, you want \MediaWiki\Session\Session.
36 * The exceptions are SessionProviders and SessionMetadata hook functions,
37 * which get an instance of this class rather than Session.
39 * The reasons for this split are:
40 * 1. A session can be attached to multiple requests, but we want the Session
41 * object to have some features that correspond to just one of those
43 * 2. We want reasonable garbage collection behavior, but we also want the
44 * SessionManager to hold a reference to every active session so it can be
45 * saved when the request ends.
50 final class SessionBackend
{
55 private $persist = false;
58 private $remember = false;
61 private $forceHTTPS = false;
63 /** @var array|null */
67 private $forcePersist = false;
70 private $metaDirty = false;
73 private $dataDirty = false;
75 /** @var string Used to detect subarray modifications */
76 private $dataHash = null;
78 /** @var CachedBagOStuff */
81 /** @var LoggerInterface */
91 private $curIndex = 0;
93 /** @var WebRequest[] Session requests */
94 private $requests = [];
96 /** @var SessionProvider provider */
99 /** @var array|null provider-specified metadata */
100 private $providerMetadata = null;
103 private $expires = 0;
106 private $loggedOut = 0;
109 private $delaySave = 0;
112 private $usePhpSessionHandling = true;
114 private $checkPHPSessionRecursionGuard = false;
117 private $shutdown = false;
120 * @param SessionId $id
121 * @param SessionInfo $info Session info to populate from
122 * @param CachedBagOStuff $store Backend data store
123 * @param LoggerInterface $logger
124 * @param int $lifetime Session data lifetime in seconds
126 public function __construct(
127 SessionId
$id, SessionInfo
$info, CachedBagOStuff
$store, LoggerInterface
$logger, $lifetime
129 $phpSessionHandling = \RequestContext
::getMain()->getConfig()->get( 'PHPSessionHandling' );
130 $this->usePhpSessionHandling
= $phpSessionHandling !== 'disable';
132 if ( $info->getUserInfo() && !$info->getUserInfo()->isVerified() ) {
133 throw new \
InvalidArgumentException(
134 "Refusing to create session for unverified user {$info->getUserInfo()}"
137 if ( $info->getProvider() === null ) {
138 throw new \
InvalidArgumentException( 'Cannot create session without a provider' );
140 if ( $info->getId() !== $id->getId() ) {
141 throw new \
InvalidArgumentException( 'SessionId and SessionInfo don\'t match' );
145 $this->user
= $info->getUserInfo() ?
$info->getUserInfo()->getUser() : new User
;
146 $this->store
= $store;
147 $this->logger
= $logger;
148 $this->lifetime
= $lifetime;
149 $this->provider
= $info->getProvider();
150 $this->persist
= $info->wasPersisted();
151 $this->remember
= $info->wasRemembered();
152 $this->forceHTTPS
= $info->forceHTTPS();
153 $this->providerMetadata
= $info->getProviderMetadata();
155 $blob = $store->get( $store->makeKey( 'MWSession', (string)$this->id
) );
156 if ( !is_array( $blob ) ||
157 !isset( $blob['metadata'] ) ||
!is_array( $blob['metadata'] ) ||
158 !isset( $blob['data'] ) ||
!is_array( $blob['data'] )
161 $this->dataDirty
= true;
162 $this->metaDirty
= true;
163 $this->logger
->debug(
164 'SessionBackend "{session}" is unsaved, marking dirty in constructor',
166 'session' => $this->id
,
169 $this->data
= $blob['data'];
170 if ( isset( $blob['metadata']['loggedOut'] ) ) {
171 $this->loggedOut
= (int)$blob['metadata']['loggedOut'];
173 if ( isset( $blob['metadata']['expires'] ) ) {
174 $this->expires
= (int)$blob['metadata']['expires'];
176 $this->metaDirty
= true;
177 $this->logger
->debug(
178 'SessionBackend "{session}" metadata dirty due to missing expiration timestamp',
180 'session' => $this->id
,
184 $this->dataHash
= md5( serialize( $this->data
) );
188 * Return a new Session for this backend
189 * @param WebRequest $request
192 public function getSession( WebRequest
$request ) {
193 $index = ++
$this->curIndex
;
194 $this->requests
[$index] = $request;
195 $session = new Session( $this, $index, $this->logger
);
200 * Deregister a Session
201 * @private For use by \MediaWiki\Session\Session::__destruct() only
204 public function deregisterSession( $index ) {
205 unset( $this->requests
[$index] );
206 if ( !$this->shutdown
&& !count( $this->requests
) ) {
208 $this->provider
->getManager()->deregisterSessionBackend( $this );
213 * Shut down a session
214 * @private For use by \MediaWiki\Session\SessionManager::shutdown() only
216 public function shutdown() {
218 $this->shutdown
= true;
222 * Returns the session ID.
225 public function getId() {
226 return (string)$this->id
;
230 * Fetch the SessionId object
231 * @private For internal use by WebRequest
234 public function getSessionId() {
239 * Changes the session ID
240 * @return string New ID (might be the same as the old)
242 public function resetId() {
243 if ( $this->provider
->persistsSessionId() ) {
244 $oldId = (string)$this->id
;
245 $restart = $this->usePhpSessionHandling
&& $oldId === session_id() &&
246 PHPSessionHandler
::isEnabled();
249 // If this session is the one behind PHP's $_SESSION, we need
250 // to close then reopen it.
251 session_write_close();
254 $this->provider
->getManager()->changeBackendId( $this );
255 $this->provider
->sessionIdWasReset( $this, $oldId );
256 $this->metaDirty
= true;
257 $this->logger
->debug(
258 'SessionBackend "{session}" metadata dirty due to ID reset (formerly "{oldId}")',
260 'session' => $this->id
,
265 session_id( (string)$this->id
);
266 AtEase
::quietCall( 'session_start' );
271 // Delete the data for the old session ID now
272 $this->store
->delete( $this->store
->makeKey( 'MWSession', $oldId ) );
279 * Fetch the SessionProvider for this session
280 * @return SessionProviderInterface
282 public function getProvider() {
283 return $this->provider
;
287 * Indicate whether this session is persisted across requests
289 * For example, if cookies are set.
293 public function isPersistent() {
294 return $this->persist
;
298 * Make this session persisted across requests
300 * If the session is already persistent, equivalent to calling
303 public function persist() {
304 if ( !$this->persist
) {
305 $this->persist
= true;
306 $this->forcePersist
= true;
307 $this->metaDirty
= true;
308 $this->logger
->debug(
309 'SessionBackend "{session}" force-persist due to persist()',
311 'session' => $this->id
,
320 * Make this session not persisted across requests
322 public function unpersist() {
323 if ( $this->persist
) {
324 // Close the PHP session, if we're the one that's open
325 if ( $this->usePhpSessionHandling
&& PHPSessionHandler
::isEnabled() &&
326 session_id() === (string)$this->id
328 $this->logger
->debug(
329 'SessionBackend "{session}" Closing PHP session for unpersist',
330 [ 'session' => $this->id
]
332 session_write_close();
336 $this->persist
= false;
337 $this->forcePersist
= true;
338 $this->metaDirty
= true;
340 // Delete the session data, so the local cache-only write in
341 // self::save() doesn't get things out of sync with the backend.
342 $this->store
->delete( $this->store
->makeKey( 'MWSession', (string)$this->id
) );
349 * Indicate whether the user should be remembered independently of the
353 public function shouldRememberUser() {
354 return $this->remember
;
358 * Set whether the user should be remembered independently of the session
360 * @param bool $remember
362 public function setRememberUser( $remember ) {
363 if ( $this->remember
!== (bool)$remember ) {
364 $this->remember
= (bool)$remember;
365 $this->metaDirty
= true;
366 $this->logger
->debug(
367 'SessionBackend "{session}" metadata dirty due to remember-user change',
369 'session' => $this->id
,
376 * Returns the request associated with a Session
377 * @param int $index Session index
380 public function getRequest( $index ) {
381 if ( !isset( $this->requests
[$index] ) ) {
382 throw new \
InvalidArgumentException( 'Invalid session index' );
384 return $this->requests
[$index];
388 * Returns the authenticated user for this session
391 public function getUser() {
396 * Fetch the rights allowed the user when this session is active.
397 * @return null|string[] Allowed user rights, or null to allow all.
399 public function getAllowedUserRights() {
400 return $this->provider
->getAllowedUserRights( $this );
404 * Indicate whether the session user info can be changed
407 public function canSetUser() {
408 return $this->provider
->canChangeUser();
412 * Set a new user for this session
413 * @note This should only be called when the user has been authenticated via a login process
414 * @param User $user User to set on the session.
415 * This may become a "UserValue" in the future, or User may be refactored
418 public function setUser( $user ) {
419 if ( !$this->canSetUser() ) {
420 throw new \
BadMethodCallException(
421 'Cannot set user on this session; check $session->canSetUser() first'
426 $this->metaDirty
= true;
427 $this->logger
->debug(
428 'SessionBackend "{session}" metadata dirty due to user change',
430 'session' => $this->id
,
436 * Get a suggested username for the login form
437 * @param int $index Session index
438 * @return string|null
440 public function suggestLoginUsername( $index ) {
441 if ( !isset( $this->requests
[$index] ) ) {
442 throw new \
InvalidArgumentException( 'Invalid session index' );
444 return $this->provider
->suggestLoginUsername( $this->requests
[$index] );
448 * Whether HTTPS should be forced
451 public function shouldForceHTTPS() {
452 return $this->forceHTTPS
;
456 * Set whether HTTPS should be forced
459 public function setForceHTTPS( $force ) {
460 if ( $this->forceHTTPS
!== (bool)$force ) {
461 $this->forceHTTPS
= (bool)$force;
462 $this->metaDirty
= true;
463 $this->logger
->debug(
464 'SessionBackend "{session}" metadata dirty due to force-HTTPS change',
466 'session' => $this->id
,
473 * Fetch the "logged out" timestamp
476 public function getLoggedOutTimestamp() {
477 return $this->loggedOut
;
481 * Set the "logged out" timestamp
482 * @param int|null $ts
484 public function setLoggedOutTimestamp( $ts = null ) {
486 if ( $this->loggedOut
!== $ts ) {
487 $this->loggedOut
= $ts;
488 $this->metaDirty
= true;
489 $this->logger
->debug(
490 'SessionBackend "{session}" metadata dirty due to logged-out-timestamp change',
492 'session' => $this->id
,
499 * Fetch provider metadata
500 * @protected For use by SessionProvider subclasses only
503 public function getProviderMetadata() {
504 return $this->providerMetadata
;
508 * Set provider metadata
509 * @protected For use by SessionProvider subclasses only
510 * @param array|null $metadata
512 public function setProviderMetadata( $metadata ) {
513 if ( $metadata !== null && !is_array( $metadata ) ) {
514 throw new \
InvalidArgumentException( '$metadata must be an array or null' );
516 if ( $this->providerMetadata
!== $metadata ) {
517 $this->providerMetadata
= $metadata;
518 $this->metaDirty
= true;
519 $this->logger
->debug(
520 'SessionBackend "{session}" metadata dirty due to provider metadata change',
522 'session' => $this->id
,
529 * Fetch the session data array
531 * Note the caller is responsible for calling $this->dirty() if anything in
532 * the array is changed.
534 * @private For use by \MediaWiki\Session\Session only.
537 public function &getData() {
542 * Add data to the session.
544 * Overwrites any existing data under the same keys.
546 * @param array $newData Key-value pairs to add to the session
548 public function addData( array $newData ) {
549 $data = &$this->getData();
550 foreach ( $newData as $key => $value ) {
551 if ( !array_key_exists( $key, $data ) ||
$data[$key] !== $value ) {
552 $data[$key] = $value;
553 $this->dataDirty
= true;
554 $this->logger
->debug(
555 'SessionBackend "{session}" data dirty due to addData(): {callers}',
557 'session' => $this->id
,
558 'callers' => wfGetAllCallers( 5 ),
566 * @private For use by \MediaWiki\Session\Session only.
568 public function dirty() {
569 $this->dataDirty
= true;
570 $this->logger
->debug(
571 'SessionBackend "{session}" data dirty due to dirty(): {callers}',
573 'session' => $this->id
,
574 'callers' => wfGetAllCallers( 5 ),
579 * Renew the session by resaving everything
581 * Resets the TTL in the backend store if the session is near expiring, and
582 * re-persists the session to any active WebRequests if persistent.
584 public function renew() {
585 if ( time() +
$this->lifetime
/ 2 > $this->expires
) {
586 $this->metaDirty
= true;
587 $this->logger
->debug(
588 'SessionBackend "{callers}" metadata dirty for renew(): {callers}',
590 'session' => $this->id
,
591 'callers' => wfGetAllCallers( 5 ),
593 if ( $this->persist
) {
594 $this->forcePersist
= true;
595 $this->logger
->debug(
596 'SessionBackend "{session}" force-persist for renew(): {callers}',
598 'session' => $this->id
,
599 'callers' => wfGetAllCallers( 5 ),
607 * Delay automatic saving while multiple updates are being made
609 * Calls to save() will not be delayed.
611 * @return \Wikimedia\ScopedCallback When this goes out of scope, a save will be triggered
613 public function delaySave() {
615 return new \Wikimedia\
ScopedCallback( function () {
616 if ( --$this->delaySave
<= 0 ) {
617 $this->delaySave
= 0;
624 * Save the session, unless delayed
625 * @see SessionBackend::save()
627 private function autosave() {
628 if ( $this->delaySave
<= 0 ) {
636 * Update both the backend data and the associated WebRequest(s) to
637 * reflect the state of the SessionBackend. This might include
638 * persisting or unpersisting the session.
640 * @param bool $closing Whether the session is being closed
642 public function save( $closing = false ) {
643 $anon = $this->user
->isAnon();
645 if ( !$anon && $this->provider
->getManager()->isUserSessionPrevented( $this->user
->getName() ) ) {
646 $this->logger
->debug(
647 'SessionBackend "{session}" not saving, user {user} was ' .
648 'passed to SessionManager::preventSessionsForUser',
650 'session' => $this->id
,
651 'user' => $this->user
,
656 // Ensure the user has a token
657 // @codeCoverageIgnoreStart
658 if ( !$anon && !$this->user
->getToken( false ) ) {
659 $this->logger
->debug(
660 'SessionBackend "{session}" creating token for user {user} on save',
662 'session' => $this->id
,
663 'user' => $this->user
,
665 $this->user
->setToken();
666 if ( !wfReadOnly() ) {
667 // Promise that the token set here will be valid; save it at end of request
669 \DeferredUpdates
::addCallableUpdate( function () use ( $user ) {
670 $user->saveSettings();
673 $this->metaDirty
= true;
675 // @codeCoverageIgnoreEnd
677 if ( !$this->metaDirty
&& !$this->dataDirty
&&
678 $this->dataHash
!== md5( serialize( $this->data
) )
680 $this->logger
->debug(
681 'SessionBackend "{session}" data dirty due to hash mismatch, {expected} !== {got}',
683 'session' => $this->id
,
684 'expected' => $this->dataHash
,
685 'got' => md5( serialize( $this->data
) ),
687 $this->dataDirty
= true;
690 if ( !$this->metaDirty
&& !$this->dataDirty
&& !$this->forcePersist
) {
694 $this->logger
->debug(
695 'SessionBackend "{session}" save: dataDirty={dataDirty} ' .
696 'metaDirty={metaDirty} forcePersist={forcePersist}',
698 'session' => $this->id
,
699 'dataDirty' => (int)$this->dataDirty
,
700 'metaDirty' => (int)$this->metaDirty
,
701 'forcePersist' => (int)$this->forcePersist
,
704 // Persist or unpersist to the provider, if necessary
705 if ( $this->metaDirty ||
$this->forcePersist
) {
706 if ( $this->persist
) {
707 foreach ( $this->requests
as $request ) {
708 $request->setSessionId( $this->getSessionId() );
709 $this->provider
->persistSession( $this, $request );
712 $this->checkPHPSession();
715 foreach ( $this->requests
as $request ) {
716 if ( $request->getSessionId() === $this->id
) {
717 $this->provider
->unpersistSession( $request );
723 $this->forcePersist
= false;
725 if ( !$this->metaDirty
&& !$this->dataDirty
) {
729 // Save session data to store, if necessary
730 $metadata = $origMetadata = [
731 'provider' => (string)$this->provider
,
732 'providerMetadata' => $this->providerMetadata
,
733 'userId' => $anon ?
0 : $this->user
->getId(),
734 'userName' => User
::isValidUserName( $this->user
->getName() ) ?
$this->user
->getName() : null,
735 'userToken' => $anon ?
null : $this->user
->getToken(),
736 'remember' => !$anon && $this->remember
,
737 'forceHTTPS' => $this->forceHTTPS
,
738 'expires' => time() +
$this->lifetime
,
739 'loggedOut' => $this->loggedOut
,
740 'persisted' => $this->persist
,
743 \Hooks
::run( 'SessionMetadata', [ $this, &$metadata, $this->requests
] );
745 foreach ( $origMetadata as $k => $v ) {
746 if ( $metadata[$k] !== $v ) {
747 throw new \
UnexpectedValueException( "SessionMetadata hook changed metadata key \"$k\"" );
751 $flags = $this->persist ?
0 : CachedBagOStuff
::WRITE_CACHE_ONLY
;
752 $flags |
= CachedBagOStuff
::WRITE_SYNC
; // write to all datacenters
754 $this->store
->makeKey( 'MWSession', (string)$this->id
),
756 'data' => $this->data
,
757 'metadata' => $metadata,
759 $metadata['expires'],
763 $this->metaDirty
= false;
764 $this->dataDirty
= false;
765 $this->dataHash
= md5( serialize( $this->data
) );
766 $this->expires
= $metadata['expires'];
770 * For backwards compatibility, open the PHP session when the global
771 * session is persisted
773 private function checkPHPSession() {
774 if ( !$this->checkPHPSessionRecursionGuard
) {
775 $this->checkPHPSessionRecursionGuard
= true;
776 $reset = new \Wikimedia\
ScopedCallback( function () {
777 $this->checkPHPSessionRecursionGuard
= false;
780 if ( $this->usePhpSessionHandling
&& session_id() === '' && PHPSessionHandler
::isEnabled() &&
781 SessionManager
::getGlobalSession()->getId() === (string)$this->id
783 $this->logger
->debug(
784 'SessionBackend "{session}" Taking over PHP session',
786 'session' => $this->id
,
788 session_id( (string)$this->id
);
789 AtEase
::quietCall( 'session_start' );