rivetkit-client-swift

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

RivetKit Swift Client

RivetKit Swift 客户端

Use this skill when building Swift clients that connect to Rivet Actors with

RivetKitClient

当你构建通过

RivetKitClient

连接到 Rivet Actors 的Swift客户端时，可参考本指南。

Version

版本

RivetKit version: 2.0.42

RivetKit 版本：2.0.42

Install

安装

Add the Swift package dependency and import

RivetKitClient

swift

// Package.swift
dependencies: [
    .package(url: "https://github.com/rivet-dev/rivetkit-swift", from: "2.0.0")
]

targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "RivetKitClient", package: "rivetkit-swift")
        ]
    )
]

添加Swift包依赖并导入

RivetKitClient

：

swift

// Package.swift
dependencies: [
    .package(url: "https://github.com/rivet-dev/rivetkit-swift", from: "2.0.0")
]

targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "RivetKitClient", package: "rivetkit-swift")
        ]
    )
]

Minimal Client

最简客户端示例

Endpoint URL

端点URL

swift

import RivetKitClient

let config = try ClientConfig(
    endpoint: "https://my-namespace:pk_...@api.rivet.dev"
)
let client = RivetKitClient(config: config)

let handle = client.getOrCreate("counter", ["my-counter"])
let count: Int = try await handle.action("increment", 1, as: Int.self)

swift

import RivetKitClient

let config = try ClientConfig(
    endpoint: "https://my-namespace:pk_...@api.rivet.dev"
)
let client = RivetKitClient(config: config)

let handle = client.getOrCreate("counter", ["my-counter"])
let count: Int = try await handle.action("increment", 1, as: Int.self)

Explicit Fields

显式字段配置

swift

import RivetKitClient

let config = try ClientConfig(
    endpoint: "https://api.rivet.dev",
    namespace: "my-namespace",
    token: "pk_..."
)
let client = RivetKitClient(config: config)

let handle = client.getOrCreate("counter", ["my-counter"])
let count: Int = try await handle.action("increment", 1, as: Int.self)

swift

import RivetKitClient

let config = try ClientConfig(
    endpoint: "https://api.rivet.dev",
    namespace: "my-namespace",
    token: "pk_..."
)
let client = RivetKitClient(config: config)

let handle = client.getOrCreate("counter", ["my-counter"])
let count: Int = try await handle.action("increment", 1, as: Int.self)

Stateless vs Stateful

无状态与有状态连接

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)

let handle = client.getOrCreate("counter", ["my-counter"])

// Stateless: each call is independent
let current: Int = try await handle.action("getCount", as: Int.self)
print("Current count: \(current)")

// Stateful: keep a connection open for realtime events
let conn = handle.connect()

// Subscribe to events using AsyncStream
let eventTask = Task {
    for await count in await conn.events("count", as: Int.self) {
        print("Event: \(count)")
    }
}

_ = try await conn.action("increment", 1, as: Int.self)

eventTask.cancel()
await conn.dispose()
await client.dispose()

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)

let handle = client.getOrCreate("counter", ["my-counter"])

// 无状态：每次调用相互独立
let current: Int = try await handle.action("getCount", as: Int.self)
print("当前计数：\(current)")

// 有状态：保持连接以接收实时事件
let conn = handle.connect()

// 使用AsyncStream订阅事件
let eventTask = Task {
    for await count in await conn.events("count", as: Int.self) {
        print("事件：\(count)")
    }
}

_ = try await conn.action("increment", 1, as: Int.self)

eventTask.cancel()
await conn.dispose()
await client.dispose()

Getting Actors

获取Actor实例

swift

import RivetKitClient

struct GameInput: Encodable {
    let mode: String
}

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)

// Get or create an actor
let room = client.getOrCreate("chatRoom", ["room-42"])

// Get an existing actor (fails if not found)
let existing = client.get("chatRoom", ["room-42"])

// Create a new actor with input
let created = try await client.create(
    "game",
    ["game-1"],
    options: CreateOptions(input: GameInput(mode: "ranked"))
)

