# -*- coding: utf-8 -*-

# This program is free software: you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation, either version 3 of the License, or

# (at your option) any later version.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program.  If not, see <http://www.gnu.org/licenses/>.

"""

kallithea.controllers.api.api

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

API controller for Kallithea

This file was forked by the Kallithea project in July 2014.

Original author and date, and relevant copyright and licensing information is below:

:created_on: Aug 20, 2011

:author: marcink

:copyright: (c) 2013 RhodeCode GmbH, and others.

:license: GPLv3, see LICENSE.md for more details.

"""

import time

import traceback

import logging

from sqlalchemy import or_

from kallithea import EXTERN_TYPE_INTERNAL

from kallithea.controllers.api import JSONRPCController, JSONRPCError

from kallithea.lib.auth import (

    PasswordGenerator, AuthUser, HasPermissionAllDecorator,

    HasPermissionAnyDecorator, HasPermissionAnyApi, HasRepoPermissionAnyApi,

    HasRepoGroupPermissionAnyApi, HasUserGroupPermissionAny)

from kallithea.lib.utils import map_groups, repo2db_mapper

from kallithea.lib.utils2 import (

    str2bool, time_to_datetime, safe_int, Optional, OAttr)

from kallithea.model.meta import Session

from kallithea.model.repo_group import RepoGroupModel

from kallithea.model.scm import ScmModel, UserGroupList

from kallithea.model.repo import RepoModel

from kallithea.model.user import UserModel

from kallithea.model.user_group import UserGroupModel

from kallithea.model.gist import GistModel

from kallithea.model.db import (

    Repository, Setting, UserIpMap, Permission, User, Gist,

    RepoGroup)

from kallithea.lib.compat import json

from kallithea.lib.exceptions import (

    DefaultUserException, UserGroupsAssignedException)

log = logging.getLogger(__name__)

def store_update(updates, attr, name):

    """

    Stores param in updates dict if it's not instance of Optional

    allows easy updates of passed in params

    """

    if not isinstance(attr, Optional):

        updates[name] = attr

