feat(quic): 合并 QUIC/HTTP/3 文档与示例到 main (#141)

* fix(server): 启用 tokio macros 支持 select

* refactor(service): 调整证书加载逻辑

* refactor(service): 支持连接downcast能力

* feat(quic): 新增quic特性与模块，提供HTTP/3/WebTransport与Alt-Svc集成，以及统一run_server接口

* refactor(quic): 移除quic_available动态检测机制

- 移除AltSvcMiddleware中的quic_available参数，始终添加alt-svc头
- 简化HybridService，移除quic_available状态管理
- 清理QuicEndpointListener中未使用的quic_available字段
- 移除service.rs中的状态更新逻辑
- 添加Listener::tls_with_cert便捷方法

后台运行成功时h3必然生效，无需动态检测

* refactor(quic): 重构QUIC启动方式，统一HTTP和QUIC接口

- Route新增with_quic_port()方法，自动添加AltSvcMiddleware
- Route的ConnectionService实现支持自动识别和处理QUIC连接
- AltSvcMiddleware改为公开API，可手动hook使用
- 移除run_server封装函数和HybridService
- 简化service.rs，移除quic_port参数传递
- 新增Route::handle_http_connection辅助方法

BREAKING CHANGE: 移除quic::run_server函数，现在使用Server::new().listen().serve()统一接口

* feat(quic): add HybridListener for automatic HTTP fallback

- Add HybridListener struct containing QUIC and HTTP TLS listeners
- Add with_http_fallback() method to QuicEndpointListener
- Listen on UDP(QUIC) and TCP(HTTP) on the same port
- Use tokio::select! to accept both connection types
- Export HybridListener to public API

Now only one listener is needed to support both QUIC and HTTP fallback

* refactor(quic): store CertificateStore in QuicEndpointListener

- Add Clone derive to CertificateStore
- Store CertificateStore in QuicEndpointListener
- Remove store parameter from with_http_fallback()
- Simplify API usage - no need to pass store twice

Breaking Change: with_http_fallback() now takes no parameters

* feat(examples): 添加QUIC/HTTP3示例与文档 (#140)

* feat(examples): 添加QUIC/HTTP3示例并启用同端口HTTPS回退
提供最小可运行示例：with_quic_port下发Alt-Svc，QuicEndpointListener混合监听
运行方式：cargo run -p example-quic，curl --http3 验证

* docs(requirements): 增加QUIC示例需求整理
记录示例目标、范围、依赖与运行方式，确保需求对齐

* style: 优化代码格式和导入顺序，移除未使用的文档

Author: hubertshelley

deny.toml

@@ -117,6 +117,7 @@ exceptions = [
     # Each entry is the crate and version constraint, and its specific allow
     # list
     #{ allow = ["Zlib"], crate = "adler32" },
+    { allow = ["CDLA-Permissive-2.0"], crate = "webpki-root-certs" },
 ]
 
 # Some crates don't have (easily) machine readable licensing information,

docs/quic-webtransport.md

@@ -0,0 +1,150 @@
+# QUIC / HTTP/3 / WebTransport 使用与编写说明
+
+> 状态：实验性（feature 可选，默认未启用）。当前已支持基于 `quinn + h3` 的 HTTP/3 与 WebTransport 基础能力，推荐在测试或内网环境先行验证。
+
+## 功能概览
+
+- QUIC 监听与同端口回退：UDP QUIC 与 TCP HTTPS 共享同一端口（混合监听）。
+- HTTP/3（h3）：常规请求-响应模型已打通，可与现有路由/中间件协同。
+- Alt-Svc：通过中间件向客户端宣告 h3 可用，浏览器可自动升级。
+- WebTransport：已开启握手与数据帧收发，内置 Echo 示例（会话 ID 使用 `scru128` 生成）。
+
+## 前置要求
+
+- Rust 1.77+ 与 Tokio 运行时。
+- 证书（PEM 或 DER），建议准备一套本地开发证书（仓库已提供示例）。
+- 客户端需支持 HTTP/3（如 curl --http3、现代浏览器）。
+
+## 启用 QUIC 特性
+
+- 在你的可执行包或示例中，启用 `silent` 的 `quic` feature：
+
+- Cargo.toml
+```toml
+[dependencies]
+silent = { path = "../../silent", features = ["quic"] }
+```
+
+> 工作区示例可参考：`examples/quic/Cargo.toml`
+
+## 证书准备
+
+- 使用 `CertificateStore` 构建 rustls 服务器配置，并设置 ALPN：库内部会自动为 QUIC 配置 `h3`/`h3-29`。
+- 你可以直接复用示例证书：`examples/tls/certs/localhost+2.pem` 与 `localhost+2-key.pem`。
+
+- 代码示例
+```rust
+fn certificate_store() -> anyhow::Result<silent::CertificateStore> {
+    let builder = silent::CertificateStore::builder()
+        .cert_path("./examples/tls/certs/localhost+2.pem")
+        .key_path("./examples/tls/certs/localhost+2-key.pem");
+    Ok(builder.build()?)
+}
+```
+
+> 若使用自签证书，浏览器需要手动信任根证书；curl 可使用 `-k` 跳过校验进行快速验证。
+
+## 启动服务（QUIC + HTTPS 回退）
+
+- 使用 `QuicEndpointListener::new(...).with_http_fallback()` 创建混合监听；
+- 通过 `Route::with_quic_port(port)` 自动添加 Alt-Svc；
+
+- 最小示例（与 `examples/quic/src/main.rs` 一致）：
+```rust
+use anyhow::{Result, anyhow};
+use silent::prelude::*;
+use silent::QuicEndpointListener;
+use tracing_subscriber::EnvFilter;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    init_tracing();
+    install_rustls_provider()?;
+
+    let routes = build_routes().with_quic_port(4433); // 自动添加 Alt-Svc
+
+    let bind_addr: std::net::SocketAddr = "127.0.0.1:4433".parse().unwrap();
+    let store = certificate_store()?;
+
+    let listener = QuicEndpointListener::new(bind_addr, &store).with_http_fallback();
+    Server::new().listen(listener).serve(routes).await;
+    Ok(())
+}
+
+fn install_rustls_provider() -> Result<()> {
+    rustls::crypto::ring::default_provider()
+        .install_default()
+        .map_err(|_| anyhow!("初始化 Rustls 加密提供者失败"))
+}
+
+fn build_routes() -> Route {
+    async fn index(_req: Request) -> silent::Result<&'static str> {
+        Ok("Hello from HTTP/3")
+    }
+    let mut root = Route::new_root();
+    root.push(Route::new("").get(index));
+    root
+}
+```
+
+## Alt-Svc（HTTP/3 升级宣告）
+
+- `with_quic_port(port)` 会自动挂载 Alt-Svc 中间件，效果等价于：
+  `Alt-Svc: h3=":4433"; ma=86400`
+
+> 注意：浏览器通常会先通过 HTTPS 访问一次，收到 Alt-Svc 后在后续请求中升级到 H3。
+
+## 客户端验证
+
+- curl：
+```bash
+curl --http3 -k https://127.0.0.1:4433/
+```
+
+- 浏览器：
+  - 访问 `https://127.0.0.1:4433/`；
+  - 打开 DevTools 网络面板，确认协议列为 `h3`；
+  - 首次访问可能仍为 `http/2`，刷新后升级。
+
+## WebTransport 使用说明（实验）
+
+- 能力：
+  - 服务端已启用 WebTransport 握手（扩展 CONNECT）、DATAGRAM；
+  - 内置 Echo 处理器用于演示：收到数据即回发，便于验证链路。
+
+- 设计要点：
+  - 会话标识使用 `scru128` 生成，满足高可用 ID 需求；
+  - API 当前未开放自定义 `WebTransportHandler` 的对外注册接口（默认 Echo）。
+
+- 客户端验证思路：
+  - 使用支持 WebTransport 的浏览器/JS API 或测试工具，发起 CONNECT + 发送数据帧；
+  - 期望收到 `echo(webtransport): <your_message>` 响应。
+
+- 可扩展建议（未来 API 方向）：
+  - 在 `Route` 上提供 `with_webtransport(path, handler)` 用于注册自定义处理器；
+  - 增加鉴权、中止条件、并发/帧大小/会话上限等保护；
+  - 暴露 QUIC/H3 参数（如并发流、超时、拥塞控制）并纳入配置。
+
+> 如需自定义 Handler，目前需要修改库内部 `quic::service` 中默认的 Echo 注册逻辑。
+
+## 性能与安全建议
+
+- 请求体大小与内存：HTTP/3 示例实现会将请求体聚合到内存，生产环境建议改为流式处理并设置上限。
+- 证书与信任：本地自签证书仅用于开发测试，生产环境请使用可信 CA 证书并妥善保管私钥。
+- 观测：配合 `tracing`/metrics 输出关键事件（握手、升级、错误、会话数量）。
+
+## 常见问题
+
+- 浏览器未升级到 H3：
+  - 确认已返回 Alt-Svc；
+  - 刷新后查看协议列；
+  - 证书是否被信任（或使用域名而非 IP）。
+- QUIC 无法建立：
+  - 端口是否被占用；
+  - 防火墙/UDP 是否放行；
+  - 证书/私钥路径是否正确。
+
+## 参考示例
+
+- 示例入口：`examples/quic/src/main.rs`
+- 证书样例：`examples/tls/certs/`

examples/quic/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "example-quic"
+version = "0.1.0"
+edition.workspace = true
+publish = false
+
+[dependencies]
+anyhow = "1"
+silent = { path = "../../silent", features = ["quic"] }
+tokio = { version = "1", features = ["full"] }
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+rustls = { version = "0.23" }

examples/quic/src/main.rs

@@ -0,0 +1,57 @@
+use anyhow::{Result, anyhow};
+use silent::QuicEndpointListener;
+use silent::prelude::*;
+use tracing_subscriber::EnvFilter;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    init_tracing();
+    install_rustls_provider()?;
+
+    let routes = build_routes().with_quic_port(4433); // 自动添加 Alt-Svc 中间件
+
+    // 端口与绑定地址由用户显式设置
+    let bind_addr: std::net::SocketAddr = "127.0.0.1:4433".parse().unwrap();
+    let store = certificate_store()?;
+
+    // QUIC listener with HTTP fallback (自动附加 HTTP/1.1 + TLS listener)
+    let listener = QuicEndpointListener::new(bind_addr, &store).with_http_fallback();
+
+    Server::new().listen(listener).serve(routes).await;
+
+    Ok(())
+}
+
+fn init_tracing() {
+    let env_filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info"));
+    tracing_subscriber::fmt()
+        .with_env_filter(env_filter)
+        .with_target(false)
+        .with_thread_ids(true)
+        .compact()
+        .init();
+}
+
+fn install_rustls_provider() -> Result<()> {
+    rustls::crypto::ring::default_provider()
+        .install_default()
+        .map_err(|_| anyhow!("初始化 Rustls 加密提供者失败"))
+}
+
+// 为示例提供一个证书加载方法：复用 tls 示例的本地证书
+fn certificate_store() -> Result<silent::CertificateStore> {
+    let builder = silent::CertificateStore::builder()
+        .cert_path("./examples/tls/certs/localhost+2.pem")
+        .key_path("./examples/tls/certs/localhost+2-key.pem");
+    builder.build().map_err(Into::into)
+}
+
+fn build_routes() -> Route {
+    async fn index(_req: Request) -> silent::Result<&'static str> {
+        Ok("Hello from HTTP/3")
+    }
+
+    let mut root = Route::new_root();
+    root.push(Route::new("").get(index));
+    root
+}

