Rivet Actors 的 RunnerConfigsUpsert API 与 RunnerConfigsUpsertResponse 模型解析

Rivet Actors 的 RunnerConfigsUpsert API 与 RunnerConfigsUpsertResponse 模型解析【免费下载链接】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 Actors 公开 API 中RunnerConfigsUpsert接口及其响应模型RunnerConfigsUpsertResponse展开讲解如何通过PUT /runner-configs/{runner_name}批量更新一个 Runner计算节点在多个数据中心下的运行配置以及服务端如何以endpoint_config_changed布尔值反馈「端点配置是否发生变化」。读完本文你将掌握该模型的字段语义、请求/响应上下文、Rust SDK 的调用方式以及服务端多数据中心扇出fan-out处理的底层实现原理。RunnerConfigsUpsertResponse一个字段的响应模型RunnerConfigsUpsertResponse是runner_configs_upsert接口的唯一响应类型定义于 engine/sdks/rust/api-full/rust/src/models/runner_configs_upsert_response.rs属于rivet-api-publicOpenAPI 文档版本 2.3.14生成的 Rust SDK 模型。其结构非常精简仅包含一个字段属性名类型描述endpoint_config_changedbool指示本次 upsert 是否导致该 Runner 的端点endpoint配置发生变化对应的 Rust 模型定义如下#[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)] pub struct RunnerConfigsUpsertResponse { #[serde(rename endpoint_config_changed)] pub endpoint_config_changed: bool, } impl RunnerConfigsUpsertResponse { pub fn new(endpoint_config_changed: bool) - RunnerConfigsUpsertResponse { RunnerConfigsUpsertResponse { endpoint_config_changed, } } }由于模型派生自serde::Serialize/serde::Deserialize它在 HTTP 响应中对应一段极简 JSON{ endpoint_config_changed: true }endpoint_config_changed 的语义该字段为true时表示本次配置写入改变了该 Runner 的端点配置例如监听地址、代理端点、健康检查相关的配置发生变更下游系统通常需要据此重新感知/刷新端点信息为false时表示配置已成功落库但端点配置没有实质变化。从服务端实现看这个布尔值并非简单的「本次请求是否成功」而是所有被更新的数据中心各自返回值取「逻辑或」后的聚合结果详见下文「服务端实现原理」一节因此可以理解为「整个集群范围内端点配置是否发生过变更」。完整的接口上下文PUT /runner-configs/{runner_name}RunnerConfigsUpsertResponse只有放入runner_configs_upsert接口中才有意义。该接口的完整定义见 engine/sdks/rust/api-full/rust/docs/RunnerConfigsUpsertApi.md。方法签名与端点项目值HTTP 方法PUT路径/runner-configs/{runner_name}认证方式bearer_authBearer Token请求 Content-Typeapplication/json响应 Acceptapplication/jsonSDK 中的函数签名为pub async fn runner_configs_upsert( configuration: configuration::Configuration, runner_name: str, namespace: str, runner_configs_upsert_request_body: models::RunnerConfigsUpsertRequestBody, ) - Resultmodels::RunnerConfigsUpsertResponse, ErrorRunnerConfigsUpsertError请求参数参数类型位置必填说明runner_nameStringPath是目标 Runner 的名称拼接在 URL 路径中namespaceStringQuery是Runner 所属的命名空间namespace作为查询参数传递runner_configs_upsert_request_bodyRunnerConfigsUpsertRequestBodyBody是JSON 请求体包含按数据中心组织的 Runner 配置从 SDK 客户端源码 engine/sdks/rust/api-full/rust/src/apis/runner_configs_upsert_api.rs 可以看到实际的请求组装逻辑let uri_str format!({}/runner-configs/{runner_name}, configuration.base_path, runner_namecrate::apis::urlencode(p_runner_name)); let mut req_builder configuration.client.request(reqwest::Method::PUT, uri_str); req_builder req_builder.query([(namespace, p_namespace.to_string())]); if let Some(ref token) configuration.bearer_access_token { req_builder req_builder.bearer_auth(token.to_owned()); }; req_builder req_builder.json(p_runner_configs_upsert_request_body);即runner_name经 URL 编码后拼入路径namespace以查询参数附加Bearer Token 作为认证头请求体以 JSON 序列化发送。当服务端返回 2xx 时响应体 JSON 会被反序列化为RunnerConfigsUpsertResponse非 2xx 时则包装为RunnerConfigsUpsertErrorUnknownValue兜底。请求体RunnerConfigsUpsertRequestBody请求体模型定义于 engine/sdks/rust/api-full/rust/docs/RunnerConfigsUpsertRequestBody.md对应源码 engine/sdks/rust/api-full/rust/src/models/runner_configs_upsert_request_body.rs属性名类型描述datacentersHashMapString, RunnerConfig以数据中心名称为键、以该数据中心的 Runner 配置为值的映射pub struct RunnerConfigsUpsertRequestBody { #[serde(rename datacenters)] pub datacenters: std::collections::HashMapString, models::RunnerConfig, }RunnerConfig 配置结构映射中的值类型RunnerConfig见 engine/sdks/rust/api-full/rust/src/models/runner_config.rs包含属性名类型描述normalRunnerConfigKindOneOfNormal普通常驻运行模式配置serverlessRunnerConfigKindOneOf1ServerlessServerless 运行模式配置drain_on_version_upgradeOptionbool已废弃Deprecated版本升级时是否排空drain该 RunnermetadataOptionserde_json::Value附加元数据任意 JSON因此一个典型请求体形如{ datacenters: { dc-01: { normal: { ...: ... }, serverless: { ...: ... }, drain_on_version_upgrade: false, metadata: { region: us-east } } } }提示normal与serverless分别对应RunnerConfigKind的两种变体runner_config_kind_one_of_normal.rs、runner_config_kind_one_of1_serverless.rs 等派生模型具体字段请以对应模型文档为准二者为枚举变体配置时按运行模式二选一填充。服务端实现原理多数据中心扇出与「任一变更」响应模型中的endpoint_config_changed之所以能反映整个集群的变更状态关键在于服务端 handler 的实现。公开 API 的服务端实现在 engine/packages/api-public/src/runner_configs/upsert.rs其处理流程如下鉴权ctx.auth().await?校验 Bearer Token数据中心对齐遍历拓扑中配置的所有数据中心ctx.config().topology().datacenters按名称从请求体的datacenters映射中取出对应的RunnerConfig未知数据中心校验若请求体中还残留未匹配的数据中心键直接返回Datacenter::NotFound错误保证只允许写入真实存在的数据中心逐数据中心扇出对每个数据中心并行buffer_unordered(16)执行若该数据中心提供了配置则通过本地 peer 层rivet_api_peer::runner_configs::upsert或远程数据中心转发request_remote_datacenter执行 upsert收集返回值endpoint_config_changed若该数据中心未提供配置映射中缺失则视为「删除该数据中心的 Runner 配置」对本地或远端数据中心执行DELETE /runner-configs/{runner_name}返回值记为false聚合结果所有数据中心的结果取.any(...)即「只要任意一个数据中心报告端点配置发生变更endpoint_config_changed即为true」——这正是响应字段的语义来源缓存预热解析命名空间并调用list_runner_config_enabled_dcs为启用了该 Runner 配置的数据中心预热 epoxy 缓存。一个值得注意的健壮性细节代码注释明确说明「当任一 peer 请求失败时必须整体报错must error when any peer request fails, not all」因此部分成功不会被静默吞掉任何数据中心的写入失败都会导致整个请求返回错误而不是返回一个误导性的成功响应。从这一实现可以推断endpoint_config_changedtrue的典型业务含义是「有数据中心至少一个的端点配置确实被改写」下游例如网关、调度器、控制面可据此触发端点信息的重新下发而纯元数据更新如仅修改metadata或配置删除路径则可能返回false。Rust SDK 调用示例结合 engine/sdks/rust/api-full/rust/src/apis/runner_configs_upsert_api.rs 与模型构造函数一次完整的调用如下示意use rivet_api_public::apis::{configuration::Configuration, runner_configs_upsert_api}; use rivet_api_public::models::{ RunnerConfig, RunnerConfigsUpsertRequestBody, RunnerConfigsUpsertResponse, }; #[tokio::main] async fn main() - Result(), Boxdyn std::error::Error { let mut config Configuration::new(); config.bearer_access_token Some(YOUR_BEARER_TOKEN.to_string()); config.base_path https://your-region.api.rivet.run.to_string(); // 构造请求体以数据中心名称为键的 RunnerConfig 映射 let body RunnerConfigsUpsertRequestBody::new( std::collections::HashMap::from([ ( dc-01.to_string(), RunnerConfig::new( /* normal: */ todo!(normal 模式配置), /* serverless: */ todo!(serverless 模式配置), ), ), ]), ); // 调用接口返回值即 RunnerConfigsUpsertResponse let resp: RunnerConfigsUpsertResponse runner_configs_upsert_api::runner_configs_upsert(config, my-runner, default, body) .await?; if resp.endpoint_config_changed { println!(endpoint 配置已变更需刷新端点信息); } Ok(()) }几点使用要点认证接口使用bearer_auth需要先在Configuration中设置bearer_access_tokenbase_pathSDK 注释中标明所有 URI 相对http://localhost实际部署时请替换为你的控制面/API 网关地址runner_name 与 namespace 组合定位 Runner同一个runner_name可在不同 namespace 下独立存在更新时两者缺一不可请求体是「按数据中心的全量对齐」语义请求体中列出的数据中心会被 upsert未列出的数据中心会被删除配置因此调用前应确保datacenters映射包含所有期望保留配置的数据中心。相关文件索引模型文档RunnerConfigsUpsertResponse.md、RunnerConfigsUpsertRequestBody.md、RunnerConfigsUpsertApi.mdSDK 源码runner_configs_upsert_response.rs、runner_configs_upsert_request_body.rs、runner_configs_upsert_api.rs服务端实现api-public/src/runner_configs/upsert.rs配套的删除/列举/刷新元数据等操作位于 api-public/src/runner_configs/Peer 层转发与错误定义api-peer/src/runner_configs.rs 以及 api-peer/src/router.rsSDK 总览api-full/rust/README.md小结RunnerConfigsUpsertResponse虽然只有一个endpoint_config_changed字段但它是 Rivet Actors 控制面「多数据中心 Runner 配置同步」能力的收口信号服务端将其作为所有数据中心 upsert/删除结果的聚合布尔值返回客户端只需读取一个字段即可判断端点配置是否需要在集群范围内刷新。理解这一点是把runner_configs_upsert正确接入自动化部署、配置下发与端点发现流程的关键。【免费下载链接】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），仅供参考