fastapi-openrpc 0.1.3__tar.gz

fastapi_openrpc-0.1.3/.env.example

@@ -0,0 +1,5 @@
+# httpYac / API 测试配置
+# 复制为 .env 并填入实际值
+# cp .env.example .env
+
+HOST=http://localhost:8000

fastapi_openrpc-0.1.3/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Linting
+.ruff_cache/
+
+# httpYac
+.env
+.env.local
+.env.*.local
+.httpyac.cache

fastapi_openrpc-0.1.3/.pre-commit-config.yaml

@@ -0,0 +1,46 @@
+# .pre-commit-config.yaml
+# 使用方法:
+#   pre-commit install                      # 安装 hook（首次）
+#   pre-commit run --all-files             # 手动运行所有文件
+#   pre-commit run                          # 仅运行 staged 文件
+#   pre-commit autoupdate                  # 更新 hook 版本
+
+repos:
+  # ========================
+  # Ruff — Lint + Format
+  # ========================
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.5
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # ========================
+  # Pyright — 类型检查
+  # ========================
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.402
+    hooks:
+      - id: pyright
+        additional_dependencies:
+          - fastapi>=0.100.0
+          - pydantic>=2.0
+          - pytest>=8.0
+          - pytest-asyncio>=0.23
+          - httpx>=0.27
+          - starlette>=0.30.0
+          - uvicorn>=0.30.0
+
+  # ========================
+  # 通用工具
+  # ========================
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: check-json
+      - id: check-added-large-files
+        args: [--maxkb=500]
+      - id: end-of-file-fixer
+      - id: trailing-whitespace

fastapi_openrpc-0.1.3/CLAUDE.md

@@ -0,0 +1,76 @@
+# CLAUDE.md
+
+These rules apply to every task in this project unless explicitly overridden.
+Bias: caution over speed on non-trivial work. Use judgment on trivial tasks.
+
+## Agent Skills
+
+### Issue tracker
+
+Local markdown issues under `.scratch/<feature-slug>/`. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Canonical labels: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: one `CONTEXT.md` + `docs/adr/` at repo root. See `docs/agents/domain.md`.
+
+## Rule 1 — Think Before Coding
+State assumptions explicitly. If uncertain, ask rather than guess.
+Present multiple interpretations when ambiguity exists.
+Push back when a simpler approach exists.
+Stop when confused. Name what's unclear.
+
+## Rule 2 — Simplicity First
+Minimum code that solves the problem. Nothing speculative.
+No features beyond what was asked. No abstractions for single-use code.
+Test: would a senior engineer say this is overcomplicated? If yes, simplify.
+
+## Rule 3 — Surgical Changes
+Touch only what you must. Clean up only your own mess.
+Don't "improve" adjacent code, comments, or formatting.
+Don't refactor what isn't broken. Match existing style.
+
+## Rule 4 — Goal-Driven Execution
+Define success criteria. Loop until verified.
+Don't follow steps. Define success and iterate.
+Strong success criteria let you loop independently.
+
+## Rule 5 — Use the model only for judgment calls
+Use me for: classification, drafting, summarization, extraction.
+Do NOT use me for: routing, retries, deterministic transforms.
+If code can answer, code answers.
+
+## Rule 6 — Token budgets are not advisory
+Per-task: 4,000 tokens. Per-session: 30,000 tokens.
+If approaching budget, summarize and start fresh.
+Surface the breach. Do not silently overrun.
+
+## Rule 7 — Surface conflicts, don't average them
+If two patterns contradict, pick one (more recent / more tested).
+Explain why. Flag the other for cleanup.
+Don't blend conflicting patterns.
+
+## Rule 8 — Read before you write
+Before adding code, read exports, immediate callers, shared utilities.
+"Looks orthogonal" is dangerous. If unsure why code is structured a way, ask.
+
+## Rule 9 — Tests verify intent, not just behavior
+Tests must encode WHY behavior matters, not just WHAT it does.
+A test that can't fail when business logic changes is wrong.
+
+## Rule 10 — Checkpoint after every significant step
+Summarize what was done, what's verified, what's left.
+Don't continue from a state you can't describe back.
+If you lose track, stop and restate.
+
+## Rule 11 — Match the codebase's conventions, even if you disagree
+Conformance > taste inside the codebase.
+If you genuinely think a convention is harmful, surface it. Don't fork silently.
+
+## Rule 12 — Fail loud
+"Completed" is wrong if anything was skipped silently.
+"Tests pass" is wrong if any were skipped.
+Default to surfacing uncertainty, not hiding it.

