feat(core/ws/openapi): complete quick-wins must-haves

Author: Tuntii

crates/rustapi-core/src/app.rs

@@ -1072,20 +1072,7 @@ impl RustApi {
         server.run().await
     }
 
-    /// Run both HTTP/1.1 and HTTP/3 servers simultaneously
-    ///
-    /// This allows clients to use either protocol. The HTTP/1.1 server
-    /// will advertise HTTP/3 availability via Alt-Svc header.
-    ///
-    /// # Example
-    ///
-    /// ```rust,ignore
-    /// RustApi::new()
-    ///     .route("/", get(hello))
-    ///     .run_dual_stack("0.0.0.0:8080", Http3Config::new("cert.pem", "key.pem"))
-    ///     .await
-    /// ```
-    /// Configure HTTP/3 support
+    /// Configure HTTP/3 support for `run_http3` and `run_dual_stack`.
     ///
     /// # Example
     ///
@@ -1101,10 +1088,10 @@ impl RustApi {
         self
     }
 
-    /// Run both HTTP/1.1 and HTTP/3 servers simultaneously
+    /// Run both HTTP/1.1 (TCP) and HTTP/3 (QUIC/UDP) simultaneously.
     ///
-    /// This allows clients to use either protocol. The HTTP/1.1 server
-    /// will advertise HTTP/3 availability via Alt-Svc header.
+    /// The HTTP/3 listener is bound to the same host and port as `http_addr`
+    /// so clients can upgrade to either protocol on one endpoint.
     ///
     /// # Example
     ///
@@ -1118,22 +1105,49 @@ impl RustApi {
     #[cfg(feature = "http3")]
     pub async fn run_dual_stack(
         mut self,
-        _http_addr: &str,
+        http_addr: &str,
     ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
-        // TODO: Dual-stack requires Router, LayerStack, InterceptorChain to implement Clone.
-        // For now, we only run HTTP/3.
-        // In the future, we can either:
-        // 1. Make Router/LayerStack/InterceptorChain Clone
-        // 2. Use Arc<RwLock<...>> pattern
-        // 3. Create shared state mechanism
-
-        let config = self
+        use std::sync::Arc;
+
+        let mut config = self
             .http3_config
             .take()
             .ok_or("HTTP/3 config not set. Use .with_http3(...)")?;
 
-        tracing::warn!("run_dual_stack currently only runs HTTP/3. HTTP/1.1 support coming soon.");
-        self.run_http3(config).await
+        let http_socket: std::net::SocketAddr = http_addr.parse()?;
+        config.bind_addr = http_socket.ip().to_string();
+        config.port = http_socket.port();
+        let http_addr = http_socket.to_string();
+
+        // Apply status page if configured
+        self.apply_status_page();
+
+        // Apply body limit layer if configured
+        if let Some(limit) = self.body_limit {
+            self.layers.prepend(Box::new(BodyLimitLayer::new(limit)));
+        }
+
+        let router = Arc::new(self.router);
+        let layers = Arc::new(self.layers);
+        let interceptors = Arc::new(self.interceptors);
+
+        let http1_server =
+            Server::from_shared(router.clone(), layers.clone(), interceptors.clone());
+        let http3_server =
+            crate::http3::Http3Server::new(&config, router, layers, interceptors).await?;
+
+        tracing::info!(
+            http1_addr = %http_addr,
+            http3_addr = %config.socket_addr(),
+            "Starting dual-stack HTTP/1.1 + HTTP/3 servers"
+        );
+
+        tokio::try_join!(
+            http1_server.run_with_shutdown(&http_addr, std::future::pending::<()>()),
+            http3_server.run_with_shutdown(std::future::pending::<()>()),
+        )?;
+
+        Ok(())
     }
 }
 

crates/rustapi-core/src/server.rs

@@ -34,6 +34,19 @@ impl Server {
         }
     }
 
+    #[cfg(feature = "http3")]
+    pub fn from_shared(
+        router: Arc<Router>,
+        layers: Arc<LayerStack>,
+        interceptors: Arc<InterceptorChain>,
+    ) -> Self {
+        Self {
+            router,
+            layers,
+            interceptors,
+        }
+    }
+
     /// Run the server
     pub async fn run(self, addr: &str) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
         self.run_with_shutdown(addr, std::future::pending()).await

crates/rustapi-openapi/README.md

