/*
 *  Copyright 2016 Anyware Services
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package org.ametys.core.right;

import java.util.Arrays;
import java.util.Collection;
import java.util.Comparator;
import java.util.Map;
import java.util.Set;

import org.apache.commons.lang3.StringUtils;

import org.ametys.core.group.GroupIdentity;
import org.ametys.core.right.RightManager.RightResult;
import org.ametys.core.user.UserIdentity;
import org.ametys.runtime.i18n.I18nizableText;
import org.ametys.runtime.plugin.component.Supporter;

/**
 * This interface is for computing the rights a user has.
 */
public interface AccessController extends Supporter<Object>
{
    /**
     * The access result when looking for a right
     */
    public enum AccessResult
    {
        /* Note: the order of the values are important ! */
        
        /** If the user is allowed because the right is allowed for any anonymous user */
        ANONYMOUS_ALLOWED,
        /** If the user is directly denied */
        USER_DENIED,
        /** If the user is directly allowed */
        USER_ALLOWED,
        /** If the user is denied through its groups and not directly */
        GROUP_DENIED,
        /** If the user is allowed through its groups and not directly */
        GROUP_ALLOWED,
        /** If the user is denied because the right is denied for any connected user */
        ANY_CONNECTED_DENIED,
        /** If the user is allowed because the right is allowed for any connected user */
        ANY_CONNECTED_ALLOWED,
        /** If the user is denied because the right is denied for any anonymous user */
        ANONYMOUS_DENIED,
        /** Cannot determine */
        UNKNOWN;
        
        /**
         * Convert the value to an access result
         * @return denied enumerated will be converted to deny, allow to allow and unknown to unknown
         */
        public RightResult toRightResult()
        {
            switch (this)
            {
                case USER_DENIED:
                case GROUP_DENIED:
                case ANY_CONNECTED_DENIED:
                case ANONYMOUS_DENIED:
                    return RightResult.RIGHT_DENY;
                case USER_ALLOWED:
                case GROUP_ALLOWED:
                case ANY_CONNECTED_ALLOWED:
                case ANONYMOUS_ALLOWED:
                    return RightResult.RIGHT_ALLOW;
                case UNKNOWN:
                default:
                    return RightResult.RIGHT_UNKNOWN;
            }
        }
        
        /**
         * Merge several access results to keep only the more important
         * @param accessResults The access results to merge. Cannot be null but can be empty.
         * @return The more important access result
         */
        public static AccessResult merge(Collection<AccessResult> accessResults)
        {
            return accessResults.stream().filter(r -> r != null).min(Comparator.naturalOrder()).orElse(AccessResult.UNKNOWN);
        }
        
        /**
         * Merge several access results to keep only the more important
         * @param accessResults The access results to merge. Cannot be null but can be empty.
         * @return The more important access result
         */
        public static AccessResult merge(AccessResult... accessResults)
        {
            return Arrays.stream(accessResults).filter(r -> r != null).min(Comparator.naturalOrder()).orElse(AccessResult.UNKNOWN);
        }
    }
    
    /**
     * Get the id of this controller
     * @return the id  of this controller
     */
    public String getId();
    
    /**
     * Gets the kind of access a user has on an object for a given right
     * @param user The user. Cannot be null.
     * @param userGroups The groups the user belongs to
     * @param rightId The id of the right of the user
     * @param object The context object to check the access
     * @return the kind of access a user has on an object for a right
     */
    public AccessResult getPermission(UserIdentity user, Set<GroupIdentity> userGroups, String rightId, Object object);

    /**
     * Gets the kind of access a user has on an object for thye read access
     * @param user The user. Cannot be null.
     * @param userGroups The groups the user belongs to
     * @param object The context object to check the access
     * @return the kind of access a user has on an object for the read access
     */
    public AccessResult getReadAccessPermission(UserIdentity user, Set<GroupIdentity> userGroups, Object object);

    /**
     * Gets the kind of access a user has on an object for all rights
     * @param user The user. Cannot be null.
     * @param userGroups The groups the user belongs to
     * @param object The context object to check the access
     * @return the kind of access a user has on an object for all rights
     */
    public Map<String, AccessResult> getPermissionByRight(UserIdentity user, Set<GroupIdentity> userGroups, Object object);
    
    /**
     * Gets the permission for Anonymous only on an object for a given right
     * @param rightId The id of the right to check
     * @param object The object
     * @return the permission for Anonymous only on an object for a given right
     */
    public AccessResult getPermissionForAnonymous(String rightId, Object object);
    