// Get actor by ID
let byId = client.getForId("chatRoom", "actor-id")

// Resolve actor ID
let resolvedId = try await room.resolve()
print("Resolved ID: \(resolvedId)")

await client.dispose()

Actions support positional overloads for 0–5 args:

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)
let handle = client.getOrCreate("counter", ["my-counter"])

let count: Int = try await handle.action("getCount")
let updated: String = try await handle.action("rename", "new-name")
let ok: Bool = try await handle.action("setScore", "user-1", 42)

print("Count: \(count), Updated: \(updated), OK: \(ok)")
await client.dispose()

If you need more than 5 arguments, use the raw JSON fallback:

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)
let handle = client.getOrCreate("counter", ["my-counter"])

let args: [JSONValue] = [
    .string("user-1"),
    .number(.int(42)),
    .string("extra"),
    .string("more"),
    .string("args"),
    .string("here")
]
let ok: Bool = try await handle.action("setScore", args: args, as: Bool.self)
print("OK: \(ok)")

await client.dispose()

swift

import RivetKitClient

struct GameInput: Encodable {
    let mode: String
}

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)

// 获取或创建一个actor
let room = client.getOrCreate("chatRoom", ["room-42"])

// 获取已存在的actor（不存在则失败）
let existing = client.get("chatRoom", ["room-42"])

// 传入参数创建新的actor
let created = try await client.create(
    "game",
    ["game-1"],
    options: CreateOptions(input: GameInput(mode: "ranked"))
)

// 通过ID获取actor
let byId = client.getForId("chatRoom", "actor-id")

// 解析actor ID
let resolvedId = try await room.resolve()
print("解析后的ID：\(resolvedId)")

await client.dispose()

操作支持0-5个参数的重载：

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)
let handle = client.getOrCreate("counter", ["my-counter"])

let count: Int = try await handle.action("getCount")
let updated: String = try await handle.action("rename", "new-name")
let ok: Bool = try await handle.action("setScore", "user-1", 42)

print("计数：\(count)，更新结果：\(updated)，状态：\(ok)")
await client.dispose()

如果需要超过5个参数，可使用原始JSON作为回退方案：

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)
let handle = client.getOrCreate("counter", ["my-counter"])

let args: [JSONValue] = [
    .string("user-1"),
    .number(.int(42)),
    .string("extra"),
    .string("more"),
    .string("args"),
    .string("here")
]
let ok: Bool = try await handle.action("setScore", args: args, as: Bool.self)
print("状态：\(ok)")

await client.dispose()

Connection Parameters

连接参数

swift

import RivetKitClient

struct ConnParams: Encodable {
    let authToken: String
}

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)

let chat = client.getOrCreate(
    "chatRoom",
    ["general"],
    options: GetOrCreateOptions(params: ConnParams(authToken: "jwt-token-here"))
)

let conn = chat.connect()

// Use the connection...
for await status in await conn.statusChanges() {
    print("Status: \(status.rawValue)")
    if status == .connected {
        break
    }
}

await conn.dispose()
await client.dispose()

swift

import RivetKitClient

struct ConnParams: Encodable {
    let authToken: String
}

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)

let chat = client.getOrCreate(
    "chatRoom",
    ["general"],
    options: GetOrCreateOptions(params: ConnParams(authToken: "jwt-token-here"))
)

let conn = chat.connect()

// 使用连接...
for await status in await conn.statusChanges() {
    print("状态：\(status.rawValue)")
    if status == .connected {
        break
    }
}

await conn.dispose()
await client.dispose()

Subscribing to Events

订阅事件

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)
let conn = client.getOrCreate("chatRoom", ["general"]).connect()

// Subscribe to events using AsyncStream
let messageTask = Task {
    for await (from, body) in await conn.events("message", as: (String, String).self) {
        print("\(from): \(body)")
    }
}

// For one-time events, break after receiving
let gameOverTask = Task {
    for await _ in await conn.events("gameOver", as: Void.self) {
        print("done")
        break
    }
}

// Let it run for a bit
try await Task.sleep(for: .seconds(5))

