Chainlink CRE 网关 HTTP Handlers V2 深度解析HTTP Action 与 Trigger 的双向链路、BFT 聚合与响应缓存机制【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink本文以 Chainlink 仓库中 HTTP Handlers V2 设计文档 为核心系统讲解 CREChainlink Runtime Environment工作流如何通过网关与外部系统双向交互出站 HTTP Action 如何携带缓存与速率限制执行入站 HTTP Trigger 如何经过 JWT 鉴权、BFT 响应聚合后驱动工作流执行。读完后你将掌握该模块的完整消息处理链路、元数据同步的拜占庭容错机制、全部配置项及其默认值并能定位到每个环节对应的源码实现与测试用例。1. 模块定位与职责HTTP Handlers V2 实现了 Gateway Handler 接口使 CRE 工作流能够通过与外部系统的 HTTP 交互形成闭环。该模块承担三类职责派发出站 HTTP 请求处理源自 HTTP Action 能力capability的外部 HTTP 请求接收入站 HTTP 触发请求将 HTTP Trigger 请求转发给能力节点启动工作流执行接收并聚合工作流元数据从 HTTP Trigger 能力节点收集授权元数据用于触发请求的鉴权与工作流查找。核心能力可归纳为六项能力说明HTTP Actions出站 HTTP 请求支持缓存与速率限制HTTP Triggers入站请求触发工作流执行基于 JWT 鉴权授权元数据管理工作流授权数据的收集与聚合响应缓存缓存 HTTP 响应减少对外部端点的重复请求速率限制多维度限流全局、按工作流属主、按能力节点响应聚合对节点响应做拜占庭容错BFT聚合在 Handler 接口 的定义中每个 DONDecentralized Oracle Network创建一个 Handler 对象其生命周期为Start()启动 → 并发的一系列HandleUserMessage/HandleNodeMessage调用Handler 必须保证线程安全→Close()关闭。HTTP Handlers V2 实现了其中的HandleJSONRPCUserMessage用户触发请求、HandleNodeMessage节点消息与Methods方法路由三个关键方法其Methods()返回四个 JSON-RPC 方法workflows.execute、http_action、push_workflow_metadata、pull_workflow_metadata见 http_handler.go。2. 架构四大组件模块由四个组件构成主协调者gatewayHandler持有并管理三个子组件。2.1 网关处理器gatewayHandler主协调者负责请求路由、生命周期管理与缓存管理同时支持 HTTP Action 与 Trigger 两类请求。从 http_handler.go 的源码结构看它维护shards []*shardEndpoint本网关服务的全部 DON 分片shard端点覆盖整个 DON×shard 矩阵nodeAddrToShard节点地址 → 所属分片的路由表用于将节点响应回送正确的连接管理器多层速率限制器全局节点限流器globalNodeRateLimiter、按节点地址的独立限流桶perNodeRateLimiters、mTLS 出站请求限流器与并发限制器responseCache、triggerHandler、metadataHandler三个子组件。节点消息进入后的路由逻辑在HandleNodeMessage中先做双层限流单节点桶 全局桶再按消息 ID 是否包含/区分节点消息与触发响应——节点消息格式为methodName/workflowID/uuid按方法名http_action、push_workflow_metadata、pull_workflow_metadata分发不含/的 ID 则被当作此前用户触发请求的节点响应交给triggerHandler.HandleNodeTriggerResponse见 http_handler.go。2.2 HTTP Trigger 处理器httpTriggerHandler处理入站触发请求职责包括请求校验、授权、限流与响应聚合关键特性为 JWT 认证、工作流解析、带重试地向各分片成员分发请求、以及 BFT 聚合。实现在 http_trigger_handler.go。2.3 工作流元数据处理器WorkflowMetadataHandler管理工作流授权元数据与密钥集合负责元数据的收集、聚合、JWT 校验与工作流选择器selector映射采用 BFT 聚合与周期性同步。实现在 workflow_metadata_handler.go。2.4 响应缓存responseCache基于 TTL 的 HTTP 响应缓存可按请求的 max age 参数决定返回缓存值或重新请求且缓存按工作流隔离。实现在 response_cache.go。3. HTTP Action 消息处理出站请求3.1 完整处理流程接收请求网关收到来自工作流节点的 HTTP Action 请求JSON-RPChttp_action方法速率限制校验节点级与全局速率限制单节点桶 全局桶双重检查解析请求从 JSON-RPC 消息的 Result 中提取OutboundHTTPRequestmethod、URL、headers、body、超时等缓存判定根据CacheSettings决定走缓存路径还是直接发起新请求执行 HTTP 请求向外部端点发起实际 HTTP 请求缓存响应仅当CacheSettings.Store为true时缓存 2xx/4xx 状态码的可缓存响应回送节点响应将OutboundHTTPResponse通过sendResponseToNode发回请求方节点。从 makeOutgoingRequest 的实现看第 46 步的关键分支为CacheSettings.MaxAgeMs 0时调用responseCache.Fetch在缓存未命中或过期时回调执行真实请求否则直接执行回调并在CacheSettings.Store为真时调用Set写缓存。HTTP 请求在独立 goroutine 中异步执行回送响应时使用单独的 5 秒超时上下文defaultSendResponseTimeoutMs避免外部请求超时导致结果无法送达节点。出站请求还支持 mTLS当请求携带Mtls认证信息时send方法通过httpClientFactory实例化一个一次性throwawayHTTP 客户端携带请求方提供的客户端证书防止认证连接泄漏给其他用户并发数由mtlsConcurrencyLimiter约束见 http_handler.go。3.2 缓存行为细则可缓存状态码2xx成功与 4xx客户端错误3xx/5xx 不缓存。源码中由 isCacheableStatusCode 判定缓存 TTL可配置默认 10 分钟OutboundRequestCacheTTLMs缓存键由请求本身method、URL、headers、body 等生成的哈希且请求哈希包含工作流上下文实现按工作流隔离防止跨工作流数据泄漏缓存失效基于时间的过期由gatewayHandler.Start启动的周期清理 goroutine 按CleanUpPeriodMs调用DeleteExpired清除过期条目缓存策略所有可缓存响应都会被写入缓存而CacheSettings.MaxAgeMs非零才决定是否直接返回缓存值Fast path 命中检查否则直接发起新请求。Fetch方法还引入了singleflight组并发请求同一缓存键时只执行一次真实 HTTP 调用其余请求复用同一结果避免缓存击穿见 response_cache.go 的注释说明。4. HTTP Trigger 消息处理入站请求4.1 处理流程与校验细节入站触发请求遵循以下流水线HandleUserTriggerRequest请求校验校验 JSON-RPC 格式、方法名必须为workflows.execute、参数结构。参数Input必须是 JSON 对象或数组{}或[]不允许原始值requestID非空且不得包含/该字符保留给节点间消息路由。工作流选择器字段有严格格式约束workflowID为 0x 前缀 64 位十六进制66 字符workflowOwner为 42 字符workflowName最长 64 字符workflowTag最长 32 字符未提供workflowID时必须同时提供 owner、name、tag 三元组见 validateWorkflowFields工作流解析若提供workflowID规范化后查元数据缓存确认存在否则将workflowName哈希截断workflows.HashTruncateName后按 owner/name/tag 三元组查表解析出 workflowIDresolveWorkflowID鉴权通过WorkflowMetadataHandler.Authorize验证 JWT 令牌ECDSA 签名并校验签名者公钥在 workflow 的授权密钥集合中。授权通过后签名者的AuthorizedKey会被注入转发给节点的消息参数中速率限制以 workflow owner 维度执行按工作流的限流检查超限返回rate limit exceeded节点分发将请求扇出到该工作流被分配的全部 shard每个分片独立运行带重试的发送循环见 4.3 节响应聚合收集并聚合节点响应需要2f1个完全一致的响应f为最大故障节点数回送用户将聚合结果通过 callback 返回给原始请求方。4.2 基于 BFT 的响应聚合聚合器为 IdenticalNodeResponseAggregator共识机制对每个节点响应计算内容摘要digest按摘要分组节点跟踪nodeToResponse记录每个节点当前所属的响应组。若节点随后提供了不同响应会被从旧组移除、加入新组阈值达到阈值2f1一致响应时返回该响应否则继续等待分片级并行setupCallback会为工作流被分配的每个 shard各建一个聚合器阈值为(len(shard.members)shard.f)/2 1。第一个达到法定人数quorum的分片产生用户响应随后关闭doneCh通知所有分片的发送循环立即停止。这是从源码结构中可以确认的设计分片间互相独立单分片慢或故障不会阻塞其他分片的出结果。聚合完成后的回调处理还做了防重复保护savedCallback.processed标记保证晚到的节点响应被识别为迟到而忽略未处理的回调会由周期性 reaper按CleanUpPeriodMs清理防止callbacks表内存泄漏reapExpiredCallbacks。4.3 广播重试逻辑触发请求重试对发送失败的节点采用指数退避 抖动backoff.BackoffMin/Max/Factor分别对应RetryConfig的三个字段Jitter: true超时整体最大时长为MaxTriggerRequestDurationMs默认 1 分钟单次节点发送另有NodeSendTimeoutMs默认 10 秒上限保证单个慢节点不会拖慢整个 DON 的分发部分成功每个分片循环维护successfulNodes集合对未成功节点持续重试直到该分片全部节点收到请求、整体超时或回调已被响应doneCh关闭。发送细节见 sendToShard每轮并发向所有未成功节点发送每节点独立 goroutine 与超时上下文汇总结果后按退避间隔重试。5. 授权元数据Auth Metadata的收集与聚合5.1 两条同步流系统通过推送 拉取双通道把工作流节点上的元数据同步到网关元数据推送注册事件驱动工作流注册时HTTP 能力节点主动将WorkflowMetadata推送到网关方法为push_workflow_metadata由 OnMetadataPush 接收并进入所属分片的聚合器元数据拉取周期同步默认每 1 分钟MetadataPullIntervalMs网关向所有 HTTP 能力节点发出pull_workflow_metadata请求节点以批量元数据响应sendMetadataPullRequest响应由OnMetadataPullResponse逐条校验后进入聚合器。每条元数据入库前都经过 validateAuthMetadata 的严格校验workflowID 长度 66、owner 长度 42、name 哈希长度 22、tag 非空且不超过 32 字符、授权密钥集合非空、密钥类型必须为 ECDSA EVM、公钥必须为 0x 前缀的 42 字符小写十六进制。5.2 BFT 聚合逻辑聚合系统位于 core/services/gateway/common/aggregation/ 目录实现拜占庭容错的元数据采集观测收集每个节点的元数据被哈希后按 digest 存储一个节点对同一元数据的重复上报只计一次阈值共识每个 shard 使用独立WorkflowMetadataAggregator阈值为f1f为该分片的最大故障节点数即达到 f1 个相同观测才认定该元数据可信去重防冲突syncMetadata将各分片聚合结果合并为本地缓存处理三种情况——同一 workflowID 被多个分片上报且引用一致时追加扇出分片列表引用冲突则丢弃同一引用出现在不同 workflowID 下时首个胜出、后续丢弃周期清理过期观测被周期性移除防止内存泄漏。5.3 同步闭环收集节点提交元数据观测push/pull 两路聚合各分片聚合器在达到 f1 共识后认定元数据同步网关按MetadataAggregationIntervalMs默认 1 分钟执行syncMetadata用聚合结果整体替换本地的authorizedKeys、workflowRefToID、workflowIDToRef、workflowShards四张表并上报缓存规模指标清理过期观测周期性移除。此外WorkflowMetadataHandler.Start还启动了第三个定时器按JWTReplayPeriodMs默认 24 小时清理 JWT 重放缓存条目。JWT 重放保护由 jwtReplayCache 实现——授权成功时记录 JWT 的jti再次出现相同jti直接拒绝JWT token has already been used。6. 配置规格6.1 服务配置结构设计文档给出的ServiceConfig结构如下type ServiceConfig struct { NodeRateLimiter ratelimit.RateLimiterConfig json:nodeRateLimiter UserRateLimiter ratelimit.RateLimiterConfig json:userRateLimiter MaxTriggerRequestDurationMs int json:maxTriggerRequestDurationMs RetryConfig RetryConfig json:retryConfig CleanUpPeriodMs int json:cleanUpPeriodMs MetadataPullIntervalMs int json:metadataPullIntervalMs MetadataAggregationIntervalMs int json:metadataAggregationIntervalMs OutboundRequestCacheTTLMs int json:outboundRequestCacheTTLMs }从 当前源码的 ServiceConfig 结构看该结构已演进除保留文档中的时间类配置外还新增了NodeSendTimeoutMs单节点发送超时且被约束不得大于MaxTriggerRequestDurationMs、MetadataPullRequestTimeoutMs元数据拉取超时、JWTReplayPeriodMsJWT 重放保护窗口而节点/用户限流的参数nodeRateLimiter、userRateLimiter不再直接作为 JSON 字段而是从cresettings.Default中的统一配置如GatewayHTTPGlobalRate、GatewayHTTPPerNodeRate、PerWorkflow.HTTPTrigger.RateLimit构造限流器——即在 NewGatewayHandler 中分别创建全局节点限流器、每个 DON 成员一个的独立限流桶、用户限流器以及 mTLS 限流器/并发池。6.2 速率限制器配置type RateLimiterConfig struct { GlobalRPS float64 json:globalRPS // 全局每秒请求数 GlobalBurst int json:globalBurst // 全局突发容量 PerSenderRPS float64 json:perSenderRPS // 每发送方每秒请求数 PerSenderBurst int json:perSenderBurst // 每发送方突发容量 }对应源码中的分层限制节点侧全局桶 按节点独立桶双层检查在HandleNodeMessage开头执行用户侧按工作流属主限流在checkRateLimit中执行。6.3 重试配置type RetryConfig struct { InitialIntervalMs int json:initialIntervalMs // 初始重试间隔 MaxIntervalTimeMs int json:maxIntervalTimeMs // 最大重试间隔 Multiplier float64 json:multiplier // 退避乘数 }6.4 默认值一览以下默认值在设计文档与 WithDefaults 中一致源码还额外给出了文档未列出的两项默认值配置项默认值说明CleanUpPeriodMs60000010 分钟缓存与回调清理间隔MaxTriggerRequestDurationMs600001 分钟触发请求处理的最大时长MetadataPullIntervalMs600001 分钟从节点拉取元数据的间隔MetadataAggregationIntervalMs600001 分钟聚合已收集元数据的间隔InitialIntervalMs100初始重试间隔MaxIntervalTimeMs3000030 秒最大重试间隔Multiplier2.0指数退避乘数OutboundRequestCacheTTLMs60000010 分钟HTTP 响应缓存 TTLNodeSendTimeoutMs源码补充1000010 秒单个节点单次发送超时JWTReplayPeriodMs源码补充8640000024 小时JWT ID 防重放缓存时长6.5 配置示例{ nodeRateLimiter: { globalRPS: 100.0, globalBurst: 100, perSenderRPS: 10.0, perSenderBurst: 20 }, userRateLimiter: { globalRPS: 50.0, globalBurst: 50, perSenderRPS: 5.0, perSenderBurst: 10 }, maxTriggerRequestDurationMs: 60000, retryConfig: { initialIntervalMs: 100, maxIntervalTimeMs: 30000, multiplier: 2.0 }, cleanUpPeriodMs: 600000, metadataPullIntervalMs: 60000, metadataAggregationIntervalMs: 60000, outboundRequestCacheTTLMs: 600000 }该 JSON 由 NewGatewayHandler 反序列化并经WithDefaults补全默认值后生效。7. 安全特性7.1 认证与授权JWT 验证所有触发请求必须携带有效 JWT 令牌Authorize中先经utils.VerifyRequestJWT完成 ECDSA 签名校验再核对签名者公钥在该 workflow 的授权密钥集合内JWT 防重放jti被缓存默认 24 小时窗口重复使用同一 token 会被拒绝地址格式校验所有地址必须 0x 前缀且小写validateHexInput同时强制小写与最大长度工作流级授权每个 workflow 维护独立的授权密钥集合authorizedKeys表由 BFT 聚合保证集合本身的正确性。7.2 速率限制双层限流节点侧与用户侧使用独立限流器按发送方限制每个发送实体节点地址 / 工作流属主拥有独立限流桶全局限制系统级限流提供整体保护源码中节点侧为单节点桶 全局桶串联检查节点被限流时会记录IncrementCapabilityNodeThrottled指标。7.3 输入校验请求 ID 校验用户请求 ID 不得包含/防止与内部节点消息路由格式http_action/{workflowID}/{uuid}混淆造成恶意注入JSON 校验Input参数必须是合法 JSON 且为对象或数组工作流字段校验选择器各字段的长度与十六进制格式严格校验公钥校验授权密钥必须为标准 ECDSA 公钥格式42 字符小写十六进制。8. 错误处理8.1 错误类型认证错误无效 JWT 或未授权密钥Auth failure: ...校验错误畸形请求或非法参数限流错误超出速率限制rate limit exceeded超时错误请求处理超时网络错误HTTP 请求失败外部端点发送/读取错误响应中区分IsExternalEndpointError与IsValidationError内部错误系统或聚合失败。8.2 错误响应格式{ jsonrpc: 2.0, id: request-id, error: { code: -32602, message: Invalid request: Auth failure } }handleUserError将 JSON-RPC 标准WireError序列化后经 callback 回送用户并按错误严重度分级记录日志内部/限流/冲突类记 Error其余记 Warn。8.3 错误码表错误码说明-32700Parse error解析错误-32600Invalid request无效请求-32601Method not found方法不存在-32602Invalid params参数无效-32603Internal error内部错误-32000Rate limit exceeded超出速率限制-32001Conflict冲突请求 ID 重复其中-32001对应setupCallback中检测到的 in-flight 请求 ID 冲突同一 requestID 在回调表尚未清理前再次出现即返回冲突错误保证请求 ID 在途唯一。9. 实现细节请求 ID 与路由9.1 请求 ID 格式用户请求普通字符串标识符不得包含/节点消息methodName/workflowID/uuid或methodName/workflowID/workflowExecutionID/uuid方法路由网关按请求 ID 中的方法名前缀第一个/之前路由消息。9.2 工作流 ID 提取对 HTTP Action 请求工作流 ID 从请求路径中按methodName/workflowID/...模式提取即按/分割后的第二段。9.3 分片端点与 DON 矩阵从 shard_endpoints.go 可以确认本网关支持完整的 DON×shard 矩阵——buildShardEndpoints将多个 DON 的多个分片展开为扁平的shardEndpoint列表并构建节点地址到分片的路由表节点成员资格必须在各分片间互斥同一节点出现在两个分片会导致构造失败。每个shardEndpoint携带独立的连接管理器、成员列表与容错参数f。10. 测试与验证该模块具备完整的单元与集成测试覆盖包括多分片限流器构造、触发请求重试、BFT 聚合与元数据同步等场景测试文件与源文件一一对应http_handler_test.go覆盖NewGatewayHandler配置解析、DON×shard 矩阵展开及限流器创建等http_trigger_handler_test.go触发请求的校验、鉴权、聚合与重试链路response_cache_test.go缓存命中/过期/singleflight 去重行为workflow_metadata_handler_test.gopush/pull 同步与冲突去重聚合器测试位于 core/services/gateway/common/aggregation/。常用测试命令# 运行全部测试 go test ./... # 带覆盖率运行 go test ./... -coverpkg./... -coverprofilecoverage.txt # 竞态检测 GORACElog_path$PWD/race go test -race ./...小结HTTP Handlers V2 是 CRE 工作流与外部世界交互的枢纽出站 HTTP Action 以缓存 限流 mTLS三件套保障外部端点调用的效率与安全入站 HTTP Trigger 以JWT 鉴权 元数据 BFT 聚合 2f1 响应共识 指数退避重试四层机制在多分片 DON 环境下实现可验证、容错的触发执行链路。所有行为参数均可通过ServiceConfig按第 6 节的规格调整默认值在零配置下即形成一套安全的基线。若需进一步深入可从 handler 接口定义 与 网关处理器工厂 入手了解该模块在整体网关服务中的装配位置。【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Chainlink CRE 网关 HTTP Handlers V2 深度解析：HTTP Action 与 Trigger 的双向链路、BFT 聚合与响应缓存机制
Chainlink CRE 网关 HTTP Handlers V2 深度解析HTTP Action 与 Trigger 的双向链路、BFT 聚合与响应缓存机制【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink本文以 Chainlink 仓库中 HTTP Handlers V2 设计文档 为核心系统讲解 CREChainlink Runtime Environment工作流如何通过网关与外部系统双向交互出站 HTTP Action 如何携带缓存与速率限制执行入站 HTTP Trigger 如何经过 JWT 鉴权、BFT 响应聚合后驱动工作流执行。读完后你将掌握该模块的完整消息处理链路、元数据同步的拜占庭容错机制、全部配置项及其默认值并能定位到每个环节对应的源码实现与测试用例。1. 模块定位与职责HTTP Handlers V2 实现了 Gateway Handler 接口使 CRE 工作流能够通过与外部系统的 HTTP 交互形成闭环。该模块承担三类职责派发出站 HTTP 请求处理源自 HTTP Action 能力capability的外部 HTTP 请求接收入站 HTTP 触发请求将 HTTP Trigger 请求转发给能力节点启动工作流执行接收并聚合工作流元数据从 HTTP Trigger 能力节点收集授权元数据用于触发请求的鉴权与工作流查找。核心能力可归纳为六项能力说明HTTP Actions出站 HTTP 请求支持缓存与速率限制HTTP Triggers入站请求触发工作流执行基于 JWT 鉴权授权元数据管理工作流授权数据的收集与聚合响应缓存缓存 HTTP 响应减少对外部端点的重复请求速率限制多维度限流全局、按工作流属主、按能力节点响应聚合对节点响应做拜占庭容错BFT聚合在 Handler 接口 的定义中每个 DONDecentralized Oracle Network创建一个 Handler 对象其生命周期为Start()启动 → 并发的一系列HandleUserMessage/HandleNodeMessage调用Handler 必须保证线程安全→Close()关闭。HTTP Handlers V2 实现了其中的HandleJSONRPCUserMessage用户触发请求、HandleNodeMessage节点消息与Methods方法路由三个关键方法其Methods()返回四个 JSON-RPC 方法workflows.execute、http_action、push_workflow_metadata、pull_workflow_metadata见 http_handler.go。2. 架构四大组件模块由四个组件构成主协调者gatewayHandler持有并管理三个子组件。2.1 网关处理器gatewayHandler主协调者负责请求路由、生命周期管理与缓存管理同时支持 HTTP Action 与 Trigger 两类请求。从 http_handler.go 的源码结构看它维护shards []*shardEndpoint本网关服务的全部 DON 分片shard端点覆盖整个 DON×shard 矩阵nodeAddrToShard节点地址 → 所属分片的路由表用于将节点响应回送正确的连接管理器多层速率限制器全局节点限流器globalNodeRateLimiter、按节点地址的独立限流桶perNodeRateLimiters、mTLS 出站请求限流器与并发限制器responseCache、triggerHandler、metadataHandler三个子组件。节点消息进入后的路由逻辑在HandleNodeMessage中先做双层限流单节点桶 全局桶再按消息 ID 是否包含/区分节点消息与触发响应——节点消息格式为methodName/workflowID/uuid按方法名http_action、push_workflow_metadata、pull_workflow_metadata分发不含/的 ID 则被当作此前用户触发请求的节点响应交给triggerHandler.HandleNodeTriggerResponse见 http_handler.go。2.2 HTTP Trigger 处理器httpTriggerHandler处理入站触发请求职责包括请求校验、授权、限流与响应聚合关键特性为 JWT 认证、工作流解析、带重试地向各分片成员分发请求、以及 BFT 聚合。实现在 http_trigger_handler.go。2.3 工作流元数据处理器WorkflowMetadataHandler管理工作流授权元数据与密钥集合负责元数据的收集、聚合、JWT 校验与工作流选择器selector映射采用 BFT 聚合与周期性同步。实现在 workflow_metadata_handler.go。2.4 响应缓存responseCache基于 TTL 的 HTTP 响应缓存可按请求的 max age 参数决定返回缓存值或重新请求且缓存按工作流隔离。实现在 response_cache.go。3. HTTP Action 消息处理出站请求3.1 完整处理流程接收请求网关收到来自工作流节点的 HTTP Action 请求JSON-RPChttp_action方法速率限制校验节点级与全局速率限制单节点桶 全局桶双重检查解析请求从 JSON-RPC 消息的 Result 中提取OutboundHTTPRequestmethod、URL、headers、body、超时等缓存判定根据CacheSettings决定走缓存路径还是直接发起新请求执行 HTTP 请求向外部端点发起实际 HTTP 请求缓存响应仅当CacheSettings.Store为true时缓存 2xx/4xx 状态码的可缓存响应回送节点响应将OutboundHTTPResponse通过sendResponseToNode发回请求方节点。从 makeOutgoingRequest 的实现看第 46 步的关键分支为CacheSettings.MaxAgeMs 0时调用responseCache.Fetch在缓存未命中或过期时回调执行真实请求否则直接执行回调并在CacheSettings.Store为真时调用Set写缓存。HTTP 请求在独立 goroutine 中异步执行回送响应时使用单独的 5 秒超时上下文defaultSendResponseTimeoutMs避免外部请求超时导致结果无法送达节点。出站请求还支持 mTLS当请求携带Mtls认证信息时send方法通过httpClientFactory实例化一个一次性throwawayHTTP 客户端携带请求方提供的客户端证书防止认证连接泄漏给其他用户并发数由mtlsConcurrencyLimiter约束见 http_handler.go。3.2 缓存行为细则可缓存状态码2xx成功与 4xx客户端错误3xx/5xx 不缓存。源码中由 isCacheableStatusCode 判定缓存 TTL可配置默认 10 分钟OutboundRequestCacheTTLMs缓存键由请求本身method、URL、headers、body 等生成的哈希且请求哈希包含工作流上下文实现按工作流隔离防止跨工作流数据泄漏缓存失效基于时间的过期由gatewayHandler.Start启动的周期清理 goroutine 按CleanUpPeriodMs调用DeleteExpired清除过期条目缓存策略所有可缓存响应都会被写入缓存而CacheSettings.MaxAgeMs非零才决定是否直接返回缓存值Fast path 命中检查否则直接发起新请求。Fetch方法还引入了singleflight组并发请求同一缓存键时只执行一次真实 HTTP 调用其余请求复用同一结果避免缓存击穿见 response_cache.go 的注释说明。4. HTTP Trigger 消息处理入站请求4.1 处理流程与校验细节入站触发请求遵循以下流水线HandleUserTriggerRequest请求校验校验 JSON-RPC 格式、方法名必须为workflows.execute、参数结构。参数Input必须是 JSON 对象或数组{}或[]不允许原始值requestID非空且不得包含/该字符保留给节点间消息路由。工作流选择器字段有严格格式约束workflowID为 0x 前缀 64 位十六进制66 字符workflowOwner为 42 字符workflowName最长 64 字符workflowTag最长 32 字符未提供workflowID时必须同时提供 owner、name、tag 三元组见 validateWorkflowFields工作流解析若提供workflowID规范化后查元数据缓存确认存在否则将workflowName哈希截断workflows.HashTruncateName后按 owner/name/tag 三元组查表解析出 workflowIDresolveWorkflowID鉴权通过WorkflowMetadataHandler.Authorize验证 JWT 令牌ECDSA 签名并校验签名者公钥在 workflow 的授权密钥集合中。授权通过后签名者的AuthorizedKey会被注入转发给节点的消息参数中速率限制以 workflow owner 维度执行按工作流的限流检查超限返回rate limit exceeded节点分发将请求扇出到该工作流被分配的全部 shard每个分片独立运行带重试的发送循环见 4.3 节响应聚合收集并聚合节点响应需要2f1个完全一致的响应f为最大故障节点数回送用户将聚合结果通过 callback 返回给原始请求方。4.2 基于 BFT 的响应聚合聚合器为 IdenticalNodeResponseAggregator共识机制对每个节点响应计算内容摘要digest按摘要分组节点跟踪nodeToResponse记录每个节点当前所属的响应组。若节点随后提供了不同响应会被从旧组移除、加入新组阈值达到阈值2f1一致响应时返回该响应否则继续等待分片级并行setupCallback会为工作流被分配的每个 shard各建一个聚合器阈值为(len(shard.members)shard.f)/2 1。第一个达到法定人数quorum的分片产生用户响应随后关闭doneCh通知所有分片的发送循环立即停止。这是从源码结构中可以确认的设计分片间互相独立单分片慢或故障不会阻塞其他分片的出结果。聚合完成后的回调处理还做了防重复保护savedCallback.processed标记保证晚到的节点响应被识别为迟到而忽略未处理的回调会由周期性 reaper按CleanUpPeriodMs清理防止callbacks表内存泄漏reapExpiredCallbacks。4.3 广播重试逻辑触发请求重试对发送失败的节点采用指数退避 抖动backoff.BackoffMin/Max/Factor分别对应RetryConfig的三个字段Jitter: true超时整体最大时长为MaxTriggerRequestDurationMs默认 1 分钟单次节点发送另有NodeSendTimeoutMs默认 10 秒上限保证单个慢节点不会拖慢整个 DON 的分发部分成功每个分片循环维护successfulNodes集合对未成功节点持续重试直到该分片全部节点收到请求、整体超时或回调已被响应doneCh关闭。发送细节见 sendToShard每轮并发向所有未成功节点发送每节点独立 goroutine 与超时上下文汇总结果后按退避间隔重试。5. 授权元数据Auth Metadata的收集与聚合5.1 两条同步流系统通过推送 拉取双通道把工作流节点上的元数据同步到网关元数据推送注册事件驱动工作流注册时HTTP 能力节点主动将WorkflowMetadata推送到网关方法为push_workflow_metadata由 OnMetadataPush 接收并进入所属分片的聚合器元数据拉取周期同步默认每 1 分钟MetadataPullIntervalMs网关向所有 HTTP 能力节点发出pull_workflow_metadata请求节点以批量元数据响应sendMetadataPullRequest响应由OnMetadataPullResponse逐条校验后进入聚合器。每条元数据入库前都经过 validateAuthMetadata 的严格校验workflowID 长度 66、owner 长度 42、name 哈希长度 22、tag 非空且不超过 32 字符、授权密钥集合非空、密钥类型必须为 ECDSA EVM、公钥必须为 0x 前缀的 42 字符小写十六进制。5.2 BFT 聚合逻辑聚合系统位于 core/services/gateway/common/aggregation/ 目录实现拜占庭容错的元数据采集观测收集每个节点的元数据被哈希后按 digest 存储一个节点对同一元数据的重复上报只计一次阈值共识每个 shard 使用独立WorkflowMetadataAggregator阈值为f1f为该分片的最大故障节点数即达到 f1 个相同观测才认定该元数据可信去重防冲突syncMetadata将各分片聚合结果合并为本地缓存处理三种情况——同一 workflowID 被多个分片上报且引用一致时追加扇出分片列表引用冲突则丢弃同一引用出现在不同 workflowID 下时首个胜出、后续丢弃周期清理过期观测被周期性移除防止内存泄漏。5.3 同步闭环收集节点提交元数据观测push/pull 两路聚合各分片聚合器在达到 f1 共识后认定元数据同步网关按MetadataAggregationIntervalMs默认 1 分钟执行syncMetadata用聚合结果整体替换本地的authorizedKeys、workflowRefToID、workflowIDToRef、workflowShards四张表并上报缓存规模指标清理过期观测周期性移除。此外WorkflowMetadataHandler.Start还启动了第三个定时器按JWTReplayPeriodMs默认 24 小时清理 JWT 重放缓存条目。JWT 重放保护由 jwtReplayCache 实现——授权成功时记录 JWT 的jti再次出现相同jti直接拒绝JWT token has already been used。6. 配置规格6.1 服务配置结构设计文档给出的ServiceConfig结构如下type ServiceConfig struct { NodeRateLimiter ratelimit.RateLimiterConfig json:nodeRateLimiter UserRateLimiter ratelimit.RateLimiterConfig json:userRateLimiter MaxTriggerRequestDurationMs int json:maxTriggerRequestDurationMs RetryConfig RetryConfig json:retryConfig CleanUpPeriodMs int json:cleanUpPeriodMs MetadataPullIntervalMs int json:metadataPullIntervalMs MetadataAggregationIntervalMs int json:metadataAggregationIntervalMs OutboundRequestCacheTTLMs int json:outboundRequestCacheTTLMs }从 当前源码的 ServiceConfig 结构看该结构已演进除保留文档中的时间类配置外还新增了NodeSendTimeoutMs单节点发送超时且被约束不得大于MaxTriggerRequestDurationMs、MetadataPullRequestTimeoutMs元数据拉取超时、JWTReplayPeriodMsJWT 重放保护窗口而节点/用户限流的参数nodeRateLimiter、userRateLimiter不再直接作为 JSON 字段而是从cresettings.Default中的统一配置如GatewayHTTPGlobalRate、GatewayHTTPPerNodeRate、PerWorkflow.HTTPTrigger.RateLimit构造限流器——即在 NewGatewayHandler 中分别创建全局节点限流器、每个 DON 成员一个的独立限流桶、用户限流器以及 mTLS 限流器/并发池。6.2 速率限制器配置type RateLimiterConfig struct { GlobalRPS float64 json:globalRPS // 全局每秒请求数 GlobalBurst int json:globalBurst // 全局突发容量 PerSenderRPS float64 json:perSenderRPS // 每发送方每秒请求数 PerSenderBurst int json:perSenderBurst // 每发送方突发容量 }对应源码中的分层限制节点侧全局桶 按节点独立桶双层检查在HandleNodeMessage开头执行用户侧按工作流属主限流在checkRateLimit中执行。6.3 重试配置type RetryConfig struct { InitialIntervalMs int json:initialIntervalMs // 初始重试间隔 MaxIntervalTimeMs int json:maxIntervalTimeMs // 最大重试间隔 Multiplier float64 json:multiplier // 退避乘数 }6.4 默认值一览以下默认值在设计文档与 WithDefaults 中一致源码还额外给出了文档未列出的两项默认值配置项默认值说明CleanUpPeriodMs60000010 分钟缓存与回调清理间隔MaxTriggerRequestDurationMs600001 分钟触发请求处理的最大时长MetadataPullIntervalMs600001 分钟从节点拉取元数据的间隔MetadataAggregationIntervalMs600001 分钟聚合已收集元数据的间隔InitialIntervalMs100初始重试间隔MaxIntervalTimeMs3000030 秒最大重试间隔Multiplier2.0指数退避乘数OutboundRequestCacheTTLMs60000010 分钟HTTP 响应缓存 TTLNodeSendTimeoutMs源码补充1000010 秒单个节点单次发送超时JWTReplayPeriodMs源码补充8640000024 小时JWT ID 防重放缓存时长6.5 配置示例{ nodeRateLimiter: { globalRPS: 100.0, globalBurst: 100, perSenderRPS: 10.0, perSenderBurst: 20 }, userRateLimiter: { globalRPS: 50.0, globalBurst: 50, perSenderRPS: 5.0, perSenderBurst: 10 }, maxTriggerRequestDurationMs: 60000, retryConfig: { initialIntervalMs: 100, maxIntervalTimeMs: 30000, multiplier: 2.0 }, cleanUpPeriodMs: 600000, metadataPullIntervalMs: 60000, metadataAggregationIntervalMs: 60000, outboundRequestCacheTTLMs: 600000 }该 JSON 由 NewGatewayHandler 反序列化并经WithDefaults补全默认值后生效。7. 安全特性7.1 认证与授权JWT 验证所有触发请求必须携带有效 JWT 令牌Authorize中先经utils.VerifyRequestJWT完成 ECDSA 签名校验再核对签名者公钥在该 workflow 的授权密钥集合内JWT 防重放jti被缓存默认 24 小时窗口重复使用同一 token 会被拒绝地址格式校验所有地址必须 0x 前缀且小写validateHexInput同时强制小写与最大长度工作流级授权每个 workflow 维护独立的授权密钥集合authorizedKeys表由 BFT 聚合保证集合本身的正确性。7.2 速率限制双层限流节点侧与用户侧使用独立限流器按发送方限制每个发送实体节点地址 / 工作流属主拥有独立限流桶全局限制系统级限流提供整体保护源码中节点侧为单节点桶 全局桶串联检查节点被限流时会记录IncrementCapabilityNodeThrottled指标。7.3 输入校验请求 ID 校验用户请求 ID 不得包含/防止与内部节点消息路由格式http_action/{workflowID}/{uuid}混淆造成恶意注入JSON 校验Input参数必须是合法 JSON 且为对象或数组工作流字段校验选择器各字段的长度与十六进制格式严格校验公钥校验授权密钥必须为标准 ECDSA 公钥格式42 字符小写十六进制。8. 错误处理8.1 错误类型认证错误无效 JWT 或未授权密钥Auth failure: ...校验错误畸形请求或非法参数限流错误超出速率限制rate limit exceeded超时错误请求处理超时网络错误HTTP 请求失败外部端点发送/读取错误响应中区分IsExternalEndpointError与IsValidationError内部错误系统或聚合失败。8.2 错误响应格式{ jsonrpc: 2.0, id: request-id, error: { code: -32602, message: Invalid request: Auth failure } }handleUserError将 JSON-RPC 标准WireError序列化后经 callback 回送用户并按错误严重度分级记录日志内部/限流/冲突类记 Error其余记 Warn。8.3 错误码表错误码说明-32700Parse error解析错误-32600Invalid request无效请求-32601Method not found方法不存在-32602Invalid params参数无效-32603Internal error内部错误-32000Rate limit exceeded超出速率限制-32001Conflict冲突请求 ID 重复其中-32001对应setupCallback中检测到的 in-flight 请求 ID 冲突同一 requestID 在回调表尚未清理前再次出现即返回冲突错误保证请求 ID 在途唯一。9. 实现细节请求 ID 与路由9.1 请求 ID 格式用户请求普通字符串标识符不得包含/节点消息methodName/workflowID/uuid或methodName/workflowID/workflowExecutionID/uuid方法路由网关按请求 ID 中的方法名前缀第一个/之前路由消息。9.2 工作流 ID 提取对 HTTP Action 请求工作流 ID 从请求路径中按methodName/workflowID/...模式提取即按/分割后的第二段。9.3 分片端点与 DON 矩阵从 shard_endpoints.go 可以确认本网关支持完整的 DON×shard 矩阵——buildShardEndpoints将多个 DON 的多个分片展开为扁平的shardEndpoint列表并构建节点地址到分片的路由表节点成员资格必须在各分片间互斥同一节点出现在两个分片会导致构造失败。每个shardEndpoint携带独立的连接管理器、成员列表与容错参数f。10. 测试与验证该模块具备完整的单元与集成测试覆盖包括多分片限流器构造、触发请求重试、BFT 聚合与元数据同步等场景测试文件与源文件一一对应http_handler_test.go覆盖NewGatewayHandler配置解析、DON×shard 矩阵展开及限流器创建等http_trigger_handler_test.go触发请求的校验、鉴权、聚合与重试链路response_cache_test.go缓存命中/过期/singleflight 去重行为workflow_metadata_handler_test.gopush/pull 同步与冲突去重聚合器测试位于 core/services/gateway/common/aggregation/。常用测试命令# 运行全部测试 go test ./... # 带覆盖率运行 go test ./... -coverpkg./... -coverprofilecoverage.txt # 竞态检测 GORACElog_path$PWD/race go test -race ./...小结HTTP Handlers V2 是 CRE 工作流与外部世界交互的枢纽出站 HTTP Action 以缓存 限流 mTLS三件套保障外部端点调用的效率与安全入站 HTTP Trigger 以JWT 鉴权 元数据 BFT 聚合 2f1 响应共识 指数退避重试四层机制在多分片 DON 环境下实现可验证、容错的触发执行链路。所有行为参数均可通过ServiceConfig按第 6 节的规格调整默认值在零配置下即形成一套安全的基线。若需进一步深入可从 handler 接口定义 与 网关处理器工厂 入手了解该模块在整体网关服务中的装配位置。【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考