Update force_https doc and add example (#884)

crates/extra/src/force_https.rs

@@ -1,11 +1,22 @@
 //! Middleware force redirect to https.
-//! 
-//! Force the current request to be redirected to the https protocol.
+//!
+//! The force-https middleware can force all requests to use the HTTPS protocol.
+//!
+//! If this middleware is applied to the Router, the protocol will be forced to
+//! convert only when the route is matched. If the page does not exist, it will
+//! not be redirected.
+//!
+//! But the more common requirement is to expect any request to be
+//! automatically redirected, even when the route fails to match and returns a
+//! 404 error. At this time, the middleware can be added to the Service.
+//! Regardless of whether the request is successfully matched by the route,
+//! the middleware added to the Service will always be executed.
 //!
 //! Example:
 //!
 //! ```no_run
 //! use salvo_core::prelude::*;
+//! use salvo_core::conn::rustls::{Keycert, RustlsConfig};
 //! use salvo_extra::force_https::ForceHttps;
 //!
 //! #[handler]
@@ -15,9 +26,20 @@
 //!
 //! #[tokio::main]
 //! async fn main() {
-//!     let router = Router::with_hoop(ForceHttps::new().https_port(1234)).goal(hello);
-//!     let acceptor = TcpListener::new("0.0.0.0:5800").bind().await;
-//!     Server::new(acceptor).serve(router).await;
+//!     let router = Router::new().get(hello);
+//!     let service = Service::new(router).hoop(ForceHttps::new().https_port(5443));
+//!
+//!     let config = RustlsConfig::new(
+//!         Keycert::new()
+//!             .cert(include_bytes!("../../core/certs/cert.pem").as_ref())
+//!             .key(include_bytes!("../../core/certs/key.pem").as_ref()),
+//!     );
+//!     let acceptor = TcpListener::new("0.0.0.0:5443")
+//!         .rustls(config)
+//!         .join(TcpListener::new("0.0.0.0:5800"))
+//!         .bind()
+//!         .await;
+//!     Server::new(acceptor).serve(service).await;
 //! }
 //! ```
 use std::borrow::Cow;

crates/oapi-macros/src/feature/mod.rs

@@ -231,8 +231,12 @@ impl TryToTokens for Feature {
             Feature::AdditionalProperties(additional_properties) => {
                 quote! { .additional_properties(#additional_properties) }
             }
-            Feature::ContentEncoding(content_encoding) => quote! { .content_encoding(#content_encoding) },
-            Feature::ContentMediaType(content_media_type) => quote! { .content_media_type(#content_media_type) },
+            Feature::ContentEncoding(content_encoding) => {
+                quote! { .content_encoding(#content_encoding) }
+            }
+            Feature::ContentMediaType(content_media_type) => {
+                quote! { .content_media_type(#content_media_type) }
+            }
             Feature::RenameAll(_) => {
                 return Err(Diagnostic::spanned(
                     Span::call_site(),

examples/force-https/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "example-force-https"
+version.workspace = true
+edition.workspace = true
+publish.workspace = true
+
+
+[dependencies]
+salvo = { workspace = true, features = ["rustls", "force-https"] }
+tokio = { workspace = true, features = ["macros"] }
+tracing.workspace = true
+tracing-subscriber.workspace = true

examples/force-https/certs/cert.pem

@@ -0,0 +1,24 @@
+-----BEGIN CERTIFICATE-----
+MIIEADCCAmigAwIBAgICAcgwDQYJKoZIhvcNAQELBQAwLDEqMCgGA1UEAwwhcG9u
+eXRvd24gUlNBIGxldmVsIDIgaW50ZXJtZWRpYXRlMB4XDTIyMDgxMTAwMjYwOVoX
+DTI4MDIwMTAwMjYwOVowGTEXMBUGA1UEAwwOdGVzdHNlcnZlci5jb20wggEiMA0G
+CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCxLgy9h8llkew2Bw09Alk7idMNbKE2
+wSxIesCfA46oDrrzUI5LK0WR2Ad47uXPjoAikveV+r63uyHx1tMOV7FTTOtLuDPq
+669FShjcNA4TZFOhYEngbRsAsdxZyvyVNBDSchZ0B+5P0VToJiCunWAWgV8JtuvA
+YTb0mGNzsVEclU9Y8RFX0gKMRO/4x0TugOlRtwlLOdQ29Xs++o30RrmijgvN9OX1
+osBtLHcRgp8OHkWrkl9m/HZ7w69OEUVUOpKBK6YRQYI/FK9t9uugMsWihzC0FLiD
+sedQYVdl5kur6yKZpc/+5hasP1GgbRBZYvCKXWqnPAwQdztoIZemOd8/AgMBAAGj
+gb4wgbswDAYDVR0TAQH/BAIwADALBgNVHQ8EBAMCBsAwHQYDVR0OBBYEFJxcZN4p
+MwrbjKGL2oujJfuY7ElCMEIGA1UdIwQ7MDmAFPuumMZTwOxgAcnlGSrXiqIVIPCp
+oR6kHDAaMRgwFgYDVQQDDA9wb255dG93biBSU0EgQ0GCAXswOwYDVR0RBDQwMoIO
+dGVzdHNlcnZlci5jb22CFXNlY29uZC50ZXN0c2VydmVyLmNvbYIJbG9jYWxob3N0
+MA0GCSqGSIb3DQEBCwUAA4IBgQCPVlRuEfjlUlgB1fwh1NkiCfbmw6T/WV7qCfzI
+fO30VHs45Nvru7gKZyKl2HrsnhfU8RaP6t5kAptJUPGAsiytkaYHsylx4te+pMvI
+ya/pvHcHQfMhrx0fPNnSg8gBZGLpegkec9/aTCujGKvunE4z+s/NWtANiTtvdGxX
+t7DQorVJbJSPdp5utAyXEZud8z653MfSKx47t795P5TYttX6H4BMUxo+fdhSfmHJ
+XfnmyKYbya3OkpBelAEslv4oI6t2Fbbg9EqKrb7MoBR+v0h7ZBAeg8YpaXErvFX6
+Ia83nTTozCnHxW8L1A6DZE2fYsL8264/nU5j2R9J4F8Vj3eVHhmMTHJMtxWH2kWu
+17i7j93mCRr2M8ajvSBkKGG/RpMTQCtEbhFPmxkxLNS8MpEwecaAGkbWTYlis6zc
+wsbNJcIpZ4MchK7VuTsWtbPV0Qo3ZuSS1YSy8G3OLAMb8wuEShuhgHT66hn8XvfX
+Z2qqYHw4gX1Gbx7R+RsgeLMurEg=
+-----END CERTIFICATE-----

examples/force-https/certs/key.pem

@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCxLgy9h8llkew2
+Bw09Alk7idMNbKE2wSxIesCfA46oDrrzUI5LK0WR2Ad47uXPjoAikveV+r63uyHx
+1tMOV7FTTOtLuDPq669FShjcNA4TZFOhYEngbRsAsdxZyvyVNBDSchZ0B+5P0VTo
+JiCunWAWgV8JtuvAYTb0mGNzsVEclU9Y8RFX0gKMRO/4x0TugOlRtwlLOdQ29Xs+
++o30RrmijgvN9OX1osBtLHcRgp8OHkWrkl9m/HZ7w69OEUVUOpKBK6YRQYI/FK9t
+9uugMsWihzC0FLiDsedQYVdl5kur6yKZpc/+5hasP1GgbRBZYvCKXWqnPAwQdzto
+IZemOd8/AgMBAAECggEAGT7QfejtH1XNbF1Q25KMGFmpAs6pod2ga6th6sZc+0Eu
+DiE6RSejQAah+e9AO3S4eTSrpmkV56P4UDcl13NTRuU82YsjiqOOU7cdF7MrFkRD
+Tkkj/aBOKqktFnY/yxqiEvpCjMHciO7wxCs6mOa/nDVOz1mK+dxgMjXMZd2sCwBW
+cnlo3JB7fbSIS2US3kT+AOGaPoLaUHVizRu40+DfPtZMfwnk8EOtCZziHoF3cT6j
+ZD9BJS9T0ph4AJqxWOM+GQDS08wmaOE8add6aV5whBf0H8mP4GFFFhabDr2+N/t7
+GZR9HbCZ79VDWKbggGA4cwlDv+LLBOGMKr784+J1oQKBgQDlsHAwZS7XG3uZrJpq
++DfAaK5fAIWNtsXn5pS5rJOXUs1UI7oswxKAQZ/pMgkUSZBLhpAWW6J6hh/ysz1L
+mQk3szfGrRlM30CC2CxYQgum7ARGtlYYdi1H9kvXyBAmoBi8MvUkgB3QltEWE1Fk
+SZ1/3uDNPudGWXsILl2zagb/mQKBgQDFecrcugQpdii9p1HMqAwugaLCviVBv9nz
+qub0eeCOm7RYHWp7EjJ0xXVQUN+/AEMP8UlqiIPKq3JtrOccx2dVwOC9341PD61t
+zY5dnIaU6UVVkv/vxt2uOnSmyGrRDfftvyRJZmQOJT5VfO1dPKgxeLjn8cY+u6FR
+idb7dYN8lwKBgB/9uyKCdUuwoD5/M+LCP8Gk0uSYhgF++4GZNA3IY6Yn+kFF2KBz
+axhCC6vHNEyHEnnyfA8hJDg8hiafoGHvJsGDTLl3UpbKYYnX4hVI3aaaKN5Qdx1h
+GF11iIq9asJ2eft8fXhf/8cVunmAp014k19EA7uSj1PVErXI/3QFyIPBAoGACWLX
+lJQ23G2kVBde2PZn1dINlWoKRUzEJEPMRHSCiuS1trZ3ODBOO6SjBdVCPUba6SgT
+0D963Cg4ASSFu6VysO3BAOVeRxK8sIpjqOlmsC9CP2YESjZOlRhsMP03roYWcbNz
+GxYFzXJRuyh788GNUQSm7Uddn9+1NDX0BPG59TMCgYEAnvDoFszjrh+Qlnnmr8c/
+fRMda8LGFqbHPRerLE7N0kRzJVeMhLs5hY8CaYUVp+0BxUgs56jCL4fw77u1u1iw
+2zGx2A0qBzK/heQvFKvK31WhZXj7lydOVW5p/CorO+nnFbqwy37KqHokb37Agbh+
+f/vchbnflC+rie5eKlI2LtA=
+-----END PRIVATE KEY-----

examples/force-https/src/main.rs

@@ -0,0 +1,27 @@
+use salvo::conn::rustls::{Keycert, RustlsConfig};
+use salvo::prelude::*;
+
+#[handler]
+async fn hello() -> &'static str {
+    "Hello World"
+}
+
+#[tokio::main]
+async fn main() {
+    tracing_subscriber::fmt().init();
+
+    let router = Router::new().get(hello);
+    let service = Service::new(router).hoop(ForceHttps::new().https_port(5443));
+
+    let config = RustlsConfig::new(
+        Keycert::new()
+            .cert(include_bytes!("../certs/cert.pem").as_ref())
+            .key(include_bytes!("../certs/key.pem").as_ref()),
+    );
+    let acceptor = TcpListener::new("0.0.0.0:5443")
+        .rustls(config)
+        .join(TcpListener::new("0.0.0.0:5800"))
+        .bind()
+        .await;
+    Server::new(acceptor).serve(service).await;
+}