Rizwan Saleem

Posted on Jun 3

Building a Real-Time, Event-Sourced Feature Flag System with Rust and WebAssembly

#frontend #webdev #react

Building a Real-Time, Event-Sourced Feature Flag System with Rust and WebAssembly

Disabling or enabling features at runtime is a common need in modern software. A robust feature flag system lets product teams experiment safely, roll out changes gradually, and reduce blast radius during incidents. In this tutorial, you’ll build a lightweight, real-time, event-sourced feature flag service composed of: a Rust-based event store, a WebAssembly (wasm) client surface, and a small Node.js server for orchestration. The approach emphasizes correctness, observability, and low latency, while staying approachable for practical use in real projects.

What you’ll learn

Principles of event sourcing for feature flags and how it improves auditability and rollbacks
Designing a compact event schema for feature flag lifecycle events
Implementing a Rust event store with append-only logs and snapshotting
Exposing a WASM module that can be embedded in frontend apps to evaluate feature flags with minimal latency
Real-time updates via server-sent events (SSE) and a simple poller fallback
Basic authorization, schema migrations, and observability considerations

Overview of the architecture

Event Store (Rust): An append-only log backed by a simple file-based database that supports snapshots. It stores events such as FlagCreated, FlagUpdated, FlagDeleted, and FlagEval.
WASM Client (Rust/WASM): A small library compiled to WebAssembly that provides a high-performance feature flag evaluator. It subscribes to events and applies the latest state to determine whether a flag is enabled for a user or context.
API Server (Node.js): A tiny HTTP server that serves the WASM module, provides endpoints for creating/updating flags, and streams updates to clients via Server-Sent Events.
Frontend integration: The WASM evaluator can be instantiated in the browser, receiving real-time updates and evaluating flags per user context.

Prerequisites

Knowledge of Rust basics (ownership, structs, enums)
Basic understanding of WebAssembly and how to use Rust to compile to wasm
Node.js installed for the API server
A small HTTP client or Postman for testing endpoints
Optional: Docker to run components in containers

Project layout

event-store/ (Rust crate for the event store)
wasm-evaluator/ (Rust crate compiled to wasm)
api-server/ (Node.js server to manage flags and SSE)

Part 1: Designing the event schema

We’ll keep the event schema compact and forward-compatible. Each event has a type, a flag_id, a version, a timestamp, and a payload.

FlagCreated: { flag_id, name, description, enabled_by_default, variants }
FlagUpdated: { flag_id, name?, description?, enabled_by_default?, variants? }
FlagDeleted: { flag_id }
FlagEval: { flag_id, context (e.g., user_id, ip, cohort), enabled (bool), reason }

Event ordering guarantees deterministic state reconstruction.

Part 2: Implementing the Rust event store

Goal: provide append-only writes, read current state, and emit deltas for subscribers.

Key components

Event enum with serde serialization
Append-only log stored as files per flag or a single log file
In-memory index to quickly compute current flag state
Snapshot mechanism to speed startup

Code sketch (Rust)

Cargo.toml dependencies: serde, serde_json, chrono, tokio, futures, tracing

Main structures

struct Event { id: Uuid, event_type: EventType, flag_id: String, version: u64, timestamp: DateTime, payload: serde_json::Value }
enum EventType { FlagCreated, FlagUpdated, FlagDeleted, FlagEval }

Core functions

append_event(flag_id, event_type, payload)
load_events(flag_id) -> Vec
build_snapshot(flag_id) -> FlagState
subscribe_updates() -> Stream

Example (high-level, simplified)

When FlagCreated arrives, create initial state: { flag_id, name, enabled_by_default, variants, is_deleted: false, version: 1 }
FlagUpdated merges fields; increment version
FlagDeleted marks is_deleted and sets version

Notes

Use a simple file-per-flag storage for clarity, or a single log with rotation.
Implement compaction: periodically create a snapshot file representing the current flag state, and trim older events.

Part 3: Building the WASM evaluator

Goal: deliver a fast, deterministic evaluation function that frontend apps can use locally.

Why WASM? Reduces JS overhead for frequent evaluations and enables offline or offline-ish experiences.

WASM design

The evaluator exposes a function evaluate(flag_state, context) -> bool
flag_state is a compact representation: flag_id, enabled_by_default, variants, current_value (derived)
context is a small map-like structure (user_id, cohort, environment)

Rust code outline (lib.rs)

#[wasm_bindgen] pub fn evaluate(flag_state_json: &str, context_json: &str) -> bool
Deserialize flag_state and context using serde_json
Apply rule: if there is a flag-specific Override or a default, return the evaluated boolean
Return a boolean that frontend can consume

Build steps

Use wasm-pack to compile to wasm
Ensure compatibility with popular bundlers (webpack, esbuild)
Export the evaluate function and a simple init for subscriptions

Frontend surface

A small wrapper around the wasm module that:
- Maintains the latest flag_state from the server
- Provides a function is_enabled(flag_id, context) that calls into wasm
- Subscribes to SSE for real-time updates and triggers wasm state refresh

Part 4: The API server (Node.js)

Responsibilities

Create, update, delete flags
Append events to the Rust event store
Serve the WASM module to clients
Provide an SSE endpoint /flags/stream that streams FlagUpdated and FlagDeleted events

Security and validation

