Rivet RunnersApi 完全指南使用 Rust SDK 列出与管理 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本文围绕 Rivet Actors 仓库中 Rust SDK 自动生成的 RunnersApi 客户端文档展开系统讲解runners_listGET /runners与runners_list_namesGET /runners/names两个端点的完整使用方式。你将掌握如何通过 Rust SDK 查询命名空间下的 Runner计算实例列表、按名称或 ID 过滤、包含已停止实例、基于游标分页以及理解从 API 网关到 pegboard 底层键值存储的完整调用链路。什么是 Runner 与 RunnersApi在 Rivet Actors 体系中Runner 是承载 Actor 实例运行的计算载体。一个 Runner 拥有固定的资源槽位slot每个 Actor 实例会占据其中若干槽位remaining_slots与total_slots之间的差值即反映了该 Runner 当前的负载状况。RunnersApi 提供了对 Runner 进行只读查询的两个端点用于运维观测、调度分析和集群管理。RunnersApi 的全部方法如下所有 URI 均相对于http://localhost方法HTTP 请求说明runners_listGET/runners列出命名空间下的 Runner 列表runners_list_namesGET/runners/names列出命名空间下所有 Runner 的名称去重聚合从仓库结构看这两个端点存在两层 APIapi-publicengine/packages/api-public/src/runners.rs负责对客户端开放、认证并跨数据中心聚合api-peerengine/packages/api-peer/src/runners.rs则是单数据中心内部的 peer 接口。Rust SDK 客户端直连的是 public 层。在 Cargo 工程中接入 SDKRunnersApi 属于rivet-api-full这个 OpenAPI 生成的 Rust 客户端包API 版本 2.3.14源码位于 engine/sdks/rust/api-full/rust。接入方式是在Cargo.toml的[dependencies]中加入本地路径依赖[dependencies] rivet-api-full { path ./rivet-api-full } tokio { version 1, features [full] }初始化客户端需要构造Configuration。该结构体定义在 engine/sdks/rust/api-full/rust/src/apis/configuration.rs包含以下关键字段字段类型用途base_pathStringAPI 服务地址默认http://localhostuser_agentOptionString附加到请求的 User-Agent 头clientreqwest::ClientHTTP 客户端bearer_access_tokenOptionStringBearer 认证令牌示例use rivet_api_full::apis::{configuration::Configuration, runners_api}; #[tokio::main] async fn main() - Result(), Boxdyn std::error::Error { let configuration Configuration { base_path: https://api.example.com.to_string(), user_agent: Some(my-rivet-client/1.0.to_string()), client: reqwest::Client::new(), bearer_access_token: Some(YOUR_TOKEN.to_string()), ..Default::default() }; let response runners_api::runners_list(configuration, my-namespace, None, None, None, None, Some(10), None).await?; println!({:?}, response.runners); Ok(()) }认证方式两个端点都要求bearer_auth认证见文档中的 Authorization 一节。SDK 在发起请求时会自动读取configuration.bearer_access_token并附加Authorization: Bearer token头见 engine/sdks/rust/api-full/rust/src/apis/runners_api.rsif let Some(ref token) configuration.bearer_access_token { req_builder req_builder.bearer_auth(token.to_owned()); };服务端在 engine/packages/api-public/src/runners.rs 中通过ctx.auth().await?校验令牌。请求头约定Content-Type未定义GET 请求无请求体Acceptapplication/jsonSDK 按Accept: application/json发送请求收到响应后根据 content-type 反序列化application/json解析为对应模型text/plain或不支持的类型会返回显式错误见 runners_api.rs 中的错误处理逻辑。runners_list列出 Runner函数签名SDK 侧pub async fn runners_list( configuration: configuration::Configuration, namespace: str, name: Optionstr, runner_ids: Optionstr, runner_id: OptionVecString, include_stopped: Optionbool, limit: Optioni32, cursor: Optionstr, ) - Resultmodels::RunnersListResponse, ErrorRunnersListError参数说明服务端查询参数定义于 engine/packages/api-types/src/runners/list.rs 的ListQuery结构参数类型必填说明namespaceString是命名空间名称注意是全局可读的名称而非 IDnameOptionString否按 Runner 名称精确过滤runner_idsOptionString否已废弃。逗号分隔的 Runner ID 列表runner_idOptionVecString否按 Runner ID 过滤支持多个SDK 以multi风格重复runner_id查询参数发送include_stoppedOptionbool否是否包含已停止的 Runner默认falselimitOptioni32否返回条数上限服务端默认100cursorOptionString否分页游标取自上一页响应的pagination.cursor注意 SDK 实现细节runner_id参数使用 multi 收集方式每个 ID 单独作为一个runner_id查询参数发送runners_api.rsreq_builder match multi { multi req_builder.query(param_value.into_iter() .map(|p| (runner_id.to_owned(), p.to_string())) .collect::Vec_()), _ /* join with comma */, };两条查询路径从服务端实现engine/packages/api-peer/src/runners.rs可以清楚看到runners_list内部会根据是否提供了 ID 走两条完全不同的路径路径 A按 ID 精确查询当传入runner_id或已废弃的runner_ids时服务端直接把 ID 交给pegboard::ops::runner::get逐条拉取 Runner返回的pagination.cursor为None无分页语义。路径 B按条件列出否则调用pegboard::ops::runner::list_for_ns携带namespace_id、name、include_stopped、created_before由cursor解析而来与limit并基于最后一个 Runner 的create_ts生成下一页游标let cursor list_res.runners.last().map(|x| x.create_ts.to_string());使用示例let response runners_api::runners_list( configuration, my-namespace, // namespace 必填 Some(worker-us-1), // 按名称过滤可选 None, // runner_ids 已废弃传 None Some(vec![r_abc123.into()]), // 按 ID 过滤可选 Some(true), // 包含已停止的 Runner Some(50), // limit None, // cursor ).await?; for runner in response.runners { println!({}: slots {}/{} dc{}, runner.runner_id, runner.remaining_slots, runner.total_slots, runner.datacenter); } // 下一页 if let Some(cursor) response.pagination.cursor { let next runners_api::runners_list( configuration, my-namespace, None, None, None, Some(true), Some(50), Some(cursor) ).await?; }返回值RunnersListResponse响应模型见 engine/sdks/rust/api-full/rust/docs/RunnersListResponse.md字段类型说明paginationmodels::Pagination游标分页信息runnersVecmodels::RunnerRunner 列表Pagination结构极为精简仅包含一个可选的cursor: OptionString定义见 engine/packages/api-types/src/pagination.rs。Runner模型的字段见 engine/sdks/rust/api-full/rust/docs/Runner.md 与 engine/packages/types/src/runners.rs字段类型说明runner_idStringRunner 唯一 IDnamespace_idString所属命名空间 IDdatacenterString所在数据中心nameStringRunner 名称keyStringRunner 密钥versioni32版本号total_slots/remaining_slotsi32总槽位 / 剩余槽位create_tsi64创建时间戳毫秒drain_tsOptioni64排空drain时间戳可选stop_tsOptioni64停止时间戳可选last_ping_tsi64最近一次心跳时间戳last_connected_tsOptioni64最近连接时间戳可选last_rtti32最近一次往返时延metadataOptionserde_json::Value附加元数据可选runners_list_names列出 Runner 名称当只需要名称清单例如构建一个名称选择器或做存在性检查时使用该端点可以显著降低数据传输量。函数签名SDK 侧pub async fn runners_list_names( configuration: configuration::Configuration, namespace: str, limit: Optioni32, cursor: Optionstr, ) - Resultmodels::RunnersListNamesResponse, ErrorRunnersListNamesError参数说明服务端参数定义于 engine/packages/api-types/src/runners/list_names.rs 的ListNamesQuery参数类型必填说明namespaceString是命名空间名称limitOptioni32否返回名称数量上限服务端默认100cursorOptionString否分页游标注意与runners_list不同该端点没有name、runner_id等过滤参数只支持分页游标遍历。Datacenter Round Trips2 次往返文档在该端点下方标注了关键的实现提示源码同样体现在 engine/packages/api-public/src/runners.rs2 round trips: - GET /runners/names (fanout) - [api-peer] namespace::ops::resolve_for_name_global这意味着一次runners_list_names调用实际包含两次数据中心往返public 层通过fanout_to_datacenters将查询**扇出fanout**到所有数据中心各自的 peer 接口GET /runners/names每个数据中心内peer 处理器先调用namespace::ops::resolve_for_name_global将命名空间名称解析为namespace_id见 engine/packages/api-peer/src/runners.rs再执行名称扫描。使用示例let response runners_api::runners_list_names( configuration, my-namespace, Some(100), // limit None, // cursor ).await?; for name in response.names { println!(runner name: {name}); }返回值RunnersListNamesResponse响应模型见 engine/sdks/rust/api-full/rust/docs/RunnersListNamesResponse.md字段类型说明namesVecStringRunner 名称列表paginationPagination分页游标public 层在聚合时会先对各数据中心返回的名称做去重IndexSet随后排序并截断到limit最后以最后一个名称作为下一页游标见 api-public/src/runners.rslet mut all_names fanout_to_datacenters::_, _, _, _, _, IndexSetString( ctx, /runners/names, query, |ctx, query| async move { rivet_api_peer::runners::list_names(ctx, (), query).await }, |_, res, agg| agg.extend(res.names), ).await?.into_iter().take(limit).collect::IndexSet_(); all_names.sort(); let cursor all_names.last().map(|x: String| x.to_string());服务端与底层的完整调用链把两个端点串联起来一次查询在仓库中的完整调用链为Rust SDK (runners_api.rs) │ GET /runners 或 /runners/namesBearer 认证 ▼ api-public 处理器 (engine/packages/api-public/src/runners.rs) │ fanout_to_datacenters扇出到所有数据中心 ▼ api-peer 处理器 (engine/packages/api-peer/src/runners.rs) │ namespace::ops::resolve_for_name_global → namespace_id ▼ pegboard operation (engine/packages/pegboard/src/ops/runner/) ├── list_for_ns.rs —— 列表扫描 get_inner 回填 └── list_names.rs —— 名称键范围扫描 ▼ universaldb 事务Snapshot 隔离级别 └── 键空间keys::ns::ActiveRunnerKey / AllRunnerKey / RunnerNameKey ...pegboard 列表扫描实现pegboard_runner_list_for_nsengine/packages/pegboard/src/ops/runner/list_for_ns.rs按四种组合分支扫描键空间每种分支都对应独立的索引键类型条件使用的键类型按名称 包含停止AllRunnerByNameKey按名称 仅活跃ActiveRunnerByNameKey无名称 包含停止AllRunnerKey无名称 仅活跃ActiveRunnerKey所有扫描都以Snapshot快照隔离级别执行——代码注释明确说明“列表时旧数据无关紧要无需 Serializable”。扫描方向为reverse: true配合created_before由游标解析实现基于创建时间的倒序分页取到 runner_id 后通过super::get::get_inner以buffered(512)并发回填完整的 Runner 数据。pegboard 名称扫描实现pegboard_runner_list_namesengine/packages/pegboard/src/ops/runner/list_names.rs基于RunnerNameKey做正向范围扫描若提供了after_name游标则以end_of_key_range从该名称之后开始StreamingMode::Exactlimit精确控制返回条数。同样使用 Snapshot 隔离级别注释说明这是为了避免与新名称插入产生争用not Serializable to prevent contention with inserting new names。键空间结构这些索引键定义于 engine/packages/pegboard/src/keys/ns.rsActiveRunnerKey(NAMESPACE, namespace_id, RUNNER, ACTIVE, create_ts, runner_id)—— 活跃 Runner 主索引AllRunnerKey(NAMESPACE, namespace_id, RUNNER, ALL, create_ts, runner_id)—— 全部 Runner含已停止RunnerNameKey(NAMESPACE, namespace_id, RUNNER, NAME, name)—— 名称去重索引值为空仅作存在性标记。键的前缀 tuple 结构意味着同一命名空间、同一前缀下的记录在存储中天然按create_ts排序这正是游标分页可以直接把create_ts字符串当作下一页起点、并用end_of_key_range截断的底层原因。游标分页与 limit 语义两个端点都遵循相同的分页约定请求时传入上一页返回的pagination.cursor服务端把游标解析为上一页最后一个元素的排序键runners_list用create_tsrunners_list_names用名称底层扫描从该键之后开始因此游标分页不会因新数据插入而重复或遗漏区别于 offset 分页首页请求不传cursor从最新记录开始。一个容易踩的坑runners_list走“按 ID 查询”路径时返回的cursor恒为None此时继续分页没有意义只有走“列表扫描”路径才会产生有效的下一页游标。常见错误处理SDK 为每个方法定义了类型化错误枚举见 runners_api.rsRunnersListError/RunnersListNamesError均只有一个UnknownValue(serde_json::Value)变体用于承接服务端返回的非预期错误体。当 HTTP 状态码为 4xx/5xx 时SDK 返回Error::ResponseError(ResponseContent { status, content, entity })其中content是原始响应文本entity是尝试反序列化出的错误枚举。实战中应优先检查status判断错误类别。典型失败场景场景表现未提供bearer_access_token服务端ctx.auth()校验失败返回 401命名空间不存在resolve_for_name_global返回None映射为Namespace::NotFound见 api-peer/src/runners.rsrunner_ids中含有非法 ID解析失败返回ApiBadRequestinvalid id inrunner_idsquery响应不是application/jsonSDK 返回反序列化错误与 Actors 查询 API 的关系RunnersApi 与仓库中同样由 OpenAPI 生成的 ActorsListApiGET /actors是配套关系Actor 运行在 Runner 之上因此常见的数据流是先用runners_list找到负载较低的 Runner再结合actors_list观察其上的 Actor 分布而runners_list_names适合做名称空间的全局普查。两者共享同一套Pagination游标约定与 fanout 架构理解本文的调用链后即可举一反三。小结本文基于 engine/sdks/rust/api-full/rust/docs/RunnersApi.md 及其对应的服务端实现完整梳理了 RunnersApi 两个端点的参数、返回值、分页机制与底层实现runners_listGET /runners返回RunnersListResponse支持按名称、按 ID 过滤以及include_stopped、limit、cursor参数服务端存在“按 ID 直查”和“按索引扫描”两条路径runners_list_namesGET /runners/names返回RunnersListNamesResponse只含名称清单跨数据中心扇出并去重排序全程 2 次数据中心往返两个端点均需 bearer_auth分页统一采用基于create_ts/ 名称的游标机制底层由 pegboard 的 universaldb 键扫描支撑索引键设计ACTIVE/ALL/NAME 前缀直接决定了查询的排序与分页能力。结合 engine/packages/api-public/src/runners.rs 与 engine/packages/api-peer/src/runners.rs 阅读即可获得从 SDK 到存储的完整视角。【免费下载链接】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），仅供参考