CBG-5327: Wire up REST API to document channel history compaction by RIT3shSapata · Pull Request #8275 · couchbase/sync_gateway

RIT3shSapata · 2026-05-15T09:24:22Z

CBG-5327

Describe your PR here...

Added routes and handlers for get and post requests of document channel history compaction
Created a get document channel history function
Added test coverage for the http requests
Updated the Document Channel history compaction to store the compacted channels as set instead of array
Updated Open API spec

Pre-review checklist

Removed debug logging (fmt.Print, log.Print, ...)
Logging sensitive data? Make sure it's tagged (e.g. base.UD(docID), base.MD(dbName))
Updated relevant information in the API specifications (such as endpoint descriptions, schemas, ...) in docs/api

Dependencies (if applicable)

Link upstream PRs
- ~~Upstream PR: CBG-5326: Function to handle document channel history compaction #8218~~
Update Go module dependencies when merged

Integration Tests

Copilot

Pull request overview

This PR wires document channel history compaction into the Admin REST API and adds a REST-accessible way to inspect a document’s channel revocation history.

Changes:

Added Admin REST routes and handlers for getting document channel history and compacting channel history.
Added GetDocChannelHistory plus updated compaction output to deduplicate compacted channel names.
Added REST/API tests and updated OpenAPI path documentation.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`rest/routing.go`	Registers new Admin channel history GET and compaction POST routes.
`rest/doc_api.go`	Adds request/response handling for channel history APIs.
`rest/api_test.go`	Adds REST coverage and updates compaction expectations for deduplicated channels.
`docs/api/paths/admin/keyspace-_history.yaml`	Updates documented GET channel history response schema.
`docs/api/paths/admin/keyspace-_history-compact.yaml`	Updates compaction response description.
`db/crud.go`	Adds channel history retrieval and deduplicates compacted channel results.

Comments suppressed due to low confidence (2)

docs/api/paths/admin/keyspace-_history.yaml:17

This description conflicts with the implemented behavior and the new test for a channel that is revoked and then re-added: such a channel is still returned because it has revocation history. Rephrase this to say active channel memberships without any revocation history are not included, rather than implying all currently assigned channels are excluded.

    names to the sequences at which the document was removed from each channel. Only channels
    that have been revoked at least once are included; channels the document is currently
    assigned to are excluded.

docs/api/paths/admin/keyspace-_history.yaml:34

This map response is missing the repository’s OpenAPI convention of naming additionalProperties keys with x-additionalPropertiesName (for example, docs/api/paths/admin/keyspace-_history-compact.yaml:59-61 uses it for doc IDs). Add an appropriate key name such as channel_name to keep generated docs consistent.

            additionalProperties:
              type: array

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

+  '/{keyspace}/_channel_history/{docid}':
    $ref: './paths/admin/keyspace-_history.yaml'
-  '/{keyspace}/_history/compact':
+  '/{keyspace}/_channel_history/compact':