// Cancel when done
messageTask.cancel()
gameOverTask.cancel()
await conn.dispose()
await client.dispose()

Event streams support 0–5 typed arguments. If you need raw values or more than 5 arguments, use

JSONValue

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)
let conn = client.getOrCreate("chatRoom", ["general"]).connect()

let rawTask = Task {
    for await args in await conn.events("message") {
        print(args)
    }
}

try await Task.sleep(for: .seconds(5))
rawTask.cancel()
await conn.dispose()
await client.dispose()

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)
let conn = client.getOrCreate("chatRoom", ["general"]).connect()

// 使用AsyncStream订阅事件
let messageTask = Task {
    for await (from, body) in await conn.events("message", as: (String, String).self) {
        print("\(from)：\(body)")
    }
}

// 一次性事件：接收后终止
let gameOverTask = Task {
    for await _ in await conn.events("gameOver", as: Void.self) {
        print("游戏结束")
        break
    }
}

// 运行一段时间
try await Task.sleep(for: .seconds(5))

// 完成后取消任务
messageTask.cancel()
gameOverTask.cancel()
await conn.dispose()
await client.dispose()

事件流支持0-5个类型化参数。如果需要原始值或超过5个参数，可使用

JSONValue

：

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)
let conn = client.getOrCreate("chatRoom", ["general"]).connect()

let rawTask = Task {
    for await args in await conn.events("message") {
        print(args)
    }
}

try await Task.sleep(for: .seconds(5))
rawTask.cancel()
await conn.dispose()
await client.dispose()

Connection Lifecycle

连接生命周期

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)
let conn = client.getOrCreate("chatRoom", ["general"]).connect()

// Monitor status changes (immediately yields current status)
let statusTask = Task {
    for await status in await conn.statusChanges() {
        print("status: \(status.rawValue)")
    }
}

// Monitor errors
let errorTask = Task {
    for await error in await conn.errors() {
        print("error: \(error.group).\(error.code)")
    }
}

// Monitor open/close events
let openTask = Task {
    for await _ in await conn.opens() {
        print("connected")
    }
}

let closeTask = Task {
    for await _ in await conn.closes() {
        print("disconnected")
    }
}

// Check current status
let current = await conn.currentStatus
print("Current status: \(current.rawValue)")

// Let it run for a bit
try await Task.sleep(for: .seconds(5))

// Cleanup
statusTask.cancel()
errorTask.cancel()
openTask.cancel()
closeTask.cancel()
await conn.dispose()
await client.dispose()

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)
let conn = client.getOrCreate("chatRoom", ["general"]).connect()

// 监听状态变化（立即返回当前状态）
let statusTask = Task {
    for await status in await conn.statusChanges() {
        print("状态：\(status.rawValue)")
    }
}

// 监听错误
let errorTask = Task {
    for await error in await conn.errors() {
        print("错误：\(error.group).\(error.code)")
    }
}

// 监听连接开启/关闭事件
let openTask = Task {
    for await _ in await conn.opens() {
        print("已连接")
    }
}

let closeTask = Task {
    for await _ in await conn.closes() {
        print("已断开连接")
    }
}

// 检查当前状态
let current = await conn.currentStatus
print("当前状态：\(current.rawValue)")

// 运行一段时间
try await Task.sleep(for: .seconds(5))

// 清理资源
statusTask.cancel()
errorTask.cancel()
openTask.cancel()
closeTask.cancel()
await conn.dispose()
await client.dispose()

Low-Level HTTP & WebSocket

底层HTTP与WebSocket

For actors that implement

onRequest

onWebSocket

, you can call them directly:

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)
let handle = client.getOrCreate("chatRoom", ["general"])

// Raw HTTP request
let response = try await handle.fetch("history")
let history: [String] = try response.json([String].self)
print("History: \(history)")

// Raw WebSocket connection
let websocket = try await handle.websocket(path: "stream")
try await websocket.send(text: "hello")
let message = try await websocket.receive()
print("Received: \(message)")

await client.dispose()

对于实现了

onRequest

或

onWebSocket

