add documentation

- added docstrings
- updated api spec

Author: RIT3shSapata

docs/api/admin.yaml

@@ -53,8 +53,6 @@ paths:
     $ref: './paths/admin/db-_user-name-_session-sessionid.yaml'
   '/{db}/_user/{name}/_history':
     $ref: './paths/admin/db-_user-name-_history.yaml'
-  '/{db}/_user/{name}/_history/compact':
-    $ref: './paths/admin/db-_user-name-_history-compact.yaml'
   '/{db}/_role/':
     $ref: './paths/admin/db-_role-.yaml'
   '/{db}/_role/{name}':

docs/api/paths/admin/db-_user-name-_history-compact.yaml

@@ -40,3 +40,51 @@ get:
   tags:
     - Database Security
   operationId: get_db-_user-name-_history
+post:
+  summary: Compact user's channel history
+  description: |-
+    Remove specified channels from a user's channel history.
+
+    Required Sync Gateway RBAC roles:
+
+    * Sync Gateway Architect
+    * Sync Gateway Application
+  requestBody:
+    description: Channels to be compacted from the user
+    content:
+      application/json:
+        schema:
+          $ref: ../../components/schemas.yaml#/UserHistory
+        example:
+          channels:
+            scope1:
+              collection1:
+                - scoped_channel1
+  responses:
+    '200':
+      description: Channels compacted successfully from user
+      content:
+        application/json:
+          schema:
+            $ref: ../../components/schemas.yaml#/UserHistory
+          example:
+            channels:
+              scope1:
+                collection1:
+                  - scoped_channel2
+    '400':
+      description: Bad request. Invalid channel names or malformed request body.
+      content:
+        application/json:
+          schema:
+            $ref: ../../components/schemas.yaml#/HTTP-Error
+          example:
+            error: "Bad Request"
+            reason: "Invalid channel format: channels must be non-empty strings"
+    '403':
+      $ref: ../../components/responses.yaml#/Unauthorized-database
+    '404':
+      $ref: ../../components/responses.yaml#/Not-found
+  tags:
+    - Database Security
+  operationId: post_db-_user-name-_history-compact

docs/api/paths/admin/db-_user-name-_history.yaml

@@ -1622,16 +1622,19 @@ func TestDeletedRoleChanHistory(t *testing.T) {
 
 }
 
-// TestDisabledUser ensures that a disabled (non-guest) user cannot authenticate to make requests.
+// TestGetUserChannelHistory tests the GET /_user/{name}/_channel_history admin endpoint,
+// which returns the revoked channel history for a user across all scopes and collections.
 func TestGetUserChannelHistory(t *testing.T) {
 	rt := NewRestTester(t, nil)
 	defer rt.Close()
 
+	// Returns 404 when the requested user does not exist.
 	t.Run("UserNotFound", func(t *testing.T) {
 		response := rt.SendAdminRequest(http.MethodGet, "/db/_user/ghost/_channel_history", "")
 		RequireStatus(t, response, http.StatusNotFound)
 	})
 
+	// Returns empty history when the user has active channels but none have ever been revoked.
 	t.Run("UserWithNoChannelHistory", func(t *testing.T) {
 		ds := rt.GetSingleDataStore()
 		response := rt.SendAdminRequest(http.MethodPut, "/db/_user/user1",
@@ -1650,6 +1653,7 @@ func TestGetUserChannelHistory(t *testing.T) {
 		assert.Empty(t, channelHistory[scope][collection])
 	})
 
+	// Returns all channels that have been revoked from the user.
 	t.Run("UserWithChannelHistory", func(t *testing.T) {
 		ds := rt.GetSingleDataStore()
 		response := rt.SendAdminRequest(http.MethodPut, "/db/_user/user2",
@@ -1673,6 +1677,7 @@ func TestGetUserChannelHistory(t *testing.T) {
 		assert.ElementsMatch(t, []string{"chan1", "chan2"}, channelHistory[scope][collection])
 	})
 
+	// Returns only revoked channels; active channels do not appear in the history.
 	t.Run("UserWithPartialChannelHistory", func(t *testing.T) {
 		ds := rt.GetSingleDataStore()
 		response := rt.SendAdminRequest(http.MethodPut, "/db/_user/user3",
@@ -1696,6 +1701,7 @@ func TestGetUserChannelHistory(t *testing.T) {
 		assert.ElementsMatch(t, []string{"chan1", "chan2"}, channelHistory[scope][collection])
 	})
 
+	// Revocation history is preserved even after a previously revoked channel is re-granted.
 	t.Run("ChannelHistoryAfterReGrant", func(t *testing.T) {
 		ds := rt.GetSingleDataStore()
 		response := rt.SendAdminRequest(http.MethodPut, "/db/_user/user4",
@@ -1725,10 +1731,13 @@ func TestGetUserChannelHistory(t *testing.T) {
 	})
 }
 
+// TestCompactUserChannelHistory tests the POST /_user/{name}/_channel_history admin endpoint,
+// which removes specified channels from a user's revocation history and returns those that were found and removed.
 func TestCompactUserChannelHistory(t *testing.T) {
 	rt := NewRestTester(t, nil)
 	defer rt.Close()
 
+	// Returns 404 when the requested user does not exist.
 	t.Run("UserNotFound", func(t *testing.T) {
 		ds := rt.GetSingleDataStore()
 		scope := ds.ScopeName()
@@ -1738,6 +1747,7 @@ func TestCompactUserChannelHistory(t *testing.T) {
 		RequireStatus(t, response, http.StatusNotFound)
 	})
 
+	// Returns 400 when the request body is not valid JSON.
 	t.Run("InvalidBody", func(t *testing.T) {
 		ds := rt.GetSingleDataStore()
 		response := rt.SendAdminRequest(http.MethodPut, "/db/_user/user1",
@@ -1748,6 +1758,7 @@ func TestCompactUserChannelHistory(t *testing.T) {
 		RequireStatus(t, response, http.StatusBadRequest)
 	})
 
+	// Removes specified channels from history and returns them; subsequent GET shows empty history.
 	t.Run("CompactsExistingChannels", func(t *testing.T) {
 		ds := rt.GetSingleDataStore()
 		scope := ds.ScopeName()
@@ -1786,6 +1797,7 @@ func TestCompactUserChannelHistory(t *testing.T) {
 		assert.Empty(t, afterResult.Channels[scope][collection])
 	})
 
+	// Returns empty for a collection when none of the requested channels exist in history; existing history is untouched.
 	t.Run("NonExistentChannelReturnsEmpty", func(t *testing.T) {
 		ds := rt.GetSingleDataStore()
 		scope := ds.ScopeName()
@@ -1824,6 +1836,7 @@ func TestCompactUserChannelHistory(t *testing.T) {
 		assert.ElementsMatch(t, []string{"chan1", "chan2"}, afterResult.Channels[scope][collection])
 	})
 
+	// Only channels present in history are removed and returned; unknown channels are silently ignored.
 	t.Run("MixOfExistingAndNonExistingChannels", func(t *testing.T) {
 		ds := rt.GetSingleDataStore()
 		scope := ds.ScopeName()
@@ -1863,6 +1876,7 @@ func TestCompactUserChannelHistory(t *testing.T) {
 	})
 }
 
+// TestDisabledUser ensures that a disabled (non-guest) user cannot authenticate to make requests.
 func TestDisabledUser(t *testing.T) {
 	rt := NewRestTester(t, nil)
 	defer rt.Close()