Rivet Actors Rust SDK 之 NsApi 解析用create_namespace创建 Namespace 的完整指南【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors导读Namespace 是 Rivet Actors 中隔离 Actor 部署与运行环境的核心逻辑分组。本篇文章聚焦于 Rivet 开源仓库中 engine/sdks/rust/api-full/docs/NsApi.md 所定义的NsApiNamespace API完整讲解create_namespace端点的请求/响应模型、Rust SDK 的调用方式、HTTP 协议细节并结合引擎端api-public、api-peer、types等源码还原服务端创建 Namespace 的完整流程。读完本文你将能够在 Rust 程序中正确配置 SDK 客户端、构造NamespacesCreateRequest发起创建请求、解析NamespacesCreateResponse并理解namespace_id、name、display_name、create_ts各字段的来源与语义从而在自己的 Actor 项目中完成 Namespace 的初始化。一、文档定位NsApi 是什么NsApi.md是 Rivet Rust SDKrivet-api-fullcrate中由 OpenAPI Generator 自动生成的一组 API 参考文档页面之一与 ActorsApi.md、模型文档 Namespace.md 等位于同一目录engine/sdks/rust/api-full/docs/。该页面声明的 API 基址为http://localhost相对 URI即 SDK 默认指向本机自托管/本地开发的 Rivet 控制面。从文档自带的方法索引可以看出NsApi目前包含一个端点MethodHTTP requestDescriptioncreate_namespacePOST/namespaces创建 Namespace对应的 Rust 顶层签名文档原始定义为models::NamespacesCreateResponse create_namespace(namespaces_create_request)该页面在 SDK 源码中的落点是 engine/sdks/rust/api-full/src/apis/ns_api.rs其中定义了异步函数create_namespace以及错误枚举CreateNamespaceError模块通过 engine/sdks/rust/api-full/src/apis/mod.rs 中的pub mod ns_api;对外暴露。二、请求模型NamespacesCreateRequestcreate_namespace唯一的必填参数是请求体NamespacesCreateRequest其模型文档为 NamespacesCreateRequest.mdRust 结构体定义在 engine/sdks/rust/api-full/src/models/namespaces_create_request.rs#[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)] pub struct NamespacesCreateRequest { #[serde(rename display_name)] pub display_name: String, #[serde(rename name)] pub name: String, } impl NamespacesCreateRequest { pub fn new(display_name: String, name: String) - NamespacesCreateRequest { NamespacesCreateRequest { display_name, name } } }两个字段均为必填字段类型语义说明display_nameString显示名称面向 UI/人工阅读的友好名称例如Production ActorsnameString逻辑名称Namespace 在系统中的唯一标识名例如prod需要注意NamespacesCreateRequest是从namespaces_create_request构造函数的参数顺序推断new(display_name, name)即第一个参数是display_name第二个是name。请求体通过Content-Type: application/json发送序列化后的 JSON 形如{ display_name: My Production Namespace, name: prod }serde(rename ...)属性保证了 Rust 字段名snake_case与 API 协议字段名snake_case在序列化/反序列化时严格对齐。三、响应模型NamespacesCreateResponse 与 Namespace接口成功时返回NamespacesCreateResponse文档见 NamespacesCreateResponse.md实现见 engine/sdks/rust/api-full/src/models/namespaces_create_response.rs#[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)] pub struct NamespacesCreateResponse { #[serde(rename namespace)] pub namespace: Boxmodels::Namespace, }即响应只包含一个嵌套的namespace对象类型为models::Namespace模型文档 Namespace.md实现见 engine/sdks/rust/api-full/src/models/namespace.rspub struct Namespace { #[serde(rename create_ts)] pub create_ts: i64, #[serde(rename display_name)] pub display_name: String, #[serde(rename name)] pub name: String, #[serde(rename namespace_id)] pub namespace_id: String, }四个响应字段的语义如下字段类型语义namespace_idString新创建 Namespace 的唯一 ID由服务端生成后续所有 Actor 部署、KV、连接等操作都以该 ID 为索引nameString与请求中的name一致display_nameString与请求中的display_name一致create_tsi64创建时间戳Unix 时间单位为秒同时用于列表接口的游标分页排序在引擎核心类型中该结构定义于 engine/packages/types/src/namespaces.rs使用Id类型承载namespace_id新版本 ID 编码并在序列化给 SDK 时转换为字符串。四、SDK 函数详解create_namespace 的完整调用链NsApi.md文档声明create_namespace不需要 AuthorizationNo authorization required并规定请求头Content-Type:application/jsonAccept:application/json不过这是 OpenAPI 生成器从api-public的utoipa元数据导出的默认结论从引擎端源码看见下文第六节api-public路由实际声明了bearer_auth安全机制因此接入真实控制面时建议仍按 API 文档配置 Bearer Token 鉴权。SDK 的完整实现位于 engine/sdks/rust/api-full/src/apis/ns_api.rs其调用流程为拼接 URIformat!({}/namespaces, configuration.base_path)默认base_path为http://localhost构造请求使用configuration.clientreqwest::Client发起reqwest::Method::POST附加 User-Agent若configuration.user_agent存在则写入请求头默认值为OpenAPI-Generator/0.0.1/rust序列化请求体req_builder.json(p_namespaces_create_request)将NamespacesCreateRequest序列化为 JSON 并设置Content-Type: application/json执行并解析响应若状态码非 4xx/5xx按响应Content-Type反序列化为NamespacesCreateResponse否则构造Error::ResponseError(ResponseContent { status, content, entity })返回错误。对应错误类型定义于 engine/sdks/rust/api-full/src/apis/mod.rspub enum ErrorT { Reqwest(reqwest::Error), Serde(serde_json::Error), Io(std::io::Error), ResponseError(ResponseContentT), }create_namespace返回ResultNamespacesCreateResponse, ErrorCreateNamespaceError其中CreateNamespaceError目前仅包含UnknownValue(serde_json::Value)兜底分支用于携带服务端返回的非结构化错误信息。五、客户端配置与最小可运行示例SDK 客户端配置结构体Configuration定义在 engine/sdks/rust/api-full/src/apis/configuration.rspub struct Configuration { pub base_path: String, pub user_agent: OptionString, pub client: reqwest::Client, pub basic_auth: OptionBasicAuth, pub oauth_access_token: OptionString, pub bearer_access_token: OptionString, pub api_key: OptionApiKey, }默认值为base_path: http://localhost、user_agent: Some(OpenAPI-Generator/0.0.1/rust)、client: reqwest::Client::new()其余鉴权字段均为None。rivet-api-full的依赖在 engine/sdks/rust/api-full/Cargo.toml 中声明核心为reqwest启用json、multipart、serde、serde_json、serde_repr、url。一个最小可运行示例基于 SDK 源码公开 API 编写use rivet_api_full::apis::configuration::Configuration; use rivet_api_full::apis::ns_api; use rivet_api_full::models::NamespacesCreateRequest; #[tokio::main] async fn main() - Result(), Boxdyn std::error::Error { // 1. 构建客户端配置默认指向 http://localhost let configuration Configuration::new(); // 2. 构造创建请求display_name 在前name 在后 let request NamespacesCreateRequest::new( My Production Namespace.to_string(), prod.to_string(), ); // 3. 调用 SDK 方法 let response ns_api::create_namespace(configuration, request).await?; // 4. 读取返回的 Namespace let namespace response.namespace; println!(namespace_id {}, namespace.namespace_id); println!(name {}, namespace.name); println!(display_name {}, namespace.display_name); println!(create_ts {}, namespace.create_ts); Ok(()) }若目标是自托管或远程控制面只需覆写base_path例如let mut configuration Configuration::new(); configuration.base_path https://api.example.com.to_string();SDK 顶层入口在 engine/sdks/rust/api-full/src/lib.rs对外只暴露pub mod apis;与pub mod models;两个模块因此上面示例中的导入路径是标准用法。注意rivet-api-fullcrate 在仓库中被标记为publish false见 Cargo.toml它主要作为生成的 SDK 参考实现/内部使用读者如需在业务中使用应复制生成产物或关注rivetkit-rust等正式 SDK 的封装方式。六、引擎端实现服务端如何处理 create_namespace虽然NsApi.md是 SDK 视角的文档但仓库中同时保留了服务端实现可帮助我们验证协议语义以下均为实现事实对应文件路径见各小节。6.1 路由注册与请求处理api-public控制面的公开 HTTP 路由在 engine/packages/api-public/src/router.rs 中注册.route(/namespaces, axum::routing::get(namespaces::list)) .route(/namespaces, axum::routing::post(namespaces::create))POST /namespaces对应create处理器实现在 engine/packages/api-public/src/namespaces.rs其utoipa元数据声明了operation_id namespaces_create、request_body为application/json的CreateRequest、成功响应CreateResponse并声明security((bearer_auth []))。处理器内部逻辑ctx.auth().await?校验调用方鉴权若当前节点是 leaderctx.config().is_leader()则直接调用rivet_api_peer::namespaces::create执行本地创建否则通过request_remote_datacenter将POST /namespaces与请求体转发到 leader 数据中心执行多数据中心路由。6.2 创建流程与 ID 生成api-peer真正的创建逻辑位于 engine/packages/api-peer/src/namespaces.rs请求体CreateRequest { name, display_name }声明了#[serde(deny_unknown_fields)]即请求中出现未知字段会直接反序列化失败服务端首先用Id::new_v1(ctx.config().dc_label())生成新的namespace_idv1 前缀 ID携带数据中心标签随后通过ctx.workflow(...)派发namespace::workflows::namespace::Input { namespace_id, name, display_name }工作流并使用tokio::select!同时等待CreateComplete与Failed两个工作流事件——成功则继续失败则把错误消息转换为ApiError返回最后通过namespace::ops::get_local读取刚创建的 Namespace 并包装为CreateResponse { namespace }返回。这一实现也印证了 SDK 文档中的事实创建是同步等待工作流完成的成功响应的namespace就是服务端持久化后的完整对象。6.3 核心数据类型types服务端与协议共用的核心类型定义在 engine/packages/types/src/namespaces.rs#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)] pub struct Namespace { pub namespace_id: Id, pub name: String, pub display_name: String, pub create_ts: i64, }它通过utoipa::ToSchema与api-public的 OpenAPI 文档rivetkit-openapi/openapi.json联动SDK 代码与文档NsApi.md、Namespace.md等正是由这份 OpenAPI 规范经 OpenAPI Generator 生成。这也解释了为什么Namespace模型的四个字段namespace_id、name、display_name、create_ts在 SDK、协议层与引擎核心类型中完全一致。七、HTTP 协议速查与边界说明NsApi.md文档给出的协议信息可整理为如下速查表项值方法POST路径/namespaces请求 Content-Typeapplication/json响应 Acceptapplication/json鉴权文档标注 No authorization required引擎端实际声明 bearer_auth见上请求体NamespacesCreateRequest { display_name, name }响应体NamespacesCreateResponse { namespace: Namespace }成功状态码200几点基于源码的边界说明字段严格性CreateRequest在引擎端开启deny_unknown_fields请求体多传字段会被拒绝SDK 侧生成的NamespacesCreateRequest结构体则不受此限制由 OpenAPI 生成器默认行为决定命名唯一性name是 Namespace 的逻辑标识创建后即与服务端 ID 绑定创建同名 Namespace 是否符合预期取决于控制面后续的命名校验逻辑从当前 SDK 生成的模型文档看并不在客户端强制约束同步语义create_namespace是一个同步等待的工作流式接口返回时 Namespace 已持久化完成可直接作为后续 Actor 操作如ActorsApi中的创建/部署的前置依赖。八、与 ActorsApi 的配合创建后如何使用 NamespaceNamespace 是 Actor 的隔离边界。在 ActorsApi.md 对应的 engine/sdks/rust/api-full/src/apis/actors_api.rs 中各类 Actor 操作创建、删除、列表、KV、休眠、重调度等都以 Namespace 为前提。典型的使用顺序是调用create_namespace获得namespace_id在后续 Actor 请求中携带该namespace_id定位运行环境通过NamespacesCreateResponse.namespace中的create_ts等信息进行运维审计与分页游标。这样一次POST /namespaces调用就完成了 Rivet Actors 有状态工作负载初始化中的第一步。九、小结NsApi.md虽然是一份精简的自动生成文档但它准确刻画了 Rivet Rust SDK 创建 Namespace 的完整契约一个POST /namespaces端点、两个必填请求字段display_name、name、一个包含namespace对象的响应模型。结合仓库源码我们可以看到这份契约从api-public路由 →api-peer工作流创建 →types核心模型 → OpenAPI 生成 SDK 的全链路实现帮助开发者在 Rust 项目中快速、正确地完成 Namespace 初始化为后续的 Actor 部署与有状态工作负载管理打好基础。参考路径索引SDK 文档engine/sdks/rust/api-full/docs/NsApi.md、engine/sdks/rust/api-full/docs/NamespacesCreateRequest.md、engine/sdks/rust/api-full/docs/NamespacesCreateResponse.md、engine/sdks/rust/api-full/docs/Namespace.mdSDK 源码engine/sdks/rust/api-full/src/apis/ns_api.rs、engine/sdks/rust/api-full/src/apis/configuration.rs、engine/sdks/rust/api-full/src/models/namespaces_create_request.rs服务端实现engine/packages/api-public/src/namespaces.rs、engine/packages/api-public/src/router.rs、engine/packages/api-peer/src/namespaces.rs、engine/packages/types/src/namespaces.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），仅供参考