的actor，你可以直接调用它们：

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)
let handle = client.getOrCreate("chatRoom", ["general"])

// 原始HTTP请求
let response = try await handle.fetch("history")
let history: [String] = try response.json([String].self)
print("历史记录：\(history)")

// 原始WebSocket连接
let websocket = try await handle.websocket(path: "stream")
try await websocket.send(text: "hello")
let message = try await websocket.receive()
print("收到消息：\(message)")

await client.dispose()

Calling from Backend

在后端中调用

Use the same client in server-side Swift (Vapor, Hummingbird, etc.):

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)

let handle = client.getOrCreate("counter", ["server-counter"])
let count: Int = try await handle.action("increment", 1, as: Int.self)
print("Count: \(count)")

await client.dispose()

在服务器端Swift（Vapor、Hummingbird等）中可使用同一个客户端：

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)

let handle = client.getOrCreate("counter", ["server-counter"])
let count: Int = try await handle.action("increment", 1, as: Int.self)
print("计数：\(count)")

await client.dispose()

Error Handling

错误处理

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)

do {
    _ = try await client.getOrCreate("user", ["user-123"])
        .action("updateUsername", "ab", as: String.self)
} catch let error as ActorError {
    print("Error code: \(error.code)")
    print("Metadata: \(String(describing: error.metadata))")
}

await client.dispose()

If you need an untyped response, you can decode to

JSONValue

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)
let handle = client.getOrCreate("data", ["raw"])

let value: JSONValue = try await handle.action("getRawPayload")
print("Raw value: \(value)")

await client.dispose()

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)

do {
    _ = try await client.getOrCreate("user", ["user-123"])
        .action("updateUsername", "ab", as: String.self)
} catch let error as ActorError {
    print("错误码：\(error.code)")
    print("元数据：\(String(describing: error.metadata))")
}

await client.dispose()

如果需要非类型化响应，可解码为

JSONValue

：

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)
let handle = client.getOrCreate("data", ["raw"])

let value: JSONValue = try await handle.action("getRawPayload")
print("原始值：\(value)")

await client.dispose()

Concepts

核心概念

Keys

键（Keys）

Keys uniquely identify actor instances. Use compound keys (arrays) for hierarchical addressing:

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)

// Use compound keys for hierarchical addressing
let room = client.getOrCreate("chatRoom", ["org-acme", "general"])
let actorId = try await room.resolve()
print("Actor ID: \(actorId)")

await client.dispose()

Don't build keys with string interpolation like

"org:\(userId)"

when

userId

contains user data. Use arrays instead to prevent key injection attacks.

键用于唯一标识actor实例。可使用复合键（数组）进行层级寻址：

swift

import RivetKitClient

let config = try ClientConfig(endpoint: "http://localhost:3000/api/rivet")
let client = RivetKitClient(config: config)

// 使用复合键进行层级寻址
let room = client.getOrCreate("chatRoom", ["org-acme", "general"])
let actorId = try await room.resolve()
print("Actor ID：\(actorId)")

await client.dispose()

当

userId

包含用户数据时，不要使用字符串拼接（如

"org:\(userId)"

）来构建键，应使用数组以避免键注入攻击。

Environment Variables

环境变量

ClientConfig

reads optional values from environment variables:

```
RIVET_NAMESPACE
```
- Namespace (can also be in endpoint URL)
```
RIVET_TOKEN
```
- Authentication token (can also be in endpoint URL)
```
RIVET_RUNNER
```
- Runner name (defaults to
```
"default"
```
)

The

endpoint

parameter is always required. There is no default endpoint.

ClientConfig

会从环境变量中读取可选值：

```
RIVET_NAMESPACE
```
- 命名空间（也可包含在端点URL中）
```
RIVET_TOKEN
```
- 认证令牌（也可包含在端点URL中）
```
RIVET_RUNNER
```
- 运行器名称（默认值为
```
"default"
```
）

endpoint

参数是必填项，没有默认值。

Endpoint Format

端点格式

Endpoints support URL auth syntax:

https://namespace:token@api.rivet.dev

You can also pass the endpoint without auth and provide

