Add non-retrying rate limit API and improve rate limit handling

[DZakh]

Summary

This PR introduces a new RateLimitResponse enum to provide callers with explicit control over rate limit handling. The get_with_rate_limit and get_arrow_with_rate_limit methods now return immediately on HTTP 429 responses instead of retrying internally, allowing applications to implement their own back-off strategies.

Key Changes

• New RateLimitResponse enum: Replaces QueryResponseWithRateLimit struct with an enum that distinguishes between successful responses and rate-limited responses

  • Success { response, rate_limit }: Query succeeded with rate limit info
  • RateLimited(RateLimitInfo): Server returned HTTP 429 (no internal retry)

• Rate limit API improvements:

  • get_arrow_with_size() now accepts a retry_on_rate_limit parameter to control retry behavior
  • get_arrow_with_rate_limit() and get_with_rate_limit() no longer retry on 429 responses
  • Added get_proactive_rate_limit_info() helper method to check if client is rate-limited without waiting
  • Proactive rate limiting now respects the retry_on_rate_limit flag

• Documentation improvements:

  • Updated docstrings for get_with_rate_limit and get_arrow_with_rate_limit to clarify non-retrying behavior
  • Clarified that other transient errors are still retried normally

• URL updates: Updated Envio plan upgrade URLs from https://app.envio.dev/api-tokens to https://envio.dev/app/api-tokens in error messages and logs

• Version bump: Updated to 1.2.0 to reflect the API changes

Implementation Details

• The get_arrow_with_size() method now conditionally applies proactive rate limiting based on the retry_on_rate_limit flag
• When retry_on_rate_limit=false, rate limit errors are returned immediately instead of being caught and retried
• The wait_for_rate_limit() method was refactored to use the new get_proactive_rate_limit_info() helper, reducing code duplication

https://claude.ai/code/session_01V1sz4C6ukyDDdaLPtk2vgi

Summary by CodeRabbit

• New Features

  • Configurable rate-limit handling: choose immediate rate-limit reporting or automatic wait-and-retry.
  • Query and streaming calls now surface explicit "rate limited" outcomes instead of hidden retries, and include updated guidance links when waiting.

• Chores

  • Package version bumped to 1.2.0.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 658f362c-7205-4ab3-ae98-8da9474c6ffc

📥 Commits

Reviewing files that changed from the base of the PR and between 3be5f54 and 576f819.

📒 Files selected for processing (1)

• hypersync-client/src/lib.rs

---

📝 Walkthrough

Walkthrough

The PR refactors rate-limit response handling in the Rust HyperSync client by replacing the QueryResponseWithRateLimit struct with a new RateLimitResponse enum, introducing a conditional-retry get_arrow_with_size helper, and exposing public query methods that surface HTTP 429 errors without automatic retry. Version bumped to 1.2.0.

Changes

Rate-Limit Response Type and API Refactor

Layer / File(s)	Summary
RateLimitResponse enum contract hypersync-client/src/types.rs	Replaces QueryResponseWithRateLimit struct with RateLimitResponse<T> enum distinguishing Success { response, rate_limit } from immediate RateLimited(rate_limit) cases.
get_arrow refactoring with conditional retry hypersync-client/src/lib.rs	Client::get_arrow now delegates to new internal get_arrow_with_size(query, wait_on_rate_limit) helper that either retries on HTTP 429 (when flag is true) or immediately returns RateLimited error (when false).
Rate-limit-aware query methods hypersync-client/src/lib.rs	New public methods get_arrow_with_rate_limit and get_with_rate_limit return RateLimitResponse<...> and surface HTTP 429 as RateLimitResponse::RateLimited without retry, converting successful results into the Success variant.
Proactive rate-limit state helpers hypersync-client/src/lib.rs	Introduces get_proactive_rate_limit_info() to compute remaining wait time from cached rate-limit state; refactors wait_for_rate_limit() to use this helper and consolidate timestamp/locking logic.
Public API exposure and error messaging hypersync-client/src/lib.rs	Updates type re-exports to expose RateLimitResponse instead of QueryResponseWithRateLimit; updates HyperSyncResponseError::RateLimited display string to reference envio.dev upgrade URL.
Streaming integration and version bump hypersync-client/src/stream.rs, hypersync-client/Cargo.toml	run_query_to_end now passes wait_on_rate_limit=true to get_arrow_with_size; crate version bumped from 1.1.4 to 1.2.0.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• enviodev/hypersync-client-rust#114: Main PR refactors and redefines the rate-limit-aware client behavior—changing return types and conditionalizing get_arrow_with_size retry behavior.
• enviodev/hypersync-client-rust#118: Overlaps with updates to the HyperSyncResponseError::RateLimited message and rate-limit guidance logging.

Suggested reviewers

• JasoonS
• Jordy-Baby

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main changes: introducing a non-retrying rate limit API (new RateLimitResponse enum) and improving rate limit handling (new retry controls and refactored logic).
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

hypersync-client/Cargo.toml (1)

1-3: 💤 Low value

Consider whether this should be a major version bump (2.0.0).

The return type of get_arrow_with_rate_limit and get_with_rate_limit changed from QueryResponseWithRateLimit to RateLimitResponse. Under semantic versioning for versions ≥1.0.0, changing public API return types is a breaking change that typically warrants a major version bump.

If existing consumers are few or the _with_rate_limit methods are rarely used externally, a minor bump may be acceptable as a pragmatic choice—but it's worth confirming this aligns with the project's versioning policy.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@hypersync-client/Cargo.toml` around lines 1 - 3, This change alters the
public return types of get_arrow_with_rate_limit and get_with_rate_limit from
QueryResponseWithRateLimit to RateLimitResponse which is a breaking API change;
decide whether to bump the crate to 2.0.0 under semver, and if so update the
version field in Cargo.toml to "2.0.0", add a clear entry in CHANGELOG.md noting
the breaking change (mentioning get_arrow_with_rate_limit, get_with_rate_limit,
QueryResponseWithRateLimit -> RateLimitResponse), and update any README or
compatibility notes; if you opt not to major-bump, document why (few/no external
consumers) in the changelog and consider adding adapter functions or a
deprecation plan to avoid surprising users.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@hypersync-client/Cargo.toml`:
- Around line 1-3: This change alters the public return types of
get_arrow_with_rate_limit and get_with_rate_limit from
QueryResponseWithRateLimit to RateLimitResponse which is a breaking API change;
decide whether to bump the crate to 2.0.0 under semver, and if so update the
version field in Cargo.toml to "2.0.0", add a clear entry in CHANGELOG.md noting
the breaking change (mentioning get_arrow_with_rate_limit, get_with_rate_limit,
QueryResponseWithRateLimit -> RateLimitResponse), and update any README or
compatibility notes; if you opt not to major-bump, document why (few/no external
consumers) in the changelog and consider adding adapter functions or a
deprecation plan to avoid surprising users.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c52503a7-8c56-4c0e-ab08-a3d80eb03da3

📥 Commits

Reviewing files that changed from the base of the PR and between b5b519e and 3be5f54.

📒 Files selected for processing (4)

• hypersync-client/Cargo.toml
• hypersync-client/src/lib.rs
• hypersync-client/src/stream.rs
• hypersync-client/src/types.rs