[sdairs]

Part 3 of 3 of the API side of the #1112 drift remediation. Fixes #1112. Stacked on API 2 (#1119, cursor/openapi-drift-1112-api-clickpipes-c05d). The plan, the decisions I was unsure about, and the follow-up issues are in the API 1 description (#1117, cursor/openapi-drift-remediation-1112-c05d).

At this head, python3 scripts/check-openapi-drift.py --dry-run against the live spec reports 0 actionable drift.

Library

• New operation. The beta click_stack_validate_webhook checks a ClickStackWebhookInput without saving it and returns ClickStackValidateWebhookResponse (valid, errors, normalized). It's added to BETA_OPERATIONS; its metadata was regenerated in API 1.
• Role permissions. ClickStackCASLPermission/ClickStackCASLPermissionResponse are unions on integration: ClickStackMongoDBCASLPermission (conditions are a map of raw JSON values) and ClickStackClickHouseCASLPermission (typed connection/table/where conditions). action and subject are now enums, and the free-form conditions alias is gone.
• Dashboard filters. ClickStackFilter, ClickStackFilterResponse and ClickStackFilterInput are unions on type (query expression, static list, Prometheus label, source). Each variant gains min_selections, max_selections (integer enums) and is_global_requirement.
• Heatmaps. ClickStackHeatmapChartConfig{,Response} are unions on heatmapMode. A missing heatmapMode selects the distribution heatmap (the former shape); a missing mode with groupBy is kept verbatim.
• Alerts. ClickStackAlertChartConfig is a union of the line, stacked-bar, stacked-line and number configs plus the overlay fields. Create/update requests now require only threshold, interval and thresholdType, so channel, channels and source become Option. Alerts gain displayName, tags and chartConfig, and the source enums add Inline.
• Tiles. Stacked-line tiles (ClickStackStackedLineChartConfig) join the tile union; lineInterpolation, raw-SQL number colorRules, tile description, the source expressions and saved-filter all are added; stacked_line joins the time-chart series enum.
• Select-item level. level is Option<f64>, matching the numeric schema.
• Write-back. TryFrom covers the permission and filter unions and their variants, and the source and saved-filter conversions carry the new fields. Chart and tile configs follow the existing precedent of having no write-back conversions.
• ClickStackSourceResponse gets #[allow(clippy::large_enum_variant)]: the four new trace-source fields crossed the size threshold, and boxing would break callers that match on the variant.
• The README covers the Rust caller migration.

The ClickStackValidationError* types are no longer in the spec, but nothing reports them and removing them would be an unforced break, so I left them.

Analyzer

A typed additionalProperties map whose value schema is an inline oneOf/anyOf now matches only serde_json::Value. Without this rule, no Rust type could satisfy ClickStackMongoDBCASLPermissionConditions (string or {"$regex", "$options"} values). Fixture tests cover both the accepted and the rejected representations. The report format is unchanged.

CLI (compile fixes only)

• Filters and role permissions are now unions, which serde_ignored can't see into. So that unknown fields are still rejected, the CLI checks each filter and permission against its variant on the raw JSON. Permissions must now set integration to mongodb or clickhouse, as the spec requires; integration-less fixtures were updated.
• Everything the CLI didn't accept before stays rejected until CLI 3: inline alerts, missing source, non-query-expression filters, and series heatmaps. Channel/channels are still both required. A test pins each case.
• Select-item level is now sent as a number. The dashboard fixture pins "level": 0.95.

Tests

Union dispatch (including dropped discriminators and unknown values), request strictness, missing/null tolerance for each new response type, write-back with missing-field names at the nested level, wiremock coverage for the new method (success and API error), facade paths, and analyzer fixtures. The library has no live ClickStack suite, so there's no integration step to extend.

Verification

• cargo fmt --all; library clippy; both clickhousectl clippy configurations; cargo check -p clickhousectl --no-default-features; cargo check --workspace --all-features: all clean.
• cargo test -p clickhouse-cloud-api -p clickhouse-openapi-analyzer --no-fail-fast: all pass, including spec_coverage_test.
• cargo test -p clickhousectl and python3 -m unittest discover -s scripts/tests -p 'test_*.py': pass.
• Live dry run: Actionable drift: 0 ... No actionable drift. Library fully covers the live spec.
• No files added or renamed.

  

[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.}