Rivet Actors TypeScript SDK 破坏性变更迁移指南ctx.db、RivetError 统一错误码与原生 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 仓库CHANGELOG.md的 Unreleased 变更记录系统梳理 TypeScript SDKrivetkit在向原生运行时迁移过程中的破坏性变更与迁移路径涵盖ctx.sql→ctx.db的数据库访问迁移、RivetError统一错误模型与isRivetErrorCode判断方式、Rust SDK action 上限提升以及Registry.handler()/Registry.serve()原生 Serverless 端点的恢复。读完本文你将掌握在当前仓库版本下如何改写既有 Actor 代码、迁移错误捕获逻辑并正确接入原生运行时提供的/api/rivet/*路由面。一、变更背景向原生运行时收敛Unreleased 变更的总体方向非常明确rivetkitTypeScript SDK不再维护一套独立的 TypeScript 内存运行时而是统一收敛到 Rust 原生运行时native runtime / envoy 子进程之上。与此对应的 SDK 表面调整包括数据库访问统一从ctx.sql迁移到ctx.dbrivetkit/db框架/运行时错误不再以 TypeScript 具体类instanceof判断暴露而是统一为标准化的RivetErrorgroupcode原生 Serverless 运行入口Registry.handler()与Registry.serve()恢复路由面固定为/api/rivet前缀一批内部模块driver-helpers、topologies/*、dynamic、sandbox/*确认移除且不再提供替代子路径。这些改动要求既有 Actor 代码在升级时同步调整导入路径、错误捕获与数据库访问方式。下文按主题逐一说明。二、Rust SDK 与 TypeScript SDK 的 Action 上限差异1. 上限变化Rust SDKactor action 集合支持的上限从 16 提升至128个 action 类型。TypeScript SDKactor 定义不受此类限制“TypeScript actor definitions remain unrestricted”。这一差异意味着当你在 Rust 侧编写包含较多 action 的 actor 时不再受旧的 16 个类型上限约束而 TypeScript 侧本就无此约束因此两侧能力在 action 数量维度上保持一致。Rust SDK 的实现位于仓库的 rivetkit-rust/packages 目录下其 action 协议相关定义可参考actor-persist/schemas/中的 schema 文件如 v3.bare 与 v4.bare其中索引字段的类型设计决定了 action 分派消息的承载能力。2. 迁移建议在 Rust SDK 中组织超过 16 个 action 的 actor 时应继续使用分组明确的命名与稳定的 action 名称在 TypeScript SDK 中则无需为此做任何特殊处理。三、数据库访问迁移从ctx.sql到ctx.db1. 变更内容rivetkit不再在 actor context 上暴露ctx.sql。原生的 SQLite 调用应迁移到ctx.db来自rivetkit/dbDrizzle ORM 的配置保持在rivetkit/db/drizzle子路径。2. 官方迁移示例CHANGELOG 给出的迁移示例完整继承import { db } from rivetkit/db; const myActor actor({ db: db(), actions: { listTodos: async (ctx) { return await ctx.db.execute(SELECT * FROM todos ORDER BY created_at DESC); }, }, });要点通过db()工厂创建数据库 provider并在actor({ db: db() })中传入在 action 内部通过ctx.db.execute(sql, params?)执行原生 SQLDrizzle 相关设置放在rivetkit/db/drizzle子路径不要从rivetkit根导出引入。3. 源码层面的数据库类型结构从仓库源码看ctx.db的能力由 rivetkit-typescript/packages/rivetkit/src/db/mod.ts 导出它转发出db工厂来自/common/database/mod一组数据库相关类型如DatabaseProvider、AnyDatabaseProvider、InferDatabaseClient、NativeDatabaseProvider、RawAccess、RawDatabaseClient、SqliteDatabase、SqliteQueryResult、SqliteTransactionOptions等。在 common/database/config.ts 中可以看到DatabaseProviderDB需要实现createClient(ctx)与可选的onMigrate(client)createClient的结果会以ctx.db形式注入 actor contextRawAccess提供execute(query, ...args)、transaction(callback, options?)、nativeMetrics()与close()SqliteDatabase提供exec、execute、executeBatch、beginTransaction、run、query、nativeMetrics与closeSqliteTransactionOptions支持name聚合事务性能的操作名、timeout死锁安全超时毫秒数以及实验性的experimental.includeState原子包含 actor 与可休眠连接状态仅支持单语句execute事务进行期间并发修改状态会以actor.state_transaction_conflict失败另有实验性的SqliteProfilingOptionsSQLite 本地 profiling 开关如slowOperationThresholdMs、baselineSampleRate、maxPrometheusSeries等。这些类型说明ctx.db不仅是简单的 SQL 执行器还承载了事务、批量执行、原生指标与 profiling 能力迁移后可以在此基础上做更细粒度的性能观测。4. 运行时错误行为测试佐证仓库中的 native-runtime-errors.test.ts 验证了原生运行时下数据库未配置时的行为未配置数据库时访问ctx.db抛出结构化RivetErrorgroup为actor、code为database_not_configured、message 为database is not configured for this actor未启用 state 时访问ctx.state抛出group: actor、code: state_not_enabled的错误未配置 engine client 时调用ctx.client()抛出group: native、code: client_not_configured缺少 registry endpoint 时buildNativeRegistry拒绝启动group: native、code: endpoint_not_configured。可见原生运行时的配置类错误同样遵循统一的RivetError结构化错误模型见下一节迁移时建议用isRivetErrorCode对这些错误做精确判断。四、错误处理标准化RivetErrorgroup/codeisRivetErrorCode1. 变更内容rivetkit不再从rivetkit/actor/errors导出旧的具象错误类如QueueFull、ActorNotFound、ActionTimedOut。原生运行时统一以RivetError加group与code表示错误保证同一个错误形态在 HTTP、WebSocket 与 bridge 边界上保持一致不再依赖跨运行时的instanceof判断。2. 迁移示例try { await actor.someAction(); } catch (e) { if (e instanceof QueueFull) { // old path } if (isRivetErrorCode(e, queue, full)) { // new path } }3. 常见类替换对照表CHANGELOG 给出的完整替换表全文继承可复制使用Removed classUse nowQueueFullisRivetErrorCode(e, queue, full)QueueMessageTooLargeisRivetErrorCode(e, queue, message_too_large)QueueMessageInvalidisRivetErrorCode(e, queue, message_invalid)QueuePayloadInvalidisRivetErrorCode(e, queue, invalid_payload)QueueCompletionPayloadInvalidisRivetErrorCode(e, queue, invalid_completion_payload)QueueAlreadyCompletedisRivetErrorCode(e, queue, already_completed)ActionTimedOutisRivetErrorCode(e, action, timed_out)ActionNotFoundisRivetErrorCode(e, action, not_found)ActorNotFoundisRivetErrorCode(e, actor, not_found)ActorStoppingisRivetErrorCode(e, actor, stopping)ActorAbortedisRivetErrorCode(e, actor, aborted)IncomingMessageTooLongisRivetErrorCode(e, message, incoming_too_long)OutgoingMessageTooLongisRivetErrorCode(e, message, outgoing_too_long)InvalidEncodingisRivetErrorCode(e, encoding, invalid)InvalidRequestisRivetErrorCode(e, request, invalid)InvalidQueryJSONisRivetErrorCode(e, request, invalid_query_json)RequestHandlerNotDefinedisRivetErrorCode(e, handler, request_not_defined)WebSocketHandlerNotDefinedisRivetErrorCode(e, handler, websocket_not_defined)FeatureNotImplementedisRivetErrorCode(e, feature, not_implemented)UnsupportedisRivetErrorCode(e, feature, unsupported)注意当你有意抛出面向用户的应用层错误时仍可继续catchUserError。此次移除只影响原本包装框架/运行时故障的内置具象子类。4. 源码级实现依据RivetError与isRivetErrorCode的实现位于 rivetkit-typescript/packages/rivetkit/src/actor/errors.ts从中可以确认RivetError构造函数签名为(group, code, message, options?)实例携带group、code、message、public是否可安全序列化返回给客户端、metadata、rayId用于关联引擎日志的请求标识、statusCode默认public为 400否则 500、actor产生错误的 actor 标识actorId、generation、可选key等字段isRivetErrorCode(error, group, code)的实现即isRivetErrorLike(error) error.group group error.code code返回类型收窄为RivetErrorisRivetErrorLike校验对象包含字符串类型的group、code、message可选校验rayId与__typeRivetError同时被导出为ActorErrorexport { RivetError as ActorError }bridge 场景下错误以BRIDGE_RIVET_ERROR_PREFIX__RIVET_ERROR_JSON__:前缀 JSON 序列化传输encodeBridgeRivetError/decodeBridgeRivetError负责编解码NativeBridgeErrorPayload会把原生桥接中缺失的rayId序列化为 null归一化为undefined——这正是“同一错误形态跨 HTTP、WebSocket、bridge 边界存活”的实现机制此外还内置了一批便捷工厂internalError、invalidEncoding、invalidRequest、actorNotFound、actorStopping、actorRestartingHTTP 503、metadata.retryable: true、forbiddenError403、unsupportedFeature以及判断 actor 休眠时“aborted”正常退出的isActorAbortedError匹配group: actor、code: aborted用于区分真正失败与 park 的runhandler 因休眠而解除阻塞的预期行为。5. 保持UserError的使用方式UserError继承自RivetError构造时固定group为user默认code为user_error且public: true。它面向的是应用开发者主动抛出的用户可见错误不在本次移除范围内可继续用于业务错误表达。五、Serverless 运行入口恢复Registry.handler()与Registry.serve()1. 变更内容Registry.handler(request)与Registry.serve()已恢复面向.agent/specs/serverless-restoration.md描述的原生 Serverless runner 端点。固定路由面为/api/rivet /api/rivet/health /api/rivet/metadata /api/rivet/start用户流量仍然经由 Rivet Engine gateway 进入。2. 源码实现在 rivetkit-typescript/packages/rivetkit/src/registry/index.ts 中可以看到handler(request)处理单个 HTTP 请求典型用法是与 Hono 等框架组合const app new Hono(); app.all(/api/rivet/*, (c) registry.handler(c.req.raw)); export default app;serve()返回一个ServerlessHandler内部fetch转发给handlerexport default registry.serve();handler内部通过isServerlessStartRequest/isServerlessMetadataRequest区分 start / metadata 请求base path 可通过serverlessBasePath配置默认/api/rivetstart 请求前会触发configureServerlessPool每个进程只 upsert 一次带重试以容忍引擎启动中若池未配置返回 503 与{ group: guard, code: service_unavailable }start 请求体超过serverlessMaxStartPayloadBytes时返回 413 与{ group: message, code: incoming_too_long }。这些错误响应同样是统一的group/codeJSON 形态与第四节的结构化错误模型一致。3. 说明Registry.handler(request)单独使用时不会安装/api/rivet/health、/api/rivet/metadata等路由处理器从配置注释可见“Handlers are NOT installed whenhandler(request)is used alone”使用方需要自行在框架层接入对应路由Registry.start()现在只启动原生 envoy 路径内置的staticDir静态文件服务尚未接入原生引擎子进程属于后续工作follow-up。六、恢复的入口点与辅助类型以下入口点已恢复为受支持的公共 APIrivetkit/test测试入口现在会等待原生 envoy 的 metadata 端点就绪而不是依赖已移除的 TypeScript 内存运行时rivetkit/inspector与rivetkit/inspector/clientinspector 相关入口根rivetkit导出恢复零运行时的*ContextOf辅助类型例如type MyActionContext ActionContextOftypeof myActor;PATH_CONNECT、PATH_WEBSOCKET_PREFIX、KV_KEYS、ActorKv、ActorInstance、ActorRouter、createActorRouter、routeWebSocket则保持移除状态。七、确认永久移除的模块清单勿继续导入以下子路径确认移除且没有仓库内替代品迁移时应在应用代码中改走公共 API 或自行实现子路径状态迁移方向rivetkit/driver-helpers保持移除改用公共的rivetkit、rivetkit/client与 engine-client API不要导入包内部实现rivetkit/driver-helpers/websocket保持移除同上rivetkit/topologies/*保持移除该分支已删除 topology helpers如仍需自定义坐标/分区逻辑请在应用代码中自行维护rivetkit/dynamic永久移除无包内替代将相关集成移出rivetkit导入rivetkit/sandbox/*永久移除同上八、迁移检查清单升级到当前 Unreleased 版本时建议按以下顺序排查既有代码数据库全局搜索ctx.sql全部改为ctx.db从rivetkit/db导入dbDrizzle 配置保持在rivetkit/db/drizzle错误捕获搜索instanceof QueueFull、instanceof ActorNotFound、instanceof ActionTimedOut等具象错误类对照第五节映射表改用isRivetErrorCode(e, group, code)业务侧主动抛出的UserError保持不变Serverless 部署如使用Registry.handler(request)/Registry.serve()确认框架层接入/api/rivet、/api/rivet/health、/api/rivet/metadata、/api/rivet/start路由handler单独使用时不自动安装后三个处理器入口与类型rivetkit/test、rivetkit/inspector、rivetkit/inspector/client可直接使用需要ActionContextOftypeof myActor等类型时从根rivetkit导出获取清理导入删除对rivetkit/driver-helpers、rivetkit/topologies/*、rivetkit/dynamic、rivetkit/sandbox/*的一切导入Rust SDK确认 actor action 集合在 128 个类型上限内组织无需处理 TypeScript 侧的类似限制。以上所有变更均可对照本仓库源码继续深入错误模型见 src/actor/errors.ts数据库类型见 src/common/database/config.ts 与 src/db/mod.tsServerless 入口见 src/registry/index.ts运行时错误行为的回归验证见 tests/native-runtime-errors.test.ts。【免费下载链接】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），仅供参考