KairoCore 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

KairoCore/example/your_project_name/action/file_upload.py

@@ -0,0 +1,71 @@
+"""
+文件上传接口示例：提供两种上传方式
+- multipart 上传（UploadFile）：POST /upload
+- Base64 上传（JSON）：POST /upload_base64
+
+签名约束：仅使用 query/body/file 三类参数名，符合 utils/router.enforce_signature 的规则。
+返回：统一使用 kQuery.to_response 结构化响应。
+"""
+from typing import Optional
+from KairoCore import kcRouter, kQuery, Panic, KcUploader, exec_with_route_error
+from KairoCore.common.errors import KCFU_UPLOAD_FAIL_ERROR, KCFU_BASE64_UPLOAD_FAIL_ERROR
+from fastapi import UploadFile
+from pydantic import BaseModel, Field
+
+router = kcRouter(tags=["文件上传"])
+
+# multipart 上传：文件 + 可选目标目录
+class UploadQuery(BaseModel):
+    target_dir: Optional[str] = Field(default="/tmp", description="文件保存目录")
+    filename: Optional[str] = Field(default=None, description="保存的文件名")
+
+
+@router.post("/upload")
+async def upload_file(query: UploadQuery, file: UploadFile):
+    """
+    使用 KcUploader 保存 multipart/form-data 上传文件。
+    """
+    uploader = KcUploader(default_target_dir="/tmp")
+    result = await exec_with_route_error(
+        uploader.save_upload_file(file=file, target_dir=query.target_dir, filename=query.filename),
+        KCFU_UPLOAD_FAIL_ERROR,
+    )
+    return kQuery.to_response(data=result, msg="上传成功")
+
+
+# Base64 上传：通过 JSON 传递字符串
+class Base64Body(BaseModel):
+    content_base64: str = Field(description="Base64 编码的文件内容")
+    filename: str = Field(description="保存的文件名")
+    target_dir: Optional[str] = Field(default="/tmp", description="保存目录")
+
+@router.post("/upload_base64")
+async def upload_base64(body: Base64Body):
+    """
+    使用 KcUploader 保存 Base64 编码内容为文件。
+    """
+    uploader = KcUploader(default_target_dir="/tmp")
+    result = await exec_with_route_error(
+        uploader.save_base64(content_base64=body.content_base64, filename=body.filename, target_dir=body.target_dir),
+        KCFU_BASE64_UPLOAD_FAIL_ERROR,
+    )
+    return kQuery.to_response(data=result, msg="上传成功")
+
+class DownloadQuery(BaseModel):
+    path: str = Field(description="服务器本地已保存的文件路径")
+    name: Optional[str] = Field(default=None, description="下载时展示的文件名（可选）")
+    inline: Optional[bool] = Field(default=False, description="是否内联显示（默认作为附件下载）")
+
+@router.get("/download")
+async def download_file(query: DownloadQuery):
+    """
+    通过接口将服务器本地文件下载到用户电脑。
+    返回 FileResponse，浏览器将触发下载。
+    """
+    uploader = KcUploader(default_target_dir="/tmp")
+    # 构建下载响应（支持自定义下载文件名、是否内联显示）
+    return await uploader.build_download_response(
+        src_path=query.path,
+        download_name=query.name,
+        inline=query.inline,
+    )

KairoCore/example/your_project_name/action/http_demo.py

@@ -0,0 +1,64 @@
+"""
+HTTP 会话示例路由：演示如何在项目中使用 KcHttpSession 进行异步 HTTP 请求
+- GET 示例：请求 httpbin.org/get 并回显查询参数
+- POST 示例：请求 httpbin.org/post 并回显提交的 JSON
+- 状态码示例：请求 httpbin.org/status/{code} 展示错误处理（4xx/5xx）
+- 下载示例：下载 httpbin 的图片到本地 /tmp 目录
+
+说明：
+- 仅使用框架允许的参数名 query/body，保持与现有签名强制规则一致
+- 使用 async with 上下文管理自动释放连接资源
+"""
+from typing import Optional
+from pydantic import BaseModel
+
+from KairoCore import kcRouter, kQuery, KcHttpSession
+
+# 分组到文档中 "HTTP会话示例"
+router = kcRouter(tags=["HTTP会话示例"])
+
+class GetDemoQuery(BaseModel):
+    foo: Optional[str] = "bar"
+
+class PostDemoBody(BaseModel):
+    x: int = 123
+    msg: str = "hello"
+
+class StatusQuery(BaseModel):
+    code: int = 200
+
+class DownloadQuery(BaseModel):
+    # 需要下载的 URL（示例默认是 httpbin 的 png 图片）
+    url: str = "https://httpbin.org/image/png"
+    # 保存路径（默认保存到 /tmp/httpbin.png）
+    save_path: str = "/tmp/httpbin.png"
+
+@router.get("/get")
+async def demo_get(query: GetDemoQuery):
+    """演示 GET 请求：将 query.foo 作为查询参数发送到 httpbin，并返回响应"""
+    async with KcHttpSession(base_url="https://httpbin.org", timeout=10, retries=2) as http:
+        resp = await http.get("/get", params={"foo": query.foo})
+        # 统一响应封装，直接返回 httpbin 的响应数据
+        return kQuery.to_response(data=resp.data, msg="GET 成功")
+
+@router.post("/post")
+async def demo_post(body: PostDemoBody):
+    """演示 POST 请求：将 body 序列化为 JSON 发送到 httpbin，并返回响应"""
+    async with KcHttpSession(base_url="https://httpbin.org", timeout=10, retries=2) as http:
+        resp = await http.post("/post", json=body.model_dump())
+        return kQuery.to_response(data=resp.data, msg="POST 成功")
+
+@router.get("/status")
+async def demo_status(query: StatusQuery):
+    """演示状态码处理：请求 /status/{code}，当 code 为 4xx/5xx 时会抛出统一异常并被全局捕获"""
+    async with KcHttpSession(base_url="https://httpbin.org", timeout=5, retries=1) as http:
+        # 2xx 时正常返回；4xx/5xx 时将抛出 Panic（KCHT_STATUS_ERROR/KCHT_REQUEST_ERROR），由全局异常处理器接管
+        resp = await http.get(f"/status/{query.code}")
+        return kQuery.to_response(data={"status_code": resp.status_code}, msg="状态码请求成功")
+
+@router.get("/download")
+async def demo_download(query: DownloadQuery):
+    """演示文件下载：下载指定 URL 到本地 save_path"""
+    async with KcHttpSession(timeout=10, retries=1) as http:
+        path = await http.download(url=query.url, save_path=query.save_path)
+        return kQuery.to_response(data={"saved": path}, msg="下载完成")