fastapi_openrpc-0.1.3/Justfile

@@ -0,0 +1,73 @@
+# Justfile for fastapi-openrpc
+
+# 默认目标：运行所有测试
+default: test
+
+# 安装依赖
+install:
+    uv sync
+
+# 开发依赖
+install-dev:
+    uv sync --extra dev
+
+# 运行所有测试
+test:
+    uv run pytest tests/ -v
+
+# 运行测试并显示覆盖率
+test-cov:
+    uv run pytest tests/ -v --cov=src/fastapi_openrpc --cov-report=term-missing
+
+# 启动 minimal 示例（PORT 环境变量可覆盖，如 PORT=9000 just run-minimal）
+run-minimal:
+    uv run uvicorn examples.minimal_app:app --host 0.0.0.0 --port 10333 --reload
+
+# 测试 minimal 示例（启动服务，退出时关闭）
+test-minimal:
+    bash -c 'uv run uvicorn examples.minimal_app:app --host 0.0.0.0 --port 10333 & PID=$$!; trap "kill $PID 2>/dev/null; wait $PID 2>/dev/null; true" EXIT; npx httpyac tests/http/minimal.http -a' 
+
+# 启动 HMAC 认证示例（需先设置 HMAC_SECRET_KEY）
+run-hmac:
+    HEADER_SIGNING_KEY=my-secret-key uv run uvicorn examples.hmac_auth_dependency:app --host 0.0.0.0 --port 10334 --reload
+
+test-hmac:
+    bash -c 'HMAC_SECRET_KEY=my-secret-key uv run uvicorn examples.hmac_auth_dependency:app --host 0.0.0.0 --port 10334 & PID=$$!; trap "kill $PID 2>/dev/null; wait $PID 2>/dev/null; true" EXIT; npx httpyac tests/http/hmac.http -a' 
+
+# 启动 Pydantic 模型示例
+run-pydantic:
+    uv run uvicorn examples.pydantic_models:app --host 0.0.0.0 --port 10335 --reload
+
+test-pydantic:
+    bash -c 'uv run uvicorn examples.pydantic_models:app --host 0.0.0.0 --port 10335 & PID=$$!; trap "kill $PID 2>/dev/null; wait $PID 2>/dev/null; true" EXIT; npx httpyac tests/http/pydantic.http -a' 
+
+# Lint
+lint:
+    uv run ruff check src/ tests/
+
+# 格式化
+fmt:
+    uv run ruff format src/ tests/
+
+# 类型检查
+typecheck:
+    uv run pyright
+
+# 完整开发检查：lint + typecheck + test
+check: lint typecheck test
+
+# 运行 pre-commit（仅 staged 文件）
+precommit:
+    uv run pre-commit run
+
+# 运行 pre-commit 所有文件
+precommit-all:
+    uv run pre-commit run --all-files
+
+# 安装 pre-commit hook（首次克隆后运行一次）
+precommit-install:
+    pre-commit install
+
+# 列出所有可用目标
+help:
+    just --list

fastapi_openrpc-0.1.3/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: fastapi-openrpc
+Version: 0.1.3
+Summary: FastAPI JSON-RPC 2.0 + OpenRPC 1.0 service discovery plugin
+Author-email: Ye Wenbin <yewenbin@winwin-tech.com>
+License: MIT
+Keywords: ai-agent,discover,fastapi,json-rpc,openrpc,rpc
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typing-extensions>=4.8
+Provides-Extra: dev
+Requires-Dist: fakeredis>=2.21; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis[hiredis]>=5.0; extra == 'redis'

fastapi_openrpc-0.1.3/README.md