+		if err != nil && !base.IsDocNotFoundError(err) {
+			return err


+            additionalProperties:
+              type: array
+              items:
+                type: integer
+                format: int64
+                minimum: 0
+              description: Sequences at which the document was removed from this channel.


Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 8 comments.

+func (h *handler) handleGetDocChannelHistory() error {
+	h.assertAdminOnly()
+
+	if !h.collection.UseXattrs() {
+		return fmt.Errorf("xattrs not enabled")
+	}


adamcfraser

Posted text cleanup from our discussion - final review pending decisions on discussion items.

- added route for get request and the handler - created a get channel history function and added test coverage

- add route and handler to handle http request - add test coverage for http request - use set instead of array to store compacted channels

- add docstrings to all functions - updated api spec

- fix golang lint - update the open api spec's path for document channel history and compaction

- add request validation - fix docstrings

This reverts commit f797210.

- changed the endpoint for GET and POST requests - changed the request body and response for POST request - changed the resposne for the GET request - updated the OPEN API spec

- renamed the api path fixes - changed the response of the get request to include multiple sequences - updated the docstrings and the open api spec - fixed the permission issue in the route - handle not found error in the rest handler

github-actions · 2026-05-26T14:05:02Z

Redocly previews

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 8 comments.

Comments suppressed due to low confidence (4)

docs/api/paths/admin/keyspace-_channel_history-compact.yaml:56

The documented 200 response schema doesn’t match the actual handler output. The code returns an object with a compacted_channels property (array of strings), but this spec currently describes an object with additionalProperties (and an unrelated x-additionalPropertiesName: doc_id). Update the schema to define compacted_channels as a property and remove the additionalProperties mapping.
docs/api/paths/admin/keyspace-_channel_history-compact.yaml:37
The request schema allows seq with minimum: 0, but the handler currently returns 400 when seq==0. Either allow 0 (treat as a valid no-op) or update the OpenAPI schema/description to require seq >= 1 so the contract matches runtime behavior.
docs/api/paths/admin/keyspace-_channel_history-compact.yaml:59
The description has a grammar typo: “A array of all the compacted channels” should be “An array of all the compacted channels”.
docs/api/paths/admin/keyspace-_channel_history-compact.yaml:67
operationId in this file still references the old _history endpoint name (post_keyspace-_history-compact), but the path is now /_channel_history/{docid}/compact. Update the operationId to match the new endpoint naming to avoid collisions/confusion in generated clients.

RIT3shSapata · 2026-05-26T14:50:52Z

+	err := h.readJSONInto(&req)
+	if err != nil {
+		return base.HTTPErrorf(http.StatusBadRequest, "invalid JSON: %v", err)
+	}
+
+	if req.Seq == 0 {
+		return base.HTTPErrorf(http.StatusBadRequest, "missing seq")
+	}


changing the open api spec

 	}
 	_, err = c.dataStore.UpdateXattrs(ctx, key, 0, cas, updatedXattr, opts)
-	return compactedChannels, err
+	return compactedChannels.ToArray(), err


+          schema:
+            type: object
+            additionalProperties:
+              type: array
+              items:
+                type: integer
+                format: int64
+                minimum: 0
+              description: Sequences at which the document was removed from this channel.
+            description: Map of channel names to their revocation sequences.


adamcfraser · 2026-05-26T21:10:50Z

+		response[chanName] = make([]uint64, 0)
+		for seq, _ := range chanEntry {
+			response[chanName] = append(response[chanName], seq)
+		}


I agree with co-pilot that the individual slices need to be sorted by value.

I would go further, and suggest that the list of channels in the response map should also be sorted by sequence (or sequence[0]), so that callers can easily find the sequence they want to use for the POST operation.

e.g. with this:
"channel1": [10, 4],
"channel2:": [5, 2],
"channel3": [12],
"channel4": [7]
it's harder to see which channels will be compacted for a given sequence value

I think it would be preferable to return sorted by first sequence:
"channel3": [12],
"channel1": [10, 4],
"channel4": [7],
"channel2:": [5, 2]

What do you think?

adamcfraser

Generally looks good, one naming suggestion and then some comments about response ordering.

adamcfraser · 2026-05-26T21:10:50Z

+		response[chanName] = make([]uint64, 0)
+		for seq, _ := range chanEntry {
+			response[chanName] = append(response[chanName], seq)
+		}


I agree with co-pilot that the individual slices need to be sorted by value.

I would go further, and suggest that the list of channels in the response map should also be sorted by sequence (or sequence[0]), so that callers can easily find the sequence they want to use for the POST operation.

e.g. with this:
"channel1": [10, 4],
"channel2:": [5, 2],
"channel3": [12],
"channel4": [7]
it's harder to see which channels will be compacted for a given sequence value

I think it would be preferable to return sorted by first sequence:
"channel3": [12],
"channel1": [10, 4],
"channel4": [7],
"channel2:": [5, 2]

What do you think?

adamcfraser · 2026-05-26T21:16:37Z


 }

+type ChannelHistory map[string]map[uint64]bool


In cases where we're just using a map to store unique keys and don't care about the value, I prefer using empty struct:

Suggested change

type ChannelHistory map[string]map[uint64]bool

type ChannelHistory map[string]map[uint64]struct{}

