dwy-webhooks 0.1.1__tar.gz

dwy_webhooks-0.1.1/.gitignore

@@ -0,0 +1,44 @@
+node_modules/
+.build/
+.build-ios/
+.swiftpm/
+dist/
+private-dist/
+.DS_Store
+*.tsbuildinfo
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/
+
+# Environment
+.env
+*.env
+.superpowers/
+
+# Keys
+.key
+/.npmrc
+
+# Local Claude Code settings
+.claude/settings.local.json
+# dwy 本机缓存（sync-state.json 等同步状态，每机不同，不入库）
+.dwy/
+dwy-cli/.agents/
+dwy-cli/.claude/
+dwy-cli/.codex/
+dwy-cli/.cursor/
+dwy-cli/.opencode/
+dwy-cli/AGENTS.md
+
+# uv lock (library should not lock dependencies)
+backend/uv.lock
+.playwright-mcp/
+.pentest-results/
+.gstack/
+.codegraph/

dwy_webhooks-0.1.1/CHANGELOG.md

@@ -0,0 +1,14 @@
+# dwy-webhooks
+
+## 0.1.1
+
+- 首个公开 PyPI 版本，通过 GitHub Actions OIDC 发布。
+- 显式声明 Ruff 的本包模块分类，使仓库根目录与包目录运行的导入排序检查一致。
+- Discord 请求的 User-Agent 版本同步为 `0.1.1`；验签、注入与发送行为保持不变。
+
+## 0.1.0（未公开）
+
+- 首次通过 GitHub Actions OIDC 发布到公开 PyPI，导入命名空间为 `dwy_webhooks`，基础依赖为 `dwyeapi==0.12.0`。
+- 提供公开配置、FastAPI 注册入口、中立事件与可替换接收器；密钥、路由、目标地址和存储资源由调用项目注入。
+- 将 Discord 发送、Resend 事件、App Store Connect HMAC 和 Apple Server Notifications V2 适配为可复用模块，包含验签、去重、失败语义和发送边界。
+- `discord`、`resend`、`apple` SDK 分别通过 extras 安装；基础安装及公开入口导入不要求这些平台 SDK。