    /**
     * Gets the read access permission for Anonymous only on an object
     * @param object The object
     * @return the read access permission for Anonymous only on an object
     */
    public AccessResult getReadAccessPermissionForAnonymous(Object object);
    
    /**
     * Gets the permission for any connected user only on an object for a given right
     * @param rightId The id of the right to check
     * @param object The object
     * @return the permission for any connected user only on an object for a given right
     */
    public AccessResult getPermissionForAnyConnectedUser(String rightId, Object object);

    /**
     * Gets the read access permission for any connected user only on an object
     * @param object The object
     * @return the read access permission for any connected user only on an object
     */
    public AccessResult getReadAccessPermissionForAnyConnectedUser(Object object);

    /**
     * Gets the permission by user only on an object for the given right. It does not take account of the groups of the user, etc.
     * @param rightId The id of the right to check
     * @param object The object
     * @return the permission by user only on an object for the given right
     */
    public Map<UserIdentity, AccessResult> getPermissionByUser(String rightId, Object object);

    /**
     * Gets the read access permission by user only on an object. It does not take account of the groups of the user, etc.
     * @param object The object
     * @return the read access permission by user only on an object
     */
    public Map<UserIdentity, AccessResult> getReadAccessPermissionByUser(Object object);
    
    /**
     * Gets the permission by group only on an object for the given right.
     * @param rightId The id of the right to check
     * @param object The object
     * @return the permission by group only on an object for the given right
     */
    public Map<GroupIdentity, AccessResult> getPermissionByGroup(String rightId, Object object);
    
    /**
     * Gets the read access permission by group only on an object.
     * @param object The object
     * @return the read access permission by group only on an object
     */
    public Map<GroupIdentity, AccessResult> getReadAccessPermissionByGroup(Object object);
    
    /**
     * Returns true if the user has a permission on at least one object, directly or though groups, for a given rights and if the object is attached to the given context that is /${WorkspaceName} and its conversions.<br>
     * @param workspacesContexts The contexts to tests such as {"/${WorkspaceName}", "/repository", "/admin"}
     * @param user The user
     * @param userGroups The groups
     * @param rightId The id of the right to check
     * @return true if the user has a permission on at least one object, directly or though groups, for a given right
     */
    public boolean hasUserAnyPermissionOnWorkspace(Set<Object> workspacesContexts, UserIdentity user, Set<GroupIdentity> userGroups, String rightId);
    
    /**
     * Returns true if the user has a read access permission on at least one object, directly or though groups, for a given rights and if the object is attached to the given context that is /${WorkspaceName} and its conversions.<br>
     * @param workspacesContexts The contexts to tests such as {"/${WorkspaceName}", "/repository", "/admin"}
     * @param user The user
     * @param userGroups The groups
     * @return true if the user has a permission on at least one object, directly or though groups, for a given right
     */
    public boolean hasUserAnyReadAccessPermissionOnWorkspace(Set<Object> workspacesContexts, UserIdentity user, Set<GroupIdentity> userGroups);
    
    /**
     * Returns true if anonymous has a permission on at least one object, directly or though groups, for a given rights and if the object is attached to the given context that is /${WorkspaceName} and its conversions.<br>
     * @param workspacesContexts The contexts to tests such as {"/${WorkspaceName}", "/repository", "/admin"}
     * @param rightId The id of the right to check
     * @return true if anonymous has a permission on at least one object, directly or though groups, for a given right
     */
    public boolean hasAnonymousAnyPermissionOnWorkspace(Set<Object> workspacesContexts, String rightId);
    
    /**
     * Returns true if anonymous has a read access permission on at least one object, directly or though groups, for a given rights and if the object is attached to the given context that is /${WorkspaceName} and its conversions.<br>
     * @param workspacesContexts The contexts to tests such as {"/${WorkspaceName}", "/repository", "/admin"}
     * @return true if anonymous has a permission on at least one object, directly or though groups, for a given right
     */
    public boolean hasAnonymousAnyReadAccessPermissionOnWorkspace(Set<Object> workspacesContexts);
    
    /**
     * Returns true if any connected user has a permission on at least one object, directly or though groups, for a given rights and if the object is attached to the given context that is /${WorkspaceName} and its conversions.<br>
     * @param workspacesContexts The contexts to tests such as {"/${WorkspaceName}", "/repository", "/admin"}
     * @param rightId The id of the right to check
     * @return true if any connected user has a permission on at least one object, directly or though groups, for a given right
     */
    public boolean hasAnyConnectedUserAnyPermissionOnWorkspace(Set<Object> workspacesContexts, String rightId);
    
