git clone https://github.com/cosmictron/cosmictron.git
cd cosmictron
cargo build --release

cargo run --release -p cosmictron-server

# Create a new Rust library
mkdir hello-cosmictron
cd hello-cosmictron
cargo init --lib

# Add Cosmictron SDK dependency
cat >> Cargo.toml << 'EOF'
[dependencies]
cosmictron-sdk = { path = "../cosmictron/crates/cosmictron-sdk" }
EOF

use cosmictron_sdk::prelude::*;
use cosmictron_sdk::datastore;
use cosmictron_sdk::query::find_first;

// Derive macros automatically handle BSATN serialization
// Saves ~50 lines of boilerplate code!
#[derive(BsatnSerialize, BsatnDeserialize)]
#[table(name = "counter")]
pub struct Counter {
    #[primary_key]
    pub id: u32,
    pub value: i64,
    pub updated_at: u64,
}

// Initialize the counter when the module loads
#[reducer(init)]
pub fn initialize() {
    // Check if counter exists using Query API
    if find_first("counter", |_c: &Counter| true).is_none() {
        // Create initial counter
        let counter = Counter {
            id: 1,
            value: 0,
            updated_at: now_ms(),
        };
        datastore::insert(&counter).ok();
        info("Counter initialized to 0");
    }
}

// Increment the counter
#[reducer]
pub fn increment() {
    // Find the counter using Query API
    if let Some(mut counter) = find_first("counter", |c: &Counter| c.id == 1) {
        counter.value += 1;
        counter.updated_at = now_ms();
        datastore::update(&counter).ok();
        info(&format!("Counter incremented to {}", counter.value));
    }
}

// Decrement the counter
#[reducer]
pub fn decrement() {
    if let Some(mut counter) = find_first("counter", |c: &Counter| c.id == 1) {
        counter.value -= 1;
        counter.updated_at = now_ms();
        datastore::update(&counter).ok();
        info(&format!("Counter decremented to {}", counter.value));
    }
}

// Export the module
describe_module!(
    tables = [Counter],
    reducers = [initialize, increment, decrement]
);

cargo build --target wasm32-unknown-unknown --release

cosmictron deploy target/wasm32-unknown-unknown/release/counter.wasm

import { CosmictronClient } from '@cosmictron/client';

const client = new CosmictronClient('ws://localhost:8080');
await client.connect();

// Call a reducer
await client.callReducer('counter', 'increment', {});

// Subscribe to changes
const sub = await client.subscribe(
  'SELECT * FROM counter',
  (delta) => console.log('Updated:', delta)
);

# Clone the repository
git clone https://github.com/cosmictron/cosmictron.git
cd cosmictron

# Build in release mode
cargo build --release

# Install the CLI globally
cargo install --path crates/cosmictron-cli

cargo install cosmictron

# Using Bun (recommended)
bun add @cosmictron/client

# Using npm
npm install @cosmictron/client

rustup target add wasm32-unknown-unknown

# Check server builds
cargo build -p cosmictron-server

# Run all tests
cargo test --workspace

# Check TypeScript SDK
cd clients/typescript && bun test

use cosmictron_sdk::prelude::*;
use cosmictron_sdk::datastore;
use cosmictron_sdk::query::{find_first, exists};

// Derive macros automatically implement BSATN serialization
// No more manual serialize/deserialize functions!
#[derive(BsatnSerialize, BsatnDeserialize)]
#[table(name = "users")]
pub struct User {
    #[primary_key]
    #[auto_inc]  // ID assigned automatically on insert
    pub id: u64,
    #[unique]
    pub username: String,
    pub display_name: String,
    pub identity: Identity,  // Store caller's identity
    pub created_at: u64,
    pub last_seen: u64,
}

#[derive(BsatnSerialize, BsatnDeserialize)]
#[table(name = "channels")]
pub struct Channel {
    #[primary_key]
    #[auto_inc]
    pub id: u64,
    #[unique]
    pub name: String,
    pub description: String,
    pub created_by: u64,
    pub is_private: bool,
}

#[derive(BsatnSerialize, BsatnDeserialize)]
#[table(name = "channel_members")]
pub struct ChannelMember {
    #[primary_key]
    #[auto_inc]
    pub id: u64,
    #[index]
    pub channel_id: u64,
    #[index]
    pub user_id: u64,
    pub joined_at: u64,
}

