mikebridge commented on code in PR #45554: URL: https://github.com/apache/superset/pull/45554#discussion_r4383646281
########## docs/developer_docs/extensions/semantic-provider-boundary.md: ########## @@ -0,0 +1,96 @@ +--- +title: Semantic provider readiness and failures +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# Semantic provider readiness and failures + +## Schema discovery + +Both schema methods require keyword-only `transport` and `readiness`. Import +`SemanticCredentialReadiness` from `superset_core.semantic_layers.config` (also +exported from `superset_core.semantic_layers`). It is a plain Enum, not a string. + +```python +@classmethod +def get_configuration_schema( + cls, configuration: MyConfig | None = None, *, + transport: ProviderTransport, readiness: SemanticCredentialReadiness, +) -> dict[str, Any]: + schema: dict[str, Any] = MyConfig.model_json_schema() + if readiness is not SemanticCredentialReadiness.RESOLVED: + return schema + if configuration is None or not configuration.password: + return schema + # Discover only after provider-specific required-field checks. + # Use the supplied transport for any HTTP request. + return schema +``` + +Apply the same positive identity check in `get_runtime_schema(configuration, +runtime_data=None, *, transport, readiness)`. Strings such as `"resolved"`, booleans +and unrelated objects must not enable discovery. A static schema must perform no +network activity or credential lookup and must not echo secrets in defaults/options. +Readiness is neither complete configuration nor authenticated/authorized access. +Providers still validate required fields and allowlisted runtime overrides. + +The host checks submitted preview values before partial validation can discard an +unresolved field. A preview does not fetch or restore saved secrets. Runtime +schemas use the saved connection after the existing layer access check. The host +alone understands its masking convention; client payload fields never select the +trusted readiness keyword. Static masking and fallback calls explicitly pass +UNRESOLVED. Direct SDK hosts must supply an explicit state using their own secret +resolution rules, without adopting Superset's mask. + +This is a coordinated schema API upgrade. Update all overrides and direct callers +with the host/core pin containing transport and readiness; there is no fallback +that retries without safety arguments. The factory's transport/context/credentials Review Comment: Corrected in 7ad72749f9: the guide now calls out the required keyword-only `transport` parameter on `SemanticLayer.from_configuration`, matching UPDATING.md and the SDK signature. ########## superset/semantic_layers/exceptions.py: ########## @@ -110,7 +151,12 @@ def execute_semantic_query( with provider_completeness(): return dispatcher(*args, **kwargs) except SemanticQueryRejectedError as ex: - raise SemanticLayerQueryRejectedError(ex.code) from ex + raise SemanticLayerQueryRejectedError(ex.code) from None + except ProviderRequestError as ex: Review Comment: Confirmed and fixed in 7ad72749f9. Transport failures during provider construction, metadata preparation and the MCP compatibility checks now go through the same sanitized normalization as dispatch, so they surface as query errors rather than the generic fallback. Added regressions for the MCP `get_table(view_id=...)` path, chart data and filter values; each failed before the fix. A failed preparation doesn't run or retry the query. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