def get_user_or_error(userid):

    """

    Get user by id or name or return JsonRPCError if not found

    :param userid:

    """

    user = UserModel().get_user(userid)

    if user is None:

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "user `<username>` already exist"

            or

            "email `<email>` already exist"

            or

            "failed to create user `<username>`"

          }

        """

        if User.get_by_username(username):

            raise JSONRPCError("user `%s` already exist" % (username,))

        if User.get_by_email(email, case_insensitive=True):

            raise JSONRPCError("email `%s` already exist" % (email,))

        if Optional.extract(extern_name):

            # generate temporary password if user is external

            password = PasswordGenerator().gen_password(length=8)

        try:

            user = UserModel().create_or_update(

                username=Optional.extract(username),

                password=Optional.extract(password),

                email=Optional.extract(email),

                firstname=Optional.extract(firstname),

                lastname=Optional.extract(lastname),

                active=Optional.extract(active),

                admin=Optional.extract(admin),

                extern_type=Optional.extract(extern_type),

                extern_name=Optional.extract(extern_name)

            )

            Session().commit()

            return dict(

                msg='created new user `%s`' % username,

                user=user.get_api_data()

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to create user `%s`' % (username,))

    @HasPermissionAllDecorator('hg.admin')

    def update_user(self, apiuser, userid, username=Optional(None),

                    firstname=Optional(None), lastname=Optional(None),

                    active=Optional(None), admin=Optional(None),

        """

        updates given user if such user exists. This command can

        be executed only using api_key belonging to user with admin rights.

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param userid: userid to update

        :type userid: str or int

        :param username: new username

        :type username: str or int

        :param email: email

        :type email: str

        :param password: password

        :type password: Optional(str)

        :param firstname: firstname

        :type firstname: Optional(str)

        :param lastname: lastname

        :type lastname: Optional(str)

        :param active: active

        :type active: Optional(bool)

        :param admin: admin

        :type admin: Optional(bool)

        :param extern_name:

        :type extern_name: Optional(str)

        :param extern_type:

        :type extern_type: Optional(str)

        OUTPUT::

            id : <id_given_in_input>

            result: {

                      "msg" : "updated user ID:<userid> <username>",

                      "user": <user_object>,

                    }

            error:  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "failed to update user `<username>`"

          }

        """

        user = get_user_or_error(userid)

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param usergroupid:

        :type usergroupid: int

        OUTPUT::

          id : <id_given_in_input>

          result : {

            "msg": "deleted user group ID:<user_group_id> <user_group_name>"

          }

          error :  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "failed to delete user group ID:<user_group_id> <user_group_name>"

            or

            "RepoGroup assigned to <repo_groups_list>"

          }

        """

        user_group = get_user_group_or_error(usergroupid)

        if not HasPermissionAnyApi('hg.admin')(user=apiuser):

            # check if we have admin permission for this user group !

            _perms = ('usergroup.admin',)

            if not HasUserGroupPermissionAny(*_perms)(

                    user=apiuser, user_group_name=user_group.users_group_name):

                raise JSONRPCError('user group `%s` does not exist' % (usergroupid,))

        try:

            UserGroupModel().delete(user_group)

            Session().commit()

            return dict(

                msg='deleted user group ID:%s %s' %

                    (user_group.users_group_id, user_group.users_group_name),

                user_group=None

            )

        except UserGroupsAssignedException as e:

            log.error(traceback.format_exc())

            raise JSONRPCError(str(e))

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to delete user group ID:%s %s' %

                               (user_group.users_group_id,

                                user_group.users_group_name)

    # permission check inside

    def add_user_to_user_group(self, apiuser, usergroupid, userid):

        """

        Adds a user to a user group. If user exists in that group success will be

        `false`. This command can be executed only using api_key

        belonging to user with admin rights  or an admin of given user group

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param usergroupid:

        :type usergroupid: int

        :param userid:

        :type userid: int

        OUTPUT::

          id : <id_given_in_input>

          result : {

              "success": True|False # depends on if member is in group

              "msg": "added member `<username>` to user group `<groupname>` |

                      User is already in that group"

          }

          error :  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "failed to add member to user group `<user_group_name>`"

          }

        """

        user = get_user_or_error(userid)

        user_group = get_user_group_or_error(usergroupid)

        if not HasPermissionAnyApi('hg.admin')(user=apiuser):

            # check if we have admin permission for this user group !

            _perms = ('usergroup.admin',)

            if not HasUserGroupPermissionAny(*_perms)(

                    user=apiuser, user_group_name=user_group.users_group_name):

                raise JSONRPCError('user group `%s` does not exist' % (usergroupid,))

        try:

            ugm = UserGroupModel().add_user_to_group(user_group, user)

            success = True if ugm != True else False

            msg = 'added member `%s` to user group `%s`' % (

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param repo_name: repository name

        :type repo_name: str

        :param owner: user_id or username

        :type owner: Optional(str)

        :param repo_type: 'hg' or 'git'

        :type repo_type: Optional(str)

        :param description: repository description

        :type description: Optional(str)

        :param private:

        :type private: bool

        :param clone_uri:

        :type clone_uri: str

        :param landing_rev: <rev_type>:<rev>

        :type landing_rev: str

        :param enable_locking:

        :type enable_locking: bool

        :param enable_downloads:

        :type enable_downloads: bool

        :param enable_statistics:

        :type enable_statistics: bool

        :param copy_permissions: Copy permission from group that repository is

            being created.

        :type copy_permissions: bool

        OUTPUT::

            id : <id_given_in_input>

            result: {

                      "msg": "Created new repository `<reponame>`",

                      "success": true,

                      "task": "<celery task id or None if done sync>"

                    }

            error:  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

             'failed to create repository `<repo_name>`

          }

        """

        if not HasPermissionAnyApi('hg.admin')(user=apiuser):

            if not isinstance(owner, Optional):

                raise JSONRPCError(

                    'Only Kallithea admin can specify `owner` param'

                )

        if isinstance(owner, Optional):

            owner = apiuser.user_id

        owner = get_user_or_error(owner)

        if RepoModel().get_by_repo_name(repo_name):

            raise JSONRPCError("repo `%s` already exist" % repo_name)

        defs = Setting.get_default_repo_settings(strip_prefix=True)

        if isinstance(private, Optional):

            private = defs.get('repo_private') or Optional.extract(private)

        if isinstance(repo_type, Optional):

            repo_type = defs.get('repo_type')

        if isinstance(enable_statistics, Optional):

            enable_statistics = defs.get('repo_enable_statistics')

        if isinstance(enable_locking, Optional):

            enable_locking = defs.get('repo_enable_locking')

        if isinstance(enable_downloads, Optional):

            enable_downloads = defs.get('repo_enable_downloads')

        clone_uri = Optional.extract(clone_uri)

        description = Optional.extract(description)

        landing_rev = Optional.extract(landing_rev)

        copy_permissions = Optional.extract(copy_permissions)

        try:

            repo_name_cleaned = repo_name.split('/')[-1]

            # create structure of groups and return the last group

            repo_group = map_groups(repo_name)

            data = dict(

                repo_name=repo_name_cleaned,

                repo_name_full=repo_name,

                repo_type=repo_type,

                repo_description=description,

                owner=owner,

                repo_private=private,

                clone_uri=clone_uri,

                repo_group=repo_group,

                repo_landing_rev=landing_rev,

                enable_statistics=enable_statistics,

                enable_locking=enable_locking,

                enable_downloads=enable_downloads,

                repo_copy_permissions=copy_permissions,

            )

                task=task_id

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError(

                'failed to create repository `%s`' % (repo_name,))

    # permission check inside

    def update_repo(self, apiuser, repoid, name=Optional(None),

                    owner=Optional(OAttr('apiuser')),

                    group=Optional(None),

                    description=Optional(''), private=Optional(False),

                    clone_uri=Optional(None), landing_rev=Optional('rev:tip'),

                    enable_statistics=Optional(False),

                    enable_locking=Optional(False),

                    enable_downloads=Optional(False)):

        """

        Updates repo

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param repoid: repository name or repository id

        :type repoid: str or int

        :param name:

        :param owner:

        :param group:

        :param description:

        :param private:

        :param clone_uri:

        :param landing_rev:

        :param enable_statistics:

        :param enable_locking:

        :param enable_downloads:

        """

        repo = get_repo_or_error(repoid)

        if not HasPermissionAnyApi('hg.admin')(user=apiuser):

            # check if we have admin permission for this repo !

            if not HasRepoPermissionAnyApi('repository.admin')(user=apiuser,

                                                               repo_name=repo.repo_name):

                raise JSONRPCError('repository `%s` does not exist' % (repoid,))

            if (name != repo.repo_name and

                not HasPermissionAnyApi('hg.create.repository')(user=apiuser)

                ):

                raise JSONRPCError('no permission to create (or move) repositories')

            if not isinstance(owner, Optional):

                raise JSONRPCError(

                    'Only Kallithea admin can specify `owner` param'

                )

        updates = {

            # update function requires this.

            'repo_name': repo.repo_name

        }

        repo_group = group

        if not isinstance(repo_group, Optional):

            repo_group = get_repo_group_or_error(repo_group)

            repo_group = repo_group.group_id

        try:

            store_update(updates, name, 'repo_name')

            store_update(updates, repo_group, 'repo_group')

            store_update(updates, owner, 'user')

            store_update(updates, description, 'repo_description')

            store_update(updates, private, 'repo_private')

            store_update(updates, clone_uri, 'clone_uri')

            store_update(updates, landing_rev, 'repo_landing_rev')

            store_update(updates, enable_statistics, 'repo_enable_statistics')

            store_update(updates, enable_locking, 'repo_enable_locking')

            store_update(updates, enable_downloads, 'repo_enable_downloads')

            RepoModel().update(repo, **updates)

            Session().commit()

            return dict(

                msg='updated repo ID:%s %s' % (repo.repo_id, repo.repo_name),

                repository=repo.get_api_data()

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to update repo `%s`' % repoid)

    @HasPermissionAnyDecorator('hg.admin', 'hg.fork.repository')

    def fork_repo(self, apiuser, repoid, fork_name,

                  owner=Optional(OAttr('apiuser')),

                  description=Optional(''), copy_permissions=Optional(False),

                  private=Optional(False), landing_rev=Optional('rev:tip')):

        """

        Creates a fork of given repo. In case of using celery this will

        immediately return success message, while fork is going to be created

        asynchronous. This command can be executed only using api_key belonging to

        user with admin rights or regular user that have fork permission, and at least

        read access to forking repository. Regular users cannot specify owner parameter.

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :type repoid: str or int

        :param fork_name:

        :param owner:

        :param description:

        :param copy_permissions:

        :param private:

        :param landing_rev:

        INPUT::

            id : <id_for_response>

            api_key : "<api_key>"

            args:     {

                        "repoid" :          "<reponame or repo_id>",

                        "fork_name":        "<forkname>",

                        "owner":            "<username or user_id = Optional(=apiuser)>",

                        "description":      "<description>",

                        "copy_permissions": "<bool>",

                        "private":          "<bool>",

                        "landing_rev":      "<landing_rev>"

                      }

        OUTPUT::

            id : <id_given_in_input>

            result: {

                      "msg": "Created fork of `<reponame>` as `<forkname>`",

                      "success": true,

                      "task": "<celery task id or None if done sync>"

                    }

            error:  null

        """

        repo = get_repo_or_error(repoid)

        repo_name = repo.repo_name

        _repo = RepoModel().get_by_repo_name(fork_name)

        if _repo:

            type_ = 'fork' if _repo.fork else 'repo'

            raise JSONRPCError("%s `%s` already exist" % (type_, fork_name))

        if HasPermissionAnyApi('hg.admin')(user=apiuser):

            pass

        elif HasRepoPermissionAnyApi('repository.admin',

                                     'repository.write',

                                     'repository.read')(user=apiuser,

                                                        repo_name=repo.repo_name):

            if not isinstance(owner, Optional):

                raise JSONRPCError(

                    'Only Kallithea admin can specify `owner` param'

                )

            if not HasPermissionAnyApi('hg.create.repository')(user=apiuser):

                raise JSONRPCError('no permission to create repositories')

        else:

            raise JSONRPCError('repository `%s` does not exist' % (repoid,))

        if isinstance(owner, Optional):

            owner = apiuser.user_id

        owner = get_user_or_error(owner)

        try:

            # create structure of groups and return the last group

            group = map_groups(fork_name)

            form_data = dict(

                repo_name=fork_name,

                repo_name_full=fork_name,

                repo_group=group,

                repo_type=repo.repo_type,

                description=Optional.extract(description),

                private=Optional.extract(private),

                copy_permissions=Optional.extract(copy_permissions),

                landing_rev=Optional.extract(landing_rev),

                update_after_clone=False,

                fork_parent_id=repo.repo_id,

            )

            task = RepoModel().create_fork(form_data, cur_user=owner)

            # no commit, it's done in RepoModel, or async via celery

            from celery.result import BaseAsyncResult

            task_id = None

            if isinstance(task, BaseAsyncResult):

                task_id = task.task_id

            return dict(

                msg='Created fork of `%s` as `%s`' % (repo.repo_name,

                                                      fork_name),

                success=True,  # cannot return the repo data here since fork

                               # can be done async

                task=task_id

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError(

                'failed to fork repository `%s` as `%s`' % (repo_name,

                                                            fork_name)

            )

    # permission check inside

    def delete_repo(self, apiuser, repoid, forks=Optional('')):

        """

        Deletes a repository. This command can be executed only using api_key belonging

        to user with admin rights or regular user that have admin access to repository.

        When `forks` param is set it's possible to detach or delete forks of deleting

        repository

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param repoid: repository name or repository id

        :type repoid: str or int

        :param forks: `detach` or `delete`, what do do with attached forks for repo

        :type forks: Optional(str)

        OUTPUT::

            id : <id_given_in_input>

            result: {

                      "msg": "Deleted repository `<reponame>`",

                      "success": true

                    }

            error:  null

        """

        repo = get_repo_or_error(repoid)

        if not HasPermissionAnyApi('hg.admin')(user=apiuser):

            # check if we have admin permission for this repo !

            if not HasRepoPermissionAnyApi('repository.admin')(user=apiuser,

                raise JSONRPCError('repository `%s` does not exist' % (repoid,))

        try:

            handle_forks = Optional.extract(forks)

            _forks_msg = ''

            _forks = [f for f in repo.forks]

            if handle_forks == 'detach':

                _forks_msg = ' ' + 'Detached %s forks' % len(_forks)

            elif handle_forks == 'delete':

                _forks_msg = ' ' + 'Deleted %s forks' % len(_forks)

            elif _forks:

                raise JSONRPCError(

                    'Cannot delete `%s` it still contains attached forks' %

                    (repo.repo_name,)

                )

            RepoModel().delete(repo, forks=forks)

            Session().commit()

            return dict(

                msg='Deleted repository `%s`%s' % (repo.repo_name, _forks_msg),

                success=True

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError(

                'failed to delete repository `%s`' % (repo.repo_name,)

            )

    @HasPermissionAllDecorator('hg.admin')

    def grant_user_permission(self, apiuser, repoid, userid, perm):

        """

        Grant permission for user on given repository, or update existing one

        if found. This command can be executed only using api_key belonging to user

        with admin rights.

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param repoid: repository name or repository id

        :type repoid: str or int

        :param userid:

        :param perm: (repository.(none|read|write|admin))

        :type perm: str

        OUTPUT::

            id : <id_given_in_input>

            result: {

                      "msg" : "Granted perm: `<perm>` for user: `<username>` in repo: `<reponame>`",

                repo_group=repo_group.get_api_data()

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to update repository group `%s`'

                               % (repogroupid,))

    @HasPermissionAllDecorator('hg.admin')

    def delete_repo_group(self, apiuser, repogroupid):

        """

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param repogroupid: name or id of repository group

        :type repogroupid: str or int

        OUTPUT::

          id : <id_given_in_input>

          result : {

            'msg': 'deleted repo group ID:<repogroupid> <repogroupname>

            'repo_group': null

          }

          error :  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "failed to delete repo group ID:<repogroupid> <repogroupname>"

          }

        """

        repo_group = get_repo_group_or_error(repogroupid)

        try:

            RepoGroupModel().delete(repo_group)

            Session().commit()

            return dict(

                msg='deleted repo group ID:%s %s' %

                    (repo_group.group_id, repo_group.group_name),

                repo_group=None

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to delete repo group ID:%s %s' %

                               (repo_group.group_id, repo_group.group_name)

    # permission check inside

    def grant_user_permission_to_repo_group(self, apiuser, repogroupid, userid,

                                            perm, apply_to_children=Optional('none')):

        """

        Grant permission for user on given repository group, or update existing

        one if found. This command can be executed only using api_key belonging

        to user with admin rights, or user who has admin right to given repository

        group.

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param repogroupid: name or id of repository group

        :type repogroupid: str or int

        :param userid:

        :param perm: (group.(none|read|write|admin))

        :type perm: str

        :param apply_to_children: 'none', 'repos', 'groups', 'all'

        :type apply_to_children: str

        OUTPUT::

            id : <id_given_in_input>

            result: {

                      "msg" : "Granted perm: `<perm>` (recursive:<apply_to_children>) for user: `<username>` in repo group: `<repo_group_name>`",

                      "success": true

                    }

            error:  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "failed to edit permission for user: `<userid>` in repo group: `<repo_group_name>`"

          }

        """

        repo_group = get_repo_group_or_error(repogroupid)

        if not HasPermissionAnyApi('hg.admin')(user=apiuser):

            # check if we have admin permission for this repo group !

            if not HasRepoGroupPermissionAnyApi('group.admin')(user=apiuser,

                                                               group_name=repo_group.group_name):

                raise JSONRPCError('repository group `%s` does not exist' % (repogroupid,))

        user = get_user_or_error(userid)

                      "msg" : "Revoked perm (recursive:<apply_to_children>) for user: `<username>` in repo group: `<repo_group_name>`",

                      "success": true

                    }

            error:  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "failed to edit permission for user: `<userid>` in repo group: `<repo_group_name>`"

          }

        """

        repo_group = get_repo_group_or_error(repogroupid)

        if not HasPermissionAnyApi('hg.admin')(user=apiuser):

            # check if we have admin permission for this repo group !

            if not HasRepoGroupPermissionAnyApi('group.admin')(user=apiuser,

                                                               group_name=repo_group.group_name):

                raise JSONRPCError('repository group `%s` does not exist' % (repogroupid,))

        user = get_user_or_error(userid)

        apply_to_children = Optional.extract(apply_to_children)

        try:

            RepoGroupModel().delete_permission(repo_group=repo_group,

                                               obj=user,

                                               obj_type="user",

                                               recursive=apply_to_children)

            Session().commit()

            return dict(

                msg='Revoked perm (recursive:%s) for user: `%s` in repo group: `%s`' % (

                    apply_to_children, user.username, repo_group.name

                ),

                success=True

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError(

                'failed to edit permission for user: `%s` in repo group: `%s`' % (

                    userid, repo_group.name))

    # permission check inside

    def grant_user_group_permission_to_repo_group(

            self, apiuser, repogroupid, usergroupid, perm,

        """

        Grant permission for user group on given repository group, or update

        existing one if found. This command can be executed only using

        api_key belonging to user with admin rights, or user who has admin

        right to given repository group.

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param repogroupid: name or id of repository group

        :type repogroupid: str or int

        :param usergroupid: id of usergroup

        :type usergroupid: str or int

        :param perm: (group.(none|read|write|admin))

        :type perm: str

        :param apply_to_children: 'none', 'repos', 'groups', 'all'

        :type apply_to_children: str

        OUTPUT::

          id : <id_given_in_input>

          result : {

            "msg" : "Granted perm: `<perm>` (recursive:<apply_to_children>) for user group: `<usersgroupname>` in repo group: `<repo_group_name>`",

            "success": true

          }

          error :  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "failed to edit permission for user group: `<usergroup>` in repo group: `<repo_group_name>`"

          }

        """

        repo_group = get_repo_group_or_error(repogroupid)

        perm = get_perm_or_error(perm, prefix='group.')

        user_group = get_user_group_or_error(usergroupid)

        if not HasPermissionAnyApi('hg.admin')(user=apiuser):

            # check if we have admin permission for this repo group !

            _perms = ('group.admin',)

            if not HasRepoGroupPermissionAnyApi(*_perms)(

                    user=apiuser, group_name=repo_group.group_name):

                raise JSONRPCError(

                    'repository group `%s` does not exist' % (repogroupid,))

            # check if we have at least read permission for this user group !

            _perms = ('usergroup.read', 'usergroup.write', 'usergroup.admin',)

            if not HasUserGroupPermissionAny(*_perms)(

                    user=apiuser, user_group_name=user_group.users_group_name):

                raise JSONRPCError(

                    'user group `%s` does not exist' % (usergroupid,))

        apply_to_children = Optional.extract(apply_to_children)

        try:

            RepoGroupModel().add_permission(repo_group=repo_group,

                                            obj=user_group,

                                            obj_type="user_group",

                                            perm=perm,

                                            recursive=apply_to_children)

            Session().commit()

            return dict(

                msg='Granted perm: `%s` (recursive:%s) for user group: `%s` in repo group: `%s`' % (

                success=True