#[derive(BsatnSerialize, BsatnDeserialize)]
#[table(name = "messages", event)]
pub struct Message {
    #[primary_key]
    #[auto_inc]
    pub id: u64,
    #[index]
    pub channel_id: u64,
    pub user_id: u64,
    pub content: String,
    pub timestamp: u64,
    pub edited: bool,
}

// Find user by their identity (32-byte public key)
fn find_user_by_identity(identity: &Identity) -> Option<User> {
    find_first("users", |u: &User| u.identity == *identity)
}

// Find channel by name
fn find_channel_by_name(name: &str) -> Option<Channel> {
    find_first("channels", |c: &Channel| c.name == name)
}

// Check if user is a member of a channel
fn is_channel_member(channel_id: u64, user_id: u64) -> bool {
    exists("channel_members", |m: &ChannelMember| {
        m.channel_id == channel_id && m.user_id == user_id
    })
}

#[reducer]
pub fn register_user(username: String, display_name: String) -> Result<u64, String> {
    // Validate input
    if username.is_empty() || username.len() > 32 {
        return Err("Username must be 1-32 characters".into());
    }
    
    // Check if username already exists using Query API
    if find_channel_by_name(&username).is_some() {
        return Err("Username already taken".into());
    }
    
    // Check if user already registered with this identity
    let identity = caller_identity();
    if let Some(user) = find_user_by_identity(&identity) {
        return Ok(user.id);
    }

    // Create new user - ID will be auto-assigned
    let now = now_ms();
    let user = User {
        id: 0,  // auto_inc will assign this
        username: username.clone(),
        display_name,
        identity,
        created_at: now,
        last_seen: now,
    };
    
    let id = datastore::insert(&user)
        .map_err(|_| "Failed to create user")?;
    
    info(&format!("User '{}' registered with id {}", username, id));
    Ok(id)
}

#[reducer]
pub fn create_channel(name: String, description: String) -> Result<u64, String> {
    // Validate
    if name.is_empty() || name.len() > 48 {
        return Err("Channel name must be 1-48 characters".into());
    }
    
    // Check for duplicate name
    if find_channel_by_name(&name).is_some() {
        return Err("Channel name already exists".into());
    }
    
    // Get current user
    let identity = caller_identity();
    let user = find_user_by_identity(&identity)
        .ok_or("User not registered")?;

    // Create channel
    let channel = Channel {
        id: 0,
        name: name.clone(),
        description,
        created_by: user.id,
        is_private: false,
    };
    
    let channel_id = datastore::insert(&channel)
        .map_err(|_| "Failed to create channel")?;
    
    // Add creator as first member
    let member = ChannelMember {
        id: 0,
        channel_id,
        user_id: user.id,
        joined_at: now_ms(),
    };
    datastore::insert(&member).ok();
    
    info(&format!("Channel '{}' created", name));
    Ok(channel_id)
}

#[reducer]
pub fn send_message(channel_id: u64, content: String) -> Result<u64, String> {
    // Validate
    if content.trim().is_empty() {
        return Err("Message cannot be empty".into());
    }
    
    // Get current user
    let identity = caller_identity();
    let user = find_user_by_identity(&identity)
        .ok_or("User not registered")?;
    
    // Verify channel membership
    if !is_channel_member(channel_id, user.id) {
        return Err("Not a member of this channel".into());
    }

    // Insert message
    let message = Message {
        id: 0,
        channel_id,
        user_id: user.id,
        content: content.clone(),
        timestamp: now_ms(),
        edited: false,
    };
    
    let msg_id = datastore::insert(&message)
        .map_err(|_| "Failed to send message")?;
    
    Ok(msg_id)
}

// Called when module is first loaded - perfect for seeding data
#[reducer(init)]
pub fn initialize() {
    info("Chat module initialized");
    
    // Create default "general" channel if it doesn't exist
    if find_channel_by_name("general").is_none() {
        let channel = Channel {
            id: 1,  // Fixed ID for default channel
            name: "general".into(),
            description: "General discussion".into(),
            created_by: 0,
            is_private: false,
        };
        datastore::insert(&channel).ok();
        info("Created default 'general' channel");
    }
}