Simple API key check for demo
Validate payload schemas with a lightweight validator
Rate-limit to protect the endpoint

Example endpoints

POST /flags -> create a new flag Body: { flag_id, name, description, enabled_by_default, variants }
PATCH /flags/:flag_id -> update a flag Body: { name?, description?, enabled_by_default?, variants? }
DELETE /flags/:flag_id -> delete a flag
GET /wasm/flag-evaluator.wasm -> serve wasm module
GET /flags/stream -> SSE stream of events

Implementation notes

On server start, load the current state from the event store to seed the wasm evaluator
When an event is appended, push the event to all connected SSE clients
Provide a small helper to convert events into a delta that clients can apply incrementally

Part 5: Observability and testing

Observability

Structured logging with tracing for Rust components
Metrics: event write rate, lag between event time and processed time
Health endpoints for each component

Testing strategy

Unit tests for event application logic in Rust
Integration test simulating creating a flag, updating it, and streaming events
End-to-end test with API server and wasm evaluator

Concrete code examples

Note: The following are condensed snippets to illustrate key ideas. They are not a full, runnable project but provide concrete patterns you can implement.

Rust event (serde-based)

use serde::{Serialize, Deserialize};
use chrono::{DateTime, Utc};
use serde_json::Value;

[derive(Serialize, Deserialize, Debug, Clone)]

pub enum EventType {
FlagCreated,
FlagUpdated,
FlagDeleted,
FlagEval,
}

[derive(Serialize, Deserialize, Debug, Clone)]

pub struct Event {
pub id: String, // UUID
pub event_type: EventType,
pub flag_id: String,
pub version: u64,
pub timestamp: DateTime,
pub payload: Value,
}

impl Event {
pub fn new(event_type: EventType, flag_id: &str, version: u64, payload: Value) -> Self {
Self {
id: uuid::Uuid::new_v4().to_string(),
event_type,
flag_id: flag_id.to_string(),
version,
timestamp: Utc::now(),
payload,
}
}
}

WASM evaluator (lib.rs, simplified)

use wasm_bindgen::prelude::*;
use serde_json::Value;

[wasm_bindgen]

pub fn evaluate(flag_state_json: &str, context_json: &str) -> bool {
// Basic deserialization
let state: Value = serde_json::from_str(flag_state_json).unwrap_or_else(|| Value::Null);
let context: Value = serde_json::from_str(context_json).unwrap_or_else(|| Value::Null);

// Simple logic: if flag has "enabled" boolean in state, return it; otherwise default
if let Some(enabled) = state.get("enabled").and_then(|v| v.as_bool()) {
return enabled;
}
// Fallback to enabled_by_default
if let Some(def) = state.get("enabled_by_default").and_then(|v| v.as_bool()) {
return def;
}
false
}

api-server (Node.js, sketch)

const express = require('express');
const { Readable } = require('stream');
const app = express();
app.use(express.json());

let events = []; // In-memory for demo; in production, pull from Rust event store

app.post('/flags', (req, res) => {
const { flag_id, name, description, enabled_by_default, variants } = req.body;
const e = { event_type: 'FlagCreated', flag_id, version: 1, payload: { name, description, enabled_by_default, variants } };
events.push(e);
res.status(201).json({ ok: true, event: e });
});

app.get('/flags/stream', (req, res) => {
res.setHeader('Content-Type', 'text/event-stream');
res.setHeader('Cache-Control', 'no-cache');
res.flushHeaders();

const onEvent = (ev) => {
res.write(data: ${JSON.stringify(ev)}\n\n);
};

// In a real app, subscribe to Rust event store
// Here we simulate with a timer or immediate push
const id = setInterval(() => {
if (events.length) onEvent(events[events.length - 1]);
}, 1000);

req.on('close', () => clearInterval(id));
});

app.listen(3000, () => {
console.log('API server listening on port 3000');
});

How to run (high level)

Build the Rust event store:
- cd event-store
- cargo build release
Build the WASM evaluator:
- cd wasm-evaluator
- wasm-pack build target web
Run API server:
- cd api-server
- npm install
- node index.js

Putting it together in practice

Start by implementing the event store with a simple append-only log. Write tests that ensure events are replayable to reconstruct state.
Build the wasm evaluator and expose a minimal evaluate function. Integrate it into a small frontend page that loads the wasm, fetches flag state, and evaluates a few sample contexts.
Create a lightweight API to manage flags and emit events. Ensure the SSE stream delivers incremental updates and that clients can rebuild state from the event log if needed.
Iterate on observability: add tracing spans around event writes and state recomputation; add a simple dashboard to show current flag states and last update times.

Next steps and refinements

Extend the event schema with per-flag evaluation rules (e.g., percentage rollouts, user cohorts).
Add a compatibility layer to migrate old flag data into the new event format.
Implement durable storage for the event log, e.g., SQLite or RocksDB-backed log with compaction.
Harden security: API authentication, authorization, and audit trails.
Consider a richer WASM surface: expose an API to subscribe to specific flag updates and to reset evaluator state.

Would you like me to tailor this tutorial to a particular tech stack you’re using (e.g., prefer Python for the API, or you want the WASM evaluator to run in a React app with Vite)? I can also provide a fuller, runnable code scaffold for Rust and Node.js with concrete file structures and complete build scripts.

Rizwan Saleem | https://rizwansaleem.co