Add tree endpoint (fixes #349) (#360)

* Start implementing tree endpoint

* Fix test

* Fix POST, add API spec

* Implement put

Author: DavidMStraub

gramps_webapi/api/__init__.py

@@ -84,6 +84,7 @@
 )
 from .resources.transactions import TransactionsResource
 from .resources.translations import TranslationResource, TranslationsResource
+from .resources.trees import TreeResource, TreesResource
 from .resources.types import (
     CustomTypeResource,
     CustomTypesResource,
@@ -162,6 +163,9 @@ def register_endpt(resource: Type[Resource], url: str, name: str):
 # Tags
 register_endpt(TagResource, "/tags/<string:handle>", "tag")
 register_endpt(TagsResource, "/tags/", "tags")
+# Trees
+register_endpt(TreeResource, "/trees/<string:tree_id>", "tree")
+register_endpt(TreesResource, "/trees/", "trees")
 # Types
 register_endpt(CustomTypeResource, "/types/custom/<string:datatype>", "custom-type")
 register_endpt(CustomTypesResource, "/types/custom/", "custom-types")

gramps_webapi/api/resources/trees.py

@@ -0,0 +1,131 @@
+#
+# Gramps Web API - A RESTful API for the Gramps genealogy program
+#
+# Copyright (C) 2023      David Straub
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Affero 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 Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+#
+
+"""Background task resources."""
+
+import os
+import re
+import uuid
+from typing import Dict, Optional
+
+from flask import abort, current_app
+from gramps.gen.config import config
+from webargs import fields
+from werkzeug.security import safe_join
+
+from ...auth.const import PERM_ADD_TREE, PERM_EDIT_OTHER_TREE, PERM_EDIT_TREE
+from ...dbmanager import WebDbManager
+from ..auth import require_permissions
+from ..util import get_tree_from_jwt, use_args
+from . import ProtectedResource
+
+# legal tree dirnames
+TREE_ID_REGEX = re.compile(r"^[a-zA-Z0-9_-]+$")
+
+
+def get_tree_details(tree_id: str) -> Dict[str, str]:
+    """Get details about a tree."""
+    try:
+        dbmgr = WebDbManager(dirname=tree_id, create_if_missing=False)
+    except ValueError:
+        abort(404)
+    return {"name": dbmgr.name, "id": tree_id}
+
+
+def get_tree_path(tree_id: str) -> Optional[str]:
+    """Get the path to the tree."""
+    dbdir = config.get("database.path")
+    return safe_join(dbdir, tree_id)
+
+
+def tree_exists(tree_id: str) -> bool:
+    """Check whether a tree exists."""
+    tree_path = get_tree_path(tree_id)
+    return tree_path and os.path.isdir(tree_path)
+
+
+def validate_tree_id(tree_id: str) -> None:
+    """Raise an error if the tree ID has an illegal format."""
+    if not TREE_ID_REGEX.match(tree_id):
+        abort(422)
+
+
+def get_single_tree_id() -> str:
+    """Get the tree ID in the case of using app.config['TREE']."""
+    dbmgr = WebDbManager(name=current_app.config["TREE"], create_if_missing=False)
+    return dbmgr.dirname
+
+
+class TreesResource(ProtectedResource):
+    """Resource for getting info about trees."""
+
+    def get(self):
+        """Get info about all trees."""
+        user_tree_id = get_tree_from_jwt() or get_single_tree_id()
+        # only allowed to see details about our own tree
+        tree_ids = [user_tree_id]
+        return [get_tree_details(tree_id) for tree_id in tree_ids]
+
+    @use_args(
+        {
+            "name": fields.Str(required=True),
+        },
+        location="json",
+    )
+    def post(self, args):
+        """Create a new tree."""
+        require_permissions([PERM_ADD_TREE])
+        tree_id = str(uuid.uuid4())
+        # TODO dbid
+        dbmgr = WebDbManager(dirname=tree_id, name=args["name"], create_if_missing=True)
+        return {"name": args["name"], "tree_id": dbmgr.dirname}, 201
+
+
+class TreeResource(ProtectedResource):
+    """Resource for a single tree."""
+
+    def get(self, tree_id: str):
+        """Get info about a tree."""
+        validate_tree_id(tree_id)
+        user_tree_id = get_tree_from_jwt() or get_single_tree_id()
+        if tree_id != user_tree_id:
+            # only allowed to see details about our own tree
+            abort(403)
+        return get_tree_details(tree_id)
+
+    @use_args(
+        {
+            "name": fields.Str(required=True),
+        },
+        location="json",
+    )
+    def put(self, args, tree_id: str):
+        """Modify a tree."""
+        user_tree_id = get_tree_from_jwt() or get_single_tree_id()
+        if tree_id == user_tree_id:
+            require_permissions([PERM_EDIT_TREE])
+        else:
+            require_permissions([PERM_EDIT_OTHER_TREE])
+            validate_tree_id(tree_id)
+        try:
+            dbmgr = WebDbManager(dirname=tree_id, create_if_missing=False)
+        except ValueError:
+            abort(404)
+        old_name, new_name = dbmgr.rename_database(new_name=args["name"])
+        return {"old_name": old_name, "new_name": new_name}

gramps_webapi/auth/const.py

@@ -37,6 +37,8 @@
 PERM_EDIT_OTHER_TREE_USER_ROLE = "EditOtherTreeUserRole"
 PERM_VIEW_OTHER_TREE_USER = "ViewOtherTreeUser"
 PERM_DEL_OTHER_TREE_USER = "DeleteOtherTreeUser"
+PERM_EDIT_OTHER_TREE = "EditOtherTree"
+PERM_ADD_TREE = "AddTree"
 
 # User permissions
 PERM_ADD_USER = "AddUser"
@@ -55,6 +57,7 @@
 PERM_EDIT_SETTINGS = "EditSettings"
 PERM_TRIGGER_REINDEX = "TriggerReindex"
 PERM_EDIT_NAME_GROUP = "EditNameGroup"
+PERM_EDIT_TREE = "EditTree"
 
 PERMISSIONS = {}
 
@@ -89,6 +92,7 @@
     PERM_VIEW_OTHER_USER,
     PERM_IMPORT_FILE,
     PERM_TRIGGER_REINDEX,
+    PERM_EDIT_TREE,
 }
 
 PERMISSIONS[ROLE_ADMIN] = PERMISSIONS[ROLE_OWNER] | {
@@ -100,6 +104,8 @@
     PERM_DEL_OTHER_TREE_USER,
     PERM_VIEW_SETTINGS,
     PERM_EDIT_SETTINGS,
+    PERM_EDIT_OTHER_TREE,
+    PERM_ADD_TREE,
 }
 
 # keys/values for user claims