#[reducer(client_connected)]
pub fn on_client_connected() {
    let identity = caller_identity();
    info(&format!("Client {} connected", 
        identity_abbr(&identity)));
    
    // Update last_seen for the connected user
    if let Some(mut user) = find_user_by_identity(&identity) {
        user.last_seen = now_ms();
        datastore::update(&user).ok();
    }
}

#[reducer(client_disconnected)]
pub fn on_client_disconnected() {
    let identity = caller_identity();
    info(&format!("Client {} disconnected",
        identity_abbr(&identity)));
}

import { CosmictronClient } from '@cosmictron/client';

const client = new CosmictronClient('ws://localhost:8080');
await client.connect();

// Subscribe to messages in #general
await client.subscribe(
  'SELECT * FROM messages WHERE channel_id = 1',
  (update) => {
    for (const msg of update.inserts) {
      renderMessage(msg);
    }
  }
);

// Send a message
await client.callReducer('chat', 'send_message', {
  channel_id: 1,
  content: 'Hello, Cosmictron!',
});

// Export tables and reducers for the Cosmictron runtime
describe_module!(
    tables = [User, Channel, ChannelMember, Message],
    reducers = [
        initialize,
        register_user,
        create_channel,
        send_message,
        on_client_connected,
        on_client_disconnected
    ]
);

# Compile to WASM
cargo build -p chat --target wasm32-unknown-unknown --release

# Deploy
cosmictron deploy target/wasm32-unknown-unknown/release/chat.wasm

# Test with CLI
cosmictron call chat register_user '{"username": "alice", "display_name": "Alice"}'
cosmictron call chat create_channel '{"name": "random", "description": "Random chat"}'
cosmictron call chat send_message '{"channel_id": 1, "content": "Hello, Cosmictron!"}'
cosmictron query "SELECT * FROM messages"

use cosmictron_sdk::prelude::*;
use cosmictron_sdk::datastore;
use cosmictron_sdk::query::{find_first, find_all, exists};

#[derive(BsatnSerialize, BsatnDeserialize)]
#[table(name = "todos")]
pub struct Todo {
    #[primary_key]
    #[auto_inc]
    pub id: u64,
    pub title: String,
    pub description: String,
    pub completed: bool,
    pub priority: u32,      // 1=low, 2=medium, 3=high
    pub created_at: u64,
    pub due_date: Option<u64>,
    #[index]
    pub owner_id: Identity,  // Store identity directly
}

#[derive(BsatnSerialize, BsatnDeserialize)]
#[table(name = "tags")]
pub struct Tag {
    #[primary_key]
    #[auto_inc]
    pub id: u64,
    #[unique]
    pub name: String,
    pub color: String,
}

#[derive(BsatnSerialize, BsatnDeserialize)]
#[table(name = "todo_tags")]
pub struct TodoTag {
    #[primary_key]
    #[auto_inc]
    pub id: u64,
    #[index]
    pub todo_id: u64,
    #[index]
    pub tag_id: u64,
}

// Find a todo by ID, verifying ownership
fn get_todo(todo_id: u64, owner: &Identity) -> Option<Todo> {
    find_first("todos", |t: &Todo| t.id == todo_id && t.owner_id == *owner)
}

// Get all todos for a user
fn get_user_todos(owner: &Identity) -> Vec<Todo> {
    find_all("todos", |t: &Todo| t.owner_id == *owner)
}

// Check if tag exists by name
fn find_tag_by_name(name: &str) -> Option<Tag> {
    find_first("tags", |t: &Tag| t.name == name)
}

#[reducer]
pub fn create_todo(
    title: String, 
    description: String, 
    priority: u32
) -> Result<u64, String> {
    // Validate
    if title.is_empty() {
        return Err("Title is required".into());
    }
    
    let owner = caller_identity();
    
    let todo = Todo {
        id: 0,  // auto_inc assigns this
        title,
        description,
        completed: false,
        priority: priority.clamp(1, 3),
        created_at: now_ms(),
        due_date: None,
        owner_id: owner,
    };
    
    let id = datastore::insert(&todo)
        .map_err(|_| "Failed to create todo")?;
    
    info(&format!("Todo {} created", id));
    Ok(id)
}

