/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.apache.cassandra.auth;

import java.util.Map;
import java.util.Set;

import org.apache.cassandra.exceptions.ConfigurationException;
import org.apache.cassandra.exceptions.RequestExecutionException;
import org.apache.cassandra.exceptions.RequestValidationException;

/**
 * Responsible for managing roles (which also includes what
 * used to be known as users), including creation, deletion,
 * alteration and the granting and revoking of roles to other
 * roles.
 */
public interface IRoleManager
{

    /**
     * Supported options for CREATE ROLE/ALTER ROLE (and
     * CREATE USER/ALTER USER, which are aliases provided
     * for backwards compatibility).
     */
    public enum Option
    {
        SUPERUSER, PASSWORD, LOGIN, OPTIONS
    }

    /**
     * Set of options supported by CREATE ROLE and ALTER ROLE queries.
     * Should never return null - always return an empty set instead.
     */
    Set<Option> supportedOptions();

    /**
     * Subset of supportedOptions that users are allowed to alter when performing ALTER ROLE [themselves].
     * Should never return null - always return an empty set instead.
     */
    Set<Option> alterableOptions();

    /**
     * Called during execution of a CREATE ROLE statement.
     * options are guaranteed to be a subset of supportedOptions().
     *
     * @param performer User issuing the create role statement.
     * @param role Rolei being created
     * @param options Options the role will be created with
     * @throws RequestValidationException
     * @throws RequestExecutionException
     */
    void createRole(AuthenticatedUser performer, RoleResource role, RoleOptions options)
    throws RequestValidationException, RequestExecutionException;

    /**
     * Called during execution of DROP ROLE statement, as well we removing any main record of the role from the system
     * this implies that we want to revoke this role from all other roles that it has been granted to.
     *
     * @param performer User issuing the drop role statement.
     * @param role Role to be dropped.
     * @throws RequestValidationException
     * @throws RequestExecutionException
     */
    void dropRole(AuthenticatedUser performer, RoleResource role) throws RequestValidationException, RequestExecutionException;

    /**
     * Called during execution of ALTER ROLE statement.
     * options are always guaranteed to be a subset of supportedOptions(). Furthermore, if the actor performing the query
     * is not a superuser and is altering themself, then options are guaranteed to be a subset of alterableOptions().
     * Keep the body of the method blank if your implementation doesn't support modification of any options.
     *
     * @param performer User issuing the alter role statement.
     * @param role Role that will be altered.
     * @param options Options to alter.
     * @throws RequestValidationException
     * @throws RequestExecutionException
     */
    void alterRole(AuthenticatedUser performer, RoleResource role, RoleOptions options)
    throws RequestValidationException, RequestExecutionException;

    /**
     * Called during execution of GRANT ROLE query.
     * Grant an role to another existing role. A grantee that has a role granted to it will inherit any
     * permissions of the granted role.
     *
     * @param performer User issuing the grant statement.
     * @param role Role to be granted to the grantee.
     * @param grantee Role acting as the grantee.
     * @throws RequestValidationException
     * @throws RequestExecutionException
     */
    void grantRole(AuthenticatedUser performer, RoleResource role, RoleResource grantee)
    throws RequestValidationException, RequestExecutionException;

    /**
     * Called during the execution of a REVOKE ROLE query.
     * Revoke an granted role from an existing role. The revokee will lose any permissions inherited from the role being
     * revoked.
     *
     * @param performer User issuing the revoke statement.
     * @param role Role to be revoked.
     * @param revokee Role from which the granted role is to be revoked.
     * @throws RequestValidationException
     * @throws RequestExecutionException
     */
    void revokeRole(AuthenticatedUser performer, RoleResource role, RoleResource revokee)
    throws RequestValidationException, RequestExecutionException;

    /**
     * Called during execution of a LIST ROLES query.
     * Returns a set of roles that have been granted to the grantee using GRANT ROLE.
     *
     * @param grantee Role whose granted roles will be listed.
     * @param includeInherited if True will list inherited roles as well as those directly granted to the grantee.
     * @return A list containing the granted roles for the user.
     * @throws RequestValidationException
     * @throws RequestExecutionException
     */
    Set<RoleResource> getRoles(RoleResource grantee, boolean includeInherited) throws RequestValidationException, RequestExecutionException;

    /**
     * Called during the execution of an unqualified LIST ROLES query.
     * Returns the total set of distinct roles in the system.
     *
     * @return the set of all roles in the system.
     * @throws RequestValidationException
     * @throws RequestExecutionException
     */
    Set<RoleResource> getAllRoles() throws RequestValidationException, RequestExecutionException;

    /**
     * Return true if there exists a Role with the given name that also has
     * superuser status. Superuser status may be inherited from another
     * granted role, so this method should return true if either the named
     * Role, or any other Role it is transitively granted has superuser
     * status.
     *
     * @param role Role whose superuser status to verify
     * @return true if the role exists and has superuser status, either
     * directly or transitively, otherwise false.
     */
    boolean isSuper(RoleResource role);

    /**
     * Return true if there exists a Role with the given name which has login
     * privileges. Such privileges is not inherited from other granted Roles
     * and so must be directly granted to the named Role with the LOGIN option
     * of CREATE ROLE or ALTER ROLE
     *
     * @param role Role whose login privileges to verify
     * @return true if the role exists and is permitted to login, otherwise false
     */
    boolean canLogin(RoleResource role);

    /**
     * Where an implementation supports OPTIONS in CREATE and ALTER operations
     * this method should return the Map<String, String> representing the custom
     * options associated with the role, as supplied to CREATE or ALTER.
     * It should never return null; if the implementation does not support
     * OPTIONS or if none were supplied then it should return an empty map.
     * @param role Role whose custom options are required
     * @return Key/Value pairs representing the custom options for the Role
     */
    Map<String, String> getCustomOptions(RoleResource role);

    /**
     * Return true is a Role with the given name exists in the system.
     *
     * @param role Role whose existence to verify
     * @return true if the name identifies an extant Role in the system,
     * otherwise false
     */
    boolean isExistingRole(RoleResource role);

    /**
     * Set of resources that should be made inaccessible to users and only accessible internally.
     *
     * @return Keyspaces and column families that will be unmodifiable by users; other resources.
     */
    Set<? extends IResource> protectedResources();

    /**
     * Hook to perform validation of an implementation's configuration (if supported).
     *
     * @throws ConfigurationException
     */
    void validateConfiguration() throws ConfigurationException;

    /**
     * Hook to perform implementation specific initialization, called once upon system startup.
     *
     * For example, use this method to create any required keyspaces/column families.
     */
    void setup();
}