silent/Cargo.toml

@@ -37,6 +37,7 @@ full = [
     "scheduler",
     "grpc",
     "tls",
+    "quic",
 ]
 multipart = [
     "tokio/fs",
@@ -46,7 +47,13 @@ multipart = [
     "dep:textnonce",
 ]
 security = ["dep:argon2", "dep:pbkdf2", "dep:aes-gcm", "dep:aes", "dep:rsa"]
-server = ["tokio/fs", "tokio/net", "tokio/rt-multi-thread", "tokio/signal"]
+server = [
+    "tokio/fs",
+    "tokio/net",
+    "tokio/rt-multi-thread",
+    "tokio/signal",
+    "tokio/macros",
+]
 session = ["cookie", "dep:async-session"]
 sse = ["dep:pin-project", "dep:tokio-stream"]
 static = ["tokio/fs", "dep:urlencoding", "dep:async-compression"]
@@ -62,7 +69,21 @@ grpc = [
 ]
 scheduler = ["dep:cron"]
 test = ["tokio/macros", "tokio/rt"]
-tls = ["dep:tokio-rustls"]
+tls = [
+    "dep:tokio-rustls",
+    "dep:rustls",
+    "dep:rustls-pemfile",
+    "dep:rustls-pki-types",
+    "server",
+]
+quic = [
+    "tls",
+    "dep:quinn",
+    "dep:h3",
+    "dep:h3-quinn",
+    "dep:scru128",
+    "dep:rand",
+]
 
 [dependencies]
 # Basic dependencies
@@ -121,7 +142,9 @@ cookie = { version = "0.18", features = [
 ], optional = true }
 
 # Grpc
-tonic = { version = "0.14", optional = true, default-features = false, features = ["codegen"] }
+tonic = { version = "0.14", optional = true, default-features = false, features = [
+    "codegen",
+] }
 
 # Security
 aes = { version = "0.8", optional = true }
@@ -136,6 +159,18 @@ tokio-rustls = { version = "0.26", optional = true, default-features = false, fe
     "logging",
     "tls12",
 ] }