This has some memory savings (which we don't really care about here), but also makes it self-documenting that we don't care about the map value.

adamcfraser · 2026-05-26T21:44:39Z

+	}
+}
+
+func (ch ChannelHistory) getChannelHistoryResponse() map[string][]uint64 {


Since this is in the db package, it's better to avoid naming like 'Response', since that implies REST functionality. Maybe just asMap() or asSequenceSlices()?

RIT3shSapata requested a review from Copilot May 15, 2026 09:24

RIT3shSapata self-assigned this May 15, 2026

Copilot started reviewing on behalf of RIT3shSapata May 15, 2026 09:25 View session

Copilot AI reviewed May 15, 2026

View reviewed changes

RIT3shSapata mentioned this pull request May 15, 2026

CBG-5328: Add audit events for document channel history compaction #8276

Open

6 tasks

RIT3shSapata force-pushed the CBG-5327 branch from 5b0c9a4 to ccc3f2e Compare May 15, 2026 18:07

RIT3shSapata requested review from adamcfraser and Copilot May 15, 2026 18:08

RIT3shSapata assigned adamcfraser and unassigned RIT3shSapata May 15, 2026

Copilot started reviewing on behalf of RIT3shSapata May 15, 2026 18:09 View session

Copilot AI reviewed May 15, 2026

View reviewed changes

adamcfraser assigned RIT3shSapata and unassigned adamcfraser May 19, 2026

RIT3shSapata force-pushed the CBG-5326 branch from 6b1e9b0 to 6632a76 Compare May 21, 2026 09:49

RIT3shSapata force-pushed the CBG-5327 branch from 38d85f7 to fee7c13 Compare May 21, 2026 11:01

RIT3shSapata requested a review from Copilot May 21, 2026 11:02

Copilot started reviewing on behalf of RIT3shSapata May 21, 2026 11:03 View session

Copilot AI reviewed May 21, 2026

View reviewed changes

RIT3shSapata assigned adamcfraser and unassigned RIT3shSapata May 21, 2026

RIT3shSapata force-pushed the CBG-5326 branch from 3620da7 to 65e314e Compare May 25, 2026 09:09

adamcfraser requested changes May 25, 2026

View reviewed changes

Comment thread docs/api/paths/admin/keyspace-_history.yaml Outdated

Comment thread docs/api/paths/admin/keyspace-_history-compact.yaml Outdated

Comment thread docs/api/paths/admin/keyspace-_history-compact.yaml Outdated

adamcfraser assigned RIT3shSapata and unassigned adamcfraser May 25, 2026

RIT3shSapata force-pushed the CBG-5327 branch from fee7c13 to f10db00 Compare May 26, 2026 12:14

Base automatically changed from CBG-5326 to main May 26, 2026 14:01

RIT3shSapata added 3 commits May 26, 2026 19:34

wire up the rest api to document channel history compaction

bfedcc6

- added route for get request and the handler - created a get channel history function and added test coverage

wire up post request to compact channel history

70b8917

- add route and handler to handle http request - add test coverage for http request - use set instead of array to store compacted channels

add documentation

9cfef82

- add docstrings to all functions - updated api spec

RIT3shSapata added 6 commits May 26, 2026 19:34

lint fix

b12b927

- fix golang lint - update the open api spec's path for document channel history and compaction

fixes based on copilot comments

56e319e

- add request validation - fix docstrings

fix the path in the documentation for post request

d3522da

Revert "fix the path in the documentation for post request"

46e17c0

This reverts commit f797210.

changes to api

a955944

- changed the endpoint for GET and POST requests - changed the request body and response for POST request - changed the resposne for the GET request - updated the OPEN API spec

fixes based on pr comments

82affc4

- renamed the api path fixes - changed the response of the get request to include multiple sequences - updated the docstrings and the open api spec - fixed the permission issue in the route - handle not found error in the rest handler

RIT3shSapata force-pushed the CBG-5327 branch from 89e5580 to 82affc4 Compare May 26, 2026 14:04

RIT3shSapata requested review from adamcfraser and Copilot May 26, 2026 14:05

Copilot started reviewing on behalf of RIT3shSapata May 26, 2026 14:05 View session

RIT3shSapata assigned adamcfraser and unassigned RIT3shSapata May 26, 2026

Copilot AI reviewed May 26, 2026

View reviewed changes

RIT3shSapata added 2 commits May 26, 2026 19:45

change the assertion from equal to ElementsMatch

62132c2

fixes based on co pilot comments

45d0775

adamcfraser requested changes May 26, 2026

View reviewed changes

	type ChannelHistory map[string]map[uint64]bool
	type ChannelHistory map[string]map[uint64]struct{}

Conversation

RIT3shSapata commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-review checklist

Dependencies (if applicable)

Integration Tests

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adamcfraser left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Redocly previews

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

RIT3shSapata May 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

adamcfraser May 26, 2026

Choose a reason for hiding this comment

Uh oh!

adamcfraser left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

adamcfraser May 26, 2026

Choose a reason for hiding this comment

Uh oh!

adamcfraser May 26, 2026

Choose a reason for hiding this comment

Uh oh!

adamcfraser May 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

RIT3shSapata commented May 15, 2026 •

edited

Loading

github-actions Bot commented May 26, 2026 •

edited

Loading