#MoonHook

#工程验证

moon check --deny-warn                      # 三个目标均 0 warning
moon test --deny-warn                       # 75 个测试
moon check --target wasm-gc --deny-warn     # 核心包保持可移植
moon check --target js --deny-warn
moon test --enable-coverage                 # 覆盖率：库代码 90% 以上（不含 CLI）
moon coverage report -f summary
moon run cmd/httpdemo -- e2e                # 真实 HTTP 投递 + 验签，端到端

#核心功能

• WebhookEvent / Hook 数据模型与校验式 Builder
• HookRegistry 注册表：注册、查询、去重、校验
• 纯 MoonBit SHA-256，通过标准测试向量
• HMAC-SHA256 签名与常量时间验签
• 时间戳签名 sign_webhook / verify_webhook，支持防重放窗口
• 接收端验签：大小写不敏感 header、sha256= 前缀兼容
• RetryPolicy：不重试、固定间隔、指数退避，参数校验
• DeliveryEngine：首投成功、重试后成功、耗尽后死信、非可重试失败、跳过
• InMemoryOutbox / InMemoryDeadLetter：待投递队列与死信队列
• IdempotencyStore：TTL 幂等去重与过期清理
• AuditLog：投递尝试审计与最近记录查询
• Hook / 待投递 / 死信 JSON 序列化与反序列化
• SignatureProvider：出站平台签名适配，覆盖 GitHub、Stripe、Slack、飞书 自定义机器人、Shopify，收发两侧共用同一套实现
• transport_http：基于 moonbitlang/async/http 的真实 HTTP 投递 （post_signed_request、http_transport）
• AsyncDeliveryEngine：异步投递引擎，按 RetryPolicy::next_delay_ms 在两次尝试之间真正 sleep，而不是背靠背重试
• webhook_receiver：接收端处理器，读 body、验签、校验时间戳窗口并回 200/401
• 演示 CLI：内存流水线、签名、验签、请求构建、平台签名，以及 HTTP 收发演示

#快速开始

moon test                          # 核心测试 + HTTP 集成测试
moon run cmd/main -- demo          # 内存流水线演示
moon run cmd/main -- sign <secret> <payload>
moon run cmd/main -- verify <secret> <payload> <signature>
moon run cmd/main -- request <hook-id> <url> <secret> <payload>

moon run cmd/httpdemo -- e2e       # 起接收端 + 真实投递 + 验签，一条命令跑通
moon run cmd/httpdemo -- serve 127.0.0.1:8080 <secret>
moon run cmd/httpdemo -- deliver <url> <secret> <payload>

[receiver] listening on http://127.0.0.1:18080/hooks/orders
[sender]   POST http://127.0.0.1:18080/hooks/orders
[sender]   attempt 1: HTTP 200 in 2ms
[sender]   status: success
[receiver] verified payloads: 1
[receiver] payload: {"order_id": "A-1001", "total": 99}

#真实 HTTP 投递

///|
async fn main {
  let registry = @MoonHook.HookRegistry::new()
  let hook = @MoonHook.Hook::new("orders", "https://example.com/hooks/orders")
    .with_secret("shared-secret")
    .with_retry_policy(@MoonHook.RetryPolicy::Exponential(200, 2.0, 5_000))
    .with_max_attempts(5)
  registry.register(hook) |> ignore
  let engine = @transport_http.AsyncDeliveryEngine::new(
    registry,
    @transport_http.http_transport(),
  )
  let outcome = engine.deliver("orders", event)
  println(outcome.status.describe())
}

///|
async fn main {
  let server = @http.Server(@socket.Addr::parse("127.0.0.1:8080"))
  server.run_forever(
    @transport_http.webhook_receiver("shared-secret", 300_000, payload => {
      println("verified webhook: \{payload}")
    }),
  )
}

#目标平台

• 核心包（事件、签名、重试、引擎、存储）保持平台无关，CI 额外验证 wasm-gc 与 js，DeliveryEngine 在这些目标上照常可用。
• transport_http 依赖 moonbitlang/async 的原生 IO，因此声明 supported_targets = "+native"，只在 native 目标上参与构建。

#平台签名适配（出站）

///|
let provider = @MoonHook.SignatureProvider::Stripe
// 发送端：把平台签名头追加到已签名的请求上

///|
let signed = request.with_provider_signature(provider, secret, timestamp_s)
// 接收端：同一个 provider 负责验签，并校验时间窗

///|
let accepted = provider.verify(secret, headers, body, now_s, 300)

moon run cmd/main -- providers
moon run cmd/main -- sign-provider stripe whsec_test_secret 1492774577 '{"id":"evt_1"}'

#收发两侧验签

///|
let request = @MoonHook.build_signed_request(hook, event)

///|
let valid = @MoonHook.verify_webhook_request_with_timestamp(
  secret, headers, body, now_ms, 300_000,
)

///|
let valid = @MoonHook.verify_webhook_request(secret, headers, body)

#代码结构

event.mbt         # 事件模型与 EventBuilder
hook.mbt          # Hook 模型与配置 Builder
registry.mbt      # Hook 注册表
retry.mbt         # 重试策略、退避计算与参数校验
sha256.mbt        # 纯 MoonBit SHA-256
hmac.mbt          # HMAC-SHA256 签名与验签
transport.mbt     # 投递结果与 Transport 抽象
engine.mbt        # DeliveryEngine 投递引擎
store.mbt         # Outbox 与死信队列
idempotency.mbt   # 幂等键存储
audit.mbt         # 审计日志
request.mbt       # 签名请求构建与接收端验签
json_codec.mbt    # 领域模型 JSON 序列化
coordinator.mbt   # MoonHook 高层门面
transport_http/   # 真实 HTTP 投递适配（native）：传输、异步引擎、接收端处理器
cmd/main/         # 内存演示 CLI
cmd/httpdemo/     # HTTP 收发演示 CLI（native）

#设计说明

///|
pub type Transport = (Hook, WebhookEvent) -> DeliveryResult

#Roadmap

• HTTP 传输适配与端到端示例（transport_http，基于 moonbitlang/async）
• 文件或 SQLite 持久化 Outbox / 死信（JSON 序列化已就绪）
• 定时调度器按退避策略执行重试（AsyncDeliveryEngine 已支持等待退避）
• WebHook 注册与管理的 HTTP API
• 连接复用（@http.Client）与代理支持
• 错误类型化与覆盖率补强

#License