Rivet Actors Rust SDK 模型解析RunnerConfigsServerlessHealthCheckResponseOneOf 与服务端健康检查响应【免费下载链接】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 Actorsstateful workloads 的构建原语面向 AI Agent、协作应用与持久化执行场景Rust SDK 中的一个具体 API 模型——RunnerConfigsServerlessHealthCheckResponseOneOf以及它所隶属的 Serverless 健康检查响应RunnerConfigsServerlessHealthCheckResponse枚举族与POST /runner-configs/serverless-health-check端点。读完本文你将掌握该响应模型的 Success / Failure 双变体结构、字段含义、序列化行为、对应端点的请求参数与鉴权方式并能结合仓库源码理解服务端健康检查的完整调用链。一、模型定位健康检查响应的“成功”变体RunnerConfigsServerlessHealthCheckResponseOneOf是自动生成的 OpenAPI 模型文档生成于rivet-api-publicOpenAPI 文档 2.3.14 版本对应 Rust SDK 源码 runner_configs_serverless_health_check_response_one_of.rs 中定义的 struct。其属性结构如下继承自原模型文档NameTypeDescriptionNotessuccessmodels::RunnerConfigsServerlessHealthCheckResponseOneOfSuccess健康检查成功结果必填在 Rust 源码中该结构通过serde的#[serde(rename success)]将 JSON 字段名success映射到同名字段#[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)] pub struct RunnerConfigsServerlessHealthCheckResponseOneOf { #[serde(rename success)] pub success: Boxmodels::RunnerConfigsServerlessHealthCheckResponseOneOfSuccess, } impl RunnerConfigsServerlessHealthCheckResponseOneOf { pub fn new(success: models::RunnerConfigsServerlessHealthCheckResponseOneOfSuccess) - RunnerConfigsServerlessHealthCheckResponseOneOf { RunnerConfigsServerlessHealthCheckResponseOneOf { success: Box::new(success), } } }其中RunnerConfigsServerlessHealthCheckResponseOneOfSuccess见模型文档与源码是成功时携带的具体负载只有一个字段NameTypeDescriptionNotesversionString运行时的版本标识必填也就是说健康检查成功后服务端返回的是运行目标的版本字符串。这在实践中通常用于客户端校验目标 Serverless Runner 是否运行在预期的 runtime 版本上从而决定是否允许注册 / 是否继续后续配置流程。二、响应枚举Success 与 Failure 双变体单独看OneOf变体只是响应枚举的一半。完整的响应类型是 RunnerConfigsServerlessHealthCheckResponse它是一个包含两个变体的枚举NameDescriptionRunnerConfigsServerlessHealthCheckResponseOneOf成功变体successRunnerConfigsServerlessHealthCheckResponseOneOf1失败变体failure对应源码 runner_configs_serverless_health_check_response.rs#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(untagged)] pub enum RunnerConfigsServerlessHealthCheckResponse { RunnerConfigsServerlessHealthCheckResponseOneOf( Boxmodels::RunnerConfigsServerlessHealthCheckResponseOneOf), RunnerConfigsServerlessHealthCheckResponseOneOf1( Boxmodels::RunnerConfigsServerlessHealthCheckResponseOneOf1), } impl Default for RunnerConfigsServerlessHealthCheckResponse { fn default() - Self { Self::RunnerConfigsServerlessHealthCheckResponseOneOf(Default::default()) } }这里有两个关键实现细节值得注意#[serde(untagged)]反序列化枚举不依赖外部type/kind标签而是根据响应 JSON 实际含有的字段自动匹配变体——若载荷包含success字段则解析为OneOf包含failure字段则解析为OneOf1。Default实现默认值是Success变体便于客户端在不关心具体结果时安全地构造默认实例。失败变体RunnerConfigsServerlessHealthCheckResponseOneOf1见模型文档的属性为NameTypeDescriptionNotesfailuremodels::RunnerConfigsServerlessHealthCheckResponseOneOf1Failure健康检查失败详情必填而OneOf1Failure见模型文档进一步封装了错误对象NameTypeDescriptionNoteserrormodels::RunnerConfigsServerlessMetadataError错误信封error envelope必填ServerlessMetadataErrorEnvelope来自pegboard::ops::serverless_metadata::fetch在 utils.rs 中 re-export用于承载元数据抓取失败时的错误信息。三、所属端点POST /runner-configs/serverless-health-check该响应类型是 Serverless 健康检查端点的返回值。端点定义见 RunnerConfigsServerlessHealthCheckApi.mdMethodHTTP requestDescriptionrunner_configs_serverless_health_checkPOST/runner-configs/serverless-health-check校验 Serverless Runner 配置对应的元数据可达性与健康状态请求参数NameTypeDescriptionRequiredNotesnamespaceString命名空间标识是作为 query 参数传递runner_configs_serverless_health_check_requestRunnerConfigsServerlessHealthCheckRequest健康检查请求体是JSON body请求体RunnerConfigsServerlessHealthCheckRequest在服务端定义serverless_health_check.rs中包含两个字段#[derive(Deserialize, Serialize, ToSchema)] #[serde(deny_unknown_fields)] #[schema(as RunnerConfigsServerlessHealthCheckRequest)] pub struct ServerlessHealthCheckRequest { pub url: String, #[serde(default)] pub headers: HashMapString, String, }url目标 Serverless Runner 的元数据端点地址必填headers抓取元数据时附加的 HTTP 请求头可省略#[serde(default)]使其缺省时为空 Map。注意服务端对请求体启用了#[serde(deny_unknown_fields)]即未知字段会导致反序列化失败客户端应严格按契约发送字段。鉴权与内容类型Authorizationbearer_authBearer Token 鉴权Content-Typeapplication/jsonAcceptapplication/json。四、响应 JSON 形态示例结合前文枚举与字段定义可以给出两种典型的响应形态。健康检查成功version字段来自目标 Runner 的运行时版本{ success: { version: 1.0.0 } }健康检查失败error携带元数据抓取错误信封{ failure: { error: { message: failed to fetch serverless metadata } } }五、服务端实现从 HTTP 处理器到 pegboard 元数据抓取在仓库服务端该端点由 engine/packages/api-public/src/runner_configs/serverless_health_check.rs 实现路由注册于 router.rsaxum::routing::post(...)路径/runner-configs/serverless-health-check。核心处理逻辑serverless_health_check_inner的调用链可以概括为鉴权ctx.auth().await?未通过鉴权直接返回ApiError解析入参解构ServerlessHealthCheckRequest { url, headers }抓取元数据调用fetch_serverless_metadata(ctx, url, headers)实现在 utils.rs该函数通过ctx.op(pegboard::ops::serverless_metadata::fetch::Input { url, headers })下发到 pegboard 层执行结果分派抓取成功返回ServerlessHealthCheckResponse::Success { version: metadata.version }抓取失败返回ServerlessHealthCheckResponse::Failure { error: error.into() }。抓取成功后返回的ServerlessMetadata结构utils.rs包含更多信息但健康检查响应只暴露其中version字段pub struct ServerlessMetadata { pub runtime: String, pub version: String, pub actor_names: HashMapString, serde_json::Value, pub envoy_version: Optionu32, }值得注意的是actor_names会从 pegboard 的输出Vec{ name, metadata }转换为HashMap形式envoy_version为可选项——这些字段在健康检查场景中并不对外返回但同一fetch_serverless_metadata底层操作也被refresh_runner_config_metadatautils.rs复用用于将 actor 名称与元数据落库刷新。由此可以推断该端点本质上是对“Serverless Runner 元数据可达性”的轻量探针失败时统一收敛为ServerlessMetadataErrorEnvelope错误信封避免把底层错误类型直接泄漏到公共 API 契约中。六、Rust SDK 客户端调用方式SDK 侧生成的异步客户端函数位于 runner_configs_serverless_health_check_api.rspub async fn runner_configs_serverless_health_check( configuration: configuration::Configuration, namespace: str, runner_configs_serverless_health_check_request: models::RunnerConfigsServerlessHealthCheckRequest, ) - Resultmodels::RunnerConfigsServerlessHealthCheckResponse, ErrorRunnerConfigsServerlessHealthCheckError客户端实现的关键细节请求 URL 为{base_path}/runner-configs/serverless-health-checkbase_path默认http://localhost可通过Configuration覆盖namespace作为 query 参数拼接配置了bearer_access_token时会自动附加 Bearer 鉴权头请求体通过req_builder.json(...)序列化发送响应按Content-Type分支处理仅application/json会被反序列化为RunnerConfigsServerlessHealthCheckResponsetext/plain与未知类型会返回类型转换错误非 2xx 响应统一封装为Error::ResponseError错误实体类型为RunnerConfigsServerlessHealthCheckErroruntagged可承载任意serde_json::Value。调用示例伪代码形态基于 SDK 签名use rivet_api_full::{apis::runner_configs_serverless_health_check_api, models, Configuration}; let config Configuration::new(); // 可在此设置 base_path 与 bearer_access_token let request models::RunnerConfigsServerlessHealthCheckRequest { url: https://runner.example.com/metadata.to_string(), headers: Default::default(), }; let resp runner_configs_serverless_health_check_api::runner_configs_serverless_health_check( config, my-namespace, request, ).await?; match resp { models::RunnerConfigsServerlessHealthCheckResponse::RunnerConfigsServerlessHealthCheckResponseOneOf(ok) { println!(healthy, version {}, ok.success.version); } models::RunnerConfigsServerlessHealthCheckResponse::RunnerConfigsServerlessHealthCheckResponseOneOf1(err) { eprintln!(unhealthy: {:?}, err.failure.error); } }七、相关文档与源码索引模型文档本主题家族RunnerConfigsServerlessHealthCheckResponseOneOf.md指定文档RunnerConfigsServerlessHealthCheckResponse.mdRunnerConfigsServerlessHealthCheckResponseOneOfSuccess.mdRunnerConfigsServerlessHealthCheckResponseOneOf1.mdRunnerConfigsServerlessHealthCheckResponseOneOf1Failure.md端点文档RunnerConfigsServerlessHealthCheckApi.mdRust SDK 源码runner_configs_serverless_health_check_response_one_of.rsrunner_configs_serverless_health_check_response.rsrunner_configs_serverless_health_check_api.rs服务端实现serverless_health_check.rsutils.rsrouter.rs结语RunnerConfigsServerlessHealthCheckResponseOneOf虽然只是一个字段极少的模型变体但它是 Rivet Actors 公共 API 中 Serverless 健康检查响应契约的“成功分支”。理解它与OneOf1失败分支如何通过#[serde(untagged)]构成双变体枚举、理解其底层由 pegboard 元数据抓取操作支撑的调用链可以帮助使用 Rust SDK 的开发者正确解析健康检查结果、区分成功与失败路径并在接入自定义 Serverless Runner 时准确对齐服务端的行为约定。【免费下载链接】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），仅供参考