status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: move streaming docs to blocking query page

This commit is contained in:
Daniel Nephin 2021-06-08 13:48:56 -04:00
parent c46f4391f0
commit 8b9ec040c3
3 changed files with 30 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
website/content/api-docs/features/blocking.mdx
View File

@ -82,6 +82,24 @@ cases that must be handled correctly.
[token bucket](https://en.wikipedia.org/wiki/Token_bucket) with burst of 2 is a simple
way to achieve this.
## 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.
When streaming is used, the Consul servers publish change events to a topic. Clients
subscribe to a topic to receive these change events. The clients use the change events to build
a local "materialized view". Clients are then able to handle requests using that view.
Streaming improves on the traditional long polling between clients and servers
by significantly reducing the quantity of data sent between them, while still allowing
clients to handle read requests.
While streaming is a significant optimization over long polling, it will not populate the
`X-Consul-LastContact` or `X-Consul-KnownLeader` response headers, because the required
data is not available to the client.
## Hash-based Blocking Queries
A limited number of agent endpoints also support blocking however because the

43
website/content/api-docs/features/streaming.mdx
View File

@ -1,43 +0,0 @@
---
layout: api
page_title: Streaming
description: |-
Some API endpoints support a feature known as "streaming". Change events
are published to a stream topic, allowing clients to build a localized
view, and removing the need to send full state-of-the-world responses
every time data changes.
---
# Streaming
A few endpoints in Consul support a feature known as "streaming". With streaming
the Consul servers publish change events to a topic. Clients can subscribe to a
topic to receive these change events. The clients use the change events to build
a local "materialized view". Clients are then able to handle requests using that view.
Streaming improves on [blocking queries][1] by significantly reducing the quantity
of data sent from servers to clients, while still allowing clients to handle
read requests.
Streaming, first introduced in Consul 1.10, is a replacement for [blocking queries][1],
and is only supported by a small number of endpoints. If streaming is supported by an
endpoint, it will be used when either the `index` or `cached` query parameters are set.
Endpoints that support streaming return an HTTP header named
`X-Consul-Index`. This is a unique identifier representing the current state of
the requested resource.
On subsequent requests for this resource, the client can set the `index` query
string parameter to the value of `X-Consul-Index`, indicating that the client
wishes to wait for any changes subsequent to that index.
When `index` is set, the HTTP request will "hang" until a change in the system
occurs, or the maximum timeout is reached. A critical note is that the return of
a blocking request is **no guarantee** of a change. It is possible that the
timeout was reached or that there was an idempotent write that does not affect
the result of the query.
Note that streaming does not support all query parameters used by blocking queries, and
that some response headers (ex: `X-Consul-LastContact` and `X-Consul-KnownLeader`) are not
set because the data is not available.
[1]: /api-docs/features/blocking

21
website/content/api-docs/health.mdx
View File

@ -197,7 +197,7 @@ the following selectors and filter operations being supported:
| `ServiceTags` | In, Not In, Is Empty, Is Not Empty |
| `Status` | Equal, Not Equal, In, Not In, Matches, Not Matches |
## List Service Instances for Service ((list-nodes-for-service))
## List Service Instances for Service ((#list-nodes-for-service))
This endpoint returns the service instances providing the service indicated on the path.
Users can also build in support for dynamic load balancing and other features by
@ -208,15 +208,19 @@ incorporating the use of health checks.
| `GET` | `/health/service/:service` | `application/json` |
The table below shows this endpoint's support for
[streaming](/api/features/streaming),
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
[required ACLs](/api#authentication).
| Streaming | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ----------| ---------------- | ----------------- | -------------------- | ------------------------ |
| `partial` | `YES` | `all` | `background refresh` | `node:read,service:read` |
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| -------------------- | ----------------- | -------------------- | ------------------------ |
| `YES` <sup>1</sup> | `all` | `background refresh` | `node:read,service:read` |
<p>
<sup>1</sup>some query parameters will use the
<a href="/api/features/blocking#streaming-backend">streaming backend</a>
</p>
### Parameters
@ -412,11 +416,11 @@ so this endpoint may be used to filter only the Connect-capable endpoints.
Parameters and response format are the same as
[`/health/service/:service`](/api/health#list-nodes-for-service).
## List Service Instances for Ingress Gateways Associated with Service
## List Service Instances for Ingress Gateways Associated with a Service
-> **1.8.0+:** This API is available in Consul versions 1.8.0 and later.
This endpoint returns the service instances providing a [ingress
This endpoint returns the service instances providing an [ingress
gateway](/docs/connect/ingress-gateway) for a service in a given datacenter.
| Method | Path | Produces |
@ -427,8 +431,7 @@ Parameters and response format are the same as
[`/health/service/:service`](/api/health#list-nodes-for-service).
**Note** that unlike `/health/connect/:service` and `/health/service/:service` this
endpoint does not support [streaming](/api/features/streaming), and will use
[blocking queries](/api/features/blocking).
endpoint does not support the [streaming backend](/api/features/blocking#streaming-backend).
## List Checks in State