[sdairs]

Part 1 of 3 of the API side of the #1112 drift remediation. Refs #1112.

Plan

The live spec reported 290 actionable findings in three CLI command groups. While I worked, it gained 22 more pgConfig settings, which I included. Following the openapi-drift-remediation skill, there's one API PR and one CLI PR per group. The six PRs form a single linear stack: the three API PRs first, then the three CLI PRs. Each CLI branch merges the branch below it, so every PR's diff shows only its own changes.

PR	Branch	Base	Scope
API 1 (this PR)	cursor/openapi-drift-remediation-1112-c05d	main	Snapshot refresh, regenerated operation metadata, Postgres ipAccessList, 22 new pgConfig settings, PgSize renames
API 2 (#1119)	cursor/openapi-drift-1112-api-clickpipes-c05d	API 1	BigQuery ClickPipe syncCron
API 3 (#1121), fixes #1112	cursor/openapi-drift-1112-api-clickstack-c05d	API 2	ClickStack: click_stack_validate_webhook, permission/filter/heatmap unions, inline alert chart configs, stacked-line tiles, remaining fields and enum values, plus one analyzer rule
CLI 1 (#1118)	cursor/openapi-drift-1112-cli-postgres-c05d	API 3	postgres create --ip-allow/--block-public-access, postgres update --add-ip-allow/--remove-ip-allow, IP rules in postgres get, the new pgConfig keys
CLI 2 (#1120)	cursor/openapi-drift-1112-cli-clickpipes-c05d	CLI 1	clickpipe create bigquery --sync-cron
CLI 3 (#1122)	cursor/openapi-drift-1112-cli-clickstack-c05d	CLI 2	clickstack webhook validate, plus alert, dashboard and role validation for the new shapes

spec_coverage_test and two analyzer entrypoint tests (executable_and_library_return_the_same_vendored_report, udf_payload_migration_remains_actionable_after_component_removal_and_snapshot_refresh) require a drift-free vendored snapshot. They fail on API 1 and API 2 by design and pass on API 3, where python3 scripts/check-openapi-drift.py --dry-run reports 0 actionable drift.

Decisions I was unsure about

• PgSize renames are breaking. The spec renamed all 61 GCP sizes (c4-highmem-16 → c4-highmem-lssd-16, z3-highlssd-8 → z3-highmem-highlssd-8) and dropped the old names. I renamed the variants instead of keeping the old ones under an exemption, because nothing shows the API still accepts the old names. Old names in a response fall through to PgSize::Unknown, and a test pins that.
• PostgresIpAccessListPatch.add/remove are required Vecs. The schema has no required[] and no "Optional" marker, so the analyzer resolves both as required. This matches the existing ClickHouse-service IpAccessListPatch.
• I included the pgConfig settings that appeared after the issue was filed, as fix(api): refresh OpenAPI snapshot; snapshot permissions, saved-query GA, Prometheus labels, pgConfig GUCs (#1088) #1091 did, so the last API PR leaves no drift.
• Operation metadata is regenerated here, not in API 3. permissions::generation_matches_committed_catalog_after_formatting requires meta/operations.rs to match the vendored snapshot, so it moves with the snapshot. It adds the clickStackValidateWebhook descriptor before its method exists, which only the snapshot-dependent tests above notice. API 3 adds the method and the beta entry.
• API 3 makes ClickStack select-item level a number (Option<f64>) and removes ClickStackSelectItemLevel. The spec now types it as a plain number, and the old string enum couldn't parse a JSON number. That changes the CLI wire value from "0.95" to 0.95.
• API 3 adds one analyzer rule. A typed additionalProperties map whose value is an inline oneOf (MongoDB CASL conditions: string or {"$regex"} object) matches only serde_json::Value. No other Rust type could satisfy the analyzer.
• API 3's standalone ClickStackAlertChartConfigOverlay is strict, because the analyzer resolves its fields as required. The composed ClickStackAlert*ChartConfig types carry the same fields as optional (the spec rejects where on raw-SQL variants), and those are what callers build.
• CLI 1 adds --block-public-access, which sends ipAccessList: []. It isn't strictly needed for parity with cloud service create, but blocking public access is a security case worth one flag.
• CLI 3 still requires an alert source, even though the spec now makes it optional. The CLI's cross-field checks depend on knowing the source, and the spec doesn't say what an omitted source means.

Follow-up issues

I can't open GitHub issues from this environment. These are the per-CLI-PR issues the skill asks for:

1. CLI: Postgres IP access rules and new pgConfig settings (OpenAPI drift: 337 gaps between live spec and library #1112). Commands: cloud postgres create --ip-allow IP_OR_CIDR:PORTS[=DESCRIPTION] (repeatable) and --block-public-access; cloud postgres update --add-ip-allow and --remove-ip-allow RULE_ID_OR_SOURCE; IP rules in cloud postgres get; the 22 new pgConfig keys in config patch --set and file validation. Not exposed: editing a rule in place (add with an existing id). Remove and re-add covers it with simpler syntax.
2. CLI: BigQuery ClickPipe sync schedules (OpenAPI drift: 337 gaps between live spec and library #1112). Commands: cloud clickpipe create bigquery --sync-cron. Not exposed: changing it after creation, because the API has no BigQuery source update.
3. CLI: ClickStack webhook validation and new alert and dashboard shapes (OpenAPI drift: 337 gaps between live spec and library #1112). Commands: cloud clickstack webhook validate; inline alerts and optional channel/channels in alert create/update; stacked-line tiles, series heatmaps and all four filter types in dashboard create/update/validate; strict role permissions. Not exposed: a typed write-back flow for roles or dashboards. The CLI keeps taking complete JSON bodies.

Changes in this PR

• Replace clickhouse_cloud_openapi.json with the live document and regenerate meta/operations.rs.
• PgSize: 61 GCP variants renamed to the spec's local-SSD names. The README covers the migration.
• Postgres IP access lists: PostgresService.ip_access_list (response), PostgresServicePostRequest.ip_access_list (None allows all, Some(vec![]) blocks public access) and PostgresServicePatchRequest.ip_access_list (PostgresIpAccessListPatch). PostgresIpAccessListEntry splits into a strict request type and an all-Option response type, with a TryFrom write-back.
• PgConfig/PgConfigResponse gain 22 settings, including the closed enums PgConfigDefaultToastCompression, PgConfigEnableParallelHash, PgConfigIoMethod and PgConfigLogLockWaits (each with VALUES). They're carried through the From write-back and added to the PgConfig partial-schema optionality exemptions.
• CLI: compile fix only. Create and update send ip_access_list: None. A subprocess test checks that neither request carries ipAccessList, including when the pre-update GET returns rules.
• Tests: missing and null tolerance, request strictness, create/patch serialization, write-back, retired size names going to Unknown, the new pgConfig enums, facade paths, a wiremock PATCH round trip, and a non-blocking live step in integration_postgres_test that adds a TEST-NET rule, reads its ID back, and removes it.
• Library README.

Verification

• cargo fmt --all, both clickhousectl clippy configurations, library clippy, cargo check -p clickhousectl --no-default-features and cargo check --workspace --all-features are clean.
• cargo test -p clickhouse-cloud-api -p clickhouse-openapi-analyzer --no-fail-fast: only the three snapshot-dependent tests above fail, and they list only the ClickPipes and ClickStack findings.
• cargo test -p clickhousectl and python3 -m unittest discover -s scripts/tests -p 'test_*.py' pass.
• No files were added or renamed, so neither classifier changes.
• I couldn't run the live Postgres step here because it needs Cloud credentials and the run-cloud-integration label, which I haven't applied.

  

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}