Add endpoint to undo a transaction from the history (#701)

* Add endpoint to undo a transaction from the history

* Update apispec

* Add undo GET endpoint

* Update tests/test_endpoints/test_history.py

Co-authored-by: Copilot <[email protected]>

* Add type hint

---------

Co-authored-by: Copilot <[email protected]>

Author: DavidMStraub

gramps_webapi/api/__init__.py

@@ -51,7 +51,11 @@
 from .resources.families import FamiliesResource, FamilyResource
 from .resources.file import MediaFileResource
 from .resources.filters import FilterResource, FiltersResource, FiltersResources
-from .resources.history import TransactionHistoryResource, TransactionsHistoryResource
+from .resources.history import (
+    TransactionHistoryResource,
+    TransactionUndoResource,
+    TransactionsHistoryResource,
+)
 from .resources.holidays import HolidayResource, HolidaysResource
 from .resources.import_media import MediaUploadZipResource
 from .resources.importers import (
@@ -152,6 +156,11 @@ def register_endpt(resource: Type[Resource], url: str, name: str):
     "/transactions/history/<int:transaction_id>",
     "transaction_history",
 )
+register_endpt(
+    TransactionUndoResource,
+    "/transactions/history/<int:transaction_id>/undo",
+    "transaction_undo",
+)
 # Token
 register_endpt(TokenResource, "/token/", "token")
 register_endpt(TokenRefreshResource, "/token/refresh/", "token_refresh")
@@ -162,7 +171,11 @@ def register_endpt(resource: Type[Resource], url: str, name: str):
 register_endpt(OIDCConfigResource, "/oidc/config/", "oidcconfigresource")
 register_endpt(OIDCTokenExchangeResource, "/oidc/tokens/", "oidctokenexchangeresource")
 register_endpt(OIDCLogoutResource, "/oidc/logout/", "oidclogoutresource")
-register_endpt(OIDCBackchannelLogoutResource, "/oidc/backchannel-logout/", "oidcbackchannellogoutresource")
+register_endpt(
+    OIDCBackchannelLogoutResource,
+    "/oidc/backchannel-logout/",
+    "oidcbackchannellogoutresource",
+)
 # People
 register_endpt(
     PersonTimelineResource, "/people/<string:handle>/timeline", "person-timeline"

gramps_webapi/api/resources/history.py

@@ -23,15 +23,32 @@
 from typing import Dict
 
 from flask import Response, current_app
+from flask_jwt_extended import get_jwt_identity
+from gramps.gen.db import REFERENCE_KEY
 from gramps.gen.db.dbconst import TXNADD, TXNDEL, TXNUPD
 from webargs import fields, validate
 
 from ...auth import get_all_user_details
-from ...auth.const import PERM_VIEW_PRIVATE
+from ...auth.const import PERM_ADD_OBJ, PERM_DEL_OBJ, PERM_EDIT_OBJ, PERM_VIEW_PRIVATE
 from ...const import TREE_MULTI
+from ...types import ResponseReturnValue
 from ..auth import require_permissions
-from ..util import get_db_handle, get_tree_from_jwt, use_args
+from ..tasks import (
+    AsyncResult,
+    make_task_response,
+    process_transactions,
+    run_task,
+    old_unchanged,
+)
+from ..util import (
+    abort_with_message,
+    get_db_handle,
+    get_tree_from_jwt,
+    get_tree_from_jwt_or_fail,
+    use_args,
+)
 from . import ProtectedResource
+from .util import reverse_transaction
 
 trans_code = {"delete": TXNDEL, "add": TXNADD, "update": TXNUPD}
 
@@ -83,7 +100,7 @@ def get(self, args: Dict) -> Response:
 
 
 class TransactionHistoryResource(ProtectedResource):
-    """Resource for database transaction history."""
+    """Resource for viewing individual transaction history."""
 
     @use_args(
         {
@@ -93,7 +110,7 @@ class TransactionHistoryResource(ProtectedResource):
         location="query",
     )
     def get(self, args: Dict, transaction_id: int) -> Response:
-        """Return a list of transactions."""
+        """Return a single transaction."""
         require_permissions([PERM_VIEW_PRIVATE])
         db_handle = get_db_handle()
         undodb = db_handle.undodb
@@ -110,6 +127,173 @@ def get(self, args: Dict, transaction_id: int) -> Response:
         return transaction
 
 
+class TransactionUndoResource(ProtectedResource):
+    """Resource for undoing transactions."""
+
+    def get(self, transaction_id: int) -> ResponseReturnValue:
+        """Check if a transaction can be undone without conflicts."""
+        require_permissions([PERM_VIEW_PRIVATE])
+
+        # Get the transaction to check
+        db_handle = get_db_handle()
+        undodb = db_handle.undodb
+        try:
+            transaction = undodb.get_transaction(
+                transaction_id=transaction_id,
+                old_data=True,
+                new_data=True,
+            )
+        except AttributeError:
+            abort_with_message(404, f"Transaction {transaction_id} not found")
+
+        if not transaction:
+            abort_with_message(404, f"Transaction {transaction_id} not found")
+
+        # Check each change in the transaction for conflicts
+        conflicts: list[dict] = []
+        can_undo_without_force = True
+
+        for change in transaction["changes"]:
+            # Skip reference entries as they are handled automatically by the database
+            if str(change["obj_class"]) == str(REFERENCE_KEY):
+                continue
+
+            class_name = change["obj_class"]
+            handle = change["obj_handle"]
+            old_data = change.get("old_data")
+
+            if change["trans_type"] == TXNDEL:
+                # Check if an object with this handle already exists (would be a conflict)
+                handle_func = db_handle.method("has_%s_handle", class_name)
+                if handle_func and handle_func(handle):
+                    conflicts.append(
+                        {
+                            "change_index": len(conflicts),
+                            "object_class": class_name,
+                            "handle": handle,
+                            "conflict_type": "object_exists",
+                            "description": f"Cannot undo delete: object with handle {handle} already exists",
+                        }
+                    )
+                    can_undo_without_force = False
+            else:
+                try:
+                    if change["trans_type"] == TXNADD:
+                        # For add transactions, check if current object differs from what was added (new_data)
+                        new_data = change.get("new_data")
+                        unchanged = old_unchanged(
+                            db_handle, class_name, handle, new_data
+                        )
+                    else:
+                        # For update transactions, check if current object differs from pre-update state (old_data)
+                        unchanged = old_unchanged(
+                            db_handle, class_name, handle, old_data
+                        )
+
+                    if not unchanged:
+                        conflicts.append(
+                            {
+                                "change_index": len(conflicts),
+                                "object_class": class_name,
+                                "handle": handle,
+                                "conflict_type": "object_changed",
+                                "description": f"Object {class_name} with handle {handle} has been modified since the original transaction",
+                            }
+                        )
+                        can_undo_without_force = False
+                except Exception as e:
+                    if "No handle function found" in str(e):
+                        # Skip objects we can't check (like references)
+                        continue
+                    conflicts.append(
+                        {
+                            "change_index": len(conflicts),
+                            "object_class": class_name,
+                            "handle": handle,
+                            "conflict_type": "check_failed",
+                            "description": f"Could not verify object state: {str(e)}",
+                        }
+                    )
+                    can_undo_without_force = False
+
+        result = {
+            "transaction_id": transaction_id,
+            "can_undo_without_force": can_undo_without_force,
+            "total_changes": len(
+                [
+                    c
+                    for c in transaction["changes"]
+                    if str(c["obj_class"]) != str(REFERENCE_KEY)
+                ]
+            ),
+            "conflicts_count": len(conflicts),
+            "conflicts": conflicts,
+        }
+
+        return result, 200
+
+    @use_args(
+        {
+            "force": fields.Boolean(load_default=False),
+        },
+        location="query",
+    )
+    def post(self, args: Dict, transaction_id: int) -> ResponseReturnValue:
+        """Undo a transaction using background processing."""
+        require_permissions([PERM_ADD_OBJ, PERM_EDIT_OBJ, PERM_DEL_OBJ])
+
+        # Get the transaction to undo
+        db_handle = get_db_handle()
+        undodb = db_handle.undodb
+        try:
+            transaction = undodb.get_transaction(
+                transaction_id=transaction_id,
+                old_data=True,
+                new_data=True,
+            )
+        except AttributeError:
+            # This happens when get_transaction returns None and we try to call _to_dict()
+            abort_with_message(404, f"Transaction {transaction_id} not found")
+
+        if not transaction:
+            abort_with_message(404, f"Transaction {transaction_id} not found")
+
+        # Convert transaction to the format expected by reverse_transaction
+        # Skip reference entries as they are handled automatically by the database
+        payload = []
+        for change in transaction["changes"]:
+            if str(change["obj_class"]) == str(REFERENCE_KEY):
+                continue  # Skip reference entries
+            item = {
+                "type": {TXNADD: "add", TXNUPD: "update", TXNDEL: "delete"}[
+                    change["trans_type"]
+                ],
+                "_class": change["obj_class"],
+                "handle": change["obj_handle"],
+                "old": change.get("old_data"),
+                "new": change.get("new_data"),
+            }
+            payload.append(item)
+
+        # Reverse the transaction
+        reversed_payload = reverse_transaction(payload)
+
+        tree = get_tree_from_jwt_or_fail()
+        user_id = get_jwt_identity()
+
+        # Always use background processing for undo operations
+        task = run_task(
+            process_transactions,
+            tree=tree,
+            user_id=user_id,
+            payload=reversed_payload,
+            force=args["force"],
+        )
+        if isinstance(task, AsyncResult):
+            return make_task_response(task)
+        return task, 200
+
+
 def get_user_dict() -> Dict[str, Dict[str, str]]:
     """Get a dictionary with user IDs to user names."""
     tree = get_tree_from_jwt()

gramps_webapi/data/apispec.yaml

@@ -5146,6 +5146,114 @@ paths:
         422:
           description: "Unprocessable Entity: Invalid or bad parameter provided."
 
+  /transactions/history/{transaction_id}/undo:
+    get:
+      tags:
+      - transactions
+      summary: "Check if a specific database transaction can be undone without conflicts."
+      operationId: checkUndoTransaction
+      security:
+        - Bearer: []
+      parameters:
+      - name: transaction_id
+        in: path
+        required: true
+        type: integer
+        description: "The ID of the transaction to check for undo feasibility."
+      responses:
+        200:
+          description: "OK: Undo feasibility check completed successfully."
+          schema:
+            type: object
+            properties:
+              transaction_id:
+                type: integer
+                description: "The ID of the transaction that was checked."
+              can_undo_without_force:
+                type: boolean
+                description: "Whether the transaction can be undone without using the force parameter."
+              total_changes:
+                type: integer
+                description: "Total number of changes in the transaction."
+              conflicts_count:
+                type: integer
+                description: "Number of conflicts that would prevent undo without force."
+              conflicts:
+                type: array
+                description: "List of specific conflicts found during the check."
+                items:
+                  type: object
+                  properties:
+                    change_index:
+                      type: integer
+                      description: "Index of the conflicting change within the transaction."
+                    object_class:
+                      type: string
+                      description: "Class of the conflicting object (e.g., 'Person', 'Family')."
+                    handle:
+                      type: string
+                      description: "Handle of the conflicting object."
+                    conflict_type:
+                      type: string
+                      description: "Type of conflict (e.g., 'object_changed', 'object_exists')."
+                    description:
+                      type: string
+                      description: "Human-readable description of the conflict."
+        400:
+          description: "Bad Request: Malformed request could not be parsed."
+        401:
+          description: "Unauthorized: Missing authorization header."
+        403:
+          description: "Forbidden: Insufficient permissions to check undo transactions."
+        404:
+          description: "Not Found: Transaction with the specified ID was not found."
+        422:
+          description: "Unprocessable Entity: Invalid or bad parameter provided."
+    post:
+      tags:
+      - transactions
+      summary: "Undo a specific database transaction using background processing."
+      operationId: undoTransaction
+      security:
+        - Bearer: []
+      parameters:
+      - name: transaction_id
+        in: path
+        required: true
+        type: integer
+        description: "The ID of the transaction to undo."
+      - name: force
+        in: query
+        required: false
+        type: boolean
+        description: "If true, force undoing the transaction even if objects have been modified since the original transaction."
+      responses:
+        200:
+          description: "OK: Transaction undo completed successfully."
+          schema:
+            type: array
+            items:
+              $ref: "#/definitions/Transaction"
+        202:
+          description: "Accepted: Transaction undo will be applied in the background."
+          schema:
+            type: object
+            properties:
+              task:
+                $ref: "#/definitions/TaskReference"
+        400:
+          description: "Bad Request: Malformed request could not be parsed."
+        401:
+          description: "Unauthorized: Missing authorization header."
+        403:
+          description: "Forbidden: Insufficient permissions to undo transactions."
+        404:
+          description: "Not Found: Transaction with the specified ID was not found."
+        409:
+          description: "Conflict: Objects have changed since the original transaction and force parameter was not used."
+        422:
+          description: "Unprocessable Entity: Invalid or bad parameter provided."
+
 
 
 ##############################################################################