Propagate required environment prompts through V10 ABI

Author: cloutiertyler

crates/client-api/src/routes/database.rs

@@ -580,21 +580,54 @@ impl From<Database> for DatabaseResponse {
     }
 }
 
-fn publish_error(error: anyhow::Error) -> axum::response::ErrorResponse {
-    if let Some(error) = error.downcast_ref::<spacetimedb_lib::environment::EnvironmentSchemaError>() {
-        return (StatusCode::BAD_REQUEST, error.to_string()).into();
-    }
-    if let Some(spacetimedb::db::environment::EnvironmentError::Schema(error)) =
-        error.downcast_ref::<spacetimedb::db::environment::EnvironmentError>()
+fn environment_validation_error(error: &anyhow::Error) -> Option<axum::response::ErrorResponse> {
+    use spacetimedb::db::environment::EnvironmentError;
+    use spacetimedb::host::module_host::InitDatabaseError;
+    use spacetimedb_lib::environment::{validate_key, EnvironmentSchemaError, EnvironmentSchemaErrorKind};
+    if let Some(InitDatabaseError::Other(error)) = error.downcast_ref::<InitDatabaseError>() {
+        return environment_validation_error(error);
+    }
+    let error =
+        error
+            .downcast_ref::<EnvironmentSchemaError>()
+            .or_else(|| match error.downcast_ref::<EnvironmentError>() {
+                Some(EnvironmentError::Schema(error)) => Some(error),
+                _ => None,
+            })?;
+    // Only typed host validation can ask the caller for a secret. Never infer
+    // missing keys from module failures or arbitrary diagnostic text.
+    if error.kind == EnvironmentSchemaErrorKind::MissingRequired
+        && let Some(key) = error.key.as_deref().filter(|key| validate_key(key).is_ok())
     {
-        return (StatusCode::BAD_REQUEST, error.to_string()).into();
+        return Some(
+            (
+                StatusCode::BAD_REQUEST,
+                axum::Json(serde_json::json!({
+                    "error": "missing_required_environment",
+                    "key": key,
+                })),
+            )
+                .into(),
+        );
+    }
+    Some((StatusCode::BAD_REQUEST, error.to_string()).into())
+}
+
+fn publish_error(error: anyhow::Error) -> axum::response::ErrorResponse {
+    if let Some(response) = environment_validation_error(&error) {
+        return response;
     }
     if let Some(error) = error.downcast_ref::<spacetimedb::host::EnvironmentVersionConflict>() {
         return (StatusCode::CONFLICT, error.to_string()).into();
     }
     log_and_500(error)
 }
 
+fn publish_migration_error(error: anyhow::Error) -> axum::response::ErrorResponse {
+    environment_validation_error(&error)
+        .unwrap_or_else(|| bad_request(format!("Failed to create or update the database: {error}").into()))
+}
+
 pub async fn environment_metadata<S>(
     State(ctx): State<S>,
     Extension(ResolvedDatabase(database)): Extension<ResolvedDatabase>,
@@ -925,7 +958,7 @@ pub async fn reset<S: NodeDelegate + ControlStateDelegate + Authorization>(
         },
     )
     .await
-    .map_err(log_and_500)?;
+    .map_err(publish_error)?;
 
     Ok(axum::Json(PublishResult::Success {
         domain: name_or_identity.name().cloned(),
@@ -1164,9 +1197,7 @@ pub async fn publish<S: NodeDelegate + ControlStateDelegate + Authorization>(
         Some(UpdateDatabaseResult::AutoMigrateError(errs)) => {
             Err(bad_request(format!("Database update rejected: {errs}").into()))
         }
-        Some(UpdateDatabaseResult::ErrorExecutingMigration(err)) => Err(bad_request(
-            format!("Failed to create or update the database: {err}").into(),
-        )),
+        Some(UpdateDatabaseResult::ErrorExecutingMigration(err)) => Err(publish_migration_error(err)),
         None | Some(UpdateDatabaseResult::NoUpdateNeeded) => Ok(success()),
         Some(
             UpdateDatabaseResult::UpdatePerformed {
@@ -1821,6 +1852,59 @@ mod tests {
     use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
     use tower::util::ServiceExt;
 
+    #[tokio::test]
+    async fn publish_environment_error_identifies_only_typed_missing_required_keys() {
+        use spacetimedb_lib::environment::{EnvironmentSchemaError, EnvironmentSchemaErrorKind};
+        let missing = || EnvironmentSchemaError {
+            key: Some("API_KEY".into()),
+            kind: EnvironmentSchemaErrorKind::MissingRequired,
+        };
+        for response in [
+            publish_error(anyhow::Error::new(missing()).context("publication failed")),
+            publish_migration_error(spacetimedb::db::environment::EnvironmentError::Schema(missing()).into()),
+            publish_error(
+                spacetimedb::host::module_host::InitDatabaseError::Other(
+                    spacetimedb::db::environment::EnvironmentError::Schema(missing()).into(),
+                )
+                .into(),
+            ),
+            publish_migration_error(
+                spacetimedb::host::module_host::InitDatabaseError::Other(
+                    spacetimedb::db::environment::EnvironmentError::Schema(missing()).into(),
+                )
+                .into(),
+            ),
+        ] {
+            let response = Err::<(), _>(response).into_response();
+            assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+            assert_eq!(response.headers()[http::header::CONTENT_TYPE], "application/json");
+            let body = axum::body::to_bytes(response.into_body(), 1024).await.unwrap();
+            assert_eq!(
+                serde_json::from_slice::<serde_json::Value>(&body).unwrap(),
+                serde_json::json!({
+                    "error": "missing_required_environment", "key": "API_KEY",
+                })
+            );
+        }
+        for error in [
+            anyhow::anyhow!("environment key API_KEY: required value is missing"),
+            EnvironmentSchemaError {
+                key: Some("API_KEY".into()),
+                kind: EnvironmentSchemaErrorKind::ConstraintMismatch,
+            }
+            .into(),
+            EnvironmentSchemaError {
+                key: Some("INVALID-KEY".into()),
+                kind: EnvironmentSchemaErrorKind::MissingRequired,
+            }
+            .into(),
+        ] {
+            let response = Err::<(), _>(publish_migration_error(error)).into_response();
+            assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+            assert_ne!(response.headers()[http::header::CONTENT_TYPE], "application/json");
+        }
+    }
+
     #[derive(Clone, Default)]
     struct DummyValidator;
 

docs/docs/00300-resources/00200-reference/00200-http-api/00300-database.md

@@ -114,6 +114,8 @@ Both publish endpoints accept `Content-Type: application/vnd.spacetimedb.publish
 
 `module` uses standard padded Base64. `environment` supplies string overrides for declared or undeclared names. Unspecified stored values survive by default. The server validates the resulting environment against the module's declarations and installs both in one transaction: all required values must exist and all present declared values must satisfy their constraints. An empty or omitted map preserves stored values, including when publishing unchanged module bytes.
 
+A missing required value returns HTTP 400 with `Content-Type: application/json` and `{"error":"missing_required_environment","key":"API_KEY"}` identifying the missing key. Clients can prompt for that value and retry the publish. Other validation and module failures do not use this error code.
+
 Optional fields `environment_remove` (an array of keys) and `environment_replace` (a boolean, default `false`) request explicit deletion or complete replacement. A key cannot be both supplied and removed. Replacement uses only the supplied map, deleting every unspecified declared and undeclared key, and rejects any nonempty removal list. Invalid updates leave the database unchanged.
 
 To update an existing database without a module, omit `module` and provide `expected_module_version` from `GET /v1/database/{name_or_identity}/environment`. That authorized endpoint returns `module_version`, `declarations`, and `stored_keys`, without secret values. Each declaration contains `name`, `optional`, and `constraint`: `"AnyString"`, `{"Literal":"value"}`, or `{"OneOf":["a","b"]}`. Metadata comes from one database version. For example: