berkus
/
wifi-densepose
mirror of https://github.com/ruvnet/wifi-densepose.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
wifi-densepose/v2/crates/homecore-server/README.md

6.8 KiB
Raw Blame History

homecore-server

Integrated HOMECORE server binary that wires state machine, API, recorder, plugins, automations, intent assistant, and HomeKit bridge into one process.

Crates.io License MSRV: 1.89+ ADR-126

The production-ready HOMECORE binary — boots all 7 subsystems (core, API, recorder, plugins, automation, assist, HAP bridge) in a single process listening on :8123.

What this crate does

homecore-server is the integration point for the entire HOMECORE ecosystem. It orchestrates:

  1. HomeCore runtime — state machine, event bus, service registry
  2. REST + WebSocket API — Axum server on :8123 (HA-compatible)
  3. SQLite Recorder — persists all state changes to disk
  4. Plugin Registry — loads and manages integrations (InProcessRuntime by default)
  5. Automation Engine — evaluates triggers, conditions, and actions
  6. Assist Pipeline — intent recognition and execution
  7. HAP Bridge — exposes accessories to HomeKit

All subsystems share the same HomeCore instance, so state changes flow through the event bus and trigger automations, record history, and notify WebSocket subscribers in lockstep.

Features

  • Single unified process — no external microservices; run with cargo run -p homecore-server
  • HA-compatible REST API — drop-in replacement for Home Assistant's /api/ on :8123
  • SQLite state history — persistent recording of all state changes
  • Automation engine — YAML-driven trigger→condition→action execution
  • Intent assistant — regex-based (P1) intent recognition + service calling
  • HomeKit bridge — exposes HOMECORE entities as HomeKit accessories
  • Plugin system — load first-party Rust plugins; Wasmtime WASM plugins (P2, --features wasmtime)
  • Configurable via CLI + env vars — no YAML required; sensible defaults
  • Structured logging — tracing output with RUST_LOG filtering
  • Feature-gated subsystems — disable recorder (--no-recorder), enable ruvector/wasmtime as needed

Subsystems

Subsystem Crate Role Notes
State Machine homecore Core domain model All other subsystems depend on this
REST API homecore-api HTTP boundary Listens on :8123; Axum framework
Recorder homecore-recorder Persistence SQLite; optional --no-recorder
Plugins homecore-plugins Extension system InProcessRuntime default; Wasmtime w/ feature
Automation homecore-automation Trigger execution Subscribes to event bus; YAML-driven
Assist homecore-assist Intent pipeline Regex recognizer (P1); semantic (P2)
HAP Bridge homecore-hap HomeKit export Accessories + characteristics; mDNS (P2)

Usage

Basic startup (in-memory recorder):

cargo build -p homecore-server
./target/debug/homecore-server
# Listens on http://localhost:8123

With persistent SQLite:

./target/debug/homecore-server \
  --bind 0.0.0.0:8123 \
  --db sqlite:~/.homecore/home.db \
  --location-name "My Home"

Full feature build (ruvector semantic search + Wasmtime plugins):

cargo build -p homecore-server --features ruvector,wasmtime --release

Via Docker (Dockerfile planned P2):

docker run -p 8123:8123 \
  -e HOMECORE_DB=sqlite:///data/home.db \
  -v ~/.homecore:/data \
  homecore-server:latest

Test the API:

# List all entities
curl http://localhost:8123/api/states

# Set a light to "on"
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"state":"on","attributes":{"brightness":200}}' \
  http://localhost:8123/api/states/light.kitchen

# WebSocket subscription (real-time state changes)
wscat -c ws://localhost:8123/api/websocket

Configuration via env:

export HOMECORE_BIND="0.0.0.0:8123"
export HOMECORE_DB="sqlite:~/.homecore/home.db"
export HOMECORE_LOCATION="Living Room"
export RUST_LOG="homecore=debug,homecore_api=info"
./target/debug/homecore-server

CLI Options

Flag Env Var Default Description
--bind HOMECORE_BIND 0.0.0.0:8123 REST API listen address
--db HOMECORE_DB sqlite::memory: SQLite path (:memory: for ephemeral)
--location-name HOMECORE_LOCATION Home Friendly name returned by /api/config
--no-recorder — off Disable SQLite recorder (low-resource deployments)

Comparison to Home Assistant

Aspect Home Assistant homecore-server
Architecture Python asyncio monolith Rust async Tokio + component traits
API protocol /api/ REST (HA wire format) Identical HA wire format
Persistence SQLite + YAML files SQLite (P1); Redis (P2)
Plugins Python integrations in homeassistant/components/ Rust (P1) + WASM (P2)
Automation execution Python asyncio event loop Tokio async tasks + trait-based
HomeKit bridge Via homekit integration Built-in homecore-hap subsystem
CLI hass command with config YAML homecore-server with feature flags
Scalability Single instance (HA Cloud for scale) Can be load-balanced (future)
Binary size ~200 MB (Python + deps) ~50 MB (Rust, release build; 200 MB w/ wasmtime)

Performance Targets (unreleased; TBD)

  • Startup time — < 2s to listen on :8123
  • REST endpoint latency — p50 < 1 ms; p99 < 10 ms
  • Event bus throughput — 10,000+ events/sec
  • Automation evaluation — < 100 μs per trigger
  • Concurrent WebSocket connections — 10,000+
  • Memory footprint — ~100 MB (idle); ~500 MB with 1,000 recorded states

Development

Run tests:

cargo test -p homecore-server

Enable debug logging:

RUST_LOG=debug cargo run -p homecore-server -- --bind 127.0.0.1:8123

Build documentation:

cargo doc -p homecore-server --open

Relation to other HOMECORE crates

homecore-server (orchestration binary)
├── homecore (state machine)
├── homecore-api (REST + WS)
├── homecore-recorder (SQLite persistence)
├── homecore-plugins (extension system)
├── homecore-automation (trigger execution)
├── homecore-assist (intent pipeline)
└── homecore-hap (HomeKit bridge)

References