Runtime Architecture

​

Overview

​

Core Components

​

BotRuntime

pub struct BotRuntime {
    workers: Vec<Worker>,
    num_workers: usize,
    secrets: Arc<SecretService>,
    guild_routes: Arc<parking_lot::Mutex<HashMap<String, usize>>>,
    migration_queues: Arc<Mutex<HashMap<String, Vec<QueuedGuildEvent>>>>,
}

• Worker pool initialization
• Guild-to-worker routing (consistent hashing)
• Event dispatch coordination
• Runtime migration between workers

​

Worker Threads

pub struct Worker {
    id: usize,
    sender: mpsc::UnboundedChannel<WorkerCommand>,
    handle: Option<JoinHandle<()>>,
    backlog: Arc<AtomicUsize>,
}

1. Listen for commands via unbounded channel
2. Execute cron tick every second
3. Process commands: deploy, dispatch, migrate, update secrets
4. Manage guild isolates lifecycle

​

JavaScript Runtime State

pub struct JsRuntimeState {
    runtime: JsRuntime,
    dispatch_fn: Option<Global<v8::Function>>,
    secrets: Arc<SecretsRuntimeData>,
}

• Separate V8 isolate per guild
• No shared global state between guilds
• Independent event loops
• Per-guild secret scopes

​

Service Layer

​

DeploymentService

• Upsert deployment (bundle + source map)
• Retrieve deployment by guild ID
• List all deployments for cache restoration
• Invalidate cache on updates

​

KvService

• Guild-scoped stores (multiple per guild)
• Sled databases at ./data/kv/{guild_id}/{store_name}
• Metadata tree for expiration and custom metadata
• In-memory LRU cache of Sled instances

​

SecretService

• Master key encryption
• Per-guild secret runtime data
• Secret scope thread-local storage
• Placeholder derivation for safe references

​

AuthService

1. User authorizes via Discord OAuth
2. Exchange code for access token
3. Store session in Redis with TTL
4. Sign session cookie with API secret

​

TokenService

​

Discord Integration

​

DiscordHandler

1. Gateway event arrives from Discord
2. Convert to typed payload (expose_payload macro)
3. Serialize to JSON
4. Route to guild runtime via BotRuntime::dispatch_js_event
5. Filter non-guild events (flora is guild-only)

• ready - Bot connected
• messageCreate - New message
• messageUpdate - Message edited
• messageDelete / messageDeleteBulk - Message(s) deleted
• interactionCreate - Slash command
• componentInteraction - Button/select menu
• modalSubmit - Modal form submission
• reactionAdd / reactionRemove / reactionRemoveAll - Reactions

​

Deno Core Integration

​

Extensions

• flora_ops - Discord operations (messages, interactions, commands)
• flora_kv - Key-value storage
• flora_cron - Cron job registration
• flora_secrets - Secret access
• deno_web - Web APIs (fetch, URL, etc.)
• deno_fetch - HTTP client
• deno_net - Network APIs
• deno_tls - TLS support

​

Ops

#[op2(async)]
pub async fn op_send_message(
    state: Rc<RefCell<OpState>>,
    #[serde] input: SendMessageInput,
) -> Result<String, JsErrorBox> {
    let http = state.borrow().borrow::<Arc<Http>>().clone();
    // ... perform Discord API call
    Ok(message_id)
}

​

Cron Scheduler

• Shared cron registry (parking_lot::Mutex)
• Tick interval: 1 second
• Jobs evaluated using croner crate
• Dispatched as synthetic events (__cron:<name>)

1. Register via op_cron from JavaScript
2. Store in worker registry with next run time
3. Tick checks for due jobs
4. Dispatch to guild runtime with timeout
5. Mark not running after completion
6. Clear on guild redeploy

​

HTTP API

• POST /deployments - Deploy guild script
• GET /deployments/:guild_id - Get deployment
• GET /logs/:guild_id - Stream logs (SSE)
• GET /kv/:guild_id/stores - List KV stores
• POST /kv/:guild_id/stores/:store/keys/:key - Set KV value
• POST /auth/login - Discord OAuth
• POST /tokens - Create API token

• Timeout layer (10s)
• Logging middleware
• Auth middleware (cookie or bearer token)

​

Worker Pool Architecture

• Consistent hashing (guild_id → worker index)
• Sticky routing (guilds stay on same worker)
• Migration support (move guild between workers)
• Backlog tracking per worker

​

Startup Sequence

1. Load configuration and initialize tracing
2. Connect to PostgreSQL and run migrations
3. Connect to Redis with exponential backoff
4. Initialize V8 once per process
5. Create worker pool
6. Initialize each worker sequentially (avoid V8 races)
7. Load SDK bundle into all workers
8. Restore cached deployments from database
9. Deploy each cached guild script
10. Start Discord client (Serenity)
11. Start HTTP API server (Axum)
12. Run both concurrently with tokio::try_join

​

Shutdown Sequence

1. Drop BotRuntime triggers shutdown
2. Attempt graceful migration of all guilds
3. Send shutdown command to each worker
4. Join worker threads
5. Drop all runtime states

​

Thread Safety

• Arc<Http> - Shared Discord HTTP client
• Arc<BotRuntime> - Shared across handlers
• Arc<SecretsRuntimeData> - Per-guild secret data

• parking_lot::Mutex for cron registry (fast, uncontended)
• tokio::Mutex for migration queues (async-aware)
• Arc<RwLock<BoundedCache>> for KV DB cache

• V8 isolates are not Send/Sync
• Worker threads never share isolates
• Migration transfers ownership via channels