Rivet Serverless 健康检查失败响应模型解析RunnerConfigsServerlessHealthCheckResponseOneOf1Failure 与错误信封【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors本篇文章聚焦 Rivet 引擎中 serverless 型 runner 配置的健康检查接口深入解析其失败分支的响应模型RunnerConfigsServerlessHealthCheckResponseOneOf1Failure。文章从 Rust SDK 自动生成的模型定义出发串联服务端 serverless_health_check.rs 的处理逻辑与 pegboard 层 serverless_metadata/fetch.rs 的元数据抓取实现完整呈现失败响应的字段结构、错误信封、各类错误kind判别方式及对应的 Rust 代码用法帮助开发者准确解析健康检查失败原因并据此排查部署问题。一、模型定位健康检查响应的失败分支在 Rivet 的 runner 配置体系中serverless 型 runner 需要通过POST /runner-configs/serverless-health-check接口验证一个 serverless 端点的元数据是否符合要求。该接口的响应被定义为二选一的枚举变体语义RunnerConfigsServerlessHealthCheckResponseOneOf健康检查成功携带version字段RunnerConfigsServerlessHealthCheckResponseOneOf1健康检查失败携带error字段其中第二个变体即本文的主角是失败分支RunnerConfigsServerlessHealthCheckResponseOneOf1内部只包含一个failure属性其类型正是RunnerConfigsServerlessHealthCheckResponseOneOf1Failure。相关枚举定义可查看 RunnerConfigsServerlessHealthCheckResponse.md两个变体分别对应 RunnerConfigsServerlessHealthCheckResponseOneOf.md 与 RunnerConfigsServerlessHealthCheckResponseOneOf1.md。二、Failure 模型的属性结构RunnerConfigsServerlessHealthCheckResponseOneOf1Failure的字段定义如下名称类型说明errormodels::RunnerConfigsServerlessMetadataError必填字段承载健康检查失败的具体错误信息该模型只有一个字段error且为必填。只要健康检查进入失败分支响应体中必然携带一个结构完整的RunnerConfigsServerlessMetadataError错误对象不存在空响应或缺失字段的情况。这一约束在 SDK 生成代码中有直接体现——runner_configs_serverless_health_check_response_one_of_1_failure.rs 中error被声明为Boxmodels::RunnerConfigsServerlessMetadataError序列化时使用#[serde(rename error)]反序列化时不带Option、无默认值缺失即报错。同时new构造函数强制要求调用方传入RunnerConfigsServerlessMetadataError实例从类型层面杜绝了构造不完整的失败响应的可能性pub fn new(error: models::RunnerConfigsServerlessMetadataError) - RunnerConfigsServerlessHealthCheckResponseOneOf1Failure { RunnerConfigsServerlessHealthCheckResponseOneOf1Failure { error: Box::new(error), } }三、错误信封message / details / metadata 三段式结构error字段引用的RunnerConfigsServerlessMetadataError是服务端暴露给 API 客户端的统一错误信封其属性如下名称类型必填说明messageString是人类可读的错误摘要detailsOptionString否可选的补充细节例如被拦截原因metadataOptionserde_json::Value否机器可读的结构化信息metadata.kind用于判别具体错误变体完整字段文档见 RunnerConfigsServerlessMetadataError.md。其生成代码位于 runner_configs_serverless_metadata_error.rs源码注释明确指出该类型的用途无论内部产生哪种ServerlessMetadataError变体都以稳定的{message, details, metadata}形状暴露给 API 客户端metadata.kind负责判别变体各变体专属字段与kind并列存放。这个稳定信封设计源自服务端 serverless_metadata/fetch.rs 中的ServerlessMetadataErrorEnvelopepub struct ServerlessMetadataErrorEnvelope { pub message: String, #[serde(default, skip_serializing_if Option::is_none)] pub details: OptionString, #[serde(default)] pub metadata: serde_json::Value, }三个字段中只有message是必需的details缺省时不输出skip_serializing_ifmetadata缺省时为空对象。这样客户端只需要解析一份固定结构的 JSON即可覆盖全部失败场景无需针对每种错误分别建模。四、错误变体全表metadata.kind 判别依据健康检查最终由 pegboard 的pegboard_serverless_metadata_fetch操作执行其内部ServerlessMetadataError枚举覆盖了从请求发起到响应校验的完整失败链见 serverless_metadata/fetch.rs。每个变体经From转换后生成对应的信封下表汇总了各变体的kind、message与metadata中携带的附加字段metadata.kindmessage内容detailsmetadata附加字段invalid_requestinvalid serverless metadata request无无destination_blockedserverless endpoint is not an allowed destination被拦截的原因reasonrequest_failedfailed to reach serverless endpoint无无request_timed_outserverless metadata request timed out无无non_success_statusserverless metadata request returned status {code}无status_code、bodyinvalid_response_jsonserverless metadata response is not valid JSON无body、parse_errorinvalid_response_schemaserverless runtime {runtime} version {version} is unsupported无runtime、versioninvalid_envoy_protocol_versionenvoy protocol version {v} is not supported (max supported: {max})无envoy_protocol_version、max_supported_envoy_protocol_version转换实现位于 serverless_metadata/fetch.rs。可以看出metadata.kind是结构化的判别键客户端应优先读取它来区分失败类别而不是依赖对message文本的字符串匹配——文本内容在 SDK 迭代中可能变化而kind是稳定的契约。4.1 各失败类别的触发场景结合抓取操作的实际代码路径可推断各kind的触发条件invalid_requestURL 为空、URL 无法解析或请求头名称/值不是合法的 HTTP 头fetch.rs。destination_blocked目标 URL 未通过 outbound 策略检查或 DNS 解析出被禁止的地址。抓取操作通过rivet_pools::reqwest::outbound_policy做前置校验并对运行期错误二次调用rivet_outbound_guard::block_reason兜底fetch.rs。request_failed/request_timed_outHTTP 请求本身失败或超过 10 秒超时REQUEST_TIMEOUT常量见 fetch.rs。non_success_status目标端点返回非 2xx 状态码body为响应体截断后的内容最大 1024 字符见 fetch.rs。invalid_response_json响应体无法按ServerlessMetadataPayload反序列化。invalid_response_schema响应可解析但runtime ! rivetkit或version为空fetch.rs。invalid_envoy_protocol_versionenvoy_protocol_version小于 1 或超过引擎集群协商的最大版本上限取ctx.config().protocols().envoy.version()而非当前二进制编译版本避免旧 pod 无法与新版 runner 通信见 fetch.rs。五、服务端如何组装失败响应RunnerConfigsServerlessHealthCheckResponseOneOf1Failure对应的服务端逻辑在 serverless_health_check.rs 中定义#[derive(Deserialize, Serialize, ToSchema)] #[serde(rename_all snake_case)] pub enum ServerlessHealthCheckResponse { Success { version: String }, Failure { error: ServerlessMetadataErrorEnvelope }, }处理流程serverless_health_check_inner非常简单先进行身份认证ctx.auth()然后调用fetch_serverless_metadata抓取目标端点的元数据抓取成功返回Success { version }即 RunnerConfigsServerlessHealthCheckResponseOneOfSuccess 模型version是 runner 的元数据版本抓取失败返回Failure { error }即本文主题模型error由ServerlessMetadataError经From自动转换为信封error.into()。值得注意的是健康检查失败并不会导致 HTTP 错误状态码——只要请求与认证本身成功服务端始终返回 200失败信息统一放在Failure分支体内。客户端需要先判别是Success变体还是Failure变体再决定读取version还是解析error。六、Rust SDK 实战请求与失败解析健康检查的完整调用链在 runner_configs_serverless_health_check_api.rs 中生成请求方法POST路径/runner-configs/serverless-health-checkQuery 参数namespace必填Rivet 中用于 ACL 区分请求体RunnerConfigsServerlessHealthCheckRequest包含必填的url与可选的headersHashMapString, String认证方式bearer_authBearer TokenContent-Type / Accept 均为application/jsonRust 侧的调用与匹配解析示例use rivet_api_full::apis::{configuration::Configuration, runner_configs_serverless_health_check_api}; use rivet_api_full::models::{RunnerConfigsServerlessHealthCheckRequest, RunnerConfigsServerlessHealthCheckResponse}; let config Configuration::new(your-bearer-token.to_string()); let req RunnerConfigsServerlessHealthCheckRequest::new( https://serverless.example.com.to_string(), ); let resp runner_configs_serverless_health_check_api::runner_configs_serverless_health_check( config, my-namespace, req, ) .await?; match resp { RunnerConfigsServerlessHealthCheckResponse::RunnerConfigsServerlessHealthCheckResponseOneOf(success) { println!(健康检查通过version {}, success.success.version); } RunnerConfigsServerlessHealthCheckResponse::RunnerConfigsServerlessHealthCheckResponseOneOf1(failure) { let err failure.failure.error; // 优先用 metadata.kind 做结构化判别 if let Some(metadata) err.metadata { if let Some(kind) metadata.get(kind).and_then(|v| v.as_str()) { println!(失败类别: {kind}); } } eprintln!(错误信息: {}, err.message); if let Some(details) err.details { eprintln!(补充细节: {details}); } } }七、跨 SDK 的对应类型该模型不只存在于 Rust SDK其他语言 SDK 也以对应命名生成TypeScriptRunnerConfigsServerlessHealthCheckResponseFailureFailure见 engine/sdks/typescript/api-full/src/api/types/RunnerConfigsServerlessHealthCheckResponseFailureFailure.ts其error对应RunnerConfigsServerlessMetadataErrorengine/sdks/typescript/api-full/src/api/types/RunnerConfigsServerlessMetadataError.ts。Go对应类型定义于 engine/sdks/go/api-full/types.go客户端方法在 engine/sdks/go/api-full/client/client.go 中。所有 SDK 的模型均由 OpenAPI 规范engine/artifacts/openapi.json统一生成字段结构与本文描述一致跨语言解析失败响应的方式完全相同。八、排查建议从 failure 到根因当收到Failure分支响应时建议按以下顺序排查读metadata.kind确定失败类别网络问题、被拦截、非 2xx、JSON 解析失败、协议版本不兼容等读message获取面向人的错误摘要如 serverless metadata request returned status 404按kind读取附加字段如non_success_status的status_code/body、destination_blocked的reason、invalid_envoy_protocol_version的版本号等核对抓取端约束目标地址必须通过引擎 outbound 策略、响应须在 10 秒内返回、响应体须符合ServerlessMetadataPayload结构runtime为rivetkit且version非空、envoy_protocol_version须在[1, max_supported]区间内。其中invalid_envoy_protocol_version对生产环境尤为关键上限是引擎集群协商出的协议版本若 runner 携带了较新的协议版本而集群中仍有旧 pod则该 runner 无法被调度服务健康检查会如实报错避免上线后出现版本不匹配的运行时故障。参考资料模型文档RunnerConfigsServerlessHealthCheckResponseOneOf1Failure.md、RunnerConfigsServerlessMetadataError.md、RunnerConfigsServerlessHealthCheckApi.mdRust 生成代码runner_configs_serverless_health_check_response_one_of_1_failure.rs、runner_configs_serverless_metadata_error.rs、runner_configs_serverless_health_check_api.rs服务端实现serverless_health_check.rs底层抓取与错误枚举serverless_metadata/fetch.rs【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考