RivetKit Swift 客户端：连接 Rivet Actors 的 iOS/macOS 开发库

rivetkit-client-swift by rivet-dev/skills

1,900 周安装量

8 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/rivet-dev/skills --skill rivetkit-client-swift

开发云服务

🇨🇳中文介绍

RivetKit Swift 客户端

在构建使用 RivetKitClient 连接 Rivet Actors 的 Swift 客户端时使用此技能。

版本

RivetKit 版本：2.1.6

错误处理策略

默认倾向于快速失败行为。
除非绝对需要，否则避免使用宽泛的 do/catch。
如果使用了 catch 块，请显式处理错误，至少应记录该错误。

安装

添加 Swift 包依赖并导入 RivetKitClient：

// 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")
        ]
    )
]

最小化客户端

端点 URL

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)

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

733,500 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

252,100 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

202,600 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

133,200 周安装

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 count: \(current)")

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

// 使用 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()

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("Resolved ID: \(resolvedId)")

await client.dispose()

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: \(status.rawValue)")
    if status == .connected {
        break
    }
}

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

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("done")
        break
    }
}

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

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

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: \(status.rawValue)")
    }
}

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

// 监控打开/关闭事件
let openTask = Task {
    for await _ in await conn.opens() {
        print("connected")
    }
}

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

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

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

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

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: \(history)")

// 原始 WebSocket 连接
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()

RivetKitClient(config:) - 使用配置创建客户端
ClientConfig - 配置端点、命名空间和令牌
client.get() / getOrCreate() / getForId() / create() - 获取 actor 句柄
client.dispose() - 销毁客户端及其所有连接

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

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() - 关闭连接

ActorConnStatus - 连接状态枚举（.idle, .connecting, .connected, .disconnected, .disposed）
ActorError - 类型化的 actor 错误，包含 group, code, message, metadata
JSONValue - 用于非类型化响应的原始 JSON 值

🇺🇸English

RivetKit Swift Client

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

Version

RivetKit version: 2.1.6

Error Handling Policy

Prefer fail-fast behavior by default.
Avoid broad do/catch unless absolutely needed.
If a catch block is used, handle the error explicitly, at minimum by logging it.

Install

Add the Swift package dependency and import RivetKitClient:

// 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

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

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

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()

Getting Actors

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:

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:

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()

Connection Parameters

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()

Subscribing to Events

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:

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

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()

Low-Level HTTP & WebSocket

For actors that implement onRequest or onWebSocket, you can call them directly:

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()

Calling from Backend

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

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()

Error Handling

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:

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()

Concepts

Keys

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

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.

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.

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.

API Reference

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

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

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

Types

ActorConnStatus - Connection status enum (.idle, .connecting, .connected, .disconnected, .disposed)
ActorError - Typed actor errors with group, code, message, metadata
- Raw JSON value for untyped responses

Need More Than the Client?

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

npx skills add rivet-dev/skills

Then use the rivetkit skill for backend guidance.

Weekly Installs

1.9K

Repository

rivet-dev/skills

GitHub Stars

First Seen

Jan 26, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

github-copilot1.9K

antigravity1.1K

codex1.1K

gemini-cli1.1K

opencode1.1K

claude-code1.1K

RivetKit Swift 客户端：连接 Rivet Actors 的 iOS/macOS 开发库

🇨🇳中文介绍

RivetKit Swift 客户端

版本

错误处理策略

安装

最小化客户端

端点 URL

相关 Skills

显式字段

无状态 vs 有状态

获取 Actors

连接参数

订阅事件

连接生命周期

底层 HTTP 和 WebSocket

从后端调用

错误处理

概念

键

环境变量

端点格式

API 参考

客户端

ActorHandle

ActorConnection

类型

需要更多关于客户端的信息？

🇺🇸English

RivetKit Swift Client

Version

Error Handling Policy

Install

Minimal Client

Endpoint URL

Explicit Fields

Stateless vs Stateful

Getting Actors

Connection Parameters

Subscribing to Events

Connection Lifecycle

Low-Level HTTP & WebSocket

Calling from Backend

Error Handling

Concepts

Keys

Environment Variables

Endpoint Format

API Reference

Client

ActorHandle

ActorConnection

Types

Need More Than the Client?

最新 Skills