dwy_webhooks-0.1.1/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: dwy-webhooks
+Version: 0.1.1
+Summary: 独立于业务来源的 Webhook 发送、安全边界与失败语义
+Requires-Python: <3.13,>=3.11
+Requires-Dist: dwyeapi==0.12.0
+Provides-Extra: apple
+Requires-Dist: app-store-server-library[async]==3.1.2; extra == 'apple'
+Provides-Extra: dev
+Requires-Dist: aiosqlite==0.22.1; extra == 'dev'
+Requires-Dist: httpx==0.28.1; extra == 'dev'
+Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
+Requires-Dist: pytest==9.0.3; extra == 'dev'
+Requires-Dist: ruff==0.15.12; extra == 'dev'
+Provides-Extra: discord
+Requires-Dist: discord-webhook[async]==1.4.1; extra == 'discord'
+Requires-Dist: httpx==0.28.1; extra == 'discord'
+Provides-Extra: resend
+Requires-Dist: resend==2.49.1; extra == 'resend'
+Description-Content-Type: text/markdown
+
+# dwy-webhooks
+
+基于 EAPI 的通用 Webhook 模块。接收 Resend、App Store Connect、Apple Server Notifications V2，并按项目配置转发到 Discord 或外部注入的业务接收函数。
+
+## 安装与依赖
+
+核心依赖固定兼容版本 `dwyeapi`；平台 SDK 按需选择 `dwy-webhooks[discord,resend,apple]`。ASC 使用标准库 HMAC；只有 Apple Server Notifications 需要 Apple SDK。源码由 dwy-shared 维护，项目安装独立 wheel，不引用共享仓库的绝对源码路径。发布配置不表示已经发布。
+
+## 配置与接入
+
+库不读取环境变量、`.env`、项目设置或证书文件。`WebhookConfig` 是纯 Pydantic 模型；项目可组合进自己的 EAPI Settings。密钥由项目取得后传入，Apple 根证书传入字节。
+
+```python
+from dwy_webhooks import WebhookConfig, install_webhooks
+from dwy_webhooks.config import ResendWebhookConfig
+
+# app 与 project_settings 都属于调用项目；库不再回读环境。
+config = WebhookConfig(
+    discord_webhook_url=project_settings.discord_webhook_url,
+    resend=ResendWebhookConfig(
+        secret=project_settings.resend_webhook_secret,
+        name="My Project", events=frozenset({"email.received", "email.failed"}),
+    ),
+)
+runtime = install_webhooks(app, config)
+```
+
+Resend 使用 Webhook 签名密钥，不使用发送邮件的 API Key。未配置来源不注册路由；各来源可独立覆盖 Discord 目标、事件集合和接收路径。
+
+- `AppStoreConnectWebhookConfig(apps={app_id: AppStoreConnectApp(name=..., secret=...)})` 配置审核、构建及 ping 通知。
+- `AppleNotificationsConfig(apps={key: AppleNotificationApp(name=..., bundle_id=..., environment="Production", app_apple_id=..., root_certificates=(certificate_bytes, ...))})` 配置 Server Notifications V2。
+- 将前两者放入 `WebhookConfig.app_store_connect`、`.apple_notifications` 后，一次注册即可接入。
+- 默认路径：`/webhooks/resend`、`/webhooks/app-store-connect/{app_id}`、`/webhooks/apple/{app_id}`；完整公开 URL 由项目域名及反向代理决定。
+
+## 资源与接收语义
+
+- 默认 `DiscordRelay` 在发送成功后确认，实例内保留最多 4096 条成功记录。失败返回非 2xx 供提供方重试。重启可能再次发送，这不是持久或恰好一次投递保证。
+- 项目可注入 `ReceiptStore`，或通过 `WebhookSinks` 按来源注入接收函数。函数接收已验证的 `WebhookEvent`，返回 True 表示接受、False 表示重复；异常不能被确认成功。
+- `SQLAlchemyDeliveryQueue` 提供持久队列，sessions、table、sender、source 和可选策略由外部注入。使用 EAPI 创建的会话，不创建、迁移或关闭项目数据库。一个表固定一个来源，防止跨来源编号碰撞。
+- `build_delivery_table` 注册到项目 metadata，由项目自己的 Alembic 管理 schema。库不在注册路由时自动建表。
+- `install_webhooks` 保留宿主生命周期，只关闭自己拥有的验证器；`create_app(config)` 可建立独立 ASGI 应用，配置仍然必填。普通错误复用 EAPI，第三方成功 ACK 保持提供方协议。
+
+```python
+from dwy_webhooks import WebhookSinks, install_webhooks
+
+# persist_verified_event 是项目自己的持久入口，或已注入资源的队列实例。
+install_webhooks(app, config, sinks=WebhookSinks(app_store_connect=persist_verified_event))
+```
+
+Apple 商品目录、账户绑定和权益发放保留在业务项目。通用模块只验证通知并提供安全事件元数据，不把测试通知或续订设置变更报告为收入。
+
+## 安全和扩展
+
+来源分别验签，并在读取原始字节时限制体积。Apple 外层、交易及续订 JWS 分别走官方 SDK，生产强制 App Apple ID。Discord 固定官方 HTTPS 地址，拒绝重定向和 mentions，等待有效消息编号；错误不记录 token 或原始响应正文。
+
+新增来源增加 provider，新增目标增加 transport；共用事件、sink 和 EAPI 资源，避免平台大分支。注册入口不覆盖项目已有的全局异常或缓存配置。
+
+`examples/new_project/app.py` 是不依赖 App Cloud 的接入示例。隔离 wheel 验收要求 `app_cloud`、`apple_iap`、`cloud_kernel`、旧 `cloud_webhooks` 和产品包缺席，公共配置、注册和三类来源仍能通过测试。

dwy_webhooks-0.1.1/README.md

