kdletters
264453a714
更新 SpacetimeDB CLI、概念和 Rust 模块 skill 到 2.5 口径 删除 TypeScript、C# 和 Unity SpacetimeDB 本地 skill 同步 AGENTS 与 Hermes 决策记录中的 skill 维护范围 补充 2.2.0 到 2.5.0 项目相关差异和 event table 规则
281 lines
9.3 KiB
Markdown
281 lines
9.3 KiB
Markdown
---
|
|
name: spacetimedb-rust
|
|
description: Develop SpacetimeDB 2.5 server modules in Rust for Genarrative. Use when writing or reviewing tables, reducers, procedures, views, migrations, row mappers, schema changes, and module logic.
|
|
---
|
|
|
|
# SpacetimeDB Rust Module Development
|
|
|
|
Use this skill for Rust code in `server-rs/crates/spacetime-module` and related Genarrative schema/migration work.
|
|
|
|
## Genarrative Rules
|
|
|
|
- Keep domain rules in `module-*`; keep SpacetimeDB tables, reducers, procedures, views, mappers, and transaction adapters in `spacetime-module`.
|
|
- Existing table fields must be appended at the end with explicit defaults. Do not rename, remove, reorder, or change field types without a user-confirmed migration plan.
|
|
- After schema changes, update `migration.rs`, table catalog/docs, generated bindings, and run `npm run spacetime:generate` plus `npm run check:spacetime-schema`.
|
|
- Private tables are backend facts. Expose user-visible state through BFF endpoints/read models rather than direct client SQL.
|
|
|
|
## Hallucinated APIs: Do Not Use
|
|
|
|
```rust
|
|
#[derive(Table)] // Tables use #[table], not derive
|
|
#[derive(Reducer)] // Reducers use #[reducer], not derive
|
|
#[derive(SpacetimeType)] // Do not derive this on #[table] structs
|
|
|
|
pub fn reducer(ctx: &mut ReducerContext) {} // Use &ReducerContext
|
|
|
|
ctx.db.player // Use ctx.db.player()
|
|
ctx.db.player.find(id) // Use ctx.db.player().id().find(&id)
|
|
ctx.sender // Use ctx.sender()
|
|
ctx.db.user().name().update(..) // Update by primary key only
|
|
|
|
spacetimedb = { version = "...", features = ["unstable"] } // Not needed for procedures in 2.5
|
|
```
|
|
|
|
## Required Patterns
|
|
|
|
```rust
|
|
use spacetimedb::{reducer, table, Identity, ReducerContext, Table, Timestamp};
|
|
use spacetimedb::SpacetimeType; // Custom types only, not tables
|
|
|
|
#[table(accessor = player, public)]
|
|
pub struct Player {
|
|
#[primary_key]
|
|
#[auto_inc]
|
|
pub id: u64,
|
|
pub owner: Identity,
|
|
pub name: String,
|
|
pub created_at: Timestamp,
|
|
}
|
|
|
|
#[reducer]
|
|
pub fn create_player(ctx: &ReducerContext, name: String) -> Result<(), String> {
|
|
if name.trim().is_empty() {
|
|
return Err("name required".to_string());
|
|
}
|
|
ctx.db.player().try_insert(Player {
|
|
id: 0,
|
|
owner: ctx.sender(),
|
|
name,
|
|
created_at: ctx.timestamp,
|
|
})?;
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
Hard requirements:
|
|
|
|
- Import `Table` for table operations.
|
|
- Use `accessor = identifier`, not string literals.
|
|
- Use `ctx.sender()` for authorization.
|
|
- Use `ctx.rng()` / `ctx.random()` / `ctx.new_uuid_*()` for deterministic randomness and UUIDs.
|
|
- Use `Result<(), String>` for expected sender errors; avoid panics except impossible states.
|
|
- Use `try_insert()` in `Result` reducers when constraint violations should be reported cleanly.
|
|
|
|
## Tables
|
|
|
|
```rust
|
|
#[spacetimedb::table(accessor = game_tick_schedule, scheduled(game_tick))]
|
|
pub struct GameTickSchedule {
|
|
#[primary_key]
|
|
#[auto_inc]
|
|
pub scheduled_id: u64,
|
|
pub scheduled_at: ScheduleAt,
|
|
}
|
|
```
|
|
|
|
Table attributes:
|
|
|
|
| Attribute | Description |
|
|
|-----------|-------------|
|
|
| `accessor = identifier` | API name used in `ctx.db.{accessor}()` |
|
|
| `public` | Visible to clients via subscriptions |
|
|
| `event` | Transient event table |
|
|
| `scheduled(function_name)` | Schedule table that triggers a reducer/procedure |
|
|
| `index(accessor = idx, btree(columns = [a, b]))` | Multi-column index |
|
|
|
|
Column attributes:
|
|
|
|
| Attribute | Description |
|
|
|-----------|-------------|
|
|
| `#[primary_key]` | One primary key per table |
|
|
| `#[auto_inc]` | Auto-generates integer values when inserting `0` |
|
|
| `#[unique]` | Unique constraint and `find()` accessor |
|
|
| `#[index(btree)]` | B-tree index and `filter()` accessor |
|
|
| `#[default(...)]` | Required for new fields on existing Genarrative tables |
|
|
|
|
## Genarrative Schema Change Pattern
|
|
|
|
```rust
|
|
#[spacetimedb::table(accessor = creation_entry_config, public)]
|
|
pub struct CreationEntryConfig {
|
|
#[primary_key]
|
|
pub id: u64,
|
|
pub existing_field: String,
|
|
|
|
// Append new fields at the end and provide a default.
|
|
#[default(false)]
|
|
pub new_flag: bool,
|
|
}
|
|
```
|
|
|
|
Then update `migration.rs`, table catalog/docs, generated bindings, and run:
|
|
|
|
```bash
|
|
npm run spacetime:generate
|
|
npm run check:spacetime-schema
|
|
```
|
|
|
|
## Table Operations
|
|
|
|
```rust
|
|
let row = ctx.db.player().insert(Player { id: 0, owner, name, created_at });
|
|
ctx.db.player().try_insert(row)?;
|
|
|
|
let by_id = ctx.db.player().id().find(&123u64);
|
|
for player in ctx.db.player().owner().filter(&ctx.sender()) {}
|
|
for player in ctx.db.player().level().filter(&(18u32..=65u32)) {}
|
|
for player in ctx.db.player().iter() {}
|
|
let count = ctx.db.player().count();
|
|
|
|
if let Some(player) = ctx.db.player().id().find(&id) {
|
|
ctx.db.player().id().update(Player { name: new_name, ..player });
|
|
}
|
|
|
|
ctx.db.player().id().delete(&id);
|
|
```
|
|
|
|
For delete/update based on non-PK filters, collect keys first to avoid iterator invalidation.
|
|
|
|
## Indexes
|
|
|
|
```rust
|
|
#[spacetimedb::table(
|
|
accessor = score,
|
|
public,
|
|
index(accessor = by_player_level, btree(columns = [player_id, level]))
|
|
)]
|
|
pub struct Score {
|
|
pub player_id: u32,
|
|
pub level: u32,
|
|
pub points: i64,
|
|
}
|
|
|
|
for row in ctx.db.score().by_player_level().filter(&(42,)) {}
|
|
for row in ctx.db.score().by_player_level().filter(&(42, 5)) {}
|
|
```
|
|
|
|
## Event Tables
|
|
|
|
```rust
|
|
#[table(accessor = damage_event, public, event)]
|
|
pub struct DamageEvent {
|
|
pub target: Identity,
|
|
pub amount: u32,
|
|
}
|
|
|
|
#[reducer]
|
|
fn deal_damage(ctx: &ReducerContext, target: Identity, amount: u32) {
|
|
ctx.db.damage_event().insert(DamageEvent { target, amount });
|
|
}
|
|
```
|
|
|
|
Event tables must be subscribed explicitly and are excluded from `subscribe_to_all_tables()`.
|
|
|
|
In 2.5, event tables support broader layout-altering automigrations than regular tables, including column removal, reordering, and type changes. This relaxed migration policy does not apply to persistent tables.
|
|
|
|
Event-table primary keys and constraints are enforced only within the current transaction. They do not make event rows persistent, and client SDKs expose event tables as insert-only event streams. Do not rely on `OnUpdate` / `on_update` / `onUpdate` for event tables; use a persistent table or a primary-keyed procedural view when update callbacks are required.
|
|
|
|
Official 2.4.1/2.5 release notes tie primary-key-backed update callbacks to procedural views, not event tables.
|
|
|
|
## Views
|
|
|
|
```rust
|
|
#[spacetimedb::view(accessor = my_players, public, primary_key = id)]
|
|
pub fn my_players(ctx: &spacetimedb::ViewContext) -> Vec<Player> {
|
|
ctx.db.player().owner().filter(&ctx.sender()).collect()
|
|
}
|
|
```
|
|
|
|
Rust and TypeScript gained primary key support for procedural views in 2.4.1. With primary keys, clients can receive update events when subscribed to such views. Avoid duplicate primary keys in view results.
|
|
|
|
## Lifecycle & Scheduled Reducers
|
|
|
|
```rust
|
|
#[spacetimedb::reducer(init)]
|
|
pub fn init(ctx: &ReducerContext) -> Result<(), String> { Ok(()) }
|
|
|
|
#[spacetimedb::reducer(client_connected)]
|
|
pub fn on_connect(ctx: &ReducerContext) -> Result<(), String> { Ok(()) }
|
|
|
|
#[spacetimedb::reducer(client_disconnected)]
|
|
pub fn on_disconnect(ctx: &ReducerContext) -> Result<(), String> { Ok(()) }
|
|
|
|
use spacetimedb::{ScheduleAt, TimeDuration};
|
|
|
|
ctx.db.game_tick_schedule().insert(GameTickSchedule {
|
|
scheduled_id: 0,
|
|
scheduled_at: ScheduleAt::Interval(std::time::Duration::from_millis(100).into()),
|
|
});
|
|
|
|
let run_at = ctx.timestamp + std::time::Duration::from_secs(60);
|
|
ctx.db.game_tick_schedule().insert(GameTickSchedule {
|
|
scheduled_id: 0,
|
|
scheduled_at: ScheduleAt::Time(run_at),
|
|
});
|
|
```
|
|
|
|
For scheduled reducers, check `ctx.sender_auth().is_internal()` when the reducer should only be system-triggered.
|
|
|
|
## Procedures
|
|
|
|
Procedures are stable in 2.5 and no longer require the `unstable` feature.
|
|
|
|
```rust
|
|
use spacetimedb::{procedure, ProcedureContext};
|
|
|
|
#[procedure]
|
|
fn save_external_data(ctx: &mut ProcedureContext, url: String) -> Result<(), String> {
|
|
let body = ctx.http.get(url).send()?.text()?;
|
|
ctx.try_with_tx(|tx| {
|
|
tx.db.external_data().insert(ExternalData { id: 0, content: body });
|
|
Ok(())
|
|
})?;
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
| Reducers | Procedures |
|
|
|----------|------------|
|
|
| `&ReducerContext` | `&mut ProcedureContext` |
|
|
| Direct `ctx.db` access | Use `with_tx()` / `try_with_tx()` |
|
|
| No HTTP/network | Outgoing HTTP via `ctx.http` |
|
|
| Deterministic transaction path | Side-effect-capable workflow path |
|
|
|
|
In Genarrative, keep external provider protocols in `platform-*` by default unless the architecture explicitly moves that workflow into the module.
|
|
|
|
## Identity & Auth
|
|
|
|
```rust
|
|
fn require_owner(ctx: &ReducerContext, owner: &Identity) -> Result<(), String> {
|
|
if ctx.sender() != *owner {
|
|
return Err("Not authorized".to_string());
|
|
}
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
`ReducerContext::identity` is deprecated since 2.3; use the current database/module identity API when needed, and use `ctx.sender()` for caller identity.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
spacetime build
|
|
spacetime publish my_database --server http://127.0.0.1:3101 --module-path . --yes=migrate
|
|
spacetime publish my_database --server http://127.0.0.1:3101 --delete-data=on-conflict --module-path . --yes=migrate
|
|
spacetime logs my_database --server http://127.0.0.1:3101
|
|
spacetime call --server http://127.0.0.1:3101 my_database create_player '"Alice"'
|
|
spacetime sql my_database --server http://127.0.0.1:3101 "SELECT * FROM player"
|
|
npm run spacetime:generate
|
|
npm run check:spacetime-schema
|
|
```
|