#[reducer]
pub fn complete_todo(todo_id: u64) -> Result<<(), String> {
    let owner = caller_identity();
    
    let mut todo = get_todo(todo_id, &owner)
        .ok_or("Todo not found or not owned by you")?;
    
    todo.completed = true;
    datastore::update(&todo)
        .map_err(|_| "Failed to update todo")?;
    
    Ok(())
}

#[reducer]
pub fn delete_todo(todo_id: u64) -> Result<<(), String> {
    let owner = caller_identity();
    
    // Verify ownership before deleting
    let todo = get_todo(todo_id, &owner)
        .ok_or("Todo not found or not owned by you")?;
    
    // Delete the todo
    datastore::delete_by_pk::<Todo>(&todo_id)
        .map_err(|_| "Failed to delete todo")?;
    
    Ok(())
}

#[reducer]
pub fn add_tag_to_todo(
    todo_id: u64, 
    tag_name: String
) -> Result<<(), String> {
    let owner = caller_identity();
    
    // Verify todo ownership
    let _todo = get_todo(todo_id, &owner)
        .ok_or("Todo not found or not owned by you")?;
    
    // Find or create tag
    let tag_id = match find_tag_by_name(&tag_name) {
        Some(tag) => tag.id,
        None => {
            // Create new tag with random color
            let colors = ["red", "blue", "green", "yellow"];
            let tag = Tag {
                id: 0,
                name: tag_name,
                color: colors[(now_ms() % 4) as usize].into(),
            };
            datastore::insert(&tag)
                .map_err(|_| "Failed to create tag")?
        }
    };
    
    // Link tag to todo
    let link = TodoTag {
        id: 0,
        todo_id,
        tag_id,
    };
    datastore::insert(&link)
        .map_err(|_| "Failed to add tag")?;
    
    Ok(())
}

const client = new CosmictronClient('ws://localhost:8080');
await client.connect();

// Subscribe to incomplete todos (real-time updates)
await client.subscribe(
  'SELECT * FROM todos WHERE completed = false',
  (update) => {
    update.inserts.forEach(todo => addTodoToUI(todo));
    update.deletes.forEach(todo => removeTodoFromUI(todo));
  }
);

// Create a todo
await client.callReducer('todo', 'create_todo', {
  title: 'Learn Cosmictron',
  description: 'Complete the tutorial',
  priority: 3,
});

# Create a new Rust project
cargo new --lib my-counter
cd my-counter

# Add Cosmictron SDK dependency
cargo add cosmictron-sdk

use cosmictron_sdk::prelude::*;

#[derive(BsatnSerialize, BsatnDeserialize)]
#[table(name = "counters")]
pub struct Counter {
    #[primary_key]
    pub owner: Identity,
    pub value: i64,
}

/// Initialize a counter for the calling user
#[reducer]
pub fn init() {
    let owner = caller_identity();
    
    // Check if counter already exists
    if find_by_primary_key::(&owner).is_none() {
        let counter = Counter { owner, value: 0 };
        datastore::insert(&counter).expect("insert failed");
        info("Counter initialized");
    }
}

/// Increment the caller's counter
#[reducer]
pub fn increment(amount: i64) {
    let owner = caller_identity();
    
    if let Some(mut counter) = find_by_primary_key::(&owner) {
        counter.value += amount;
        datastore::update(&counter).expect("update failed");
        info(&format!("Counter incremented to {}", counter.value));
    } else {
        panic!("Counter not initialized. Call init() first.");
    }
}

/// Decrement the caller's counter
#[reducer]
pub fn decrement(amount: i64) {
    increment(-amount)  // Reuse increment with negative value
}

describe_module!(
    tables: [Counter],
    reducers: [init, increment, decrement],
);

# Build for WASM target
cargo build --target wasm32-unknown-unknown --release

# Deploy to Cosmictron server
cosmictron deploy target/wasm32-unknown-unknown/release/my_counter.wasm --name counter

import { CosmictronClient } from '@cosmictron/client';

const client = new CosmictronClient('ws://localhost:8080');
await client.connect();