+rustls = { version = "0.23", optional = true, default-features = false, features = [
+    "logging",
+    "ring",
+    "std",
+] }
+rustls-pemfile = { version = "2", optional = true }
+rustls-pki-types = { version = "1", optional = true }
+quinn = { version = "0.11", optional = true }
+h3 = { version = "0.0.8", optional = true }
+h3-quinn = { version = "0.0.10", optional = true }
+scru128 = { version = "4.0.0-beta.1", optional = true, package = "scru128" }
+rand = { version = "0.8", optional = true }
 
 # Cloudflare Workers
 worker = { version = "0.6", optional = true }

silent/src/lib.rs

@@ -47,11 +47,13 @@ pub use crate::middleware::{MiddleWareHandler, middlewares};
 #[cfg(feature = "server")]
 pub use crate::protocol::Protocol;
 #[cfg(feature = "server")]
-pub use crate::service::connection::Connection;
+pub use crate::service::connection::{BoxedConnection, Connection};
 #[cfg(feature = "server")]
-pub use crate::service::listener::{Listen, Listener, Listeners, ListenersBuilder};
+pub use crate::service::listener::{AcceptFuture, Listen, Listener, Listeners, ListenersBuilder};
 #[cfg(feature = "server")]
-pub use crate::service::{BoxError, BoxedConnection, ConnectionFuture, ConnectionService, Server};
+pub use crate::service::{BoxError, ConnectionFuture, ConnectionService, Server};
+#[cfg(all(feature = "server", feature = "tls"))]
+pub use crate::service::{CertificateStore, CertificateStoreBuilder};
 pub use error::SilentError;
 pub use error::SilentResult as Result;
 pub use handler::Handler;
