Metadata-Version: 2.4
Name: fish-edge-gateway-sdk
Version: 0.1.0
Summary: Service-side SDK for apex-edge-gateway: declare a FastAPI service's routes for discovery, report usage in band, verify gateway-origin auth, and join the gateway's trace
Project-URL: Homepage, https://fish.audio
Author: Fish Audio
License-Expression: MIT OR Apache-2.0
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Keywords: edge,fastapi,fish-audio,gateway,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.100
Requires-Dist: pydantic>=2
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# fish-edge-gateway-sdk (Python)

接入 apex-edge-gateway 的服务侧 SDK：manifest 声明与暴露、internal auth、trace 透传。协议契约见仓库 `docs/contracts/`。

## 安装（不发布 PyPI，直接 git 依赖）

```
# requirements.txt / pyproject dependency（锁 tag 或 commit，不要追 main）
fish-edge-gateway-sdk @ git+ssh://git@github.com/fishaudio/apex-edge-gateway.git@<tag-or-sha>#subdirectory=sdk-python
```

```sh
# 本地开发
pip install "fish-edge-gateway-sdk @ git+ssh://git@github.com/fishaudio/apex-edge-gateway.git@main#subdirectory=sdk-python"

# uv
uv add "fish-edge-gateway-sdk @ git+ssh://git@github.com/fishaudio/apex-edge-gateway.git@main#subdirectory=sdk-python"

# CI / Docker（https + token，避免挂 ssh key）
pip install "fish-edge-gateway-sdk @ git+https://${GITHUB_TOKEN}@github.com/fishaudio/apex-edge-gateway.git@<sha>#subdirectory=sdk-python"
```

版本锁定约定：SDK 变更打 `sdk-python/vX.Y.Z` 形式的 git tag，服务锁 tag 升级；紧急验证可锁 commit sha。

## 集成

```python
from fastapi import Depends, FastAPI
from fish_edge_gateway_sdk import edge_route, mount_edge, require_gateway

app = FastAPI()

@app.post("/internal/asr", dependencies=[Depends(require_gateway)])
@edge_route(auth="internal")
async def asr(payload: dict) -> dict: ...

mount_edge(app, service="omni-asr")   # 挂载 GET /.edge/manifest
```

k8s Service 侧标注（manifest 契约 §2.1）：

```yaml
metadata:
  annotations:
    fish.audio/edge-discovery: enable
    # 可选：manifest 端点与业务端口分离时
    # fish.audio/edge-discovery-port: "9090"
    # fish.audio/edge-discovery-url: /.edge/manifest
```

gateway 侧无需额外授权：发现 namespace 的成员资格就是信任边界（manifest 契约 §11），被发现的 manifest 其 route 直接编译。

## 环境变量

| 变量 | 语义 |
| -- | -- |
| `FISH_EDGE_GATEWAY_TOKEN` | 期望的 `x-fish-gateway-token`。未设 = 观察模式（只记日志） |
| `FISH_EDGE_REQUIRE_GATEWAY` | `1` 时强制校验（403 拒绝非 gateway 流量）。P6 gateway 下发 token 后开启 |

## 开发

```sh
pip install -e "sdk-python[dev]"
pytest sdk-python/tests -q
```
