feat: add REDUCE_PAGE_SIZE response action for dynamic page-size reduction

[Daryna Ishchenko (darynaishchenko)]

Summary

Adds a new ResponseAction.REDUCE_PAGE_SIZE that enables declarative connectors to dynamically halve the page size when the API returns server errors (e.g. 502/504), then reset to the configured default after a successful fetch. This addresses the need from airbytehq/airbyte-internal-issues#16492 for source-github's GraphQL streams that currently implement ad-hoc page-size reduction via direct stream.page_size mutation.

Signal flow:

ErrorHandler returns REDUCE_PAGE_SIZE
  → HttpClient raises PageSizeReductionRequiredException
    → SimpleRetriever._read_pages() catches it
      → PaginationStrategy.reduce_page_size() halves the effective page size (min 1)
        → retries _fetch_next_page() with the reduced size
          → on success, PaginationStrategy.reset_page_size() restores the default

Key difference from source-github's current approach: the CDK version actually retries the failed request with the reduced page size (by re-entering _fetch_next_page() which rebuilds the request), whereas source-github's current implementation retries the same PreparedRequest with the original size baked in and only benefits from the reduction on subsequent pages.

Follows the existing RESET_PAGINATION / PaginationResetRequiredException pattern. All three concrete strategies (CursorPaginationStrategy, OffsetIncrement, PageIncrement) implement the new reduce_page_size() / reset_page_size() methods.

Declarative YAML usage:

error_handler:
  response_filters:
    - http_codes: [502, 504]
      action: REDUCE_PAGE_SIZE
      error_message: "Server returned a gateway error. Reducing page size and retrying."

Test coverage: Strategy-level tests for all 3 implementations (halving, floor-at-1, reset, no-op-on-None) plus retriever-level integration tests verifying the retry uses the same page token with the reduced size and that the page size resets after success.

Requested by Daryna Ishchenko (@darynaishchenko).

Link to Devin session: https://app.devin.ai/sessions/d00a1a4ed316400cab27fd1fb87681fb

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

Testing This CDK Version

You can test this version of the CDK using the following:

# Run the CLI from this branch:
uvx 'git+https://github.com/airbytehq/airbyte-python-cdk.git@devin/1782130672-reduce-page-size#egg=airbyte-python-cdk[dev]' --help

# Update a connector to use the CDK from this branch ref:
cd airbyte-integrations/connectors/source-example
poe use-cdk-branch devin/1782130672-reduce-page-size

PR Slash Commands

Airbyte Maintainers can execute the following slash commands on your PR:

• /autofix - Fixes most formatting and linting issues
• /poetry-lock - Updates poetry.lock file
• /test - Runs connector tests with the updated CDK
• /prerelease - Triggers a prerelease publish with default arguments
• /poe build - Regenerate git-committed build artifacts, such as the pydantic models which are generated from the manifest JSON schema in YAML.
• /poe <command> - Runs any poe command in the CDK environment

📚 Show Repo Guidance

Helpful Resources

• CDK API Reference

📝 Edit this welcome message.

[github-actions]

PyTest Results (Fast)

4 143 tests  +24   4 132 ✅ +24   8m 23s ⏱️ +7s
    1 suites ± 0      11 💤 ± 0 
    1 files   ± 0       0 ❌ ± 0 

Results for commit ca17f70. ± Comparison against base commit 977f051.

♻️ This comment has been updated with latest results.

[github-actions]

PyTest Results (Full)

4 146 tests  +24   4 134 ✅ +24   11m 35s ⏱️ -1s
    1 suites ± 0      12 💤 ± 0 
    1 files   ± 0       0 ❌ ± 0 

Results for commit ca17f70. ± Comparison against base commit 977f051.

♻️ This comment has been updated with latest results.