update ndc-spec from 0.1.0-rc.13 to 0.1.0-rc.14 (#93)

Dockerfile

@@ -1,4 +1,4 @@
-FROM rust:1.70.0-slim-buster AS build
+FROM rust:1.76.0-slim-buster AS build
 
 WORKDIR app
 

rust-connector-sdk/Cargo.toml

@@ -13,8 +13,8 @@ path = "bin/main.rs"
 
 [dependencies]
 gdc_rust_types = { git = "https://github.com/hasura/gdc_rust_types.git", rev = "3273434" }
-ndc-client = { git = "http://github.com/hasura/ndc-spec.git", tag = "v0.1.0-rc.13" }
-ndc-test = { git = "http://github.com/hasura/ndc-spec.git", tag = "v0.1.0-rc.13" }
+ndc-client = { git = "http://github.com/hasura/ndc-spec.git", tag = "v0.1.0-rc.14" }
+ndc-test = { git = "http://github.com/hasura/ndc-spec.git", tag = "v0.1.0-rc.14" }
 
 async-trait = "^0.1.74"
 axum = "^0.6.20"

rust-connector-sdk/src/connector.rs

@@ -105,7 +105,7 @@ pub enum QueryError {
 
 /// Errors which occur when explaining a query.
 ///
-/// See [`Connector::explain`].
+/// See [`Connector::query_explain`, `Connector::mutation_explain`].
 #[derive(Debug, Error)]
 pub enum ExplainError {
     /// The request was invalid or did not match the
@@ -123,7 +123,7 @@ pub enum ExplainError {
     /// or just an unimplemented feature.
     #[error("unsupported operation: {0}")]
     UnsupportedOperation(String),
-    #[error("error explaining query: {0}")]
+    #[error("explain error: {0}")]
     Other(#[from] Box<dyn Error + Send + Sync>),
 }
 
@@ -163,8 +163,8 @@ pub enum MutationError {
 ///
 ///
 /// It provides methods which implement the standard endpoints
-/// defined by the specification: capabilities, schema, query, mutation
-/// and explain.
+/// defined by the specification: capabilities, schema, query, mutation,
+/// query/explain, and mutation/explain.
 ///
 /// In addition, it introduces names for types to manage
 /// state and configuration (if any), and provides any necessary context
@@ -269,14 +269,24 @@ pub trait Connector {
 
     /// Explain a query by creating an execution plan
     ///
-    /// This function implements the [explain endpoint](https://hasura.github.io/ndc-spec/specification/explain.html)
+    /// This function implements the [query/explain endpoint](https://hasura.github.io/ndc-spec/specification/explain.html)
     /// from the NDC specification.
-    async fn explain(
+    async fn query_explain(
         configuration: &Self::Configuration,
         state: &Self::State,
         request: models::QueryRequest,
     ) -> Result<JsonResponse<models::ExplainResponse>, ExplainError>;
 
+    /// Explain a mutation by creating an execution plan
+    ///
+    /// This function implements the [mutation/explain endpoint](https://hasura.github.io/ndc-spec/specification/explain.html)
+    /// from the NDC specification.
+    async fn mutation_explain(
+        configuration: &Self::Configuration,
+        state: &Self::State,
+        request: models::MutationRequest,
+    ) -> Result<JsonResponse<models::ExplainResponse>, ExplainError>;
+
     /// Execute a mutation
     ///
     /// This function implements the [mutation endpoint](https://hasura.github.io/ndc-spec/specification/mutations/index.html)

rust-connector-sdk/src/connector/example.rs

@@ -52,13 +52,17 @@ impl Connector for Example {
 
     async fn get_capabilities() -> JsonResponse<models::CapabilitiesResponse> {
         models::CapabilitiesResponse {
-            versions: "^0.1.0".into(),
+            version: "0.1.0".into(),
             capabilities: models::Capabilities {
-                explain: None,
                 relationships: None,
                 query: models::QueryCapabilities {
                     variables: None,
                     aggregates: None,
+                    explain: None,
+                },
+                mutation: models::MutationCapabilities {
+                    transactional: None,
+                    explain: None,
                 },
             },
         }
@@ -84,14 +88,22 @@ impl Connector for Example {
         .into())
     }
 
-    async fn explain(
+    async fn query_explain(
         _configuration: &Self::Configuration,
         _state: &Self::State,
         _request: models::QueryRequest,
     ) -> Result<JsonResponse<models::ExplainResponse>, ExplainError> {
         todo!()
     }
 
+    async fn mutation_explain(
+        _configuration: &Self::Configuration,
+        _state: &Self::State,
+        _request: models::MutationRequest,
+    ) -> Result<JsonResponse<models::ExplainResponse>, ExplainError> {
+        todo!()
+    }
+
     async fn mutation(
         _configuration: &Self::Configuration,
         _state: &Self::State,

rust-connector-sdk/src/default_main.rs

@@ -294,8 +294,9 @@ where
         .route("/metrics", get(get_metrics::<C>))
         .route("/schema", get(get_schema::<C>))
         .route("/query", post(post_query::<C>))
-        .route("/explain", post(post_explain::<C>))
+        .route("/query/explain", post(post_query_explain::<C>))
         .route("/mutation", post(post_mutation::<C>))
+        .route("/mutation/explain", post(post_mutation_explain::<C>))
         .layer(
             TraceLayer::new_for_http()
                 .make_span_with(make_span)
@@ -373,7 +374,7 @@ where
         .route("/query", post(v2_compat::post_query::<C>))
         // .route("/mutation", post(v2_compat::post_mutation::<C>))
         // .route("/raw", post(v2_compat::post_raw::<C>))
-        .route("/explain", post(v2_compat::post_explain::<C>))
+        .route("/query/explain", post(v2_compat::post_explain::<C>))
         .layer(
             TraceLayer::new_for_http()
                 .make_span_with(make_span)
@@ -464,11 +465,18 @@ async fn get_schema<C: Connector>(
     routes::get_schema::<C>(&state.configuration).await
 }
 
-async fn post_explain<C: Connector>(
+async fn post_query_explain<C: Connector>(
     State(state): State<ServerState<C>>,
     WithRejection(Json(request), _): WithRejection<Json<QueryRequest>, JsonRejection>,
 ) -> Result<JsonResponse<ExplainResponse>, (StatusCode, Json<ErrorResponse>)> {
-    routes::post_explain::<C>(&state.configuration, &state.state, request).await
+    routes::post_query_explain::<C>(&state.configuration, &state.state, request).await
+}
+
+async fn post_mutation_explain<C: Connector>(
+    State(state): State<ServerState<C>>,
+    WithRejection(Json(request), _): WithRejection<Json<MutationRequest>, JsonRejection>,
+) -> Result<JsonResponse<ExplainResponse>, (StatusCode, Json<ErrorResponse>)> {
+    routes::post_mutation_explain::<C>(&state.configuration, &state.state, request).await
 }
 
 async fn post_mutation<C: Connector>(

rust-connector-sdk/src/default_main/v2_compat.rs

@@ -67,17 +67,31 @@ pub async fn get_capabilities<C: Connector>(
                                 models::Type::Named { name } => Some((function_name, name)),
                                 models::Type::Nullable { .. } => None,
                                 models::Type::Array { .. } => None,
+                                models::Type::Predicate { .. } => None,
                             },
                         ),
                     )),
                     comparison_operators: Some(IndexMap::from_iter(
                         scalar_type.comparison_operators.into_iter().filter_map(
-                            |(operator_name, comparison_operator)| match comparison_operator
-                                .argument_type
-                            {
-                                models::Type::Named { name } => Some((operator_name, name)),
-                                models::Type::Nullable { .. } => None,
-                                models::Type::Array { .. } => None,
+                            |(operator_name, comparison_operator)| match comparison_operator {
+                                models::ComparisonOperatorDefinition::Equal => {
+                                    Some(("equal".to_string(), "equal".to_string()))
+                                }
+                                models::ComparisonOperatorDefinition::In => {
+                                    Some(("in".to_string(), "in".to_string()))
+                                }
+                                models::ComparisonOperatorDefinition::Custom {
+                                    argument_type: models::Type::Named { name },
+                                } => Some((operator_name, name)),
+                                models::ComparisonOperatorDefinition::Custom {
+                                    argument_type: models::Type::Nullable { .. },
+                                } => None,
+                                models::ComparisonOperatorDefinition::Custom {
+                                    argument_type: models::Type::Array { .. },
+                                } => None,
+                                models::ComparisonOperatorDefinition::Custom {
+                                    argument_type: models::Type::Predicate { .. },
+                                } => None,
                             },
                         ),
                     )),
@@ -116,7 +130,7 @@ pub async fn get_capabilities<C: Connector>(
         },
         config_schemas: get_openapi_config_schema_response(),
         display_name: None,
-        release_name: Some(v3_capabilities.versions.to_owned()),
+        release_name: Some(v3_capabilities.version.to_owned()),
     };
 
     Ok(Json(response))
@@ -355,6 +369,7 @@ fn get_field_type(column_type: &models::Type, schema: &models::SchemaResponse) -
                 nullable: matches!(**element_type, models::Type::Nullable { .. }),
             })
         }
+        models::Type::Predicate { .. } => todo!(),
     }
 }
 
@@ -415,7 +430,7 @@ pub async fn post_explain<C: Connector>(
             }),
         )
     })?;
-    let response = C::explain(&state.configuration, &state.state, request.clone())
+    let response = C::query_explain(&state.configuration, &state.state, request.clone())
         .await
         .and_then(JsonResponse::into_value)
         .map_err(|err| match err {
@@ -479,7 +494,7 @@ fn map_query_request(request: QueryRequest) -> Result<models::QueryRequest, Erro
                         name: key.to_owned(),
                         path: vec![],
                     },
-                    operator: models::BinaryComparisonOperator::Equal,
+                    operator: "equal".to_string(),
                     value: models::ComparisonValue::Variable {
                         name: key.to_owned(),
                     },
@@ -658,7 +673,10 @@ fn map_query(
                             Field::Column {
                                 column,
                                 column_type: _,
-                            } => models::Field::Column { column },
+                            } => models::Field::Column {
+                                column,
+                                fields: None,
+                            },
                             Field::Relationship {
                                 query,
                                 relationship,
@@ -808,12 +826,13 @@ fn map_order_by_path(
             relationship: format!("{}.{}", source_table, segment),
             arguments,
             predicate: if let Some(predicate) = &relation.r#where {
-                Box::new(map_expression(predicate, &target_table, relationships)?)
+                Some(Box::new(map_expression(
+                    predicate,
+                    &target_table,
+                    relationships,
+                )?))
             } else {
-                // hack: predicate is not optional, so default to empty "And" expression, which evaluates to true.
-                Box::new(models::Expression::And {
-                    expressions: vec![],
-                })
+                None
             },
         });
 
@@ -897,28 +916,12 @@ fn map_expression(
         } => models::Expression::BinaryComparisonOperator {
             column: map_comparison_column(column)?,
             operator: match operator {
-                BinaryComparisonOperator::LessThan => models::BinaryComparisonOperator::Other {
-                    name: "less_than".to_string(),
-                },
-                BinaryComparisonOperator::LessThanOrEqual => {
-                    models::BinaryComparisonOperator::Other {
-                        name: "less_than_or_equal".to_string(),
-                    }
-                }
-                BinaryComparisonOperator::Equal => models::BinaryComparisonOperator::Equal,
-                BinaryComparisonOperator::GreaterThan => models::BinaryComparisonOperator::Other {
-                    name: "greater_than".to_string(),
-                },
-                BinaryComparisonOperator::GreaterThanOrEqual => {
-                    models::BinaryComparisonOperator::Other {
-                        name: "greater_than_or_equal".to_string(),
-                    }
-                }
-                BinaryComparisonOperator::Other(operator) => {
-                    models::BinaryComparisonOperator::Other {
-                        name: operator.to_owned(),
-                    }
-                }
+                BinaryComparisonOperator::LessThan => "less_than".to_string(),
+                BinaryComparisonOperator::LessThanOrEqual => "less_than_or_equal".to_string(),
+                BinaryComparisonOperator::Equal => "equal".to_string(),
+                BinaryComparisonOperator::GreaterThan => "greater_than".to_string(),
+                BinaryComparisonOperator::GreaterThanOrEqual => "greater_than_or_equal".to_string(),
+                BinaryComparisonOperator::Other(operator) => operator.to_owned(),
             },
             value: match value {
                 ComparisonValue::Scalar {
@@ -937,10 +940,10 @@ fn map_expression(
             operator,
             value_type: _,
             values,
-        } => models::Expression::BinaryArrayComparisonOperator {
+        } => models::Expression::BinaryComparisonOperator {
             column: map_comparison_column(column)?,
             operator: match operator {
-                BinaryArrayComparisonOperator::In => models::BinaryArrayComparisonOperator::In,
+                BinaryArrayComparisonOperator::In => "in".to_string(),
                 BinaryArrayComparisonOperator::Other(operator) => {
                     return Err(ErrorResponse {
                         details: None,
@@ -949,20 +952,21 @@ fn map_expression(
                     })
                 }
             },
-            values: values
-                .iter()
-                .map(|value| models::ComparisonValue::Scalar {
-                    value: value.clone(),
-                })
-                .collect(),
+            value: models::ComparisonValue::Scalar {
+                value: serde_json::to_value(values).unwrap(),
+            },
         },
         Expression::Exists { in_table, r#where } => match in_table {
             ExistsInTable::Unrelated { table } => models::Expression::Exists {
                 in_collection: models::ExistsInCollection::Unrelated {
                     collection: get_name(table)?,
                     arguments: BTreeMap::new(),
                 },
-                predicate: Box::new(map_expression(r#where, &get_name(table)?, relationships)?),
+                predicate: Some(Box::new(map_expression(
+                    r#where,
+                    &get_name(table)?,
+                    relationships,
+                )?)),
             },
             ExistsInTable::Related { relationship } => {
                 let (target_table, arguments) =
@@ -973,7 +977,11 @@ fn map_expression(
                         relationship: format!("{}.{}", collection, relationship),
                         arguments,
                     },
-                    predicate: Box::new(map_expression(r#where, &target_table, relationships)?),
+                    predicate: Some(Box::new(map_expression(
+                        r#where,
+                        &target_table,
+                        relationships,
+                    )?)),
                 }
             }
         },