209 lines
8.7 KiB
Python
209 lines
8.7 KiB
Python
|
"""Webhook 入站路由（WHK-RECV-01 / WHK-09 / WHK-TEST）。
|
|||
|
|
|
|||
|
|
模板 B（数据面）用于入站接收与签名校验（WHK-RECV-01 / WHK-09），不依赖
|
|||
|
|
管理员鉴权（签名校验下沉入站管道）。模板 A（控制面端口路由）用于 Webhook
|
|||
|
|
测试（WHK-TEST），依赖 ``get_admin_user`` 鉴权，经 ``AccountManagementPort.testWebhook``
|
|||
|
|
控制面管道执行。子 router 不自行设置 prefix，根前缀 ``/channels`` 由
|
|||
|
|
``channels_router`` 聚合 router 统一追加，最终路径为
|
|||
|
|
``/channels/{channel_type}/webhook`` 等。
|
|||
|
|
|
|||
|
|
端点清单（对应《07-投递基础设施域设计方案》§2.1）：
|
|||
|
|
- POST /{channel_type}/webhook WHK-RECV-01 receiveWebhook
|
|||
|
|
- POST /{channel_type}/webhook/signature/verify WHK-09 verifySignature
|
|||
|
|
- POST /{channel_type}/webhook/test WHK-TEST testWebhook
|
|||
|
|
"""
|
|||
|
|
|
|||
|
|
from __future__ import annotations
|
|||
|
|
|
|||
|
|
from typing import Any
|
|||
|
|
|
|||
|
|
from fastapi import APIRouter, Depends, Request
|
|||
|
|
from pydantic import BaseModel, ConfigDict, Field
|
|||
|
|
from yuxi.channels.contract.dtos.channel import ChannelType, WebhookTestCmd
|
|||
|
|
from yuxi.channels.contract.dtos.inbound import ReceiveInboundCmd
|
|||
|
|
from yuxi.channels.contract.errors import NotImplementedError as ChannelNotImplementedError
|
|||
|
|
from yuxi.channels.contract.errors import NotFoundError, ValidationError
|
|||
|
|
from yuxi.storage.postgres.models_business import User
|
|||
|
|
|
|||
|
|
from server.routers.channels import (
|
|||
|
|
build_operator,
|
|||
|
|
dataclass_to_dict,
|
|||
|
|
get_channel_use_cases,
|
|||
|
|
raiseOnControlFailure,
|
|||
|
|
sanitize_headers,
|
|||
|
|
serialize_control_data,
|
|||
|
|
)
|
|||
|
|
from server.utils.auth_middleware import get_admin_user
|
|||
|
|
|
|||
|
|
webhook_router = APIRouter(tags=["channels-webhook"])
|
|||
|
|
|
|||
|
|
# Webhook 原始 body 大小上限（1 MiB），防止恶意大 payload 导致 OOM
|
|||
|
|
MAX_WEBHOOK_BODY_SIZE = 1 * 1024 * 1024
|
|||
|
|
|
|||
|
|
|
|||
|
|
# ---------------- Request Schemas ----------------
|
|||
|
|
|
|||
|
|
|
|||
|
|
class SignatureVerifyRequest(BaseModel):
|
|||
|
|
"""Webhook 签名验证测试请求体（WHK-09）。"""
|
|||
|
|
|
|||
|
|
model_config = ConfigDict(frozen=True)
|
|||
|
|
|
|||
|
|
raw_event: str = Field(..., min_length=1, description="待验证的原始事件体（UTF-8 字符串）")
|
|||
|
|
headers: dict[str, str] = Field(..., description="渠道侧请求头（含签名字段）")
|
|||
|
|
|
|||
|
|
|
|||
|
|
class SignatureVerifyResponse(BaseModel):
|
|||
|
|
"""Webhook 签名验证测试响应体（WHK-09）。"""
|
|||
|
|
|
|||
|
|
model_config = ConfigDict(frozen=True)
|
|||
|
|
|
|||
|
|
valid: bool = Field(..., description="签名校验是否通过")
|
|||
|
|
reason: str | None = Field(default=None, description="校验失败原因（通过时为 None）")
|
|||
|
|
|
|||
|
|
|
|||
|
|
class WebhookTestRequest(BaseModel):
|
|||
|
|
"""Webhook 测试请求体（WHK-TEST）。"""
|
|||
|
|
|
|||
|
|
model_config = ConfigDict(frozen=True)
|
|||
|
|
|
|||
|
|
account_id: str | None = Field(
|
|||
|
|
default=None,
|
|||
|
|
description="渠道账户 ID（可选，缺省取该渠道首个账户）",
|
|||
|
|
)
|
|||
|
|
event_type: str = Field(
|
|||
|
|
default="test_event",
|
|||
|
|
description="测试事件类型",
|
|||
|
|
)
|
|||
|
|
payload: dict[str, Any] | None = Field(
|
|||
|
|
default=None,
|
|||
|
|
description="测试事件负载（可选）",
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
|
|||
|
|
# ---------------- Endpoints ----------------
|
|||
|
|
|
|||
|
|
|
|||
|
|
@webhook_router.post("/{channel_type}/webhook", response_model=dict)
|
|||
|
|
async def receive_webhook(
|
|||
|
|
channel_type: ChannelType,
|
|||
|
|
request: Request,
|
|||
|
|
use_cases=Depends(get_channel_use_cases),
|
|||
|
|
) -> dict[str, Any]:
|
|||
|
|
"""接收渠道入站 webhook 回调（WHK-RECV-01）。
|
|||
|
|
|
|||
|
|
采用模板 B（数据面）：不经过控制面管道，直接调用
|
|||
|
|
use_cases.inbound_message.receiveWebhook(cmd)。
|
|||
|
|
|
|||
|
|
签名校验与幂等去重下沉到入站管道（signature-verify / status-route 阶段），
|
|||
|
|
Router 仅负责透传原始 body 与脱敏后的 headers。不调用 raiseOnControlFailure
|
|||
|
|
（fire-and-forget 模型），由渠道契约决定回调响应内容。
|
|||
|
|
|
|||
|
|
``ReceiveInboundCmd`` 构造时由 ``__post_init__`` 校验字段，违规抛
|
|||
|
|
``ValidationError``（HTTP 400），交由 ``unified_error_handler`` 统一映射，
|
|||
|
|
不在 Router 内捕获原生异常（INV-7 禁止原生异常穿透至核心层）。
|
|||
|
|
|
|||
|
|
raw_body 直接 ``await request.body()`` 获取原始字节流，不经 Pydantic 解析，
|
|||
|
|
避免字节序列改变导致签名校验失败。解码使用 ``errors="strict"``：非法
|
|||
|
|
UTF-8 字节会显式失败并转译为 ``ValidationError``（400），而非静默替换为
|
|||
|
|
U+FFFD 破坏原始字节序列导致签名校验失败。
|
|||
|
|
"""
|
|||
|
|
raw_body = await request.body()
|
|||
|
|
if len(raw_body) > MAX_WEBHOOK_BODY_SIZE:
|
|||
|
|
raise ValidationError(
|
|||
|
|
"body",
|
|||
|
|
f"webhook body size {len(raw_body)} exceeds limit {MAX_WEBHOOK_BODY_SIZE} bytes",
|
|||
|
|
)
|
|||
|
|
try:
|
|||
|
|
raw_event = raw_body.decode("utf-8", errors="strict")
|
|||
|
|
except UnicodeDecodeError as exc:
|
|||
|
|
raise ValidationError(
|
|||
|
|
"body",
|
|||
|
|
"webhook body is not valid UTF-8",
|
|||
|
|
) from exc
|
|||
|
|
sanitized_headers = sanitize_headers(request.headers)
|
|||
|
|
cmd = ReceiveInboundCmd(
|
|||
|
|
channel_type=channel_type,
|
|||
|
|
raw_event=raw_event,
|
|||
|
|
headers=sanitized_headers,
|
|||
|
|
)
|
|||
|
|
result = await use_cases.inbound_message.receiveWebhook(cmd)
|
|||
|
|
return {"success": True, "data": dataclass_to_dict(result)}
|
|||
|
|
|
|||
|
|
|
|||
|
|
@webhook_router.post("/{channel_type}/webhook/signature/verify", response_model=dict)
|
|||
|
|
async def verify_webhook_signature(
|
|||
|
|
channel_type: ChannelType,
|
|||
|
|
payload: SignatureVerifyRequest,
|
|||
|
|
use_cases=Depends(get_channel_use_cases),
|
|||
|
|
) -> dict[str, Any]:
|
|||
|
|
"""测试 webhook 签名验证（WHK-09）。
|
|||
|
|
|
|||
|
|
采用模板 B（数据面）：通过 ``InboundMessagePort.verifyWebhookSignature``
|
|||
|
|
调用渠道适配器的 ``verifySignature``，不触发真实消息处理链路，辅助接入
|
|||
|
|
调试。与生产路径调用同一 ``verifySignature`` 适配器方法，确保测试结果与
|
|||
|
|
生产签名校验行为完全一致。
|
|||
|
|
|
|||
|
|
异常处理（HTTP 语义对齐）：渠道未注册入站适配器时用例服务抛
|
|||
|
|
``NotFoundError``（404），设计文档要求 WHK-09 显式 501，故在 Router
|
|||
|
|
内翻译为契约 ``NotImplementedError`` 交由 ``unified_error_handler`` 统一
|
|||
|
|
映射；适配器未实现 ``verifySignature`` 抛 Python 内置 ``NotImplementedError``
|
|||
|
|
时同样翻译为契约异常，避免被 ``unhandled_exception_handler`` 兜底为 500。
|
|||
|
|
契约 ``NotImplementedError``（适配器显式抛出）直接上抛，由全局处理器映射为 501。
|
|||
|
|
"""
|
|||
|
|
try:
|
|||
|
|
valid = await use_cases.inbound_message.verifyWebhookSignature(
|
|||
|
|
channel_type=channel_type,
|
|||
|
|
raw_event=payload.raw_event,
|
|||
|
|
headers=payload.headers,
|
|||
|
|
)
|
|||
|
|
except NotFoundError as exc:
|
|||
|
|
# 渠道未注册入站适配器：设计要求显式 501，翻译为契约 NotImplementedError，
|
|||
|
|
# 交由 unified_error_handler 统一映射（HTTP 501），并保留原始 traceback。
|
|||
|
|
raise ChannelNotImplementedError(
|
|||
|
|
operation="verify_signature",
|
|||
|
|
message=f"inbound adapter not registered for channel: {channel_type.value}",
|
|||
|
|
) from exc
|
|||
|
|
except NotImplementedError as exc:
|
|||
|
|
# Python 内置 NotImplementedError（适配器未实现 verifySignature）：
|
|||
|
|
# 翻译为契约 NotImplementedError，避免原生异常被兜底为 500。
|
|||
|
|
# 契约 NotImplementedError 不在此捕获，直接上抛由全局处理器统一映射。
|
|||
|
|
raise ChannelNotImplementedError(
|
|||
|
|
operation="verify_signature",
|
|||
|
|
message=f"verifySignature not implemented for channel: {channel_type.value}",
|
|||
|
|
) from exc
|
|||
|
|
|
|||
|
|
reason = None if valid else "signature verification failed"
|
|||
|
|
return {
|
|||
|
|
"success": True,
|
|||
|
|
"data": SignatureVerifyResponse(valid=valid, reason=reason).model_dump(),
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
|
|||
|
|
@webhook_router.post("/{channel_type}/webhook/test", response_model=dict)
|
|||
|
|
async def test_webhook(
|
|||
|
|
channel_type: ChannelType,
|
|||
|
|
payload: WebhookTestRequest,
|
|||
|
|
request: Request,
|
|||
|
|
use_cases=Depends(get_channel_use_cases),
|
|||
|
|
current_user: User = Depends(get_admin_user),
|
|||
|
|
) -> dict[str, Any]:
|
|||
|
|
"""测试 Webhook 投递（WHK-TEST）。
|
|||
|
|
|
|||
|
|
采用模板 A（控制面端口路由）：构造 ``WebhookTestCmd`` 经
|
|||
|
|
``AccountManagementPort.testWebhook`` 控制面管道执行，isinstance 检查
|
|||
|
|
``WebhookTestable`` 能力 → 调用 ``testWebhook`` 发送测试事件 → 返回
|
|||
|
|
投递结果。未注册 ``WebhookTestable`` 时返回 501 NOT_IMPLEMENTED。
|
|||
|
|
"""
|
|||
|
|
operator = build_operator(current_user, request)
|
|||
|
|
cmd = WebhookTestCmd(
|
|||
|
|
channel_type=channel_type,
|
|||
|
|
operator=operator,
|
|||
|
|
account_id=payload.account_id,
|
|||
|
|
event_type=payload.event_type,
|
|||
|
|
payload=payload.payload,
|
|||
|
|
)
|
|||
|
|
result = await use_cases.account_management.testWebhook(cmd)
|
|||
|
|
raiseOnControlFailure(result)
|
|||
|
|
return {"success": True, "data": serialize_control_data(result.data)}
|