@@ -11,7 +11,7 @@ Automated API specifications and Swagger UI integration for RustAPI.
 
 1. **Reflection**: RustAPI macros collect metadata about your routes (path, method, input types, output types) at compile time
 2. **Schema Gen**: Uses RustAPI's native schema engine to generate OpenAPI-compatible JSON Schemas
-3. **Spec Build**: At runtime, assembles the full OpenAPI 3.0 JSON specification
+3. **Spec Build**: At runtime, assembles the full OpenAPI 3.1 JSON specification with schema ref integrity checks
 4. **UI Serve**: Embeds the Swagger UI assets and serves them at your specified path
 
 ## Route Metadata Macros

crates/rustapi-openapi/src/tests.rs

@@ -267,4 +267,100 @@ mod tests {
         let missing = result.unwrap_err();
         assert!(missing.contains(&"#/components/schemas/NonExistent".to_string()));
     }
+
+    #[test]
+    fn test_ref_integrity_components_traverses_all_ref_bearing_members() {
+        let mut spec = OpenApiSpec::new("Test", "1.0");
+        let mut components = crate::spec::Components::default();
+
+        components.responses.insert(
+            "badResponse".to_string(),
+            crate::spec::ResponseSpec {
+                description: "bad".to_string(),
+                content: std::collections::BTreeMap::from([(
+                    "application/json".to_string(),
+                    crate::spec::MediaType {
+                        schema: Some(SchemaRef::Ref {
+                            reference: "#/components/schemas/MissingFromResponse".to_string(),
+                        }),
+                        example: None,
+                    },
+                )]),
+                headers: std::collections::BTreeMap::from([(
+                    "X-Callback".to_string(),
+                    crate::spec::Header {
+                        description: None,
+                        schema: Some(SchemaRef::Ref {
+                            reference: "#/components/schemas/MissingFromResponseHeader".to_string(),
+                        }),
+                    },
+                )]),
+            },
+        );
+
+        components.request_bodies.insert(
+            "badRequestBody".to_string(),
+            crate::spec::RequestBody {
+                description: None,
+                required: Some(true),
+                content: std::collections::BTreeMap::from([(
+                    "application/json".to_string(),
+                    crate::spec::MediaType {
+                        schema: Some(SchemaRef::Ref {
+                            reference: "#/components/schemas/MissingFromRequestBody".to_string(),
+                        }),
+                        example: None,
+                    },
+                )]),
+            },
+        );
+
+        components.headers.insert(
+            "badHeader".to_string(),
+            crate::spec::Header {
+                description: None,
+                schema: Some(SchemaRef::Ref {
+                    reference: "#/components/schemas/MissingFromHeader".to_string(),
+                }),
+            },
+        );
+
+        let mut callback_operation = crate::spec::Operation::new();
+        callback_operation.request_body = Some(crate::spec::RequestBody {
+            description: None,
+            required: Some(true),
+            content: std::collections::BTreeMap::from([(
+                "application/json".to_string(),
+                crate::spec::MediaType {
+                    schema: Some(SchemaRef::Ref {
+                        reference: "#/components/schemas/MissingFromCallback".to_string(),
+                    }),
+                    example: None,
+                },
+            )]),
+        });
+
+        let mut callback_path = crate::spec::PathItem::default();
+        callback_path.post = Some(callback_operation);
+
+        components.callbacks.insert(
+            "badCallback".to_string(),
+            std::collections::BTreeMap::from([(
+                "{$request.body#/callbackUrl}".to_string(),
+                callback_path,
+            )]),
+        );
+
+        spec.components = Some(components);
+
+        let missing = spec
+            .validate_integrity()
+            .expect_err("should report all missing schema refs");
+
+        assert!(missing.contains(&"#/components/schemas/MissingFromResponse".to_string()));
+        assert!(missing.contains(&"#/components/schemas/MissingFromResponseHeader".to_string()));
+        assert!(missing.contains(&"#/components/schemas/MissingFromRequestBody".to_string()));
+        assert!(missing.contains(&"#/components/schemas/MissingFromHeader".to_string()));
+        assert!(missing.contains(&"#/components/schemas/MissingFromCallback".to_string()));
+    }
 }

crates/rustapi-ws/src/compression.rs

@@ -68,7 +68,10 @@ mod tests {
                 .client_window_bits(client_window_bits);
 
             let client_extensions = if client_supports_compression {
-                Some("permessage-deflate; client_max_window_bits".to_string())
+                Some(
+                    "permessage-deflate; server_max_window_bits=15; client_max_window_bits"
+                        .to_string(),
+                )
             } else {
                 None
             };