    /**
     * Returns true if any connected user has a read access permission on at least one object, directly or though groups, for a given rights and if the object is attached to the given context that is /${WorkspaceName} and its conversions.<br>
     * @param workspacesContexts The contexts to tests such as {"/${WorkspaceName}", "/repository", "/admin"}
     * @return true if any connected user has a permission on at least one object, directly or though groups, for a given right
     */
    public boolean hasAnyConnectedUserAnyReadAccessPermissionOnWorkspace(Set<Object> workspacesContexts);
    
    /**
     * Explain the read access permission for anonymous on the given object.
     * 
     * The access result in the explanation MUST be the same value as the one returned by
     * {@link #getReadAccessPermissionForAnonymous(Object)}. And the explanation should described the
     * actual object that granted the right to allow final user to see if any context conversion happened
     * @param object the object to test
     * @return an explanation of the access
     */
    public default AccessExplanation explainReadAccessPermissionForAnonymous(Object object)
    {
        return getDefaultAccessExplanation(getId(), getReadAccessPermissionForAnonymous(object));
    }
    /**
     * Explain the permission for anonymous on the given object.
     * 
     * The access result in the explanation MUST be the same value as the one returned by
     * {@link #getPermissionForAnonymous(String, Object)}. And the explanation should described the
     * actual object that granted the right to allow final user to see if any context conversion happened
     * @param rightId the right to test
     * @param object the object to test
     * @return an explanation of the access
     */
    public default AccessExplanation explainPermissionForAnonymous(String rightId, Object object)
    {
        return getDefaultAccessExplanation(getId(), getPermissionForAnonymous(rightId, object));
    }

    /**
     * Explain the read access permission for any connected user on the given object.
     * 
     * The access result in the explanation MUST be the same value as the one returned by
     * {@link #getReadAccessPermissionForAnyConnectedUser(Object)}. And the explanation should described the
     * actual object that granted the right to allow final user to see if any context conversion happened
     * @param object the object to test
     * @return an explanation of the access
     */
    public default AccessExplanation explainReadAccessPermissionForAnyConnectedUser(Object object)
    {
        return getDefaultAccessExplanation(getId(), getReadAccessPermissionForAnyConnectedUser(object));
    }

    /**
     * Explain the permission for any connected user on the given object.
     * 
     * The access result in the explanation MUST be the same value as the one returned by
     * {@link #getPermissionForAnyConnectedUser(String, Object)}. And the explanation should described the
     * actual object that granted the right to allow final user to see if any context conversion happened
     * @param rightId the right to test
     * @param object the object to test
     * @return an explanation of the access
     */
    public default AccessExplanation explainPermissionForAnyConnectedUser(String rightId, Object object)
    {
        return getDefaultAccessExplanation(getId(), getPermissionForAnyConnectedUser(rightId, object));
    }

    /**
     * Explain the read access permission for a user on the given object.
     * 
     * The access result in the explanation MUST be the same value as the one returned by
     * {@link #getReadAccessPermission(UserIdentity, Set, Object)}. And the explanation should described the
     * actual object that granted the right to allow final user to see if any context conversion happened
     * @param user the user to test
     * @param groups the groups of the user
     * @param object the object to test
     * @return an explanation of the access
     */
    public default AccessExplanation explainReadAccessPermission(UserIdentity user, Set<GroupIdentity> groups, Object object)
    {
        return getDefaultAccessExplanation(getId(), getReadAccessPermission(user, groups, object));
    }
    
    /**
     * Explain the permission for a user on the given object.
     * 
     * The access result in the explanation MUST be the same value as the one returned by
     * {@link #getPermission(UserIdentity, Set, String, Object)}. And the explanation should described the
     * actual object that granted the right to allow final user to see if any context conversion happened
     * @param user the user to test
     * @param groups the groups of the user
     * @param rightId the right to test
     * @param object the object to test
     * @return an explanation of the access
     */
    public default AccessExplanation explainPermission(UserIdentity user, Set<GroupIdentity> groups, String rightId, Object object)
    {
        return getDefaultAccessExplanation(getId(), getPermission(user, groups, rightId, object));
    }
    
    /**
     * Build a default explanation for an access result provided by a controller.
     * 
     * This method should be used as a fallback.
     * AccessController should provide their own explanation with more details
     * @param controllerId the access controller id
     * @param result the access result
     * @return an label describing the result
     */
    public static AccessExplanation getDefaultAccessExplanation(String controllerId, AccessResult result)
    {
        I18nizableText label = new I18nizableText("plugin.core", "PLUGINS_CORE_RIGHTS_EXPLAIN_TOOL_RESULT_" + result.name(), Map.of("controllerId", new I18nizableText(controllerId)));
        return new AccessExplanation(controllerId, result, label);
    }
    
