Resolve OpenAPI drift and add scaling-schedule API coverage#150
Merged
sdairs merged 5 commits intoMay 14, 2026
Merged
Conversation
Refreshes the OpenAPI snapshot and brings the typed client in sync with the new horizontal-autoscaling / scaling-schedule feature on ClickHouse Cloud. Also fixes a resolver bug exposed by a spec convention transition: the OpenAPI team is starting to add `required[]` arrays to schemas but only listing newly-introduced fields, which the previous required[]-exclusive interpretation mis-classified as flipping every other field to optional. - Adds 7 new model types: `CurrentScaling`, `ScalingSchedule`, `ScalingScheduleBaseConfig`, `ScalingScheduleEntry`, `ScalingScheduleEntryRequest`, `ScalingSchedulePatchRequest`, `ScalingSchedulePostRequest`. - Adds 5 new fields to `Service` and `ServiceScalingPatchResponse` (`currentScaling`, `scalingSchedule`, `minReplicas`, `maxReplicas`, `replicaMemoryGb`) and 3 to `ServiceReplicaScalingPatchRequest`. - Adds 3 new client methods: `scaling_schedule_get`, `scaling_schedule_upsert`, `scaling_schedule_replace`. - Introduces `PARTIAL_REQUIRED_SCHEMAS` (mirrored in Rust and Python resolvers) so schemas whose `required[]` only lists new fields fall back to the description heuristic for older fields. Currently `Service` and `ServiceScalingPatchResponse`. - Python drift checker now parses `NON_OPENAPI_CLIENT_METHODS` and `OPTIONALITY_EXEMPTIONS` from `spec_coverage_test.rs` to stay in sync with the Rust test's intentional divergences. Closes #149. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds `BETA_OPERATIONS` (and `is_beta_operation`) to `clickhouse_cloud_api`, sourced from `x-badges` Beta markers in the OpenAPI spec. Consumers — the CLI in this repo, and any external user of the library — can now derive a "(Beta)" affordance from spec metadata rather than maintaining a parallel list by hand. - New `meta.rs` module with a sorted constant of 36 snake-case operation names plus a `binary_search`-backed helper. - `spec_coverage_test.rs` gains `beta_operations_match_spec` (snapshot) and `_live` variants. Drift produces a clear failure pointing at the regenerator script. - `scripts/regenerate-beta-lists.py` reads the snapshot and prints the array body — run after each `clickhouse_cloud_openapi.json` refresh. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
`check-openapi-drift.py` now parses `BETA_OPERATIONS` out of `meta.rs` and diffs it against `x-badges` Beta markers in the live spec. The "Beta Status Changes" issue section calls out newly-Beta operations (that need adding to the constant) and graduations (that need removing), and the count rolls into the summary table. This catches stability transitions that the snapshot-driven Rust test cannot — e.g. an existing operation flipping from GA to Beta or vice versa on the published spec before we refresh the snapshot. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Postgres subcommand's help text already advertised "(beta)" via a hand-written doc comment. Capitalise it to `(Beta)` (matching how the OpenAPI spec's `x-badges` renders it) and add a test that asserts the label is present iff `clickhouse_cloud_api::is_beta_operation` reports the underlying operation as Beta. If Postgres ever graduates, the daily drift check flags it, we delete the suffix, and the test keeps passing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reverts commit e11d3bd. The label-and-test approach was overbuilt for what it solved: the CLI never actually consults `is_beta_operation` at runtime — clap renders help text from compile-time metadata, and nothing in the CLI declares which client method each subcommand wraps. The test held a literal string accountable to spec metadata without the CLI ever consuming that metadata, which is rigour without leverage on a surface that has one beta-backed command today. The library-side `BETA_OPERATIONS` constant and the daily drift checker remain. Those are the genuine consumers: external Rust callers of `clickhouse-cloud-api` get a programmatic stability signal, and the drift check flags upstream Beta/GA transitions. The Postgres help text goes back to a hand-written `(beta)` doc comment — the same it was before this stack. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
iskakaushik
approved these changes
May 14, 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
Resolves the daily OpenAPI drift report in #149 by:
CurrentScaling,ScalingSchedule,ScalingScheduleBaseConfig,ScalingScheduleEntry,ScalingScheduleEntryRequest,ScalingSchedulePatchRequest,ScalingSchedulePostRequest).Service/ServiceScalingPatchResponse/ServiceReplicaScalingPatchRequest(currentScaling,scalingSchedule,minReplicas,maxReplicas,replicaMemoryGb).scaling_schedule_get,scaling_schedule_upsert,scaling_schedule_replace.Resolver fix
The drift report also surfaced 86 field optionality mismatches caused by a recent spec convention shift: the OpenAPI team is now adding
required[]arrays to schemas but only listing newly-introduced fields, leaving older fields to the existing "description doesn't start with 'Optional'" heuristic. Our previous resolver treatedrequired[]as exclusive when present, which mis-classified every other field onServiceandServiceScalingPatchResponseas optional.This PR introduces a
PARTIAL_REQUIRED_SCHEMASlist (mirrored in bothscripts/resolve-field-requirements.pyandtests/spec_coverage_test.rs). Schemas in this list fall back to the description heuristic for fields absent fromrequired[]. CurrentlyServiceandServiceScalingPatchResponse. Other schemas with comprehensiverequired[]arrays (e.g.Scim*) keep the exclusive interpretation.The Python drift checker now also parses
NON_OPENAPI_CLIENT_METHODSandOPTIONALITY_EXEMPTIONSdirectly fromspec_coverage_test.rs, so the daily report stays in sync with the Rust test's intentional divergences without a second source of truth.Note
Stacked on #148 so it merges clean once that lands. Retarget to `main` after #148 (and #146) merge.
Closes #149.
Test plan
🤖 Generated with Claude Code