<?php

namespace MediaWiki\Extensions\IPInfo;

use MediaWiki\User\UserIdentity;
use StatusValue;

interface UserAccessManager {

	/**
	 * Whether the user has enabled the tool. For use with `UserAccessManager::userHasAccess()` and
	 * `UserAccessManager::userCanRequestAccess()`.
	 */
	public const USER_ENABLED = 1;

	/**
	 * Whether the user has agreed to the terms of use of the tool. For use with
	 * `UserAccessManager::userHasAccess()` and `UserAccessManager::userCanRequestAccess()`.
	 */
	public const USER_AGREED_TO_TERMS = 2;

	/**
	 * Grants the user the specified level of access to the tool.
	 *
	 * If the user cannot be granted the specified level of access, e.g. they have had their access
	 * permanently revoked by another user, then a fatal status is returned.
	 *
	 * If the level of access is `UserAccessManager::USER_AGREED_TO_TERMS`, then the grant is
	 * logged.
	 *
	 * @param UserIdentity $user
	 * @param int $access The level of access being granted, i.e. `UserAccessManager::USER_ENABLED`
	 *  or `UserAccessManager::USER_AGREED_TO_TERMS`
	 * @return StatusValue
	 */
	public function grantUserAccess( UserIdentity $user, int $access ): StatusValue;

	public function userHasAccess( UserIdentity $user, int $access ): StatusValue;

	/**
	 * Gets whether the user can be granted the specified level of access and, if not, then why
	 * not.
	 *
	 * @param UserIdentity $user
	 * @param int $access The level of access being granted, i.e. `UserAccessManager::USER_ENABLED`
	 *  or `UserAccessManager::USER_AGREED_TO_TERMS`
	 * @return StatusValue
	 */
	public function userCanBeGranted( UserIdentity $user, int $access ): StatusValue;

	/**
	 * Revokes all access for the user and logs it.
	 *
	 * @internal
	 *
	 * @param UserIdentity $target
	 * @param UserIdentity $actor The user who is performing the revocation
	 * @param bool $permanent
	 * @return StatusValue
	 */
	public function revokeUserAccess( UserIdentity $target, UserIdentity $actor, bool $permanent = false ): StatusValue;

	/**
	 * Revokes all access for all users.
	 *
	 * @internal
	 *
	 * @param UserIdentity $actor
	 * @param bool $permanent
	 * @return StatusValue
	 */
	public function revokeAllUsersAccess( UserIdentity $actor, bool $permanent = false ): StatusValue;
}