From 7f44ba1d0609dae63ad517e3ac58f378e53b91ad Mon Sep 17 00:00:00 2001
From: Justin Gu <97915@qq.com>
Date: Fri, 12 Jun 2026 03:00:49 +0800
Subject: [PATCH] feat(web): scaffold web API module with [web] optional
 dependency

---
 pyproject.toml                       |  5 +++
 src/easy_tdx/web/__init__.py         | 50 ++++++++++++++++++++++++++++
 src/easy_tdx/web/routers/__init__.py |  1 +
 3 files changed, 56 insertions(+)
 create mode 100644 src/easy_tdx/web/__init__.py
 create mode 100644 src/easy_tdx/web/routers/__init__.py

diff --git a/pyproject.toml b/pyproject.toml
index fff8203..e172e44 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -15,6 +15,7 @@ easy-tdx = "easy_tdx.cli:cli"  # cli/__init__.py exposes the click group
 
 [project.optional-dependencies]
 dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "pytest-cov", "mypy>=1.9", "ruff>=0.4"]
+web = ["fastapi>=0.110", "uvicorn[standard]>=0.29"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/easy_tdx"]
@@ -31,6 +32,10 @@ ignore_missing_imports = true
 module = "easy_tdx.MyTT"
 # Type stubs provided via MyTT.pyi — keep strict checks enabled
 
+[[tool.mypy.overrides]]
+module = ["fastapi.*", "uvicorn.*", "pydantic.*"]
+ignore_missing_imports = true
+
 [tool.ruff]
 target-version = "py310"
 line-length = 100
diff --git a/src/easy_tdx/web/__init__.py b/src/easy_tdx/web/__init__.py
new file mode 100644
index 0000000..a989925
--- /dev/null
+++ b/src/easy_tdx/web/__init__.py
@@ -0,0 +1,50 @@
+"""easy-tdx Web API — FastAPI REST + WebSocket layer.
+
+Install with: pip install easy-tdx[web]
+
+Usage::
+
+    from easy_tdx.web import create_app
+
+    app = create_app()
+
+    # Run with uvicorn:
+    # uvicorn easy_tdx.web:app --host 0.0.0.0 --port 8000
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+
+def create_app(
+    host: str | None = None,
+    port: int | None = None,
+    timeout: float | None = None,
+) -> FastAPI:
+    """Create and configure the FastAPI application.
+
+    Args:
+        host: TDX server host (None = auto-detect best host).
+        port: TDX server port (None = default 7709).
+        timeout: Connection timeout in seconds.
+
+    Returns:
+        Configured FastAPI application instance.
+    """
+    from easy_tdx.web.app import _create_app
+
+    return _create_app(host=host, port=port, timeout=timeout)
+
+
+def app_factory() -> FastAPI:
+    """Factory function for uvicorn --reload mode."""
+    from easy_tdx.web.app import _create_app
+
+    return _create_app()
+
+
+__all__ = ["create_app", "app_factory"]
diff --git a/src/easy_tdx/web/routers/__init__.py b/src/easy_tdx/web/routers/__init__.py
new file mode 100644
index 0000000..fb0a2f8
--- /dev/null
+++ b/src/easy_tdx/web/routers/__init__.py
@@ -0,0 +1 @@
+"""API route modules."""