RIVET_NAMESPACE

and

RIVET_TOKEN

separately. For serverless deployments, set the endpoint to your app's

/api/rivet

URL. See Endpoints for details.

端点支持URL认证语法：

https://namespace:token@api.rivet.dev

你也可以传递不带认证信息的端点，再单独提供

RIVET_NAMESPACE

和

RIVET_TOKEN

。对于无服务器部署，可将端点设置为你的应用的

/api/rivet

URL。详情请参考端点文档。

API Reference

API参考

Client

客户端（Client）

```
RivetKitClient(config:)
```
- Create a client with a config
```
ClientConfig
```
- Configure endpoint, namespace, and token

client.get()

getOrCreate()

getForId()

create()

- Get actor handles

```
client.dispose()
```
- Dispose the client and all connections

```
RivetKitClient(config:)
```
- 使用配置创建客户端
```
ClientConfig
```
- 配置端点、命名空间和令牌

client.get()

getOrCreate()

getForId()

create()

- 获取actor句柄

```
client.dispose()
```
- 销毁客户端及所有连接

ActorHandle

Actor句柄（ActorHandle）

```
handle.action(name, args..., as:)
```
- Stateless action call
```
handle.connect()
```
- Create a stateful connection
```
handle.resolve()
```
- Get the actor ID
```
handle.getGatewayUrl()
```
- Get the raw gateway URL
```
handle.fetch(path, request:)
```
- Raw HTTP request
```
handle.websocket(path:)
```
- Raw WebSocket connection

```
handle.action(name, args..., as:)
```
- 无状态操作调用
```
handle.connect()
```
- 创建有状态连接
```
handle.resolve()
```
- 获取actor ID
```
handle.getGatewayUrl()
```
- 获取原始网关URL
```
handle.fetch(path, request:)
```
- 原始HTTP请求
```
handle.websocket(path:)
```
- 原始WebSocket连接

ActorConnection

Actor连接（ActorConnection）

```
conn.action(name, args..., as:)
```
- Action call over WebSocket
```
conn.events(name, as:)
```
- AsyncStream of typed events
```
conn.statusChanges()
```
- AsyncStream of status changes
```
conn.errors()
```
- AsyncStream of connection errors
```
conn.opens()
```
- AsyncStream that yields on connection open
```
conn.closes()
```
- AsyncStream that yields on connection close
```
conn.currentStatus
```
- Current connection status
```
conn.dispose()
```
- Close the connection

```
conn.action(name, args..., as:)
```
- 通过WebSocket调用操作
```
conn.events(name, as:)
```
- 类型化事件的AsyncStream
```
conn.statusChanges()
```
- 状态变化的AsyncStream
```
conn.errors()
```
- 连接错误的AsyncStream
```
conn.opens()
```
- 连接开启事件的AsyncStream
```
conn.closes()
```
- 连接关闭事件的AsyncStream
```
conn.currentStatus
```
- 当前连接状态
```
conn.dispose()
```
- 关闭连接

Types

类型定义

ActorConnStatus

- Connection status enum (

.idle

.connecting

.connected

.disconnected

.disposed

)

```
ActorError
```
- Typed actor errors with
```
group
```
,
```
code
```
,
```
message
```
,
```
metadata
```
```
JSONValue
```
- Raw JSON value for untyped responses

ActorConnStatus

- 连接状态枚举（

.idle

.connecting

.connected

.disconnected

.disposed

）

```
ActorError
```
- 带
```
group
```
、
```
code
```
、
```
message
```
、
```
metadata
```
的类型化actor错误
```
JSONValue
```
- 用于非类型化响应的原始JSON值

Need More Than the Client?

需要更多功能？

If you need more about Rivet Actors, registries, or server-side RivetKit, add the main skill:

bash

npx skills add rivet-dev/skills

Then use the

rivetkit

skill for backend guidance.

如果你需要了解更多关于Rivet Actors、注册中心或服务器端RivetKit的内容，可添加主技能包：

bash

npx skills add rivet-dev/skills

然后使用

rivetkit

技能获取后端相关指导。