Skip to main content

Dev Workflow

Standard dev session​

You need three terminal windows for the full development loop.

Terminal 1 — the server​

cd homeCore/core
cargo run -p homecore

HomeCore uses the current working directory as its base. Running from core/ picks up config/homecore.toml and writes data to data/ right there.

On first run, copy the admin password from the startup output.

To restart after a code change: Ctrl-C, then cargo run -p homecore again. Changed crates only — only they recompile.

Terminal 2 — virtual device (optional)​

Start after the server is up:

cargo run -p virtual-device -- --broker 127.0.0.1 --port 1883 --id plugin.virtual

Terminal 3 — API calls​

TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YOUR_PASSWORD"}' | jq -r .token)

Optional: Terminal 4 — live event stream​

websocat "ws://localhost:8080/api/v1/events/stream?token=$TOKEN"

Typical loop​

  1. Make a code change
  2. Ctrl-C in Terminal 1
  3. cargo run -p homecore (only changed crates recompile)
  4. Re-test with curl in Terminal 3
  5. Check Terminal 1 for log output

Cargo commands reference​

# Fastest feedback — check compiles without building
cargo check --workspace
cargo check -p hc-core        # single crate

# Build
cargo build --workspace
cargo build --release          # optimized binary

# Run
cargo run -p homecore
cargo run -p homecore --release

# Run virtual device
cargo run -p virtual-device -- --broker 127.0.0.1 --port 1883 --id plugin.virtual

# Test
cargo test --workspace
cargo test -p hc-auth          # single crate
cargo test -p hc-core          # rule engine tests
cargo test -p hc-api           # API + WebSocket auth tests
cargo test -p homecore --test integration_test   # full-stack integration test
cargo test -p hc-core repeat_until               # specific test by name
cargo test --workspace -- --nocapture            # show println! output

# Watch for changes (install once: cargo install cargo-watch)
cargo watch -x "check -p hc-core"
cargo watch -x "test -p hc-api"

Test coverage​

CrateTestsCoverage
hc-auth11Password hashing, JWT issue/validate/expire/tamper/role
hc-core12Rule engine trigger matching, executor RepeatUntil/Delay, CallService
hc-api22Event log ring buffer, WebSocket auth, scope enforcement
hc-topic-map4Pattern matching and transforms
http-poller19Path extraction, field_map, JSON↔Dynamic bridge, Rhai transform
homecore (integration)1Full stack: virtual device → MQTT → rule fires → command
Total69

Admin UI development​

The Leptos/WASM admin UI (hc-web-leptos) has its own dev workflow that coexists with the server.

Development: Run trunk serve on port 3000 from the hc-web-leptos directory. Trunk proxies /api requests to HomeCore on port 8080 automatically. Leave [web_admin] enabled = false in homecore.toml (the default) so the server does not serve static files that conflict with trunk's dev server.

Production: Build with trunk build --release, copy the dist/ directory to the deploy location, and enable in homecore.toml:

[web_admin]
enabled   = true
dist_path = "ui/dist"   # relative to HOMECORE_HOME

HomeCore serves the built assets via tower-http ServeDir with SPA fallback. API routes at /api/v1 take priority.

Both can coexist: Disabling web_admin does not affect the trunk dev workflow. You can develop the UI with trunk serve while HomeCore runs with web_admin disabled, then switch to built-in serving for production.

Isolated dev environment​

Use a throwaway directory to keep state separate from your main installation:

HOMECORE_HOME=/tmp/hc-dev cargo run -p homecore
# or
cargo run -p homecore -- --home /tmp/hc-dev

Reset it cleanly:

rm -rf /tmp/hc-dev/data/
HOMECORE_HOME=/tmp/hc-dev cargo run -p homecore

Debugging with RUST_LOG​

# Rule engine internals
RUST_LOG=info,hc_core::engine=debug,hc_core::executor=debug cargo run -p homecore

# MQTT traffic
RUST_LOG=info,hc_mqtt_client=debug cargo run -p homecore

# State bridge
RUST_LOG=info,hc_core::state_bridge=debug cargo run -p homecore

# Everything (very noisy)
RUST_LOG=trace cargo run -p homecore

# All rule-engine related
RUST_LOG=info,hc_core=debug,hc_mqtt_client=debug,hc_broker=warn cargo run -p homecore

Common compiler errors​

"cannot borrow self as mutable because it is also borrowed as immutable"​

Usually means you're holding a reference across an async await point. The fix is to clone the value before the await:

// ❌ fails
let name = &self.state.get_name();
self.state.update().await?;  // borrow problem

// ✅ fix
let name = self.state.get_name().clone();
self.state.update().await?;

"future cannot be sent between threads safely" / Send bound​

An async fn that captures a non-Send type (e.g. Rc, RefCell) passed to tokio::spawn. Either use Arc<Mutex<>> instead, or restructure so the non-Send value is dropped before the first await.

"the trait bound is not satisfied for Box<dyn Future>"​

Recursive async functions need Box::pin:

fn run_action(action: Action) -> Pin<Box<dyn Future<Output = Result<()>> + Send>> {
    Box::pin(async move {
        match action {
            Action::Parallel { actions } => {
                for a in actions {
                    run_action(a).await?;   // ← recursive call OK inside Box::pin
                }
            }
            // ...
        }
        Ok(())
    })
}

Deadlock in RwLock​

Never hold a write lock across an await. Take the data you need, drop the lock, then do async work:

// ❌ deadlock
let mut rules = self.rules.write().await;
rules.push(new_rule);
persist_to_db(&new_rule).await?;  // deadlock — write lock still held

// ✅ fix
{
    let mut rules = self.rules.write().await;
    rules.push(new_rule.clone());
}  // lock dropped here
persist_to_db(&new_rule).await?;

Adding a new REST endpoint​

  1. Add handler function in crates/hc-api/src/handlers.rs (or a new file for new resource types)
  2. Add route in crates/hc-api/src/lib.rs build_router()
  3. Add scope extractor parameter to the handler signature
  4. Add utoipa #[utoipa::path(...)] attribute for OpenAPI generation
  5. Register in openapi.rs if using the OpenAPI macro router
  6. Write a test in hc-api module tests

Adding a new action type​

  1. Add the variant to Action enum in crates/hc-types/src/rule.rs
  2. Add serde deserialization (usually automatic with #[serde(tag = "type", rename_all = "snake_case")])
  3. Add match arm in executor.rs run_single_action()
  4. Write unit tests in hc-core module tests
  5. Add to the action type reference in docs/devNotes.md

Integration test​

The integration test starts a full HomeCore instance on a random port:

cargo test -p homecore --test integration_test

It:

  1. Starts HomeCore with an in-memory config (temp files under /tmp/)
  2. Connects the virtual device plugin
  3. Creates a rule via the REST API
  4. Publishes a state change via MQTT
  5. Asserts the rule fired and the expected command was published

To add a new integration test scenario, add a test function in tests/integration_test.rs.