@@ -0,0 +1,206 @@
+# fastapi-openrpc
+
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-openrpc)](https://pypi.org/project/fastapi-openrpc/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-openrpc.svg)](https://pypi.org/project/fastapi-openrpc/)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Declarative JSON-RPC 2.0 interface and OpenRPC 1.0 service discovery for FastAPI applications.
+
+## Features
+
+- **Declarative Registration** — `@method()` decorator with automatic JSON Schema inference
+- **OpenRPC Service Discovery** — `GET /openrpc.json` returns complete OpenRPC document
+- **Pydantic Support** — Automatic schema generation with `$ref` references
+- **RpcContext Propagation** — Secure caller context injection via FastAPI `Depends()`
+- **HMAC Authentication** — Built-in signature verification with Nonce replay protection
+- **Role-Based Authorization** — Method-level role declarations with composition semantics
+
+## Installation
+
+```bash
+pip install fastapi-openrpc
+```
+
+Optional dependencies:
+
+```bash
+# Redis support (Nonce replay protection)
+pip install fastapi-openrpc[redis]
+
+# Development dependencies
+pip install fastapi-openrpc[dev]
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from fastapi_openrpc import OpenRpcRouter, RpcContext, method
+
+app = FastAPI()
+
+openrpc_router = OpenRpcRouter(
+    title="My API",
+    version="1.0.0",
+    description="My JSON-RPC service",
+)
+
+@method(name="getUser")
+async def get_user(ctx: RpcContext, user_id: str) -> dict:
+    """Get user information by user_id."""
+    return {"id": user_id, "name": "Alice", "roles": ctx.roles}
+
+@method(name="listUsers")
+async def list_users(ctx: RpcContext, limit: int = 10) -> list[dict]:
+    """Return a list of users."""
+    return [{"id": i, "name": f"User {i}"} for i in range(limit)]
+
+app.include_router(openrpc_router)
+```
+
+After starting the server, access `GET /openrpc.json` to view the OpenRPC service document.
+
+## Authentication
+
+### HMAC Authentication
+
+```python
+from fastapi_openrpc.authentication import HMACAuthentication
+
+auth = HMACAuthentication(secret_key="your-secret-key")
+openrpc_router = OpenRpcRouter(
+    authentication=auth,
+)
+```
+
+### Nonce Replay Protection
+
+```python
+auth = HMACAuthentication(
+    secret_key="your-secret-key",
+    enable_nonce=True,
+    redis_url="redis://localhost:6379",
+    nonce_ttl=3600,
+    redis_required=True,       # Reject requests when Redis is unavailable
+    connect_timeout=2.0,      # Redis connection timeout (seconds)
+    operation_timeout=5.0,     # Redis operation timeout (seconds)
+    cleanup_timeout=2.0,      # Redis cleanup timeout (seconds)
+)
+```
+
+Header format:
+
+```json
+{
+  "roles": ["admin"],
+  "nonce": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+## Authorization
+
+```python
+from fastapi_openrpc import Require
+
+@method(name="adminAction", required_roles=["admin"])
+async def admin_action(ctx: RpcContext) -> dict:
+    """Admin only."""
+    return {"status": "done"}
+
+@method(name="editContent", required_roles=["editor", "admin"], require=Require.ALL)
+async def edit_content(ctx: RpcContext) -> dict:
+    """Requires both editor and admin roles."""
+    return {"status": "edited"}
+```
+
+## Error Handling
+
+```python
+from fastapi_openrpc import InvalidParams, MethodNotFound
+
+@method(name="divide")
+async def divide(ctx: RpcContext, a: float, b: float) -> float:
+    if b == 0:
+        raise InvalidParams("Division by zero")
+    return a / b
+```
+
+Built-in error codes:
+
+| Error | Code |
+|-------|------|
+| Parse error | -32700 |
+| Invalid Request | -32600 |
+| Method Not Found | -32601 |
+| Invalid Params | -32602 |
+| Internal Error | -32603 |
+| Forbidden | -32000 |
+| Replay Detected | -32002 |
+
+Library reserves -32000 ~ -32099, application custom errors start from -32100.
+
+## API Reference
+
+### OpenRpcRouter
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+
+executor = ThreadPoolExecutor(max_workers=4)
+openrpc_router = OpenRpcRouter(
+    title="My API",
+    version="1.0.0",
+    description="...",
+    servers=[{"url": "https://api.example.com"}],
+    authentication=HMACAuthentication(secret_key="..."),  # Optional
+    executor=executor,  # Optional, for sync handler thread pool
+)
+app.include_router(openrpc_router)
+```
+
+### @method() Decorator
+
+```python
+@method(
+    name="myMethod",           # RPC method name
+    tags=["admin"],           # OpenRPC tags
+    summary="Short description",
+    deprecated=False,
+    required_roles=["admin"],  # Required roles
+    require=Require.ALL,      # Role composition semantics
+)
+async def my_handler(ctx: RpcContext, arg1: str, arg2: int = 10) -> dict:
+    return {"result": arg1}
+```
+
+> **Note**: `ctx: RpcContext` is a reserved parameter name for injecting caller context.
+
+## Usage Examples
+
+```bash
+# Call RPC method
+curl -X POST http://localhost:8000/ \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "id": 1, "method": "getUser", "params": {"user_id": "42"}}'
+
+# Service discovery
+curl http://localhost:8000/openrpc.json
+```
+
+## Documentation
+
+For detailed user documentation, see [docs/index.md](docs/index.md).
+
+Additional guides:
+
+- [Tutorial: Pydantic Models](docs/tutorial-pydantic-models.md) — 4 scenarios covering flat params, nested models, optional fields, and validation
+- [How-to: Error Handling](docs/howto-error-handling.md) — custom errors, Nonce replay protection, best practices
+- [Explanation: Concurrency Model](docs/explanation-concurrency.md) — ThreadPoolExecutor, sync handler wrapping, closure safety
+
+## Contributing
+
+Issues and Pull Requests are welcome.
+
+## License
+
+MIT

fastapi_openrpc-0.1.3/README_zh.md

@@ -0,0 +1,196 @@
+# fastapi-openrpc
+
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-openrpc)](https://pypi.org/project/fastapi-openrpc/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-openrpc.svg)](https://pypi.org/project/fastapi-openrpc/)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+为 FastAPI 应用提供声明式 JSON-RPC 2.0 接口和 OpenRPC 1.0 服务发现支持。
+
+## 特性
+
+- **声明式注册** — `@method()` 装饰器，自动推断 JSON Schema
+- **OpenRPC 服务发现** — `GET /openrpc.json` 返回完整 OpenRPC 文档
+- **Pydantic 支持** — 自动生成 schema，支持 `$ref` 引用
+- **RpcContext 传递** — 通过 FastAPI `Depends()` 安全注入调用者上下文
+- **HMAC 认证** — 内置签名验证，支持 Nonce 重放攻击防护
+- **角色授权** — 方法级角色声明与组合语义支持
+
+## 安装
+
+```bash
+pip install fastapi-openrpc
+```
+
+可选依赖：
+
+```bash
+# Redis 支持（Nonce 重放防护）
+pip install fastapi-openrpc[redis]
+
+# 开发依赖
+pip install fastapi-openrpc[dev]
+```
+
+## 快速开始
+
+```python
+from fastapi import FastAPI
+from fastapi_openrpc import OpenRpcRouter, RpcContext, method
+
+app = FastAPI()
+
+openrpc_router = OpenRpcRouter(
+    title="My API",
+    version="1.0.0",
+    description="My JSON-RPC service",
+)
+
+@method(name="getUser")
+async def get_user(ctx: RpcContext, user_id: str) -> dict:
+    """根据 user_id 返回用户信息。"""
+    return {"id": user_id, "name": "Alice", "roles": ctx.roles}
+
+@method(name="listUsers")
+async def list_users(ctx: RpcContext, limit: int = 10) -> list[dict]:
+    """返回用户列表。"""
+    return [{"id": i, "name": f"User {i}"} for i in range(limit)]
+
+app.include_router(openrpc_router)
+```
+
+启动后访问 `GET /openrpc.json` 查看 OpenRPC 服务文档。
+
+## 认证
+
+### HMAC 认证
+
+```python
+from fastapi_openrpc.authentication import HMACAuthentication
+
+auth = HMACAuthentication(secret_key="your-secret-key")
+openrpc_router = OpenRpcRouter(
+    authentication=auth,
+)
+```
+
+### Nonce 重放防护
+
+```python
+auth = HMACAuthentication(
+    secret_key="your-secret-key",
+    enable_nonce=True,
+    redis_url="redis://localhost:6379",
+    nonce_ttl=3600,
+    redis_required=True,       # Redis 不可用时拒绝请求
+    connect_timeout=2.0,      # Redis 连接超时（秒）
+    operation_timeout=5.0,     # Redis 操作超时（秒）
+    cleanup_timeout=2.0,       # Redis 清理超时（秒）
+)
+```
+
+Header 格式：
+
+```json
+{
+  "roles": ["admin"],
+  "nonce": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+## 授权
+
+```python
+from fastapi_openrpc import Require
+
+@method(name="adminAction", required_roles=["admin"])
+async def admin_action(ctx: RpcContext) -> dict:
+    """仅限 admin 角色。"""
+    return {"status": "done"}
+
+@method(name="editContent", required_roles=["editor", "admin"], require=Require.ALL)
+async def edit_content(ctx: RpcContext) -> dict:
+    """需要同时拥有 editor 和 admin 角色。"""
+    return {"status": "edited"}
+```
+
+## 错误处理
+
+```python
+from fastapi_openrpc import InvalidParams, MethodNotFound
+
+@method(name="divide")
+async def divide(ctx: RpcContext, a: float, b: float) -> float:
+    if b == 0:
+        raise InvalidParams("Division by zero")
+    return a / b
+```
+
+内置错误码：
+
+| 错误 | 码 |
+|------|-----|
+| Parse error | -32700 |
+| Invalid Request | -32600 |
+| Method Not Found | -32601 |
+| Invalid Params | -32602 |
+| Internal Error | -32603 |
+| Forbidden | -32000 |
+| Replay Detected | -32002 |
+
+库保留 -32000 ~ -32099，应用自定义错误从 -32100 起。
+
+## API 参考
+
+### OpenRpcRouter
+
+```python
+openrpc_router = OpenRpcRouter(
+    title="My API",
+    version="1.0.0",
+    description="...",
+    servers=[{"url": "https://api.example.com"}],
+    authentication=HMACAuthentication(secret_key="..."),  # 可选
+)
+app.include_router(openrpc_router)
+```
+
+### @method() 装饰器
+
+```python
+@method(
+    name="myMethod",           # RPC 方法名
+    tags=["admin"],           # OpenRPC 标签
+    summary="简短描述",
+    deprecated=False,
+    required_roles=["admin"],  # 所需角色
+    require=Require.ALL,      # 角色组合语义
+)
+async def my_handler(ctx: RpcContext, arg1: str, arg2: int = 10) -> dict:
+    return {"result": arg1}
+```
+
+> **注意**: 参数 `ctx: RpcContext` 是保留参数名，用于注入调用者上下文。
+
+## 调用示例
+
+```bash
+# 调用 RPC 方法
+curl -X POST http://localhost:8000/ \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "id": 1, "method": "getUser", "params": {"user_id": "42"}}'
+
+# 服务发现
+curl http://localhost:8000/openrpc.json
+```
+
+## 完整文档
+
+详细的用户文档请参阅 [docs/index.md](docs/zh/index.md)。
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request。
+
+## License
+
+MIT

fastapi_openrpc-0.1.3/docs/agents/domain.md

@@ -0,0 +1,47 @@
+# Domain Context
+
+Single-context project: one `CONTEXT.md` at repo root + `docs/adr/` for architectural decisions.
+
+## CONTEXT.md
+
+Project-level context: what the project does, key concepts, terminology, and patterns.
+
+## docs/adr/
+
+Architecture Decision Records documenting significant choices.
+
+### ADR format
+
+```
+docs/adr/<YYYY-MM-DD>-<short-title>.md
+```
+
+Example: `docs/adr/2024-01-15-use-pydantic-v2-for-validation.md`
+
+### ADR template
+
+```markdown
+# ADR-001: Use Pydantic V2 for validation
+
+**Status:** Accepted
+**Date:** 2024-01-15
+
+## Context
+
+What problem prompted this decision?
+
+## Decision
+
+What was decided?
+
+## Consequences
+
+### Positive
+- Benefit 1
+
+### Negative
+- Tradeoff 1
+
+### Neutral
+- Side effect 1
+```