gramps_webapi/data/apispec.yaml

@@ -6571,6 +6571,122 @@ paths:
           description: "Unauthorized: Missing authorization header."
 
 
+##############################################################################
+# Endpoint - Trees
+##############################################################################
+
+  /trees/:
+    get:
+      tags:
+      - trees
+      summary: "Return information about multiple trees."
+      operationId: getTree
+      security:
+        - Bearer: []
+      responses:
+        200:
+          description: "OK: Successful operation."
+          schema:
+            type: array
+            items:
+              $ref: "#/definitions/Tree"
+        401:
+          description: "Unauthorized: Missing authorization header."
+        422:
+          description: "Unprocessable Entity: Invalid token."
+    post:
+      parameters:
+      - name: name
+        in: body
+        required: true
+        description: "The name of the tree."
+        type: string
+      tags:
+      - trees
+      summary: "Create a new empty tree."
+      operationId: addTree
+      security:
+        - Bearer: []
+      responses:
+        201:
+          description: "OK: resource created."
+          schema:
+            type: object
+            properties:
+              name:
+                description: "The tree name."
+                type: string
+              tree_id:
+                description: "The tree ID."
+                type: string
+        401:
+          description: "Unauthorized: Missing authorization header."
+        404:
+          description: "Not found: tree does not exist."
+        422:
+          description: "Unprocessable Entity: Invalid token."
+
+
+  /trees/{tree_id}:
+    parameters:
+      - name: tree_id
+        in: path
+        required: true
+        type: string
+        description: "The tree ID."
+    get:
+      tags:
+      - trees
+      summary: "Return information about a tree."
+      operationId: getTree
+      security:
+        - Bearer: []
+      responses:
+        200:
+          description: "OK: Successful operation."
+          schema:
+            $ref: "#/definitions/Tree"
+        401:
+          description: "Unauthorized: Missing authorization header."
+        404:
+          description: "Not found: tree does not exist."
+        422:
+          description: "Unprocessable Entity: Invalid token."
+    put:
+      parameters:
+        - name: tree_id
+          in: path
+          required: true
+          type: string
+          description: "The tree ID."
+      tags:
+      - trees
+      summary: "Update details about a tree."
+      operationId: updateTree
+      security:
+        - Bearer: []
+      responses:
+        200:
+          description: "OK: Successful operation."
+          schema:
+            type: object
+            properties:
+              old_name:
+                description: "The old tree name."
+                type: string
+              new_name:
+                description: "The new tree name."
+                type: string
+        401:
+          description: "Unauthorized: Missing authorization header."
+        403:
+          description: "Unauthorized: insufficient permissions."
+        404:
+          description: "Not found: tree does not exist."
+        422:
+          description: "Unprocessable Entity: Invalid token."
+
+
 ##############################################################################
 # Model definitions
 ##############################################################################
@@ -9902,3 +10018,19 @@ definitions:
         description: "The unique identifier for a task."
         type: string
         example: "b9ed86ea-1c6b-400a-bb70-af9cb11bdf13"
+
+##############################################################################
+# Model - Tree
+##############################################################################
+
+  Tree:
+    type: object
+    properties:
+      name:
+        description: "The name of the tree."
+        type: string
+        example: "Example Family"
+      id:
+        description: "The ID of the tree."
+        type: string
+        example: "b9ed86ea-1c6b-400a-bb70-af9cb11bdf13"

gramps_webapi/dbmanager.py

@@ -26,7 +26,7 @@
 import os
 import uuid
 
-from typing import Optional
+from typing import Optional, Tuple
 
 from gramps.cli.clidbman import CLIDbManager, NAME_FILE
 from gramps.cli.user import User
@@ -166,3 +166,15 @@ def get_db(self, readonly: bool = True, force_unlock: bool = False) -> DbState:
             self.path, mode=mode, username=self.username, password=self.password
         )
         return dbstate
+
+    def rename_database(self, new_name: str) -> Tuple[str, str]:
+        """Rename the database by writing the new value to the name.txt file.
+
+        Returns old_name, new_name.
+        """
+        filepath = os.path.join(self.dbdir, self.dirname, NAME_FILE)
+        with open(filepath, "r", encoding="utf8") as name_file:
+            old_name = name_file.read()
+        with open(filepath, "w", encoding="utf8") as name_file:
+            name_file.write(new_name)
+        return old_name, new_name