hashicorp / hashicorp/consul

Expand blocking query docs beyond instructions for usage

Open
#12,115 0 comments 0 reactions 0 assignees View on GitHub
type/docs
Dominant language
Go
Stars
30.1k
Forks
4.6k
Avg merge
1d 18h
Merged PRs (30d)
39

Description

The current blocking query docs primarily state how to use blocking queries, and could be expanded to include additional details about their behavior. Here are a couple ideas on behavior that could be documented about them:

#### Index returned for various queries
Depending on the query, the index returned can vary. At times it is the max index for the table, at times it is the max index of the result set, at times it is the index of a given resource.

#### Behavior of blocking on resources that don't exist
When a blocking query is set up for a resource that doesn't exist, such as a KV key, unrelated key updates can lead to the blocking query firing. This is due to how memdb will watch for changes, and the fact that when the resource doesn't exist the index considered by the query is the max for the table/partition/namespace.

This issue is being addressed in #12110, but the existing behavior should be documented since it has been a cause for confusion/concern in several deployments.

Contributor guide

Open the contributing guide

Research direction

Start by locating the blocking query documentation and reviewing issue #12110 for the behavior changes it addresses. Document how returned indexes vary by query and how blocking behaves for nonexistent resources, including the relevant memdb behavior. Done when these cases are explained clearly for users.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.