@@ -60,3 +62,7 @@ pub use headers;
 pub use hyper::{Method, StatusCode, header};
 #[cfg(feature = "scheduler")]
 pub use scheduler::{ProcessTime, SCHEDULER, Scheduler, SchedulerExt, Task};
+#[cfg(feature = "quic")]
+pub mod quic;
+#[cfg(feature = "quic")]
+pub use quic::{HybridListener, QuicEndpointListener};

silent/src/quic/connection.rs

@@ -0,0 +1,47 @@
+use std::pin::Pin;
+use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};
+
+pub struct QuicConnection {
+    connecting: Option<quinn::Incoming>,
+}
+impl QuicConnection {
+    pub(crate) fn new(connecting: quinn::Incoming) -> Self {
+        Self {
+            connecting: Some(connecting),
+        }
+    }
+    pub(crate) fn into_incoming(mut self) -> quinn::Incoming {
+        self.connecting.take().expect("connecting available")
+    }
+}
+impl AsyncRead for QuicConnection {
+    fn poll_read(
+        self: Pin<&mut Self>,
+        _cx: &mut std::task::Context<'_>,
+        buf: &mut ReadBuf<'_>,
+    ) -> std::task::Poll<std::io::Result<()>> {
+        buf.clear();
+        std::task::Poll::Ready(Ok(()))
+    }
+}
+impl AsyncWrite for QuicConnection {
+    fn poll_write(
+        self: Pin<&mut Self>,
+        _cx: &mut std::task::Context<'_>,
+        _buf: &[u8],
+    ) -> std::task::Poll<std::io::Result<usize>> {
+        std::task::Poll::Ready(Ok(0))
+    }
+    fn poll_flush(
+        self: Pin<&mut Self>,
+        _cx: &mut std::task::Context<'_>,
+    ) -> std::task::Poll<std::io::Result<()>> {
+        std::task::Poll::Ready(Ok(()))
+    }
+    fn poll_shutdown(
+        self: Pin<&mut Self>,
+        _cx: &mut std::task::Context<'_>,
+    ) -> std::task::Poll<std::io::Result<()>> {
+        std::task::Poll::Ready(Ok(()))
+    }
+}