// Subscribe to see your counter
await client.subscribe(
  'SELECT * FROM counters',
  (update) => console.log('Counter update:', update)
);

// Initialize your counter
await client.callReducer('counter', 'init', {});

// Increment it
await client.callReducer('counter', 'increment', { amount: 5 });

// Decrement it
await client.callReducer('counter', 'decrement', { amount: 2 });

#[table(name = "users", public)]
pub struct User {
    #[primary_key]
    pub id: u64,

    #[unique]
    pub username: String,

    #[index]
    pub created_at: u64,
}

#[reducer]
pub fn create_user(username: String, email: String) {
    // Validate input
    if username.is_empty() {
        panic!("Username is required");
    }

    // Insert into database
    insert(User { id: 0, username, email });
}

#[derive(BsatnSerialize, BsatnDeserialize)]
#[table(name = "products")]
pub struct Product {
    #[primary_key] #[auto_inc]
    pub id: u64,
    pub name: String,
    pub price: u64,
}

// The derive macros automatically implement:
// - BsatnSerialize::serialize() -> Vec
// - BsatnDeserialize::deserialize(bytes) -> Option

use cosmictron_sdk::query::{find_first, exists, find_all};

#[reducer]
pub fn add_to_cart(product_id: u64) {
    // Check if product exists
    let product = find_first("products", |p: &Product| p.id == product_id)
        .expect("Product not found");
    
    // Check if already in cart
    if exists("cart_items", |c: &CartItem| {
        c.product_id == product_id && c.user_id == caller_identity()
    }) {
        panic!("Already in cart");
    }
    
    // Get all items for inventory check
    let items = find_all("cart_items", |c: &CartItem| {
        c.user_id == caller_identity()
    });
}

#[reducer(init)]
pub fn initialize() {
    // Create default channel when module loads
    let channel = Channel {
        id: 1,
        name: "general".to_string(),
        description: "Welcome!".to_string(),
    };
    datastore::insert(&channel);
    info("Created default channel");
}

#[reducer(client_connected)]
pub fn on_connect() {
    let identity = caller_identity();
    info(&format!("User {} connected", 
        identity_abbr(&identity)));
    
    // Update last_seen timestamp
    if let Some(mut user) = find_first("users", |u| u.identity == identity) {
        user.last_seen = now_ms();
        datastore::update(&user);
    }
}

// Subscribe to all messages in a channel
await client.subscribe(
  'SELECT * FROM messages WHERE channel_id = 1',
  (update) => {
    // `inserts` = new or updated rows
    update.inserts.forEach(row => {
      console.log('New message:', row.content);
    });

    // `deletes` = removed rows
    update.deletes.forEach(row => {
      console.log('Deleted message:', row.id);
    });
  }
);

// Unsubscribe when done
await sub.unsubscribe();

#[reducer]
pub fn create_user(username: String) -> Result<u64, String> {
    // Validate input
    if username.len() < 3 {
        return Err("Username must be at least 3 characters".to_string());
    }
    
    if username.len() > 20 {
        return Err("Username must be at most 20 characters".to_string());
    }
    
    // Check if username already exists
    if find_user_by_username(&username).is_some() {
        return Err("Username already taken".to_string());
    }
    
    // Create the user
    let user = User {
        id: 0,
        username,
        created_at: now_ms(),
    };
    
    match datastore::insert(&user) {
        Ok(id) => {
            info(&format!("User {} created", id));
            Ok(id)
        }
        Err(e) => Err(format!("Database error: {:?}", e)),
    }
}

// Pattern 1: Propagate errors with ?
let id = datastore::insert(&item)?;

// Pattern 2: Map errors to custom messages
let id = datastore::insert(&item)
    .map_err(|e| format!("Failed to create item: {:?}", e))?;

// Pattern 3: Handle specific cases
match datastore::update(&item) {
    Ok(_) => info("Updated successfully"),
    Err(DatastoreError::NotFound) => return Err("Item not found".into()),
    Err(e) => return Err(format!("Update failed: {:?}", e)),
}

