using System.Threading.Tasks;

using IwbZero.MultiTenancy;

namespace IwbZero.Authorization.Base.Users
{
    /// <summary>
    /// 定义外部授权源
    /// </summary>
    /// <typeparam name="TTenant">Tenant type</typeparam>
    /// <typeparam name="TUser">User type</typeparam>
    public interface IExternalAuthenticationSource<TTenant, TUser>
        where TTenant : IwbTenant<TUser>
        where TUser : UserBase
    {
        /// <summary>
        /// 唯一的认证源名称.
        /// This source name is set to <see cref="UserBase.AuthenticationSource"/>
        /// 如果用户通过此认证源认证
        /// </summary>
        string Name { get; }

        /// <summary>
        /// 用于尝试通过此源对用户进行身份验证
        /// </summary>
        /// <param name="userNameOrEmailAddress">User name or email address</param>
        /// <param name="plainPassword">用户的普通密码</param>
        /// <param name="tenant">Tenant of the user or null (if user is a host user)</param>
        /// <returns>True, indicates that this used has authenticated by this source</returns>
        Task<bool> TryAuthenticateAsync(string userNameOrEmailAddress, string plainPassword, TTenant tenant);

        /// <summary>
        /// 此方法是由该源验证的用户，但该源尚不存在，因此源应创建用户和填充属性。
        /// </summary>
        /// <param name="userNameOrEmailAddress">User name or email address</param>
        /// <param name="tenant">Tenant of the user or null (if user is a host user)</param>
        /// <returns>Newly created user</returns>
        Task<TUser> CreateUserAsync(string userNameOrEmailAddress, TTenant tenant);

        /// <summary>
        /// 此方法是在现有用户通过此源的身份验证后调用的，它可用于由源更新用户的某些属性。
        /// </summary>
        /// <param name="user">The user that can be updated</param>
        /// <param name="tenant">Tenant of the user or null (if user is a host user)</param>
        Task UpdateUserAsync(TUser user, TTenant tenant);
    }
}