KairoCore/example/your_project_name/action/protected_demo.py

@@ -0,0 +1,85 @@
+"""
+受保护接口示例：演示普通接口如何带上 token 校验进行请求
+
+- 基础校验：只要求 access token（/ping）
+- 多租户校验：要求 access token + 租户 tid（/tenant/ping）
+- 角色校验：要求 access token + 具备 admin 角色（/admin/ping）
+- 仅限 API_KEY：无需登录，持有永久有效 API_KEY 即可（/api-key/ping）
+
+调用方式：
+- 使用 Authorization 头：Authorization: Bearer <access_token>
+- 或在浏览器场景使用 HttpOnly Cookie：access_token=<access_token>
+- 使用 X-API-Key 头或查询参数 api_key=<key>
+
+完整路径前缀（默认）：/example/api/protected_demo/*
+"""
+from typing import Any, Dict
+from fastapi import APIRouter, Depends
+
+from KairoCore import kcRouter, kQuery, KairoAuth
+
+# 文档分组到 "Token校验示例"
+router = kcRouter(tags=["Token校验示例"]) 
+
+# 1) 仅要求 access token
+base_router = APIRouter(dependencies=[Depends(KairoAuth.require_access_token)])
+
+@base_router.get("/ping")
+async def ping() -> Dict[str, Any]:
+    principal = KairoAuth.get_current_principal() or {}
+    return kQuery.to_response(
+        data={
+            "message": "pong",
+            "user_id": principal.get("sub"),
+            "roles": principal.get("roles") or [],
+        },
+        msg="ok",
+    )
+
+# 2) 要求存在租户 tid
+tenant_router = APIRouter(dependencies=[Depends(KairoAuth.require_access_token), Depends(KairoAuth.require_tenant)])
+
+@tenant_router.get("/tenant/ping")
+async def tenant_ping() -> Dict[str, Any]:
+    principal = KairoAuth.get_current_principal() or {}
+    return kQuery.to_response(
+        data={
+            "message": "pong-tenant",
+            "tenant_id": principal.get("tid"),
+        },
+        msg="ok",
+    )
+
+# 3) 要求具有 admin 角色
+admin_router = APIRouter(dependencies=[Depends(KairoAuth.require_access_token), Depends(KairoAuth.require_roles(["admin"]))])
+
+@admin_router.get("/admin/ping")
+async def admin_ping() -> Dict[str, Any]:
+    principal = KairoAuth.get_current_principal() or {}
+    return kQuery.to_response(
+        data={
+            "message": "pong-admin",
+            "roles": principal.get("roles") or [],
+        },
+        msg="ok",
+    )
+
+# 4) 仅限 API_KEY，无需 access token
+api_key_router = APIRouter(dependencies=[Depends(KairoAuth.require_api_key)])
+
+@api_key_router.get("/api-key/ping")
+async def api_key_ping() -> Dict[str, Any]:
+    principal = KairoAuth.get_current_principal() or {}
+    return kQuery.to_response(
+        data={
+            "message": "pong-api-key",
+            "principal": principal,  # 对于 API_KEY 认证，principal 可能为 {"api_key": "...", "type": "api_key"}
+        },
+        msg="ok",
+    )
+
+# 将子路由挂载到主路由（最终路径会是 /example/api/protected_demo/...）
+router.include_router(base_router, prefix="")
+router.include_router(tenant_router, prefix="")
+router.include_router(admin_router, prefix="")
+router.include_router(api_key_router, prefix="")

KairoCore/example/your_project_name/schema/auth.py

@@ -0,0 +1,14 @@
+from typing import List, Optional
+from pydantic import BaseModel
+
+class LoginBody(BaseModel):
+    username: str
+    password: str
+    tenant_id: Optional[str] = None
+    roles: Optional[List[str]] = None
+
+class RefreshBody(BaseModel):
+    refresh_token: str
+
+class LogoutBody(BaseModel):
+    refresh_token: str