fn validate_message(text: &str) -> Result<String, String> {
    let trimmed = text.trim();
    
    if trimmed.is_empty() {
        return Err("Message cannot be empty".to_string());
    }
    
    if trimmed.len() > 2000 {
        return Err("Message too long (max 2000 chars)".to_string());
    }
    
    // Check for invalid characters
    if trimmed.chars().any(|c| c.is_control() && c != '\n') {
        return Err("Message contains invalid characters".to_string());
    }
    
    Ok(trimmed.to_string())
}

#[reducer]
pub fn delete_post(post_id: u64) -> Result<(), String> {
    let caller = caller_identity();
    
    // Fetch the post
    let post = find_by_primary_key::<Post>(&post_id)
        .ok_or("Post not found")?;
    
    // Check ownership
    if post.author_id != caller {
        return Err("You can only delete your own posts".to_string());
    }
    
    // Check if post is locked
    if post.locked {
        return Err("Cannot delete a locked post".to_string());
    }
    
    datastore::delete(&post)
        .map_err(|e| format!("Delete failed: {:?}", e))?;
    
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use cosmictron_sdk::test::*;

    #[test]
    fn test_create_user() {
        // Create a test context with a mock identity
        let ctx = TestContext::new()
            .with_identity(Identity::from_bytes(&[1; 32]));
        
        // Call the reducer
        let result = ctx.call(|| create_user("alice".to_string()));
        
        // Assert success
        assert!(result.is_ok(), "Should create user: {:?}", result);
        let user_id = result.unwrap();
        assert!(user_id > 0, "Should return valid ID");
        
        // Verify user was created
        let user = find_by_primary_key::<User>(&user_id);
        assert!(user.is_some());
        assert_eq!(user.unwrap().username, "alice");
    }

    #[test]
    fn test_duplicate_username_fails() {
        let ctx = TestContext::new()
            .with_identity(Identity::from_bytes(&[1; 32]));
        
        // Create first user
        let _ = ctx.call(|| create_user("bob".to_string())).unwrap();
        
        // Try to create second user with same name (different identity)
        let ctx2 = TestContext::new()
            .with_identity(Identity::from_bytes(&[2; 32]));
        let result = ctx2.call(|| create_user("bob".to_string()));
        
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("already taken"));
    }
}

#[test]
fn test_chat_between_users() {
    let alice_id = Identity::from_bytes(&[1; 32]);
    let bob_id = Identity::from_bytes(&[2; 32]);
    
    // Alice creates a channel
    let ctx_alice = TestContext::new().with_identity(alice_id);
    let channel_id = ctx_alice
        .call(|| create_channel("general".to_string()))
        .unwrap();
    
    // Bob joins the channel
    let ctx_bob = TestContext::new().with_identity(bob_id);
    ctx_bob.call(|| join_channel(channel_id)).unwrap();
    
    // Bob sends a message
    ctx_bob
        .call(|| send_message(channel_id, "Hello Alice!".to_string()))
        .unwrap();
    
    // Verify message exists
    let messages = find_all::<Message>("messages");
    assert_eq!(messages.len(), 1);
    assert_eq!(messages[0].text, "Hello Alice!");
}

#[test]
fn test_unauthorized_action_fails() {
    let ctx = TestContext::new();
    
    // Try to perform action without proper setup
    let result = ctx.call(|| delete_post(999));
    
    assert!(result.is_err());
    assert!(result.unwrap_err().contains("not found"));
}

#[test]
fn test_validation_rejects_invalid_input() {
    let ctx = TestContext::new();
    
    // Test empty username
    let result = ctx.call(|| create_user("".to_string()));
    assert!(result.is_err());
    
    // Test username too long
    let result = ctx.call(|| create_user("a".repeat(100)));
    assert!(result.is_err());
}

#[test]
fn test_find_user_by_username() {
    let ctx = TestContext::new();
    
    // Create test users
    ctx.call(|| create_user("alice".to_string())).unwrap();
    ctx.call(|| create_user("bob".to_string())).unwrap();
    
    // Test query
    let user = find_user_by_username("alice");
    assert!(user.is_some());
    assert_eq!(user.unwrap().username, "alice");
    
    // Test non-existent user
    assert!(find_user_by_username("charlie").is_none());
}

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_create_user

# Run tests with logging
RUST_LOG=debug cargo test

[tag: u8][length: u32 little-endian][payload: bytes]

