Merge remote-tracking branch 'origin/main' into deployment-spec-sdk

.github/workflows/test.yaml

@@ -0,0 +1,23 @@
+name: test
+
+on:
+  push:
+
+jobs:
+  cargo-test:
+    name: run cargo test
+    runs-on: ubuntu-latest
+    env:
+      CARGO_NET_GIT_FETCH_WITH_CLI: "true"
+      RUSTFLAGS: "-D warnings" # fail on warnings
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: install tools
+        run: |
+          rustup show
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: run tests
+        run: cargo test

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.15" }
+ndc-test = { git = "http://github.com/hasura/ndc-spec.git", tag = "v0.1.0-rc.15" }
 
 async-trait = "^0.1.74"
 axum = "^0.6.20"

rust-connector-sdk/src/connector.rs

@@ -95,7 +95,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
@@ -113,7 +113,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>),
 }
 
@@ -153,8 +153,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
@@ -251,14 +251,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

@@ -43,13 +43,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,
                 },
             },
         }
@@ -75,14 +79,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

@@ -275,8 +275,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)
@@ -354,7 +355,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)
@@ -445,11 +446,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>(