    /**
     * Get {@link AccessExplanation} for each permission given to the user by this access controller.
     * 
     * Returns a pair of permission/access explanation for each object with a granted or denied permission to this user by this access controller.
     * 
     * Each explanation should be equivalent to calling the {@link #explainPermission(UserIdentity, Set, String, Object)}
     * or {@link #explainReadAccessPermission(UserIdentity, Set, Object)} for the user, on the object with the corresponding right
     * 
     * @param identity the user identity
     * @param groups the groups the user belongs to.
     * @return all the user's permissions handled by this controller
     */
    public Map<ExplanationObject, Map<Permission, AccessExplanation>> explainAllPermissions(UserIdentity identity, Set<GroupIdentity> groups);
    
    
    /**
     * Get the explanation object representing the object
     * @param object the object
     * @return the explanation object
     */
    public default ExplanationObject getExplanationObject(Object object)
    {
        return new ExplanationObject(
                object,
                getObjectLabel(object),
                getObjectCategory(object),
                getObjectPriority(object)
                );
    }
    
    /**
     * Get a label describing the object handled by this access controller
     * @param object the object
     * @return the label
     */
    public abstract I18nizableText getObjectLabel(Object object);
    
    
    /**
     * Get a label classifying the object handled by this access controller
     * @param object the object
     * @return the label
     */
    public I18nizableText getObjectCategory(Object object);

    
    /**
     * Get the priority of the object to order it in its category
     * @param object the object
     * @return the priority
     */
    public default int getObjectPriority(Object object)
    {
        return 0;
    }
    

    /**
     * A object with an associated label, category and order.
     * 
     * @param object the object
     * @param label a label for the context represented by the object
     * @param category the category the context belongs to
     * @param order order of the context in the category
     */
    public record ExplanationObject(Object object, I18nizableText label, I18nizableText category, int order) {
        /**
         * An object with an associated label and category.
         * 
         * @param object the object
         * @param label a label for the context represented by the object
         * @param category the category the context belongs to
         */
        public ExplanationObject(Object object, I18nizableText label, I18nizableText category)
        {
            this(object, label, category, 0);
        }
        
        @Override
        public final boolean equals(Object other)
        {
            if (other instanceof ExplanationObject otherContext)
            {
                return object.equals(otherContext.object())
                        && (category == null && otherContext.category() == null
                            || category != null && category.equals(otherContext.category()));
            }
            return false;
        }
        
        @Override
        public final int hashCode()
        {
            return object.hashCode() + (category != null ? 23 * category.hashCode() : 0);
        }
    }
    
    /**
     * A permission given by an AccessController
     * @param type the type of permission given
     * @param id the id of the permission (right's id or profile's id). Can be null for types {@link PermissionType#READ} or {@link PermissionType#ALL_RIGHTS}
     */
    public record Permission(PermissionType type, String id) {
        @Override
        public String toString()
        {
            if (StringUtils.isNotBlank(id))
            {
                return type.name() + "#" + id;
            }
            else
            {
                return type.name();
            }
        }
        /**
         * A type of permission
         */
        public enum PermissionType
        {
            /** Read access */
            READ,
            /** A single right */
            RIGHT,
            /** A profile */
            PROFILE,
            /** All rights */
            ALL_RIGHTS
        }
    }

    /**
     * Get all the permissions granted to an anonymous user on the object.
     * @param object the right context to check. it must be supported by the controller (see {@link #supports}
     * @return the permissions with their associated explanation
     */
    public Map<Permission, AccessExplanation> explainAllPermissionsForAnonymous(Object object);
    
    /**
     * Get all the permissions granted to any connected user on the object.
     * The result must only include permissions specific to any connected user
     * 
     * @param object the right context to check. it must be supported by the controller (see {@link #supports}
     * @return the permissions with their associated explanation
     */
    public Map<Permission, AccessExplanation> explainAllPermissionsForAnyConnected(Object object);

    /**
     * Get all the permissions granted to users on the object.
     * The result must only include permissions specific to a user
     * 
     * @param object the right context to check. it must be supported by the controller (see {@link #supports}
     * @return the permissions with their associated explanation for each user
     */
    public Map<UserIdentity, Map<Permission, AccessExplanation>> explainAllPermissionsByUser(Object object);

    /**
     * Get all the permissions granted to groups on the object.
     * The result must only include permissions specific to a group
     * 
     * @param object the right context to check. it must be supported by the controller (see {@link #supports}
     * @return the permissions with their associated explanation for each group
     */
    public Map<GroupIdentity, Map<Permission, AccessExplanation>> explainAllPermissionsByGroup(Object object);
}