更新 SpacetimeDB 本地技能
更新 SpacetimeDB CLI、概念和 Rust 模块 skill 到 2.5 口径 删除 TypeScript、C# 和 Unity SpacetimeDB 本地 skill 同步 AGENTS 与 Hermes 决策记录中的 skill 维护范围 补充 2.2.0 到 2.5.0 项目相关差异和 event table 规则
This commit is contained in:
@@ -1,312 +1,170 @@
|
||||
---
|
||||
name: spacetimedb-rust
|
||||
description: Develop SpacetimeDB server modules in Rust. Use when writing reducers, tables, or module logic.
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
author: clockworklabs
|
||||
version: "2.0"
|
||||
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
|
||||
|
||||
SpacetimeDB modules are WebAssembly applications that run inside the database. They define tables to store data and reducers to modify data. Clients connect directly to the database and execute application logic inside it.
|
||||
Use this skill for Rust code in `server-rs/crates/spacetime-module` and related Genarrative schema/migration work.
|
||||
|
||||
> **Tested with:** SpacetimeDB 2.0+ APIs
|
||||
## 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
|
||||
|
||||
**These APIs/patterns are incorrect. LLMs frequently hallucinate them.**
|
||||
|
||||
Both macro forms are valid in 2.0: `#[spacetimedb::table(...)]` / `#[table(...)]` and `#[spacetimedb::reducer]` / `#[reducer]`.
|
||||
## Hallucinated APIs: Do Not Use
|
||||
|
||||
```rust
|
||||
#[derive(Table)] // Tables use #[table] attribute, not derive
|
||||
#[derive(Reducer)] // Reducers use #[reducer] attribute
|
||||
#[derive(Table)] // Tables use #[table], not derive
|
||||
#[derive(Reducer)] // Reducers use #[reducer], not derive
|
||||
#[derive(SpacetimeType)] // Do not derive this on #[table] structs
|
||||
|
||||
// WRONG — SpacetimeType on tables
|
||||
#[derive(SpacetimeType)] // DO NOT use on #[table] structs!
|
||||
#[table(accessor = my_table)]
|
||||
pub struct MyTable { ... }
|
||||
pub fn reducer(ctx: &mut ReducerContext) {} // Use &ReducerContext
|
||||
|
||||
// WRONG — mutable context
|
||||
pub fn my_reducer(ctx: &mut ReducerContext, ...) { } // Should be &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
|
||||
|
||||
// WRONG — table access without parentheses
|
||||
ctx.db.player // Should be ctx.db.player()
|
||||
ctx.db.player.find(id) // Should be ctx.db.player().id().find(&id)
|
||||
|
||||
// WRONG — old 1.0 patterns
|
||||
ctx.sender // Use ctx.sender() — method, not field (2.0)
|
||||
.with_module_name("db") // Use .with_database_name() (2.0)
|
||||
ctx.db.user().name().update(..) // Update only via primary key (2.0)
|
||||
spacetimedb = { version = "...", features = ["unstable"] } // Not needed for procedures in 2.5
|
||||
```
|
||||
|
||||
### CORRECT PATTERNS:
|
||||
## Required Patterns
|
||||
|
||||
```rust
|
||||
use spacetimedb::{table, reducer, Table, ReducerContext, Identity, Timestamp};
|
||||
use spacetimedb::SpacetimeType; // Only for custom types, NOT tables
|
||||
use spacetimedb::{reducer, table, Identity, ReducerContext, Table, Timestamp};
|
||||
use spacetimedb::SpacetimeType; // Custom types only, not tables
|
||||
|
||||
// CORRECT TABLE — accessor, not name; no SpacetimeType derive!
|
||||
#[table(accessor = player, public)]
|
||||
pub struct Player {
|
||||
#[primary_key]
|
||||
pub id: u64,
|
||||
pub name: String,
|
||||
}
|
||||
|
||||
// CORRECT REDUCER — immutable context, sender() is a method
|
||||
#[reducer]
|
||||
pub fn create_player(ctx: &ReducerContext, name: String) {
|
||||
ctx.db.player().insert(Player { id: 0, name });
|
||||
}
|
||||
|
||||
// CORRECT TABLE ACCESS — methods with parentheses, sender() method
|
||||
let player = ctx.db.player().id().find(&player_id);
|
||||
let caller = ctx.sender();
|
||||
```
|
||||
|
||||
### DO NOT:
|
||||
- **Derive `SpacetimeType` on `#[table]` structs** — the macro handles this
|
||||
- **Use mutable context** — `&ReducerContext`, not `&mut ReducerContext`
|
||||
- **Forget `Table` trait import** — required for table operations
|
||||
- **Use field access for tables** — `ctx.db.player()` not `ctx.db.player`
|
||||
- **Use `ctx.sender`** — it's `ctx.sender()` (method) in 2.0
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes Table
|
||||
|
||||
| Wrong | Right | Error |
|
||||
|-------|-------|-------|
|
||||
| `#[table(accessor = "my_table")]` | `#[table(accessor = my_table)]` | String literals not allowed |
|
||||
| Missing `public` on table | Add `public` flag | Clients can't subscribe |
|
||||
| Network/filesystem in reducer | Use procedures instead | Sandbox violation |
|
||||
| Panic for expected errors | Return `Result<(), String>` | WASM instance destroyed |
|
||||
|
||||
---
|
||||
|
||||
## Hard Requirements
|
||||
|
||||
1. **DO NOT derive `SpacetimeType` on `#[table]` structs** — the macro handles this
|
||||
2. **Import `Table` trait** — required for all table operations
|
||||
3. **Use `&ReducerContext`** — not `&mut ReducerContext`
|
||||
4. **Tables are methods** — `ctx.db.table()` not `ctx.db.table`
|
||||
5. **Use `ctx.sender()`** — method call, not field access (2.0)
|
||||
6. **Use `accessor =` for API handles** — `name = "..."` is optional canonical naming in table/index attributes
|
||||
7. **Reducers must be deterministic** — no filesystem, network, timers, or external RNG
|
||||
8. **Use `ctx.rng()`** — not `rand` crate for random numbers
|
||||
9. **Add `public` flag** — if clients need to subscribe to a table
|
||||
10. **Update only via primary key** — use delete+insert for non-PK changes (2.0)
|
||||
|
||||
---
|
||||
|
||||
## Project Setup
|
||||
|
||||
```toml
|
||||
[package]
|
||||
name = "my-module"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
|
||||
[lib]
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
spacetimedb = { workspace = true }
|
||||
log = "0.4"
|
||||
```
|
||||
|
||||
### Essential Imports
|
||||
|
||||
```rust
|
||||
use spacetimedb::{ReducerContext, Table};
|
||||
use spacetimedb::{Identity, Timestamp, ConnectionId, ScheduleAt};
|
||||
```
|
||||
|
||||
## Table Definitions
|
||||
|
||||
```rust
|
||||
#[spacetimedb::table(accessor = player, public)]
|
||||
pub struct Player {
|
||||
#[primary_key]
|
||||
#[auto_inc]
|
||||
id: u64,
|
||||
name: String,
|
||||
score: u32,
|
||||
pub id: u64,
|
||||
pub owner: Identity,
|
||||
pub name: String,
|
||||
pub created_at: Timestamp,
|
||||
}
|
||||
```
|
||||
|
||||
### Table Attributes
|
||||
|
||||
| Attribute | Description |
|
||||
|-----------|-------------|
|
||||
| `accessor = identifier` | Required. The API name used in `ctx.db.{accessor}()` |
|
||||
| `public` | Makes table visible to clients via subscriptions |
|
||||
| `scheduled(function_name)` | Creates a schedule table that triggers the named reducer or procedure |
|
||||
| `index(accessor = idx, btree(columns = [a, b]))` | Multi-column index |
|
||||
|
||||
### Column Attributes
|
||||
|
||||
| Attribute | Description |
|
||||
|-----------|-------------|
|
||||
| `#[primary_key]` | Unique identifier for the row (one per table max) |
|
||||
| `#[unique]` | Enforces uniqueness, enables `find()` method |
|
||||
| `#[auto_inc]` | Auto-generates unique integer values when inserting 0 |
|
||||
| `#[index(btree)]` | Creates a B-tree index for efficient lookups |
|
||||
|
||||
### Supported Column Types
|
||||
|
||||
**Primitives**: `u8`-`u256`, `i8`-`i256`, `f32`, `f64`, `bool`, `String`
|
||||
|
||||
**SpacetimeDB Types**: `Identity`, `ConnectionId`, `Timestamp`, `Uuid`, `ScheduleAt`
|
||||
|
||||
**Collections**: `Vec<T>`, `Option<T>`, `Result<T, E>`
|
||||
|
||||
**Custom Types**: Any struct/enum with `#[derive(SpacetimeType)]`
|
||||
|
||||
---
|
||||
|
||||
## Reducers
|
||||
|
||||
```rust
|
||||
#[spacetimedb::reducer]
|
||||
#[reducer]
|
||||
pub fn create_player(ctx: &ReducerContext, name: String) -> Result<(), String> {
|
||||
if name.is_empty() {
|
||||
return Err("Name cannot be empty".to_string());
|
||||
if name.trim().is_empty() {
|
||||
return Err("name required".to_string());
|
||||
}
|
||||
ctx.db.player().insert(Player { id: 0, name, score: 0 });
|
||||
ctx.db.player().try_insert(Player {
|
||||
id: 0,
|
||||
owner: ctx.sender(),
|
||||
name,
|
||||
created_at: ctx.timestamp,
|
||||
})?;
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### Reducer Rules
|
||||
Hard requirements:
|
||||
|
||||
1. First parameter must be `&ReducerContext`
|
||||
2. Return `()`, `Result<(), String>`, or `Result<(), E>` where `E: Display`
|
||||
3. All changes roll back on panic or `Err` return
|
||||
4. Must import `Table` trait: `use spacetimedb::Table;`
|
||||
- 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.
|
||||
|
||||
### ReducerContext
|
||||
## Tables
|
||||
|
||||
```rust
|
||||
ctx.db // Database access
|
||||
ctx.sender() // Identity of the caller (method, not field!)
|
||||
ctx.connection_id() // Option<ConnectionId> (None for scheduled/system reducers)
|
||||
ctx.timestamp // Invocation timestamp
|
||||
ctx.identity() // Module's own identity
|
||||
ctx.rng() // Deterministic RNG (method, not field!)
|
||||
#[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
|
||||
|
||||
### Insert
|
||||
|
||||
```rust
|
||||
// Insert returns the row with auto_inc values populated
|
||||
let player = ctx.db.player().insert(Player { id: 0, name: "Alice".into(), score: 100 });
|
||||
log::info!("Created player with id: {}", player.id);
|
||||
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);
|
||||
```
|
||||
|
||||
### Find and Filter
|
||||
|
||||
```rust
|
||||
// Find by unique/primary key — returns Option
|
||||
if let Some(player) = ctx.db.player().id().find(&123) {
|
||||
log::info!("Found: {}", player.name);
|
||||
}
|
||||
|
||||
// Optional clarity: typed literals can avoid inference ambiguity
|
||||
if let Some(player) = ctx.db.player().id().find(&123u64) {
|
||||
log::info!("Found: {}", player.name);
|
||||
}
|
||||
|
||||
// Filter by indexed column — returns iterator
|
||||
for player in ctx.db.player().name().filter(&"Alice".to_string()) {
|
||||
log::info!("Player: {}", player.name);
|
||||
}
|
||||
|
||||
// Full table scan
|
||||
for player in ctx.db.player().iter() { }
|
||||
let total = ctx.db.player().count();
|
||||
```
|
||||
|
||||
### Update
|
||||
|
||||
```rust
|
||||
// Update via primary key (2.0: only primary key has update)
|
||||
if let Some(player) = ctx.db.player().id().find(&123) {
|
||||
ctx.db.player().id().update(Player { score: player.score + 10, ..player });
|
||||
}
|
||||
|
||||
// For non-PK changes: delete + insert
|
||||
if let Some(old) = ctx.db.player().id().find(&id) {
|
||||
ctx.db.player().id().delete(&id);
|
||||
ctx.db.player().insert(Player { name: new_name, ..old });
|
||||
}
|
||||
```
|
||||
|
||||
### Delete
|
||||
|
||||
```rust
|
||||
// Delete by primary key
|
||||
ctx.db.player().id().delete(&123);
|
||||
|
||||
// Delete by indexed column (collect first to avoid iterator invalidation)
|
||||
let to_remove: Vec<u64> = ctx.db.player().name().filter(&"Alice".to_string())
|
||||
.map(|p| p.id)
|
||||
.collect();
|
||||
for id in to_remove {
|
||||
ctx.db.player().id().delete(&id);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
For delete/update based on non-PK filters, collect keys first to avoid iterator invalidation.
|
||||
|
||||
## Indexes
|
||||
|
||||
```rust
|
||||
// Single-column index
|
||||
#[spacetimedb::table(accessor = player, public)]
|
||||
pub struct Player {
|
||||
#[primary_key]
|
||||
id: u64,
|
||||
#[index(btree)]
|
||||
level: u32,
|
||||
name: String,
|
||||
}
|
||||
|
||||
// Multi-column index
|
||||
#[spacetimedb::table(
|
||||
accessor = score, public,
|
||||
accessor = score,
|
||||
public,
|
||||
index(accessor = by_player_level, btree(columns = [player_id, level]))
|
||||
)]
|
||||
pub struct Score {
|
||||
player_id: u32,
|
||||
level: u32,
|
||||
points: i64,
|
||||
pub player_id: u32,
|
||||
pub level: u32,
|
||||
pub points: i64,
|
||||
}
|
||||
|
||||
// Multi-column index querying: prefix match (first column only)
|
||||
for s in ctx.db.score().by_player_level().filter(&(42,)) {
|
||||
log::info!("Player 42, any level: {} pts", s.points);
|
||||
}
|
||||
|
||||
// Full match (both columns)
|
||||
for s in ctx.db.score().by_player_level().filter(&(42, 5)) {
|
||||
log::info!("Player 42, level 5: {} pts", s.points);
|
||||
}
|
||||
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 (2.0)
|
||||
|
||||
Reducer callbacks are removed in 2.0. Use event tables + `on_insert` instead.
|
||||
## Event Tables
|
||||
|
||||
```rust
|
||||
#[table(accessor = damage_event, public, event)]
|
||||
@@ -321,182 +179,65 @@ fn deal_damage(ctx: &ReducerContext, target: Identity, amount: u32) {
|
||||
}
|
||||
```
|
||||
|
||||
Client subscribes and uses `on_insert`:
|
||||
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
|
||||
conn.db.damage_event().on_insert(|ctx, event| {
|
||||
play_damage_animation(event.target, event.amount);
|
||||
});
|
||||
#[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()
|
||||
}
|
||||
```
|
||||
|
||||
Event tables must be subscribed explicitly — they are excluded from `subscribe_to_all_tables()`.
|
||||
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 Reducers
|
||||
## Lifecycle & Scheduled Reducers
|
||||
|
||||
```rust
|
||||
#[spacetimedb::reducer(init)]
|
||||
pub fn init(ctx: &ReducerContext) -> Result<(), String> {
|
||||
log::info!("Database initializing...");
|
||||
ctx.db.config().insert(Config {
|
||||
id: 0,
|
||||
max_players: 100,
|
||||
game_mode: "default".to_string(),
|
||||
});
|
||||
Ok(())
|
||||
}
|
||||
pub fn init(ctx: &ReducerContext) -> Result<(), String> { Ok(()) }
|
||||
|
||||
#[spacetimedb::reducer(client_connected)]
|
||||
pub fn on_connect(ctx: &ReducerContext) -> Result<(), String> {
|
||||
let caller = ctx.sender();
|
||||
log::info!("Client connected: {}", caller);
|
||||
|
||||
if let Some(user) = ctx.db.user().identity().find(&caller) {
|
||||
ctx.db.user().identity().update(User { online: true, ..user });
|
||||
} else {
|
||||
ctx.db.user().insert(User {
|
||||
identity: caller,
|
||||
name: format!("User-{}", &caller.to_hex()[..8]),
|
||||
online: true,
|
||||
});
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
pub fn on_connect(ctx: &ReducerContext) -> Result<(), String> { Ok(()) }
|
||||
|
||||
#[spacetimedb::reducer(client_disconnected)]
|
||||
pub fn on_disconnect(ctx: &ReducerContext) -> Result<(), String> {
|
||||
let caller = ctx.sender();
|
||||
if let Some(user) = ctx.db.user().identity().find(&caller) {
|
||||
ctx.db.user().identity().update(User { online: false, ..user });
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
pub fn on_disconnect(ctx: &ReducerContext) -> Result<(), String> { Ok(()) }
|
||||
|
||||
---
|
||||
use spacetimedb::{ScheduleAt, TimeDuration};
|
||||
|
||||
## Scheduled Reducers
|
||||
|
||||
```rust
|
||||
use spacetimedb::ScheduleAt;
|
||||
use std::time::Duration;
|
||||
|
||||
#[spacetimedb::table(accessor = game_tick_schedule, scheduled(game_tick))]
|
||||
pub struct GameTickSchedule {
|
||||
#[primary_key]
|
||||
#[auto_inc]
|
||||
scheduled_id: u64,
|
||||
scheduled_at: ScheduleAt,
|
||||
}
|
||||
|
||||
#[spacetimedb::reducer]
|
||||
fn game_tick(ctx: &ReducerContext, schedule: GameTickSchedule) {
|
||||
if !ctx.sender_auth().is_internal() { return; }
|
||||
log::info!("Game tick at {:?}", ctx.timestamp);
|
||||
}
|
||||
|
||||
// Schedule at interval (e.g., in init reducer)
|
||||
ctx.db.game_tick_schedule().insert(GameTickSchedule {
|
||||
scheduled_id: 0,
|
||||
scheduled_at: ScheduleAt::Interval(Duration::from_millis(100).into()),
|
||||
scheduled_at: ScheduleAt::Interval(std::time::Duration::from_millis(100).into()),
|
||||
});
|
||||
|
||||
// Schedule at specific time
|
||||
let run_at = ctx.timestamp + Duration::from_secs(delay_secs);
|
||||
ctx.db.reminder_schedule().insert(ReminderSchedule {
|
||||
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.
|
||||
|
||||
## Identity and Authentication
|
||||
## Procedures
|
||||
|
||||
```rust
|
||||
#[spacetimedb::table(accessor = user, public)]
|
||||
pub struct User {
|
||||
#[primary_key]
|
||||
identity: Identity,
|
||||
name: String,
|
||||
online: bool,
|
||||
}
|
||||
|
||||
#[spacetimedb::reducer]
|
||||
pub fn set_name(ctx: &ReducerContext, new_name: String) -> Result<(), String> {
|
||||
let caller = ctx.sender();
|
||||
let user = ctx.db.user().identity().find(&caller)
|
||||
.ok_or("User not found — connect first")?;
|
||||
ctx.db.user().identity().update(User { name: new_name, ..user });
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### Owner-Only Reducer Pattern
|
||||
|
||||
```rust
|
||||
fn require_owner(ctx: &ReducerContext, entity_owner: &Identity) -> Result<(), String> {
|
||||
if ctx.sender() != *entity_owner {
|
||||
Err("Not authorized: you don't own this entity".to_string())
|
||||
} else {
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
#[spacetimedb::reducer]
|
||||
pub fn rename_character(ctx: &ReducerContext, char_id: u64, new_name: String) -> Result<(), String> {
|
||||
let character = ctx.db.character().id().find(&char_id)
|
||||
.ok_or("Character not found")?;
|
||||
require_owner(ctx, &character.owner)?;
|
||||
ctx.db.character().id().update(Character { name: new_name, ..character });
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
```rust
|
||||
// Sender error — return Err (user sees message, transaction rolls back cleanly)
|
||||
#[spacetimedb::reducer]
|
||||
pub fn transfer(ctx: &ReducerContext, to: Identity, amount: u64) -> Result<(), String> {
|
||||
let sender = ctx.db.wallet().identity().find(&ctx.sender())
|
||||
.ok_or("Wallet not found")?;
|
||||
if sender.balance < amount {
|
||||
return Err("Insufficient balance".to_string());
|
||||
}
|
||||
// ... proceed with transfer
|
||||
Ok(())
|
||||
}
|
||||
|
||||
// Programmer error — panic (destroys the WASM instance, expensive!)
|
||||
// Only use for truly impossible states
|
||||
#[spacetimedb::reducer]
|
||||
pub fn process(ctx: &ReducerContext, id: u64) {
|
||||
let item = ctx.db.item().id().find(&id)
|
||||
.expect("BUG: item should exist at this point");
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Prefer `Result<(), String>` for all expected failure cases. Panics destroy and recreate the WASM instance.
|
||||
|
||||
---
|
||||
|
||||
## Procedures (Beta)
|
||||
|
||||
> Procedures are behind the `unstable` feature in `spacetimedb`.
|
||||
> In `Cargo.toml`: `spacetimedb = { version = "...", features = ["unstable"] }`
|
||||
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 data = fetch_from_url(&url)?;
|
||||
let body = ctx.http.get(url).send()?.text()?;
|
||||
ctx.try_with_tx(|tx| {
|
||||
tx.db.external_data().insert(ExternalData { id: 0, content: data });
|
||||
tx.db.external_data().insert(ExternalData { id: 0, content: body });
|
||||
Ok(())
|
||||
})?;
|
||||
Ok(())
|
||||
@@ -505,52 +246,35 @@ fn save_external_data(ctx: &mut ProcedureContext, url: String) -> Result<(), Str
|
||||
|
||||
| Reducers | Procedures |
|
||||
|----------|------------|
|
||||
| `&ReducerContext` (immutable) | `&mut ProcedureContext` (mutable) |
|
||||
| Direct `ctx.db` access | Must use `ctx.with_tx()` |
|
||||
| No HTTP/network | HTTP allowed |
|
||||
| No return values | Can return data |
|
||||
| `&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.
|
||||
|
||||
## Custom Types
|
||||
## Identity & Auth
|
||||
|
||||
```rust
|
||||
use spacetimedb::SpacetimeType;
|
||||
|
||||
#[derive(SpacetimeType)]
|
||||
pub enum PlayerStatus { Active, Idle, Away }
|
||||
|
||||
#[derive(SpacetimeType)]
|
||||
pub struct Position { x: f32, y: f32, z: f32 }
|
||||
|
||||
// Use in table (DO NOT derive SpacetimeType on the table!)
|
||||
#[spacetimedb::table(accessor = player, public)]
|
||||
pub struct Player {
|
||||
#[primary_key]
|
||||
id: u64,
|
||||
status: PlayerStatus,
|
||||
position: Position,
|
||||
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 --module-path .
|
||||
spacetime publish my_database --clear-database --module-path .
|
||||
spacetime logs my_database
|
||||
spacetime call my_database create_player "Alice"
|
||||
spacetime sql my_database "SELECT * FROM player"
|
||||
spacetime generate --lang rust --out-dir <client>/src/module_bindings --module-path <backend-dir>
|
||||
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
|
||||
```
|
||||
|
||||
## Important Constraints
|
||||
|
||||
1. **No Global State**: Static/global variables are undefined behavior across reducer calls
|
||||
2. **No Side Effects**: Reducers cannot make network requests or file I/O
|
||||
3. **Deterministic Execution**: Use `ctx.rng()` and `ctx.new_uuid_*()` for randomness
|
||||
4. **Transactional**: All reducer changes roll back on failure
|
||||
5. **Isolated**: Reducers don't see concurrent changes until commit
|
||||
|
||||
Reference in New Issue
Block a user