api: add Snapshot endpoint, with raw/binary transport support#122
Merged
Conversation
added 2 commits
July 3, 2026 10:17
Both sync (std.py, requests-based) and async (aio.py, aiohttp-based) HTTP clients unconditionally decoded every response body as UTF-8 text, which corrupts binary payloads (e.g. the gzip archive returned by GET /v1/snapshot). Adds a `raw: bool = False` parameter to HTTPClient.get() across base/std/aio: when set, the response body is kept as raw bytes (response.content / await resp.read()) instead of being decoded. Also widens put()'s data param to str | bytes, and adds CB.binary() for endpoints that need the raw body with normal status-code error handling. Off by default, so every existing endpoint is unaffected. Verified end-to-end (not just unit-level) against a live Consul instance for both the sync and async clients ahead of the Snapshot endpoint that depends on this.
Adds consul.snapshot.save()/restore(), built on the raw/binary response mode added in the previous commit. Both endpoints require a management-level ACL token, not a granular ACL rule. Verified against a live Consul instance for both the sync and async clients: save a snapshot, mutate state, restore, and confirm the pre-mutation state comes back.
mbrulatout
requested review from
cpaillet,
dclaisse,
manu-ns,
mougams and
pierrecdn
July 3, 2026 08:19
5 tasks
manu-ns
approved these changes
Jul 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to #121 — implements the Snapshot endpoint that PR deliberately deferred.
raw: bool = Falsemode toHTTPClient.get()in both the sync (std.py, requests-based) and async (aio.py, aiohttp-based) clients. Previously every response body was unconditionally decoded as UTF-8 text, which corrupts binary payloads. Off by default, so every existing endpoint is unaffected — verified via a full test suite run. Also widensput()'sdataparam tostr | bytes, and addsCB.binary()for endpoints that need the raw body with normal status-code error handling.consul/api/snapshot.py) —save()/restore(), built on the above. Both require a management-level ACL token (not a granular ACL rule), per Consul's docs.Verification
Beyond the new pytest integration tests (
tests/api/test_snapshot.py, run against real dockerized Consul 1.20.6/1.21.5/1.22.0), I also directly exercised the full save → mutate → restore → verify round-trip against a live Consul container for both the sync and async clients, since the async path isn't covered by the existing test suite's fixtures:Test plan
mypy consul/ --no-sqlite-cache— cleanruff check ./ruff format --diff .— cleantests/api/test_snapshot.py— passing across all 3 Consul versions