Repository navigation
feat(sdk): expose response metadata and status on successful calls - #420
Merged
Merged
Conversation
This change introduces a metadata-aware execution path so callers can read the HTTP status and allowlisted response headers on success, not only on failure. **New capability:** * Added `Client::execute_with_metadata`, which runs the same request, redirects and decoding as `execute` but returns a `Response<T>` carrying the decoded `data`, the final `status`, and the redacted `SafeHeaders`. * Added the public `Response<T>` struct and re-exported it from the crate root alongside `Client` and `ClientBuilder`. * `execute` now delegates to `execute_with_metadata` and returns just the data, so existing behaviour is unchanged; the internal header filtering uses the same allowlist as `Error::headers` (`retry-after`, `x-proxy-*`, `x-ratelimit-*`). **Why:** * This lets callers inspect proxy cache status and remaining daily budget (`x-proxy-cache`, `x-proxy-daily-remaining`) on successful responses without dropping down to the transport layer. **Docs and tests:** * Documented the metadata form in the README and on the method, showing how to read cache and budget headers. * Added `tests/success_headers.rs` covering the headers surfaced on success.
This commit adds a way to read the proxy's cache status and remaining daily budget after a successful call. Callers attach a ResponseMetadata to the call's context with WithResponseMetadata, and the client fills it once the response decodes successfully. **New capability:** * Added response_metadata.go introducing ResponseMetadata and WithResponseMetadata, which carry a *ResponseMetadata through the call's context. * On a decoded success the client records the endpoint id, the HTTP status and the allowlisted, redacted headers (the same allowlist as errors: Retry-After, X-Proxy-*, X-RateLimit-*) via a new recordResponseMetadata call in binary.go, client.go and csv.go. * Errors leave the metadata untouched since *Error already carries its own headers. Each call needs its own ctx/meta pair; sharing one meta across concurrent calls races on it. **Documentation and tests:** * Documented the feature in README.md and doc.go, including the X-Proxy-Cache and X-Proxy-Daily-Remaining use case. * Added response_metadata_test.go covering the new behaviour.
This pull request adds an optional response observer to the client so callers can watch every successful response made through it, including those from endpoint methods. The main changes introduce the registration API, the data passed to observers, and the firing logic. **Observer registration and types:** * Added `ClientBuilder::on_response`, which stores a `ResponseObserver` closure and replaces any previously registered observer, carried through the builder into the client configuration. * Added the `ResponseObserver` type alias and the `ResponseInfo` struct, exposing the endpoint id, the final HTTP status, and the allowlisted, redacted headers, and re-exported both from the crate root. **Firing behaviour:** * The observer runs inline once per call, only after the body decodes successfully, and never fires on status, provider-message, decode, or transport errors, since those already carry their headers on the error. * Included the observer state in the builder and client `Debug` output as a presence flag. **Documentation and tests:** * Documented the observer in the README and on the builder method, noting it cannot fail the call and should stay cheap and non-blocking. * Added tests covering that the observer sees endpoint-method successes with the expected endpoint, status, and headers, and stays silent across status, provider-message, and decode errors.
This pull request adds an optional `on_response` callback to `FmpClient`
so callers can read the proxy's cache status and remaining daily budget
after every successful request, across all namespace methods.
**New response callback:**
* `FmpClient(on_response=...)` accepts a callable invoked as
`on_response(endpoint_id, status, headers)` after each successful
response, before the method returns.
* `headers` carries only the allowlisted response headers (`retry-after`,
`x-proxy-*`, `x-ratelimit-*`), lowercase and redacted, keeping the first
value for a repeated name, and is `{}` rather than `None` when none were
sent, mirroring an error's `headers`.
* The callback runs on the calling thread with the GIL held, making it safe
to use from several threads at once; it is never invoked for errors, which
already carry their own `headers`, and if it raises, the method raises that
exception and discards the decoded data.
**Implementation:**
* Added `response_hook` module to capture and deliver allowlisted headers,
wired through `ClientHandle` and `block_on`.
* Validated that `on_response` is callable or `None` at construction time.
**Docs and tests:**
* Documented the callback in the README and the `__init__.pyi` and Rust
docstrings.
* Added `tests/test_on_response.py` covering the new behaviour.
close #417
benbenbang
enabled auto-merge (rebase)
October 6, 2026 11:01
github-actions
Bot
added
documentation
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
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.
Callers previously could only inspect response headers and status when a request failed, forcing them to drop to the transport layer to read proxy cache status and remaining daily budget on success. This change surfaces that metadata on successful responses across all client surfaces.
close #417