CBG-4213: add attachment migration api (#7183)

* CBG-4213: add attachment migration api

* tidy up

* fix api docs lint error

* Update db/background_mgr_attachment_migration.go

Co-authored-by: Ben Brooks <ben.brooks@couchbase.com>

* Update db/background_mgr_attachment_migration.go

Co-authored-by: Ben Brooks <ben.brooks@couchbase.com>

---------

Co-authored-by: Ben Brooks <ben.brooks@couchbase.com>

Author: gregns1

db/background_mgr_attachment_migration.go

@@ -66,9 +66,14 @@ func (a *AttachmentMigrationManager) Init(ctx context.Context, options map[strin
 		var statusDoc AttachmentMigrationManagerStatusDoc
 		err := base.JSONUnmarshal(clusterStatus, &statusDoc)
 
+		reset, _ := options["reset"].(bool)
+		if reset {
+			base.InfofCtx(ctx, base.KeyAll, "Attachment Migration: Resetting migration process. Will not resume any partially completed process")
+		}
+
 		// If the previous run completed, or there was an error during unmarshalling the status we will start the
 		// process from scratch with a new migration ID. Otherwise, we should resume with the migration ID, stats specified in the doc.
-		if statusDoc.State == BackgroundProcessStateCompleted || err != nil {
+		if statusDoc.State == BackgroundProcessStateCompleted || err != nil || reset {
 			return newRunInit()
 		}
 		a.MigrationID = statusDoc.MigrationID

docs/api/admin.yaml

@@ -124,6 +124,8 @@ paths:
     $ref: ./paths/admin/_all_dbs.yaml
   '/{db}/_compact':
     $ref: './paths/admin/db-_compact.yaml'
+  '/{db}/_attachment_migration':
+    $ref: './paths/admin/db-_attachment_migration.yaml'
   '/{db}/':
     $ref: './paths/admin/db-.yaml'
   '/{keyspace}/':

docs/api/components/schemas.yaml

@@ -2099,6 +2099,41 @@ Resync-status:
     - docs_changed
     - docs_processed
   title: Resync-status
+Attachment-Migration-status:
+  description: The status of a attachment migration operation
+  type: object
+  properties:
+    status:
+      description: The status of the current attachment migration operation.
+      type: string
+      enum:
+        - running
+        - completed
+        - stopping
+        - stopped
+        - error
+    start_time:
+      description: The ISO-8601 date and time the attachment migration operation was started.
+      type: string
+    last_error:
+      description: The last error that occurred in the attachment migration operation (if any).
+      type: string
+    migration_id:
+      description: The UUID given to the attachment migration operation.
+      type: string
+    docs_changed:
+      description: The amount of documents that have had attachment metadata migrated as a result of attachment migration operation.
+      type: integer
+    docs_processed:
+      description: The amount of docs that have been processed through the attachment migration operation.
+      type: integer
+  required:
+    - status
+    - start_time
+    - last_error
+    - docs_changed
+    - docs_processed
+  title: Attachment-Migration-status
 Compact-status:
   description: The status returned from a compaction.
   type: object

docs/api/paths/admin/db-_attachment_migration.yaml

@@ -0,0 +1,73 @@
+# Copyright 2024-Present Couchbase, Inc.
+#
+# Use of this software is governed by the Business Source License included
+# in the file licenses/BSL-Couchbase.txt.  As of the Change Date specified
+# in that file, in accordance with the Business Source License, use of this
+# software will be governed by the Apache License, Version 2.0, included in
+# the file licenses/APL2.txt.
+parameters:
+  - $ref: ../../components/parameters.yaml#/db
+post:
+  summary: Manage a attachment migration operation
+  description: |-
+    This allows a new attachment migration operation to be done on the database, or to stop an existing running attachment migration operation.
+
+    Attachment Migration is a single node process and can only one node can be running it at one point.
+
+    Required Sync Gateway RBAC roles:
+
+    * Sync Gateway Architect
+  parameters:
+    - name: action
+      in: query
+      description: Defines whether the an attachment migration operation is being started or stopped.
+      schema:
+        type: string
+        default: start
+        enum:
+          - start
+          - stop
+    - name: reset
+      in: query
+      description: |-
+        This forces a fresh attachment migration start instead of trying to resume the previous failed migration operation.
+      schema:
+        type: boolean
+  responses:
+    '200':
+      description: Started or stopped compact operation successfully
+    '400':
+      $ref: ../../components/responses.yaml#/request-problem
+    '404':
+      $ref: ../../components/responses.yaml#/Not-found
+    '503':
+      description: Cannot start attachment migration due to another migration operation still running.
+      content:
+        application/json:
+          schema:
+            $ref: ../../components/schemas.yaml#/HTTP-Error
+  tags:
+    - Database Management
+  operationId: post_db-_attachment_migration
+get:
+  summary: Get the status of the most recent attachment migration operation
+  description: |-
+    This will retrieve the current status of the most recent attachment migration operation.
+
+    Required Sync Gateway RBAC roles:
+
+    * Sync Gateway Architect
+  responses:
+    '200':
+      description: Attachment migration status retrieved successfully
+      content:
+        application/json:
+          schema:
+            $ref: ../../components/schemas.yaml#/Attachment-Migration-status
+    '400':
+      $ref: ../../components/responses.yaml#/request-problem
+    '404':
+      $ref: ../../components/responses.yaml#/Not-found
+  tags:
+    - Database Management
+  operationId: get_db-_attachment_migration

rest/api.go

@@ -130,6 +130,52 @@ func (h *handler) handleGetCompact() error {
 	return nil
 }
 
+func (h *handler) handleAttachmentMigration() error {
+	action := h.getQuery("action")
+	if action == "" {
+		action = string(db.BackgroundProcessActionStart)
+	}
+	reset := h.getBoolQuery("reset")
+
+	if action != string(db.BackgroundProcessActionStart) && action != string(db.BackgroundProcessActionStop) {
+		return base.HTTPErrorf(http.StatusBadRequest, "Unknown parameter for 'action'. Must be start or stop")
+	}
+
+	if action == string(db.BackgroundProcessActionStart) {
+		err := h.db.AttachmentMigrationManager.Start(h.ctx(), map[string]interface{}{
+			"reset": reset,
+		})
+		if err != nil {
+			return err
+		}
+		status, err := h.db.AttachmentMigrationManager.GetStatus(h.ctx())
+		if err != nil {
+			return err
+		}
+		h.writeRawJSON(status)
+	} else if action == string(db.BackgroundProcessActionStop) {
+		err := h.db.AttachmentMigrationManager.Stop()
+		if err != nil {
+			return err
+		}
+		status, err := h.db.AttachmentMigrationManager.GetStatus(h.ctx())
+		if err != nil {
+			return err
+		}
+		h.writeRawJSON(status)
+	}
+	return nil
+}
+
+func (h *handler) handleGetAttachmentMigration() error {
+	status, err := h.db.AttachmentMigrationManager.GetStatus(h.ctx())
+	if err != nil {
+		return err
+	}
+	h.writeRawJSON(status)
+	return nil
+}
+
 func (h *handler) handleCompact() error {
 	action := h.getQuery("action")
 	if action == "" {