@@ -0,0 +1,58 @@
+# dwy-webhooks
+
+基于 EAPI 的通用 Webhook 模块。接收 Resend、App Store Connect、Apple Server Notifications V2，并按项目配置转发到 Discord 或外部注入的业务接收函数。
+
+## 安装与依赖
+
+核心依赖固定兼容版本 `dwyeapi`；平台 SDK 按需选择 `dwy-webhooks[discord,resend,apple]`。ASC 使用标准库 HMAC；只有 Apple Server Notifications 需要 Apple SDK。源码由 dwy-shared 维护，项目安装独立 wheel，不引用共享仓库的绝对源码路径。发布配置不表示已经发布。
+
+## 配置与接入
+
+库不读取环境变量、`.env`、项目设置或证书文件。`WebhookConfig` 是纯 Pydantic 模型；项目可组合进自己的 EAPI Settings。密钥由项目取得后传入，Apple 根证书传入字节。
+
+```python
+from dwy_webhooks import WebhookConfig, install_webhooks
+from dwy_webhooks.config import ResendWebhookConfig
+
+# app 与 project_settings 都属于调用项目；库不再回读环境。
+config = WebhookConfig(
+    discord_webhook_url=project_settings.discord_webhook_url,
+    resend=ResendWebhookConfig(
+        secret=project_settings.resend_webhook_secret,
+        name="My Project", events=frozenset({"email.received", "email.failed"}),
+    ),
+)
+runtime = install_webhooks(app, config)
+```
+
+Resend 使用 Webhook 签名密钥，不使用发送邮件的 API Key。未配置来源不注册路由；各来源可独立覆盖 Discord 目标、事件集合和接收路径。
+
+- `AppStoreConnectWebhookConfig(apps={app_id: AppStoreConnectApp(name=..., secret=...)})` 配置审核、构建及 ping 通知。
+- `AppleNotificationsConfig(apps={key: AppleNotificationApp(name=..., bundle_id=..., environment="Production", app_apple_id=..., root_certificates=(certificate_bytes, ...))})` 配置 Server Notifications V2。
+- 将前两者放入 `WebhookConfig.app_store_connect`、`.apple_notifications` 后，一次注册即可接入。
+- 默认路径：`/webhooks/resend`、`/webhooks/app-store-connect/{app_id}`、`/webhooks/apple/{app_id}`；完整公开 URL 由项目域名及反向代理决定。
+
+## 资源与接收语义
+
+- 默认 `DiscordRelay` 在发送成功后确认，实例内保留最多 4096 条成功记录。失败返回非 2xx 供提供方重试。重启可能再次发送，这不是持久或恰好一次投递保证。
+- 项目可注入 `ReceiptStore`，或通过 `WebhookSinks` 按来源注入接收函数。函数接收已验证的 `WebhookEvent`，返回 True 表示接受、False 表示重复；异常不能被确认成功。
+- `SQLAlchemyDeliveryQueue` 提供持久队列，sessions、table、sender、source 和可选策略由外部注入。使用 EAPI 创建的会话，不创建、迁移或关闭项目数据库。一个表固定一个来源，防止跨来源编号碰撞。
+- `build_delivery_table` 注册到项目 metadata，由项目自己的 Alembic 管理 schema。库不在注册路由时自动建表。
+- `install_webhooks` 保留宿主生命周期，只关闭自己拥有的验证器；`create_app(config)` 可建立独立 ASGI 应用，配置仍然必填。普通错误复用 EAPI，第三方成功 ACK 保持提供方协议。
+
+```python
+from dwy_webhooks import WebhookSinks, install_webhooks
+
+# persist_verified_event 是项目自己的持久入口，或已注入资源的队列实例。
+install_webhooks(app, config, sinks=WebhookSinks(app_store_connect=persist_verified_event))
+```
+
+Apple 商品目录、账户绑定和权益发放保留在业务项目。通用模块只验证通知并提供安全事件元数据，不把测试通知或续订设置变更报告为收入。
+
+## 安全和扩展
+
+来源分别验签，并在读取原始字节时限制体积。Apple 外层、交易及续订 JWS 分别走官方 SDK，生产强制 App Apple ID。Discord 固定官方 HTTPS 地址，拒绝重定向和 mentions，等待有效消息编号；错误不记录 token 或原始响应正文。
+
+新增来源增加 provider，新增目标增加 transport；共用事件、sink 和 EAPI 资源，避免平台大分支。注册入口不覆盖项目已有的全局异常或缓存配置。
+
+`examples/new_project/app.py` 是不依赖 App Cloud 的接入示例。隔离 wheel 验收要求 `app_cloud`、`apple_iap`、`cloud_kernel`、旧 `cloud_webhooks` 和产品包缺席，公共配置、注册和三类来源仍能通过测试。

