Documentation error regarding streaming usage
- Dominant language
- Go
- Stars
- 30.1k
- Forks
- 4.6k
- Avg merge
- 1d 18h
- Merged PRs (30d)
- 39
Description
Hey guys,
It looks like in the documentation it says that to use streaming it can be achieved through adding either `cached` or `index` to the URL.
https://www.consul.io/api/features/blocking#streaming-backend
```
The streaming backend, first introduced in Consul 1.10, is a replacement for the long polling backend. If streaming is supported by an endpoint, it will be used when either the index or cached query parameters are set.
```
In another page it looks like it can be activated only by using `cached` : https://www.hashicorp.com/blog/announcing-hashicorp-consul-1-9
```
Streaming is now available for the service health HTTP endpoint. It can be enabled through configuration flags and adding the cached URL parameter. In subsequent releases, we will continue to enable streaming in more endpoints.
```
trying the query without any param:
```
/ # curl -i 172.17.0.2:8500/v1/health/service/counting
HTTP/1.1 200 OK
Content-Type: application/json
Vary: Accept-Encoding
X-Consul-Default-Acl-Policy: allow
X-Consul-Effective-Consistency: leader
X-Consul-Index: 10
X-Consul-Knownleader: true
X-Consul-Lastcontact: 0
X-Consul-Query-Backend: blocking-query
Date: Sun, 01 Aug 2021 12:52:02 GMT
Content-Length: 2
```
no streaming is used ( X-Consul-Query-Backend: blocking-query )
with `cached` parameter:
```
/ # curl -i 172.17.0.2:8500/v1/health/service/counting?cached
HTTP/1.1 200 OK
Content-Type: application/json
Vary: Accept-Encoding
X-Cache: MISS
X-Consul-Default-Acl-Policy: allow
X-Consul-Effective-Consistency: leader
X-Consul-Index: 10
X-Consul-Knownleader: false
X-Consul-Lastcontact: 0
X-Consul-Query-Backend: streaming
Date: Sun, 01 Aug 2021 12:52:12 GMT
Content-Length: 2
```
it uses streaming (X-Consul-Query-Backend: streaming)
with `index` parameter:
```
/ # curl -i 172.17.0.2:8500/v1/health/service/counting?index
HTTP/1.1 200 OK
Content-Type: application/json
Vary: Accept-Encoding
X-Consul-Default-Acl-Policy: allow
X-Consul-Effective-Consistency: leader
X-Consul-Index: 10
X-Consul-Knownleader: true
X-Consul-Lastcontact: 0
X-Consul-Query-Backend: blocking-query
Date: Sun, 01 Aug 2021 12:52:18 GMT
Content-Length: 2
```
no streaming is used ( X-Consul-Query-Backend: blocking-query )
#### Reproduction Steps
Using the example from your doc site: https://learn.hashicorp.com/tutorials/consul/docker-container-agents
(badger = master, fox = client)
```
docker run -d -p 8500:8500 -p 8600:8600/udp --name=badger consul agent -server -ui -node=server-1 -bootstrap-expect=1 -client=0.0.0.0
```
and:
```
docker run --name=fox -d consul agent -node=client-1 -join=172.17.0.2
```
### Consul info for both Client and Server
Client info
```
agent:
check_monitors = 0
check_ttls = 0
checks = 0
services = 1
build:
prerelease =
revision = db839f18
version = 1.10.1
consul:
acl = disabled
known_servers = 1
server = false
runtime:
arch = amd64
cpu_count = 3
goroutines = 52
max_procs = 3
os = linux
version = go1.16.6
serf_lan:
coordinate_resets = 0
encrypted = false
event_queue = 0
event_time = 3
failed = 0
health_score = 0
intent_queue = 0
left = 0
member_time = 3
members = 2
query_queue = 0
query_time = 1
```
Server info
```
agent:
check_monitors = 0
check_ttls = 0
checks = 0
services = 0
build:
prerelease =
revision = db839f18
version = 1.10.1
consul:
acl = disabled
bootstrap = true
known_datacenters = 1
leader = true
leader_addr = 172.17.0.2:8300
server = true
raft:
applied_index = 45
commit_index = 45
fsm_pending = 0
last_contact = 0
last_log_index = 45
last_log_term = 2
last_snapshot_index = 0
last_snapshot_term = 0
latest_configuration = [{Suffrage:Voter ID:cb0008ab-efa4-4d58-bd3c-bfa7817c812b Address:172.17.0.2:8300}]
latest_configuration_index = 0
num_peers = 0
protocol_version = 3
protocol_version_max = 3
protocol_version_min = 0
snapshot_version_max = 1
snapshot_version_min = 0
state = Leader
term = 2
runtime:
arch = amd64
cpu_count = 3
goroutines = 111
max_procs = 3
os = linux
version = go1.16.6
serf_lan:
coordinate_resets = 0
encrypted = false
event_queue = 0
event_time = 3
failed = 0
health_score = 0
intent_queue = 0
left = 0
member_time = 3
members = 2
query_queue = 0
query_time = 1
serf_wan:
coordinate_resets = 0
encrypted = false
event_queue = 0
event_time = 1
failed = 0
health_score = 0
intent_queue = 0
left = 0
member_time = 1
members = 1
query_queue = 0
query_time = 1
```
What im trying to understand is - how is `index` related to using streaming?
why does using `index` doesnt return a `X-Consul-Query-Backend: streaming` ?
And why are 2 params used for the exact same function ?
Contributor guide
Research direction
Start by comparing the linked Consul streaming backend documentation with the linked Consul 1.9 announcement. Reproduce the service-health requests using the documented Docker setup and compare the X-Consul-Query-Backend headers for cached and index parameters. Done means the documentation clearly explains which parameter enables streaming and how index relates to it.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100