Skip to content

Commit c7a1505

Browse files
simon-dewdgnicholson
simon-dew
authored and
dgnicholson
committed
DOC-12777: Update Eventing REST API with sync-gateway-aware options (#163)
* Update eventing schemas to master * Add examples for Sync Gateway compatibility * Updates after review: add overlay for new settings * Updates after review: update Gradle to normalize spec and apply overlay * Updates after review: add cursor limit * Rebuild output documentation
1 parent 058e593 commit c7a1505

6 files changed

Lines changed: 306 additions & 9 deletions

File tree

‎docs/modules/eventing-rest-api/pages/index.adoc‎

Lines changed: 187 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4276,8 +4276,7 @@ GET /api/v1/config
42764276
[markdown]
42774277
--
42784278
Shows all global configuration settings.
4279-
There are currently just two settings: `enable_debugger` and `ram_quota`.
4280-
Both of these settings can also be adjusted via the UI.
4279+
Note that the `enable_debugger` and `ram_quota` settings can also be adjusted via the UI.
42814280
--
42824281

42834282

@@ -7846,6 +7845,38 @@ maximum time the handler can run before it is forcefully terminated (in seconds)
78467845
a¦ Integer
78477846

78487847

7848+
a¦
7849+
*cursor_checkpoint_timeout* +
7850+
_optional_
7851+
a¦
7852+
7853+
[markdown]
7854+
--
7855+
The maximum time the checkpoint writer can run before it is forcefully terminated (in seconds).
7856+
--
7857+
7858+
[%hardbreaks]
7859+
*Minimum:* `1`
7860+
{blank}
7861+
a¦ Integer
7862+
7863+
7864+
a¦
7865+
*on_deploy_timeout* +
7866+
_optional_
7867+
a¦
7868+
7869+
[markdown]
7870+
--
7871+
maximum time the OnDeploy handler can run before it is terminated (in seconds)
7872+
--
7873+
7874+
[%hardbreaks]
7875+
*Minimum:* `1`
7876+
{blank}
7877+
a¦ Integer
7878+
7879+
78497880
a¦
78507881
*language_compatibility* +
78517882
_optional_
@@ -8223,6 +8254,138 @@ maximum allowable curl call response in 'MegaBytes'. Setting the value to 0 lift
82238254
a¦ Integer
82248255

82258256

8257+
a¦
8258+
*allow_transaction_mutations* +
8259+
_optional_
8260+
a¦
8261+
8262+
[markdown]
8263+
--
8264+
allow staged transaction mutations
8265+
--
8266+
8267+
[%hardbreaks]
8268+
{blank}
8269+
a¦ Boolean
8270+
8271+
8272+
a¦
8273+
*allow_sync_documents* +
8274+
_optional_
8275+
a¦
8276+
8277+
[markdown]
8278+
--
8279+
Specifies whether the function allows Sync Gateway mutations.
8280+
8281+
* By default, this setting is `true`, for compatibility with previous versions of Couchbase Server.
8282+
8283+
* When this setting is `false`, the specified function skips all internal Sync Gateway documents, whose IDs are prefixed with `_sync`.
8284+
This enables the function to work with Sync Gateway.
8285+
8286+
You must ensure that none of the documents which contain your own working data have IDs which are prefixed with `_sync`.
8287+
(Note that internal Sync Gateway attachment documents, whose IDs are prefixed with `_sync:att`, are still processed by the specified function.)
8288+
--
8289+
8290+
[%hardbreaks]
8291+
{blank}
8292+
a¦ Boolean
8293+
8294+
8295+
a¦
8296+
*cursor_aware* +
8297+
_optional_
8298+
a¦
8299+
8300+
[markdown]
8301+
--
8302+
Specifies whether the function suppresses potential duplicate mutations caused by App Services or Sync Gateway book-keeping.
8303+
8304+
Enabling this setting guarantees that the Eventing function will only trigger once for any given mutation received from App Services or Sync Gateway.
8305+
8306+
Note that enabling this setting may have a noticeable impact on the performance of the Eventing function.
8307+
--
8308+
8309+
[%hardbreaks]
8310+
{blank}
8311+
a¦ Boolean
8312+
8313+
8314+
a¦
8315+
*high_seq_check_interval* +
8316+
_optional_
8317+
a¦
8318+
8319+
[markdown]
8320+
--
8321+
number of milliseconds before checking for high seq number
8322+
--
8323+
8324+
[%hardbreaks]
8325+
{blank}
8326+
a¦ Integer
8327+
8328+
8329+
a¦
8330+
*max_unacked_bytes* +
8331+
_optional_
8332+
a¦
8333+
8334+
[markdown]
8335+
--
8336+
max MBs to wait to send more bytes to c++ side
8337+
--
8338+
8339+
[%hardbreaks]
8340+
{blank}
8341+
a¦ Integer
8342+
8343+
8344+
a¦
8345+
*max_unacked_count* +
8346+
_optional_
8347+
a¦
8348+
8349+
[markdown]
8350+
--
8351+
max number of messages on c++ side
8352+
--
8353+
8354+
[%hardbreaks]
8355+
{blank}
8356+
a¦ Integer
8357+
8358+
8359+
a¦
8360+
*message_flush_time* +
8361+
_optional_
8362+
a¦
8363+
8364+
[markdown]
8365+
--
8366+
number of milliseconds before sending message to c++ side
8367+
--
8368+
8369+
[%hardbreaks]
8370+
{blank}
8371+
a¦ Integer
8372+
8373+
8374+
a¦
8375+
*max_parallel_vb* +
8376+
_optional_
8377+
a¦
8378+
8379+
[markdown]
8380+
--
8381+
number of parallel vb request per cpp thread
8382+
--
8383+
8384+
[%hardbreaks]
8385+
{blank}
8386+
a¦ Integer
8387+
8388+
82268389
|===
82278390

82288391
//end::settings_schema[]
@@ -8298,6 +8461,28 @@ For details, see [Debugging and Diagnosability](/server/8.0/eventing/eventing-de
82988461
a¦ Boolean
82998462

83008463

8464+
a¦
8465+
*cursor_limit* +
8466+
_optional_
8467+
a¦
8468+
8469+
[markdown]
8470+
--
8471+
The maximum number of cursor-aware Eventing functions that can coexist on a given source keyspace. (A cursor-aware Eventing function is one for which the `cursor_aware` setting is `true`.)
8472+
8473+
Increasing this setting enables more cursor-aware Eventing functions to register and listen to any given collection.
8474+
8475+
Decreasing this setting prevents further cursor-aware Eventing functions from being registered on any given collection; however, it doesn't unregister already registered cursor-aware Eventing functions.
8476+
--
8477+
8478+
[%hardbreaks]
8479+
*Default:* `5`
8480+
*Minimum:* `1`
8481+
*Maximum:* `20`
8482+
{blank}
8483+
a¦ Integer
8484+
8485+
83018486
|===
83028487

83038488
//end::UnivConfig[]

‎docs/modules/eventing-rest-api/partials/paths/adv_settings_update/http-request.adoc‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,44 @@ curl -XPOST -d '{
128128
----
129129
====
130130

131+
[#ex-sync-gateway-global]
132+
.Enable Sync Gateway compatibility for a global function
133+
====
134+
This example sets `allow_sync_documents` to `false`, to enable compatibility with Sync Gateway.
135+
The function is currently paused.
136+
137+
.Curl request
138+
[source,sh]
139+
----
140+
curl -XPOST -d '{
141+
"deployment_status": true,
142+
"processing_status": false,
143+
"allow_sync_documents": false
144+
}' "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings"
145+
----
146+
147+
For details, see xref:sync-gateway::server-compatibility-eventing.adoc[].
148+
====
149+
150+
[#ex-sync-gateway-scoped]
151+
.Enable Sync Gateway compatibility for a scoped function
152+
====
153+
This example sets `allow_sync_documents` to `false`, to enable compatibility with Sync Gateway.
154+
The function is currently paused.
155+
156+
.Curl request
157+
[source,sh]
158+
----
159+
curl -XPOST -d '{
160+
"deployment_status": true,
161+
"processing_status": false,
162+
"allow_sync_documents": false
163+
}' "http://$USER:$PASSWORD@$HOST:8096/api/v1/functions/my_function/settings?bucket=bulk&scope=data"
164+
----
165+
166+
For details, see xref:sync-gateway::server-compatibility-eventing.adoc[].
167+
====
168+
131169
.Deploy an undeployed global function -- deprecated
132170
====
133171
.Curl request

‎docs/modules/eventing-rest-api/partials/paths/config_update/http-request.adoc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,16 @@ curl -XPOST "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/config" \
2020
----
2121
====
2222

23+
.Set cursor limit
24+
====
25+
.Curl request
26+
[source,sh]
27+
----
28+
curl -XPOST "http://$ADMIN:$PASSWORD@$HOST:8096/api/v1/config" \
29+
-d '{"cursor_limit": 10}'
30+
----
31+
====
32+
2333
.Allow interbucket recursion
2434
====
2535
This example disables the safety checks that prevent basic infinite recursive Eventing functions.

‎src/eventing/eventing.gradle‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,31 @@
1+
plugins {
2+
id("io.datapith.jayOverlay").version("0.1.11")
3+
}
4+
5+
jayOverlay {
6+
targetFile.set("${projectDir}/build/bundle/eventing.yaml")
7+
overlayFile.set("${projectDir}/swagger/overlay.json")
8+
outputDir.set("${projectDir}/build/overlay")
9+
}
10+
111
apply plugin: 'org.openapi.generator'
212

13+
task bundleSpec(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask) {
14+
generatorName = "openapi-yaml"
15+
inputSpec = file("swagger/eventing.yaml").getAbsolutePath().toString()
16+
outputDir = "${projectDir}/build/bundle"
17+
globalProperties = [
18+
generateAliasAsModel: "true"
19+
]
20+
additionalProperties = [
21+
outputFile: "eventing.yaml",
22+
]
23+
generateAliasAsModel = true
24+
}
25+
326
openApiGenerate {
427
generatorName = "asciidoc"
5-
inputSpec = file("swagger/eventing.yaml").getAbsolutePath().toString()
28+
inputSpec = file("build/overlay/eventing.yaml").getAbsolutePath().toString()
629
outputDir = "${rootDir}/docs/modules/eventing-rest-api/pages"
730
templateDir = "${rootDir}/templates"
831
gitRepoId = "cb-swagger"
@@ -29,4 +52,7 @@ openApiGenerate {
2952
depcfg_schema_constants_inner: "Deployment Constants",
3053
depcfg_schema_curl_inner: "Deployment URL"
3154
]
32-
}
55+
}
56+
57+
tasks.applyOverlay.dependsOn(bundleSpec)
58+
tasks.openApiGenerate.dependsOn(applyOverlay)

‎src/eventing/swagger/eventing.yaml‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -615,8 +615,7 @@ paths:
615615
summary: List Global Config
616616
description: |-
617617
Shows all global configuration settings.
618-
There are currently just two settings: `enable_debugger` and `ram_quota`.
619-
Both of these settings can also be adjusted via the UI.
618+
Note that the `enable_debugger` and `ram_quota` settings can also be adjusted via the UI.
620619
tags:
621620
- global config
622621
security:
@@ -841,13 +840,13 @@ components:
841840
842841
schemas:
843842
settings_schema:
844-
$ref: 'https://raw.githubusercontent.com/couchbase/eventing/refs/heads/7.6.3/parser/settings_schema.json'
843+
$ref: 'https://raw.githubusercontent.com/couchbase/eventing/refs/heads/master/parser/settings_schema.json'
845844

846845
depcfg_schema:
847-
$ref: 'https://raw.githubusercontent.com/couchbase/eventing/refs/heads/7.6.3/parser/depcfg_schema.json'
846+
$ref: 'https://raw.githubusercontent.com/couchbase/eventing/refs/heads/master/parser/depcfg_schema.json'
848847

849848
handler_schema:
850-
$ref: 'https://raw.githubusercontent.com/couchbase/eventing/refs/heads/7.6.3/parser/handler_schema.json'
849+
$ref: 'https://raw.githubusercontent.com/couchbase/eventing/refs/heads/master/parser/handler_schema.json'
851850

852851
AppCode:
853852
type: string
@@ -893,6 +892,18 @@ components:
893892
description: |-
894893
Enables the Eventing service debugger.
895894
For details, see [Debugging and Diagnosability](/server/8.0/eventing/eventing-debugging-and-diagnosability.html).
895+
cursor_limit:
896+
type: integer
897+
default: 5
898+
maximum: 20
899+
minimum: 1
900+
x-has-default: true
901+
description: |-
902+
The maximum number of cursor-aware Eventing functions that can coexist on a given source keyspace. (A cursor-aware Eventing function is one for which the `cursor_aware` setting is `true`.)
903+
904+
Increasing this setting enables more cursor-aware Eventing functions to register and listen to any given collection.
905+
906+
Decreasing this setting prevents further cursor-aware Eventing functions from being registered on any given collection; however, it doesn't unregister already registered cursor-aware Eventing functions.
896907
897908
responses:
898909
OK:

‎src/eventing/swagger/overlay.json‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"overlay": "1.0.0",
3+
"info": {
4+
"title": "Overlay for Eventing Settings Schema",
5+
"version": 1.0
6+
},
7+
"actions": [
8+
{
9+
"target": "components.schemas.settings_schema.properties.allow_sync_documents",
10+
"update": {
11+
"description": "Specifies whether the function allows Sync Gateway mutations.\n\n* By default, this setting is `true`, for compatibility with previous versions of Couchbase Server.\n\n* When this setting is `false`, the specified function skips all internal Sync Gateway documents, whose IDs are prefixed with `_sync`.\nThis enables the function to work with Sync Gateway.\n\nYou must ensure that none of the documents which contain your own working data have IDs which are prefixed with `_sync`.\n(Note that internal Sync Gateway attachment documents, whose IDs are prefixed with `_sync:att`, are still processed by the specified function.)"
12+
}
13+
},
14+
{
15+
"target": "components.schemas.settings_schema.properties.cursor_aware",
16+
"update": {
17+
"description": "Specifies whether the function suppresses potential duplicate mutations caused by App Services or Sync Gateway book-keeping.\n\nEnabling this setting guarantees that the Eventing function will only trigger once for any given mutation received from App Services or Sync Gateway.\n\nNote that enabling this setting may have a noticeable impact on the performance of the Eventing function."
18+
}
19+
},
20+
{
21+
"target": "components.schemas.settings_schema.properties.cursor_checkpoint_timeout",
22+
"update": {
23+
"description": "The maximum time the checkpoint writer can run before it is forcefully terminated (in seconds)."
24+
}
25+
}
26+
]
27+
}

0 commit comments

Comments
 (0)