dwy_webhooks-0.1.1/examples/new_project/app.py

@@ -0,0 +1,22 @@
+"""独立项目示例：项目创建配置后注入，不依赖 App Cloud 的任何包。"""
+
+from dwyeapi.exceptions import register_exception_handlers
+from fastapi import FastAPI
+
+from dwy_webhooks import WebhookConfig, WebhookSinks, install_webhooks
+from dwy_webhooks.sinks import ReceiptStore
+
+
+def create_project_app(config: WebhookConfig, *, sinks: WebhookSinks | None = None,
+                       receipts: ReceiptStore | None = None) -> FastAPI:
+    """配置、密钥取得方式和可选资源均由调用项目决定。"""
+    app = FastAPI(title="Independent webhook consumer")
+    register_exception_handlers(app)
+
+    @app.get("/status")
+    def status():
+        """项目自己的端点用于确认集成不会占用整个应用。"""
+        return {"status": "ok"}
+
+    install_webhooks(app, config, sinks=sinks, receipts=receipts)
+    return app

dwy_webhooks-0.1.1/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "dwy-webhooks"
+version = "0.1.1"
+description = "独立于业务来源的 Webhook 发送、安全边界与失败语义"
+readme = "README.md"
+requires-python = ">=3.11,<3.13"
+# EAPI 提供配置模型、Web 框架、数据库和日志基础，平台 SDK 按需安装。
+dependencies = ["dwyeapi==0.12.0"]
+
+[project.optional-dependencies]
+# 沿用当前集成已验收版本；基础包导入不强制加载平台 SDK。
+discord = ["discord-webhook[async]==1.4.1", "httpx==0.28.1"]
+resend = ["resend==2.49.1"]
+apple = ["app-store-server-library[async]==3.1.2"]
+dev = ["pytest==9.0.3", "pytest-asyncio==1.3.0", "httpx==0.28.1", "aiosqlite==0.22.1", "ruff==0.15.12"]
+
+[build-system]
+requires = ["hatchling==1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dwy_webhooks"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 110
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["dwy_webhooks"]

dwy_webhooks-0.1.1/src/dwy_webhooks/__init__.py

@@ -0,0 +1,21 @@
+"""基于 EAPI 的 Webhook 集成；配置由项目注入，平台 SDK 按需加载。"""
+
+from .config import WebhookConfig
+from .errors import WebhookDeliveryError
+from .events import WebhookEvent
+from .fastapi import WebhookRuntime, WebhookSinks, install_webhooks
+from .validation import validate_discord_webhook_url
+
+__all__ = [
+    "DiscordWebhookSender", "WebhookConfig", "WebhookDeliveryError", "WebhookEvent",
+    "WebhookRuntime", "WebhookSinks", "install_webhooks", "validate_discord_webhook_url",
+]
+
+
+def __getattr__(name: str):
+    """核心导入不强制安装 Discord SDK；只有使用发送能力才加载该 extra。"""
+    if name == "DiscordWebhookSender":
+        from .discord import DiscordWebhookSender
+
+        return DiscordWebhookSender
+    raise AttributeError(name)

dwy_webhooks-0.1.1/src/dwy_webhooks/config.py

@@ -0,0 +1,126 @@
+"""外部注入的配置契约；不读取环境变量、dotenv 或任何项目设置。"""
+
+import base64
+import binascii
+from itertools import combinations
+from typing import Annotated, Literal
+
+from pydantic import (
+    BaseModel,
+    BeforeValidator,
+    ConfigDict,
+    Field,
+    SecretStr,
+    field_validator,
+    model_validator,
+)
+
+from .validation import paths_overlap, validate_discord_webhook_url
+
+
+def _destination(value):
+    """共享官方目标校验；空环境值关闭目标，错误不得回显凭据。"""
+    if value is None or value == "":
+        return None
+    raw = value.get_secret_value() if isinstance(value, SecretStr) else value
+    validate_discord_webhook_url(raw)
+    return value
+
+
+Destination = Annotated[SecretStr | None, BeforeValidator(_destination)]
+EventType = Annotated[str, Field(min_length=1, max_length=100, pattern=r"^[A-Za-z0-9_.-]+$")]
+AppKey = Annotated[str, Field(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_-]+$")]
+ASCAppID = Annotated[str, Field(min_length=1, max_length=20, pattern=r"^[0-9]+$")]
+LocalPath = Annotated[str, Field(max_length=256, pattern=r"^/(?:[A-Za-z0-9_-]+/)*[A-Za-z0-9_-]+$")]
+ScopedPath = Annotated[str, Field(max_length=256, pattern=r"^/(?:[A-Za-z0-9_-]+/)+\{app_id\}$")]
+
+
+class WebhookSourceConfig(BaseModel):
+    """已实际重复的来源选项：可覆盖发送目标，并按事件类型筛选。"""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    discord_webhook_url: Destination = Field(default=None, max_length=2048, repr=False)
+    # None 使用提供方适配器自己的已知事件集，避免配置与事件格式维护两份列表。
+    events: frozenset[EventType] | None = Field(default=None, max_length=100)
+
+
+class ResendWebhookConfig(WebhookSourceConfig):
+    """Resend 原文签名配置，不需要发送邮件的 API Key。"""
+
+    secret: SecretStr = Field(min_length=1, max_length=512, repr=False)
+    name: str = Field(default="Resend", min_length=1, max_length=100)
+    scope: AppKey = "resend"
+    path: LocalPath = "/webhooks/resend"
+
+    @field_validator("secret")
+    @classmethod
+    def valid_secret(cls, value: SecretStr) -> SecretStr:
+        """验证 Svix 密钥编码，不接受格式错误后在请求阶段静默失败。"""
+        raw = value.get_secret_value()
+        try:
+            if not raw.startswith("whsec_") or len(base64.b64decode(raw[6:], validate=True)) < 16:
+                raise ValueError
+        except (ValueError, binascii.Error):
+            raise ValueError("Resend requires a valid signing secret") from None
+        return value
+
+
+class AppStoreConnectApp(BaseModel):
+    """每个 App 的显示名称与独立 HMAC 密钥。"""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    name: str = Field(min_length=1, max_length=128)
+    secret: SecretStr = Field(min_length=32, max_length=512, repr=False)
+
+
+class AppStoreConnectWebhookConfig(WebhookSourceConfig):
+    """ASC 审核/构建通知；App ID 与签名密钥固定由项目配置。"""
+
+    apps: dict[ASCAppID, AppStoreConnectApp] = Field(min_length=1, max_length=100)
+    path: ScopedPath = "/webhooks/app-store-connect/{app_id}"
+
+
+class AppleNotificationApp(BaseModel):
+    """Server Notifications V2 身份及证书；不需要 App Cloud 商品目录。"""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    name: str = Field(default="Apple", min_length=1, max_length=100)
+    bundle_id: str = Field(min_length=1, max_length=255)
+    environment: Literal["Production", "Sandbox"] = "Production"
+    app_apple_id: int | None = Field(default=None, ge=1)
+    root_certificates: tuple[bytes, ...] = Field(min_length=1, max_length=8, repr=False)
+    enable_online_checks: bool = True
+    verification_workers: int = Field(default=2, ge=1, le=8)
+
+    @model_validator(mode="after")
+    def production_identity(self):
+        """生产环境必须同时校验 Apple App ID；不能退回 Sandbox 验证。"""
+        if self.environment == "Production" and self.app_apple_id is None:
+            raise ValueError("Production Apple notifications require app_apple_id")
+        return self
+
+
+class AppleNotificationsConfig(WebhookSourceConfig):
+    """多个独立 App 的 Server Notifications 接入配置。"""
+
+    apps: dict[AppKey, AppleNotificationApp] = Field(min_length=1, max_length=100)
+    path: ScopedPath = "/webhooks/apple/{app_id}"
+
+
+class WebhookConfig(BaseModel):
+    """由项目 Settings 显式组合；未配置来源不注册路由，不读取部署环境。"""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    discord_webhook_url: Destination = Field(default=None, max_length=2048, repr=False)
+    resend: ResendWebhookConfig | None = None
+    app_store_connect: AppStoreConnectWebhookConfig | None = None
+    apple_notifications: AppleNotificationsConfig | None = None
+
+    @model_validator(mode="after")
+    def unique_paths(self):
+        """显式配置不同来源时，不能让相同路径静默遮蔽另一验签协议。"""
+        paths = [source.path for source in
+                 (self.resend, self.app_store_connect, self.apple_notifications) if source is not None]
+        if any(paths_overlap(left, right) for left, right in combinations(paths, 2)):
+            raise ValueError("Webhook source paths must not overlap")
+        return self

dwy_webhooks-0.1.1/src/dwy_webhooks/delivery.py

@@ -0,0 +1,153 @@
+"""外部会话、表与发送器驱动的持久投递；模块不连接或初始化项目数据库。"""
+
+import asyncio
+import math
+import re
+import time
+from collections.abc import Awaitable, Callable
+from uuid import uuid4
+
+from dwyeapi.logger import get_logger
+from pydantic import BaseModel, ConfigDict, Field
+from sqlalchemy import JSON, BigInteger, Column, Integer, MetaData, String, Table, select, update
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.dialects.sqlite import insert as sqlite_insert
+
+from .errors import WebhookDeliveryError
+from .events import WebhookEvent
+
+
+class DeliveryPolicy(BaseModel):
+    """调用方可显式注入投递预算，缺省与已有 ASC 消费者行为一致。"""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    max_attempts: int = Field(default=8, ge=1, le=100)
+    batch_size: int = Field(default=25, ge=1, le=500)
+    lease_seconds: int = Field(default=60, ge=1, le=3600)
+    poll_seconds: float = Field(default=2, gt=0, le=3600, allow_inf_nan=False)
+    retry_cap_seconds: int = Field(default=3600, ge=1, le=86400)
+    provider_retry_cap_seconds: int = Field(default=86400, ge=1, le=604800)
+
+
+def build_delivery_table(metadata: MetaData, name: str = "webhook_deliveries", *,
+                         scope_length: int = 128) -> Table:
+    """仅构造表定义；调用项目通过自己的 Alembic 迁移管理实际 schema。
+
+    app_id 是来源内的隔离 scope；沿用已有字段名以兼容 ASC 账本。
+    一个表归属一个来源，由调用方分别注入，不能把不同来源写进同一表。
+    """
+    if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]{0,62}", name) is None or not 1 <= scope_length <= 255:
+        raise ValueError("Invalid webhook delivery table definition")
+    return Table(
+        name, metadata,
+        Column("app_id", String(scope_length), primary_key=True),
+        Column("id", String(128), primary_key=True),
+        Column("event_type", String(128), nullable=False),
+        Column("payload", JSON, nullable=False),
+        Column("status", String(20), nullable=False),
+        Column("attempts", Integer, nullable=False, server_default="0"),
+        Column("next_attempt_at", BigInteger, nullable=False, server_default="0"),
+        Column("lease_until", BigInteger, nullable=False, server_default="0"),
+        Column("lease_token", String(36)),
+        Column("error_code", String(64)),
+        Column("message_id", String(128)),
+    )
+
+
+class SQLAlchemyDeliveryQueue:
+    """每个来源拥有独立账本；发送在事务外，完成更新必须持有本轮租约。"""
+
+    def __init__(self, sessions, table: Table, sender: Callable[[str], Awaitable[str]], *,
+                 source: str, policy: DeliveryPolicy | None = None,
+                 clock: Callable[[], float] = time.time):
+        """资源全部由调用方注入；消费者不创建、迁移或关闭任何项目资源。"""
+        if re.fullmatch(r"[a-z][a-z0-9_.-]{0,63}", source) is None:
+            raise ValueError("Invalid webhook source")
+        self.sessions, self.table, self.sender = sessions, table, sender
+        self.source, self.clock = source, clock
+        self.policy = policy if policy is not None else DeliveryPolicy()
+
+    async def __call__(self, event: WebhookEvent) -> bool:
+        """接收器可直接作为 sink 注入；错误来源必须在持久化前拒绝。"""
+        if event.source != self.source:
+            raise ValueError("Webhook source does not match the delivery queue")
+        return await self.enqueue(event.scope, event.event_id, event.event_type, event.content)
+
+    async def enqueue(self, app_id: str, event_id: str, event_type: str, content: str) -> bool:
+        """原子去重和入队；返回后接收端才能向提供方确认成功。"""
+        table = self.table
+        async with self.sessions.begin() as db:
+            dialect = db.get_bind().dialect.name
+            factory = {"sqlite": sqlite_insert, "postgresql": pg_insert}.get(dialect)
+            if factory is None:
+                raise ValueError("Webhook queue requires PostgreSQL or SQLite")
+            result = await db.execute(factory(table).values(
+                app_id=app_id, id=event_id, event_type=event_type,
+                payload={"content": content}, status="pending",
+            ).on_conflict_do_nothing(index_elements=["app_id", "id"]))
+            return bool(result.rowcount)
+
+    async def process_pending(self) -> int:
+        """有界条件领取；进程崩溃后由其他消费者接管过期租约。"""
+        table, sent = self.table, 0
+        for _ in range(self.policy.batch_size):
+            now, token = int(self.clock()), str(uuid4())
+            ready = (table.c.status.in_(("pending", "retry", "processing")),
+                     table.c.next_attempt_at <= now, table.c.lease_until <= now)
+            async with self.sessions.begin() as db:
+                row = (await db.execute(select(table).where(*ready).order_by(
+                    table.c.next_attempt_at, table.c.app_id, table.c.id
+                ).limit(1))).mappings().first()
+                if row is None:
+                    break
+                key = (table.c.app_id == row["app_id"], table.c.id == row["id"])
+                claimed = await db.execute(update(table).where(*key, *ready).values(
+                    status="processing", lease_token=token, lease_until=now + self.policy.lease_seconds))
+                if not claimed.rowcount:
+                    continue
+                row = dict(row)
+            values = await self._send(row)
+            async with self.sessions.begin() as db:
+                result = await db.execute(update(table).where(
+                    *key, table.c.lease_token == token
+                ).values(**values, lease_token=None, lease_until=0))
+                sent += int(bool(result.rowcount) and values["status"] == "sent")
+        return sent
+
+    async def _send(self, row) -> dict:
+        failure = None
+        try:
+            message_id = await self.sender(row["payload"]["content"])
+            if not isinstance(message_id, str) or not 1 <= len(message_id) <= 128:
+                raise WebhookDeliveryError("webhook_invalid_response")
+        except WebhookDeliveryError as error:
+            failure = error
+        except Exception:
+            # 第三方 sender 的异常也不能泄露原文，且必须受重试次数约束。
+            failure = WebhookDeliveryError("webhook_delivery_error")
+        if failure is not None:
+            # 不持久化用户自定义 sender 可能抛出的地址或响应正文。
+            code = (failure.code if isinstance(failure.code, str)
+                    and re.fullmatch(r"[a-z][a-z0-9_.-]{0,63}", failure.code) else "webhook_delivery_error")
+            delay = 0
+            if (not isinstance(failure.retry_after, bool) and isinstance(failure.retry_after, (int, float))
+                    and math.isfinite(failure.retry_after) and failure.retry_after >= 0):
+                delay = min(math.ceil(failure.retry_after), self.policy.provider_retry_cap_seconds)
+            attempts = row["attempts"] + 1
+            return dict(
+                status="dead" if failure.permanent or attempts >= self.policy.max_attempts else "retry",
+                attempts=attempts,
+                next_attempt_at=int(self.clock()) + max(
+                    delay, min(self.policy.retry_cap_seconds, 2 ** attempts)),
+                error_code=code,
+            )
+        return dict(status="sent", message_id=message_id, error_code=None)
+
+    async def run(self) -> None:
+        """由调用项目的 lifespan 启停；未知失败只记录固定错误码。"""
+        while True:
+            try:
+                await self.process_pending()
+            except Exception:
+                get_logger(__name__).error("Webhook processor failed code=WEBHOOK_PROCESSOR_FAILED")
+            await asyncio.sleep(self.policy.poll_seconds)

dwy_webhooks-0.1.1/src/dwy_webhooks/discord.py

@@ -0,0 +1,100 @@
+"""Discord 单次传输；消息内容、验签和重试账本不属于传输层。"""
+
+import logging
+import re
+from contextlib import asynccontextmanager
+from math import isfinite
+
+import httpx
+from discord_webhook import AsyncDiscordWebhook
+
+from .errors import WebhookDeliveryError
+from .validation import validate_discord_webhook_url
+
+
+class _WebhookCredentialsFilter(logging.Filter):
+    """渲染后移除 token，正常 HTTP 请求日志继续保留。"""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """修改已渲染消息并清空 args，避免日志格式化再次插入原始 token。"""
+        message = record.getMessage()
+        redacted = re.sub(
+            r"(https://discord\.com/api/(?:v10/)?webhooks/[0-9]+/)[A-Za-z0-9_-]+",
+            r"\1[REDACTED]", message,
+        )
+        if redacted != message:
+            record.msg, record.args = redacted, ()
+        return True
+
+
+# 常驻安装，避免并发请求在临时添加/移除过滤器时出现脱敏空窗。
+logging.getLogger("httpx").addFilter(_WebhookCredentialsFilter())
+
+
+def discord_client() -> httpx.AsyncClient:
+    """每次请求使用有界客户端，取消和异常时由上下文负责关闭。"""
+    return httpx.AsyncClient(
+        timeout=10, follow_redirects=False, headers={"User-Agent": "dwy-webhooks/0.1.1"}
+    )
+
+
+class _DiscordWebhook(AsyncDiscordWebhook):
+    """复用成熟 SDK 的载荷和查询参数，只替换受控客户端。"""
+
+    @property
+    @asynccontextmanager
+    async def http_client(self):
+        """禁止跟随重定向，防止将凭据发送到另一地址。"""
+        async with discord_client() as client:
+            yield client
+
+
+def _retry_after(response: httpx.Response) -> float | None:
+    """Discord 延迟单位为秒；畸形值交给调用方的默认退避。"""
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    value = body.get("retry_after") if isinstance(body, dict) else None
+    if value is None:
+        value = response.headers.get("Retry-After")
+    if isinstance(value, bool):
+        return None
+    try:
+        seconds = float(value)
+    except (TypeError, ValueError, OverflowError):
+        return None
+    return seconds if isfinite(seconds) and seconds >= 0 else None
+
+
+class DiscordWebhookSender:
+    """只发送一次并返回消息编号；不休眠、重发或保存领域状态。"""
+
+    def __init__(self, webhook_url: str):
+        """公共包独立使用时也必须校验目标；异常不回显传入 URL。"""
+        self._webhook_url = validate_discord_webhook_url(webhook_url)
+
+    async def __call__(self, content: str, *, suppress_embeds: bool = False) -> str:
+        """wait 确认实际消息；预览选项只映射 Discord 的原生消息标志。"""
+        webhook = _DiscordWebhook(
+            url=self._webhook_url, content=content, allowed_mentions={"parse": []},
+            flags=4 if suppress_embeds else None, rate_limit_retry=False, timeout=10, wait=True,
+        )
+        try:
+            # execute() 会记录原始错误正文；只复用 SDK 的单次请求入口。
+            response = await webhook.api_post_request()
+        except httpx.HTTPError:
+            raise WebhookDeliveryError("discord_network_error") from None
+        if response.status_code == 429:
+            raise WebhookDeliveryError("discord_rate_limited", retry_after=_retry_after(response))
+        if not 200 <= response.status_code < 300:
+            raise WebhookDeliveryError("discord_http_error", permanent=300 <= response.status_code < 500)
+        try:
+            body = response.json()
+        except ValueError:
+            raise WebhookDeliveryError("discord_invalid_response") from None
+        message_id = body.get("id") if isinstance(body, dict) else None
+        if (not isinstance(message_id, str) or not message_id.isascii()
+                or not message_id.isdigit() or len(message_id) > 128):
+            raise WebhookDeliveryError("discord_invalid_response")
+        return message_id