Rivet Actors RunnerConfigKind 枚举详解normal 与 serverless 两种运行模式的配置模型【免费下载链接】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 SDKRust中由 OpenAPI 生成的模型RunnerConfigKind完整解析其两个枚举变体RunnerConfigKindOneOfnormal 模式与RunnerConfigKindOneOf1serverless 模式的字段语义、JSON 序列化形态并结合后端版本化迁移源码namespace_runner_config.rs说明该枚举在配置演进中的真实作用。读完本文你将掌握 Runner 配置的完整字段表、两种模式的核心差异以及如何在实际代码中构造与解析该配置。背景RunnerConfigKind 在模型体系中的位置RunnerConfigKind是rivet-api-publicRivet Actors 公共 APIRust SDK 中描述Runner 运行配置类型的枚举模型源码位于 engine/sdks/rust/api-full/rust/src/models/runner_config_kind.rs。它与RunnerConfig、RunnerConfigResponse等模型共同组成 API 对 Actor 运行器Runner配置的完整描述。从 API 参考文档 engine/sdks/rust/api-full/rust/docs/RunnerConfigKind.md 可以看到该枚举只有两个变体NameDescriptionRunnerConfigKindOneOfRunnerConfigKindOneOf1文档本身是 OpenAPI Generator 自动生成的模型参考描述为空但其含义需要结合相邻模型文档与实现源码才能完整还原。它的本质是一个未标记枚举untagged enum——即一个字段既可以承载 normal 模式配置、也可以承载 serverless 模式配置的判别联合discriminated union。这也对应了 Rivet 的general-runtime-modes概念一个命名空间下的 Runner 可以选择常驻normal或Serverless两种运行形态。枚举定义untagged 联合与默认变体#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(untagged)] pub enum RunnerConfigKind { RunnerConfigKindOneOf(Boxmodels::RunnerConfigKindOneOf), RunnerConfigKindOneOf1(Boxmodels::RunnerConfigKindOneOf1), } impl Default for RunnerConfigKind { fn default() - Self { Self::RunnerConfigKindOneOf(Default::default()) } }关键实现细节engine/sdks/rust/api-full/rust/src/models/runner_config_kind.rs#[serde(untagged)]意味着不带任何外部标签直接内联序列化变体内容。反序列化时 serde 依次尝试每个变体直到某个变体成功解析为止。Default实现指向RunnerConfigKindOneOf即当用户不显式选择时默认采用 normal 模式语义。两个变体分别包装了RunnerConfigKindOneOf与RunnerConfigKindOneOf1这两个结构体各自只有一个字段充当命名空间包装器。两种变体的内部结构RunnerConfigKindOneOfnormal 模式对应文档 engine/sdks/rust/api-full/rust/docs/RunnerConfigKindOneOf.md源码在 engine/sdks/rust/api-full/rust/src/models/runner_config_kind_one_of.rspub struct RunnerConfigKindOneOf { #[serde(rename normal)] pub normal: Boxmodels::RunnerConfigKindOneOfNormal, }它只包含一个normal字段指向 RunnerConfigKindOneOfNormal。JSON 形态为{ normal: { ... } }。RunnerConfigKindOneOf1serverless 模式对应文档 engine/sdks/rust/api-full/rust/docs/RunnerConfigKindOneOf1.md源码在 engine/sdks/rust/api-full/rust/src/models/runner_config_kind_one_of_1.rspub struct RunnerConfigKindOneOf1 { #[serde(rename serverless)] pub serverless: Boxmodels::RunnerConfigKindOneOf1Serverless, }它只包含一个serverless字段指向 RunnerConfigKindOneOf1Serverless。JSON 形态为{ serverless: { ... } }。由于RunnerConfigKind是 untagged 枚举序列化时{ normal: ... }会被识别为RunnerConfigKindOneOf{ serverless: ... }会被识别为RunnerConfigKindOneOf1从而通过字段名即标签的方式实现了模式判别。字段详解normal 模式配置RunnerConfigKindOneOfNormalRunnerConfigKindOneOfNormal源码engine/sdks/rust/api-full/rust/src/models/runner_config_kind_one_of_normal.rs定义了常驻模式下与Actor 驱逐eviction相关的三个速率控制参数以及版本升级时的排空开关字段类型单位说明actor_eviction_delayOptioni32秒驱逐延迟时间actor_eviction_periodOptioni32秒驱逐周期actor_eviction_rateOptionf32每秒 Actor 数驱逐速率上限drain_on_version_upgradeOptionbool—版本升级时是否先排空再升级这些字段控制着平台在资源压力下回收空闲 Actor 的行为actor_eviction_period决定了驱逐检查的间隔actor_eviction_rate限制了单位时间内的驱逐数量避免雪崩actor_eviction_delay则给 Actor 一段宽限期再执行回收。所有字段均声明为OptionOptionT通过serde_with::rust::double_option用于区分字段缺失与显式 null两种状态。字段详解serverless 模式配置RunnerConfigKindOneOf1Serverlessserverless 模式是字段最丰富的变体见 RunnerConfigKindOneOf1Serverless源码engine/sdks/rust/api-full/rust/src/models/runner_config_kind_one_of_1_serverless.rs字段类型单位说明request_lifespani32必填秒单个请求的最长生命周期到达后请求结束urlString必填—serverless 服务的入口地址actor_eviction_delayOptioni32秒驱逐延迟时间actor_eviction_periodOptioni32秒驱逐周期actor_eviction_rateOptionf32每秒 Actor 数驱逐速率上限drain_grace_periodOptioni32秒排空宽限期drain_on_version_upgradeOptionbool—版本升级时是否先排空headersOptionHashMapString, String—附加请求头max_concurrent_actorsOptioni64—最大并发 Actor 数metadata_poll_intervalOptioni64毫秒元数据轮询间隔未设置时使用全局默认值max_runnersOptioni32—已弃用min_runnersOptioni32—已弃用runners_marginOptioni32—已弃用slots_per_runnerOptioni32—已弃用值得注意的几点request_lifespan与url是必填字段构造器RunnerConfigKindOneOf1Serverless::new(request_lifespan, url)也印证了这一点见源码第 57 行。max_runners、min_runners、runners_margin、slots_per_runner四个字段在文档中标注为Deprecated其能力已被max_concurrent_actors取代——这一演进在后端迁移代码中有明确体现。headers允许为 serverless 目标注入自定义请求头适合鉴权或路由场景。RunnerConfig两种模式的顶层组合RunnerConfigKind通常不会单独出现而是作为 RunnerConfig 的组成部分被使用。RunnerConfig源码engine/sdks/rust/api-full/rust/src/models/runner_config.rs将两种模式同时以必填字段列出pub struct RunnerConfig { #[serde(rename normal)] pub normal: Boxmodels::RunnerConfigKindOneOfNormal, #[serde(rename serverless)] pub serverless: Boxmodels::RunnerConfigKindOneOf1Serverless, /// Deprecated. #[serde(rename drain_on_version_upgrade, default, ...)] pub drain_on_version_upgrade: OptionOptionbool, #[serde(rename metadata, ...)] pub metadata: OptionOptionserde_json::Value, }这种两个模式都出现、运行时择一使用的设计让配置对象可以在不同命名空间/环境中复用normal 与 serverless 的配置并存于同一个RunnerConfig中平台根据实际运行的运行模式选择对应字段。此外drain_on_version_upgrade在RunnerConfig层标记为Deprecated该开关已被下沉到各模式内部。metadata是一个自由格式的serde_json::Value用于携带自定义元数据。响应侧模型 RunnerConfigResponse 在RunnerConfig基础上额外增加了protocol_version协议版本与runner_pool_error运行池错误信息两个字段用于 API 回传时附带运行时状态。后端佐证配置版本的迁移链v1 → v5在服务端实现中Runner 配置同样是按版本演进的。位于 engine/sdks/rust/data/src/versioned/namespace_runner_config.rs 的迁移代码展示了RunnerConfigKind从 v1 到 v5 的完整演进过程可以从源码结构推断出以下关键事实v1 仅支持 serverless 模式v1到v2的迁移中v1配置被整体包进RunnerConfigKind::Serverless而反向迁移时遇到RunnerConfigKind::Normal会直接bail!(namespace runner config v1 does not support normal runner config)——也就是说 normal 模式是后续版本才引入的。字段演进路径清晰v2→v3 迁移保留url、headers、request_lifespan、slots_per_runner、min_runners、max_runners、runners_margin等字段到 v4→v5 迁移时max_runners as u64被映射为max_concurrent_actors与 SDK 中弃用max_runners、引入max_concurrent_actors的字段标注完全吻合。Normal 变体在 v2 之后持续存在从 v2 到 v5 的所有版本都定义了RunnerConfigKind::Normal与RunnerConfigKind::Serverless(serverless)两个变体与 SDK 中RunnerConfigKind枚举的两个变体一一对应。这段迁移链从实现层面证实了RunnerConfigKind的 two-variant 设计不仅存在于 API 模型层也是服务端命名空间配置的持久化形态SDK 文档中的 Deprecated 标注与后端迁移逻辑保持一致。序列化形态与使用要点由于#[serde(untagged)]RunnerConfigKind在 JSON 中不携带任何枚举标签直接表现为嵌套对象// 变体 1normal 模式 { normal: { actor_eviction_rate: 5.0, actor_eviction_period: 60, drain_on_version_upgrade: true } } // 变体 2serverless 模式 { serverless: { url: https://worker.example.com/handle, request_lifespan: 30, max_concurrent_actors: 100, headers: { Authorization: Bearer xxx } } }使用时的几个要点构造时通过RunnerConfigKind::RunnerConfigKindOneOf(Box::new(...))显式包装Default默认取 normal 变体。反序列化依赖字段名判别normal/serverless字段必须出现否则对应的 untagged 变体匹配失败。必填字段注意serverless 变体的url与request_lifespan缺失会导致该变体解析失败此时 untagged 枚举会回退尝试其他变体。可选字段的三态语义OptionOptionTdouble option区分JSON 中未出现None与JSON 中显式为 nullSome(None)在平台侧两者处理策略不同。弃用字段避免使用max_runners、min_runners、runners_margin、slots_per_runner请改用max_concurrent_actors。小结RunnerConfigKind虽然是一份由 OpenAPI 自动生成的简短枚举文档但它精确刻画了 Rivet Actors 的核心运行模型两个变体分别对应normal常驻与serverless按需两种运行模式通过untagged 联合 字段名判别实现无标签的多态序列化字段设计围绕Actor 驱逐控制actor_eviction_*与版本升级排空drain_on_version_upgrade两大主题serverless 模式额外包含url、request_lifespan、headers、max_concurrent_actors等运行时参数服务端namespace_runner_config.rs的 v1→v5 迁移链验证了该枚举的演进历史与 Deprecated 标注的准确性。对于需要以 Rust 方式操作 Rivet Actors 命名空间配置的开发者本文的字段表与源码引用路径模型定义、normal 字段、serverless 字段、后端迁移可作为直接查阅与联调的依据。【免费下载链接】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），仅供参考 Rivet Actors RunnerConfigKind 枚举详解：normal 与 serverless 两种运行模式的配置模型
Rivet Actors RunnerConfigKind 枚举详解normal 与 serverless 两种运行模式的配置模型【免费下载链接】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 SDKRust中由 OpenAPI 生成的模型RunnerConfigKind完整解析其两个枚举变体RunnerConfigKindOneOfnormal 模式与RunnerConfigKindOneOf1serverless 模式的字段语义、JSON 序列化形态并结合后端版本化迁移源码namespace_runner_config.rs说明该枚举在配置演进中的真实作用。读完本文你将掌握 Runner 配置的完整字段表、两种模式的核心差异以及如何在实际代码中构造与解析该配置。背景RunnerConfigKind 在模型体系中的位置RunnerConfigKind是rivet-api-publicRivet Actors 公共 APIRust SDK 中描述Runner 运行配置类型的枚举模型源码位于 engine/sdks/rust/api-full/rust/src/models/runner_config_kind.rs。它与RunnerConfig、RunnerConfigResponse等模型共同组成 API 对 Actor 运行器Runner配置的完整描述。从 API 参考文档 engine/sdks/rust/api-full/rust/docs/RunnerConfigKind.md 可以看到该枚举只有两个变体NameDescriptionRunnerConfigKindOneOfRunnerConfigKindOneOf1文档本身是 OpenAPI Generator 自动生成的模型参考描述为空但其含义需要结合相邻模型文档与实现源码才能完整还原。它的本质是一个未标记枚举untagged enum——即一个字段既可以承载 normal 模式配置、也可以承载 serverless 模式配置的判别联合discriminated union。这也对应了 Rivet 的general-runtime-modes概念一个命名空间下的 Runner 可以选择常驻normal或Serverless两种运行形态。枚举定义untagged 联合与默认变体#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(untagged)] pub enum RunnerConfigKind { RunnerConfigKindOneOf(Boxmodels::RunnerConfigKindOneOf), RunnerConfigKindOneOf1(Boxmodels::RunnerConfigKindOneOf1), } impl Default for RunnerConfigKind { fn default() - Self { Self::RunnerConfigKindOneOf(Default::default()) } }关键实现细节engine/sdks/rust/api-full/rust/src/models/runner_config_kind.rs#[serde(untagged)]意味着不带任何外部标签直接内联序列化变体内容。反序列化时 serde 依次尝试每个变体直到某个变体成功解析为止。Default实现指向RunnerConfigKindOneOf即当用户不显式选择时默认采用 normal 模式语义。两个变体分别包装了RunnerConfigKindOneOf与RunnerConfigKindOneOf1这两个结构体各自只有一个字段充当命名空间包装器。两种变体的内部结构RunnerConfigKindOneOfnormal 模式对应文档 engine/sdks/rust/api-full/rust/docs/RunnerConfigKindOneOf.md源码在 engine/sdks/rust/api-full/rust/src/models/runner_config_kind_one_of.rspub struct RunnerConfigKindOneOf { #[serde(rename normal)] pub normal: Boxmodels::RunnerConfigKindOneOfNormal, }它只包含一个normal字段指向 RunnerConfigKindOneOfNormal。JSON 形态为{ normal: { ... } }。RunnerConfigKindOneOf1serverless 模式对应文档 engine/sdks/rust/api-full/rust/docs/RunnerConfigKindOneOf1.md源码在 engine/sdks/rust/api-full/rust/src/models/runner_config_kind_one_of_1.rspub struct RunnerConfigKindOneOf1 { #[serde(rename serverless)] pub serverless: Boxmodels::RunnerConfigKindOneOf1Serverless, }它只包含一个serverless字段指向 RunnerConfigKindOneOf1Serverless。JSON 形态为{ serverless: { ... } }。由于RunnerConfigKind是 untagged 枚举序列化时{ normal: ... }会被识别为RunnerConfigKindOneOf{ serverless: ... }会被识别为RunnerConfigKindOneOf1从而通过字段名即标签的方式实现了模式判别。字段详解normal 模式配置RunnerConfigKindOneOfNormalRunnerConfigKindOneOfNormal源码engine/sdks/rust/api-full/rust/src/models/runner_config_kind_one_of_normal.rs定义了常驻模式下与Actor 驱逐eviction相关的三个速率控制参数以及版本升级时的排空开关字段类型单位说明actor_eviction_delayOptioni32秒驱逐延迟时间actor_eviction_periodOptioni32秒驱逐周期actor_eviction_rateOptionf32每秒 Actor 数驱逐速率上限drain_on_version_upgradeOptionbool—版本升级时是否先排空再升级这些字段控制着平台在资源压力下回收空闲 Actor 的行为actor_eviction_period决定了驱逐检查的间隔actor_eviction_rate限制了单位时间内的驱逐数量避免雪崩actor_eviction_delay则给 Actor 一段宽限期再执行回收。所有字段均声明为OptionOptionT通过serde_with::rust::double_option用于区分字段缺失与显式 null两种状态。字段详解serverless 模式配置RunnerConfigKindOneOf1Serverlessserverless 模式是字段最丰富的变体见 RunnerConfigKindOneOf1Serverless源码engine/sdks/rust/api-full/rust/src/models/runner_config_kind_one_of_1_serverless.rs字段类型单位说明request_lifespani32必填秒单个请求的最长生命周期到达后请求结束urlString必填—serverless 服务的入口地址actor_eviction_delayOptioni32秒驱逐延迟时间actor_eviction_periodOptioni32秒驱逐周期actor_eviction_rateOptionf32每秒 Actor 数驱逐速率上限drain_grace_periodOptioni32秒排空宽限期drain_on_version_upgradeOptionbool—版本升级时是否先排空headersOptionHashMapString, String—附加请求头max_concurrent_actorsOptioni64—最大并发 Actor 数metadata_poll_intervalOptioni64毫秒元数据轮询间隔未设置时使用全局默认值max_runnersOptioni32—已弃用min_runnersOptioni32—已弃用runners_marginOptioni32—已弃用slots_per_runnerOptioni32—已弃用值得注意的几点request_lifespan与url是必填字段构造器RunnerConfigKindOneOf1Serverless::new(request_lifespan, url)也印证了这一点见源码第 57 行。max_runners、min_runners、runners_margin、slots_per_runner四个字段在文档中标注为Deprecated其能力已被max_concurrent_actors取代——这一演进在后端迁移代码中有明确体现。headers允许为 serverless 目标注入自定义请求头适合鉴权或路由场景。RunnerConfig两种模式的顶层组合RunnerConfigKind通常不会单独出现而是作为 RunnerConfig 的组成部分被使用。RunnerConfig源码engine/sdks/rust/api-full/rust/src/models/runner_config.rs将两种模式同时以必填字段列出pub struct RunnerConfig { #[serde(rename normal)] pub normal: Boxmodels::RunnerConfigKindOneOfNormal, #[serde(rename serverless)] pub serverless: Boxmodels::RunnerConfigKindOneOf1Serverless, /// Deprecated. #[serde(rename drain_on_version_upgrade, default, ...)] pub drain_on_version_upgrade: OptionOptionbool, #[serde(rename metadata, ...)] pub metadata: OptionOptionserde_json::Value, }这种两个模式都出现、运行时择一使用的设计让配置对象可以在不同命名空间/环境中复用normal 与 serverless 的配置并存于同一个RunnerConfig中平台根据实际运行的运行模式选择对应字段。此外drain_on_version_upgrade在RunnerConfig层标记为Deprecated该开关已被下沉到各模式内部。metadata是一个自由格式的serde_json::Value用于携带自定义元数据。响应侧模型 RunnerConfigResponse 在RunnerConfig基础上额外增加了protocol_version协议版本与runner_pool_error运行池错误信息两个字段用于 API 回传时附带运行时状态。后端佐证配置版本的迁移链v1 → v5在服务端实现中Runner 配置同样是按版本演进的。位于 engine/sdks/rust/data/src/versioned/namespace_runner_config.rs 的迁移代码展示了RunnerConfigKind从 v1 到 v5 的完整演进过程可以从源码结构推断出以下关键事实v1 仅支持 serverless 模式v1到v2的迁移中v1配置被整体包进RunnerConfigKind::Serverless而反向迁移时遇到RunnerConfigKind::Normal会直接bail!(namespace runner config v1 does not support normal runner config)——也就是说 normal 模式是后续版本才引入的。字段演进路径清晰v2→v3 迁移保留url、headers、request_lifespan、slots_per_runner、min_runners、max_runners、runners_margin等字段到 v4→v5 迁移时max_runners as u64被映射为max_concurrent_actors与 SDK 中弃用max_runners、引入max_concurrent_actors的字段标注完全吻合。Normal 变体在 v2 之后持续存在从 v2 到 v5 的所有版本都定义了RunnerConfigKind::Normal与RunnerConfigKind::Serverless(serverless)两个变体与 SDK 中RunnerConfigKind枚举的两个变体一一对应。这段迁移链从实现层面证实了RunnerConfigKind的 two-variant 设计不仅存在于 API 模型层也是服务端命名空间配置的持久化形态SDK 文档中的 Deprecated 标注与后端迁移逻辑保持一致。序列化形态与使用要点由于#[serde(untagged)]RunnerConfigKind在 JSON 中不携带任何枚举标签直接表现为嵌套对象// 变体 1normal 模式 { normal: { actor_eviction_rate: 5.0, actor_eviction_period: 60, drain_on_version_upgrade: true } } // 变体 2serverless 模式 { serverless: { url: https://worker.example.com/handle, request_lifespan: 30, max_concurrent_actors: 100, headers: { Authorization: Bearer xxx } } }使用时的几个要点构造时通过RunnerConfigKind::RunnerConfigKindOneOf(Box::new(...))显式包装Default默认取 normal 变体。反序列化依赖字段名判别normal/serverless字段必须出现否则对应的 untagged 变体匹配失败。必填字段注意serverless 变体的url与request_lifespan缺失会导致该变体解析失败此时 untagged 枚举会回退尝试其他变体。可选字段的三态语义OptionOptionTdouble option区分JSON 中未出现None与JSON 中显式为 nullSome(None)在平台侧两者处理策略不同。弃用字段避免使用max_runners、min_runners、runners_margin、slots_per_runner请改用max_concurrent_actors。小结RunnerConfigKind虽然是一份由 OpenAPI 自动生成的简短枚举文档但它精确刻画了 Rivet Actors 的核心运行模型两个变体分别对应normal常驻与serverless按需两种运行模式通过untagged 联合 字段名判别实现无标签的多态序列化字段设计围绕Actor 驱逐控制actor_eviction_*与版本升级排空drain_on_version_upgrade两大主题serverless 模式额外包含url、request_lifespan、headers、max_concurrent_actors等运行时参数服务端namespace_runner_config.rs的 v1→v5 迁移链验证了该枚举的演进历史与 Deprecated 标注的准确性。对于需要以 Rust 方式操作 Rivet Actors 命名空间配置的开发者本文的字段表与源码引用路径模型定义、normal 字段、serverless 字段、后端迁移可作为直接查阅与联调的依据。【免费下载链接】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），仅供参考