cosmictron deploy path/to/module.wasm

# Generate a new identity and token
cosmictron auth --generate

# Set the token
export COSMICTRON_TOKEN="<your-token>"

# Call with arguments
cosmictron call counter increment '{"amount": 5}'

# Call without arguments
cosmictron call my-module init '{}'

# Table format (default)
cosmictron query "SELECT * FROM users"

# JSON format
cosmictron query "SELECT * FROM users" --format json

# CSV format
cosmictron query "SELECT * FROM orders" --format csv > orders.csv

# Subscribe indefinitely
cosmictron subscribe "SELECT * FROM messages WHERE channel = 'general'"

# Subscribe for 30 seconds
cosmictron subscribe "SELECT * FROM events" --duration 30

# Simple list
cosmictron modules

# Detailed information
cosmictron modules --detailed

bun add @cosmictron/client
# or: npm install @cosmictron/client

import { CosmictronClient } from '@cosmictron/client';

// Create client
const client = new CosmictronClient('ws://localhost:8080', {
  reconnect: true,
  reconnectInterval: 1000,
  timeout: 5000,
});

// Connect
await client.connect();

// Get identity
const identity = client.getIdentity();
const token = client.getToken();

// Call a reducer
const result = await client.callReducer('module', 'reducer', args);

// One-time query
const rows = await client.query('SELECT * FROM users');

// Subscribe to live updates
const sub = await client.subscribe(sql, callback);
await sub.unsubscribe();

// Disconnect
client.disconnect();

import { CosmictronProvider } from '@cosmictron/client/react';

function App() {
  return (
    <CosmictronProvider 
      url="ws://localhost:8080"
      reconnect={true}
      autoConnect={true}
    >
      <ChatApp />
    </CosmictronProvider>
  );
}

import { useSubscription } from '@cosmictron/client/react';

interface Message {
  id: number;
  channel_id: number;
  sender: string;
  text: string;
  sent_at: number;
}

function MessageList({ channelId }: { channelId: number }) {
  const { data: messages, error, isLoading } = useSubscription<Message[]>(
    `SELECT * FROM messages WHERE channel_id = ${channelId} ORDER BY sent_at`
  );

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div className="messages">
      {messages?.map(msg => (
        <div key={msg.id} className="message">
          <span className="sender">{msg.sender}</span>
          <p>{msg.text}</p>
        </div>
      ))}
    </div>
  );
}

import { useReducer } from '@cosmictron/client/react';

function SendMessage({ channelId }: { channelId: number }) {
  const [text, setText] = useState('');
  
  // Create a typed reducer hook
  const { call, isLoading, error } = useReducer<{ text: string }>(
    'chat',
    'send_message'
  );

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!text.trim()) return;

    const result = await call({ channel_id: channelId, text });
    
    if (result.success) {
      setText('');
    } else {
      console.error('Failed to send:', result.error);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={text}
        onChange={e => setText(e.target.value)}
        placeholder="Type a message..."
        disabled={isLoading}
      />
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Sending...' : 'Send'}
      </button>
      {error && <span className="error">{error}</span>}
    </form>
  );
}

import { useQuery } from '@cosmictron/client/react';

function UserProfile({ userId }: { userId: number }) {
  // One-time query with 30 second cache
  const { data: user, isLoading, refetch } = useQuery(
    ['user', userId],
    `SELECT * FROM users WHERE id = ${userId}`,
    { staleTime: 30000 }  // 30 second cache
  );

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <h1>{user?.username}</h1>
      <p>Joined: {user?.created_at}</p>
      <button onClick={refetch}>Refresh</button>
    </div>
  );
}

import { useConnectionState } from '@cosmictron/client/react';

function ConnectionStatus() {
  const { state, isConnected, reconnect } = useConnectionState();

  if (isConnected) {
    return <span className="status connected">🟢 Connected</span>;
  }

  return (
    <div className="status disconnected">
      <span>🔴 {state}</span>
      <button onClick={reconnect}>Reconnect</button>
    </div>
  );
}

import { 
  CosmictronProvider, 
  useSubscription, 
  useReducer,
  useConnectionState 
} from '@cosmictron/client/react';

