diff --git a/website/content/api-docs/features/blocking.mdx b/website/content/api-docs/features/blocking.mdx index 093bd1e545..2b7a9ae860 100644 --- a/website/content/api-docs/features/blocking.mdx +++ b/website/content/api-docs/features/blocking.mdx @@ -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 diff --git a/website/content/api-docs/features/streaming.mdx b/website/content/api-docs/features/streaming.mdx deleted file mode 100644 index 8a2c912d0f..0000000000 --- a/website/content/api-docs/features/streaming.mdx +++ /dev/null @@ -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 diff --git a/website/content/api-docs/health.mdx b/website/content/api-docs/health.mdx index 26943f06a3..77721a7cbc 100644 --- a/website/content/api-docs/health.mdx +++ b/website/content/api-docs/health.mdx @@ -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` 1 | `all` | `background refresh` | `node:read,service:read` | + +

+ 1some query parameters will use the + streaming backend +

### 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