function ChatPage() {
  const [channelId, setChannelId] = useState(1);

  return (
    <div className="chat-app">
      <ConnectionStatus />
      <ChannelList onSelect={setChannelId} />
      <MessageList channelId={channelId} />
      <SendMessage channelId={channelId} />
    </div>
  );
}

// App entry point
export default function App() {
  return (
    <CosmictronProvider url="ws://localhost:8080">
      <ChatPage />
    </CosmictronProvider>
  );
}

#[derive(BsatnSerialize, BsatnDeserialize)]
#[table(name = "users")]
pub struct User {
    #[primary_key]
    #[auto_inc]
    pub id: u64,
    pub username: String,
    
    // New column with default value
    #[default = "UTC"]
    pub timezone: String,
    
    // Renamed from 'created_at' to 'joined_at'
    #[migrate(from = "created_at")]
    pub joined_at: Timestamp,
}

// Custom migration hook
#[migrate(to = "v2")]
pub fn migrate_v1_to_v2() {
    // Migrate data from old schema to new
    for user in find_all::User("users") {
        // Transform data as needed
        let updated = UserV2 {
            id: user.id,
            username: user.username.to_lowercase(),
            timezone: "UTC".to_string(),
            joined_at: user.created_at,
        };
        datastore::update(&updated).unwrap();
    }
    
    info("Migration v1→v2 complete");
}

// Index columns used in WHERE clauses
#[index]
pub user_id: Identity,

// Composite index for multi-column queries
#[index(columns = [user_id, created_at])]
pub workspace_id: u64,

// Unique index
#[index(unique)]
pub email: String,

// BAD: Subscribes to ALL messages
await client.subscribe('SELECT * FROM messages', callback);

// GOOD: Only messages in this channel
await client.subscribe(
  `SELECT * FROM messages WHERE channel_id = ${channelId}`,
  callback
);

// BEST: Limited + paginated
await client.subscribe(
  `SELECT * FROM messages 
   WHERE channel_id = ${channelId} 
   ORDER BY sent_at DESC 
   LIMIT 100`,
  callback
);

// BAD: N individual inserts
#[reducer]
pub fn import_items_slow(items: Vec<Item>) {
    for item in items {
        datastore::insert(&item).unwrap();  // N operations
    }
}

// GOOD: Single batch operation
#[reducer]
pub fn import_items_fast(items: Vec<Item>) {
    datastore::insert_batch(&items).unwrap();  // 1 operation
}

# Run load tests
cargo test --release -p cosmictron-test --test load_test

# Profile your module
wasm-prof my_module.wasm --reducer create_user --count 1000

# Network
COSMICTRON_SERVER=0.0.0.0:8080
COSMICTRON_MAX_CONNECTIONS=10000

# Persistence
COSMICTRON_DATA_DIR=/var/lib/cosmictron
COSMICTRON_SNAPSHOT_INTERVAL=3600

# Observability
COSMICTRON_LOG_LEVEL=info
COSMICTRON_LOG_FORMAT=json
COSMICTRON_METRICS_PORT=9090

# Security
COSMICTRON_RATE_LIMIT_ENABLED=true
COSMICTRON_TOKEN_ROTATION_INTERVAL=3600

# Resources
COSMICTRON_SHUTDOWN_TIMEOUT=60
COSMICTRON_WASM_FUEL_LIMIT=10000000

groups:
  - name: cosmictron
    rules:
      - alert: HighReducerLatency
        expr: histogram_quantile(0.99, 
          rate(cosmictron_reducer_duration_us_bucket[5m])) > 100000
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High reducer latency detected"
          
      - alert: TooManyConnections
        expr: cosmictron_websocket_connections_active > 8000
        for: 1m
        labels:
          severity: critical

#!/bin/bash
BACKUP_DIR=/backup/cosmictron
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

# Trigger snapshot
curl -X POST http://localhost:8080/admin/snapshot

# Copy to backup location
cp -r $COSMICTRON_DATA_DIR/snapshots/latest $BACKUP_DIR/$TIMESTAMP

# Upload to S3
aws s3 sync $BACKUP_DIR/$TIMESTAMP s3://my-backup-bucket/cosmictron/$TIMESTAMP

kill -TERM <pid>