mirror of
https://github.com/ruvnet/RuView
synced 2026-07-06 14:43:17 +00:00
Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 github-actions[bot]
|
43168b38fb |
@@ -1 +1 @@
|
||||
ca58956c1bbee8c46f1798b3d6b6f1f829aa5db90bba53e07177830eca429199
|
||||
667eb054c44ac510342665bf9c93d608868a8ead948ae8774b2796ebce6f8fe7
|
||||
@@ -26,12 +26,7 @@ class Settings(BaseSettings):
|
||||
workers: int = Field(default=1, description="Number of worker processes")
|
||||
|
||||
# Security settings
|
||||
secret_key: str = Field(
|
||||
default="dev-not-secret-CHANGE-IN-PROD",
|
||||
description="Secret key for JWT tokens (production deployments "
|
||||
"MUST override via SECRET_KEY env or .env; the dev "
|
||||
"default is rejected by validate_production_config)",
|
||||
)
|
||||
secret_key: str = Field(..., description="Secret key for JWT tokens")
|
||||
jwt_algorithm: str = Field(default="HS256", description="JWT algorithm")
|
||||
jwt_expire_hours: int = Field(default=24, description="JWT token expiration in hours")
|
||||
allowed_hosts: List[str] = Field(default=["*"], description="Allowed hosts")
|
||||
@@ -163,14 +158,7 @@ class Settings(BaseSettings):
|
||||
model_config = SettingsConfigDict(
|
||||
env_file=".env",
|
||||
env_file_encoding="utf-8",
|
||||
case_sensitive=False,
|
||||
# Tolerate `.env` keys that this Settings model doesn't declare
|
||||
# (e.g., NPM_TOKEN, DOCKER_HUB_TOKEN, PYPI_TOKEN used by other
|
||||
# tooling). Without `extra="ignore"` pydantic-settings 2.x
|
||||
# raises `ValidationError: Extra inputs are not permitted` and
|
||||
# leaks the offending values into the error message — a real
|
||||
# security concern for secret tokens. See verify.py / `./verify`.
|
||||
extra="ignore",
|
||||
case_sensitive=False
|
||||
)
|
||||
|
||||
@field_validator("environment")
|
||||
|
||||
@@ -19,13 +19,9 @@ COPY vendor/ruvector/ /build/vendor/ruvector/
|
||||
# (ADR-115) is wired in (auto-discovery topics flow to Home Assistant)
|
||||
# - cog-ha-matter, the ADR-116 Cognitum cog that wraps HA-DISCO +
|
||||
# HA-MIND + mDNS + embedded broker for Home Assistant / Matter
|
||||
# - homecore-server, the ADRs-126-134 HOMECORE native Rust port of
|
||||
# Home Assistant (HA-wire-compat REST + WebSocket on :8123,
|
||||
# SQLite + ruvector recorder, automation, assist, plugins, HAP)
|
||||
RUN cargo build --release -p wifi-densepose-sensing-server --features mqtt 2>&1 \
|
||||
&& cargo build --release -p cog-ha-matter 2>&1 \
|
||||
&& cargo build --release -p homecore-server 2>&1 \
|
||||
&& strip target/release/sensing-server target/release/cog-ha-matter target/release/homecore-server
|
||||
&& strip target/release/sensing-server target/release/cog-ha-matter
|
||||
|
||||
# Stage 2: Runtime
|
||||
FROM debian:bookworm-slim
|
||||
@@ -39,7 +35,6 @@ WORKDIR /app
|
||||
# Copy binaries
|
||||
COPY --from=builder /build/target/release/sensing-server /app/sensing-server
|
||||
COPY --from=builder /build/target/release/cog-ha-matter /app/cog-ha-matter
|
||||
COPY --from=builder /build/target/release/homecore-server /app/homecore-server
|
||||
|
||||
# Copy UI assets
|
||||
COPY ui/ /app/ui/
|
||||
@@ -57,7 +52,6 @@ RUN set -e; \
|
||||
done; \
|
||||
test -x /app/sensing-server || { echo "FATAL: /app/sensing-server is not executable"; exit 1; }; \
|
||||
test -x /app/cog-ha-matter || { echo "FATAL: /app/cog-ha-matter is not executable"; exit 1; }; \
|
||||
test -x /app/homecore-server || { echo "FATAL: /app/homecore-server is not executable"; exit 1; }; \
|
||||
echo "image assets OK"
|
||||
|
||||
# Optional bearer-token auth on /api/v1/*: leave unset for LAN-mode (default),
|
||||
@@ -73,8 +67,6 @@ EXPOSE 3001
|
||||
EXPOSE 5005/udp
|
||||
# MQTT broker (cog-ha-matter embedded broker — Home Assistant + Matter)
|
||||
EXPOSE 1883
|
||||
# HOMECORE HA-compatible REST + WebSocket (homecore-server)
|
||||
EXPOSE 8123
|
||||
|
||||
ENV RUST_LOG=info
|
||||
|
||||
|
||||
@@ -28,14 +28,6 @@ case "${1:-}" in
|
||||
--sensing-url "${SENSING_URL:-http://127.0.0.1:3000}" \
|
||||
"$@"
|
||||
;;
|
||||
homecore|homecore-server)
|
||||
# Route to the HOMECORE native Rust port of Home Assistant
|
||||
# (ADRs 126-134, v0.10.0). Default bind matches HA at :8123.
|
||||
shift
|
||||
exec /app/homecore-server \
|
||||
--bind "${HOMECORE_BIND:-0.0.0.0:8123}" \
|
||||
"$@"
|
||||
;;
|
||||
esac
|
||||
|
||||
# If the first argument looks like a flag (starts with -), prepend the
|
||||
|
||||
@@ -1,176 +0,0 @@
|
||||
# ADR-133: HOMECORE-ASSIST — Voice/Intent Pipeline + Ruflo Agent Bridge
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-25 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **HOMECORE-ASSIST** |
|
||||
| **Relates to** | [ADR-126](ADR-126-ruview-native-ha-port-master.md) (HOMECORE master), [ADR-127](ADR-127-homecore-state-machine-rust.md) (HOMECORE-CORE), [ADR-130](ADR-130-homecore-rest-websocket-api.md) (HOMECORE-API), [ADR-124](ADR-124-rvagent-mcp-ruvector-npm-integration.md) (SENSE-BRIDGE) |
|
||||
| **Tracking issue** | TBD |
|
||||
| **Crate** | `v2/crates/homecore-assist` |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
Home Assistant's Assist pipeline (`homeassistant/components/assist_pipeline/`) provides
|
||||
voice-to-intent-to-response processing. It chains:
|
||||
|
||||
1. **STT** (speech-to-text) — Whisper, cloud, or satellite
|
||||
2. **NLU** (natural language understanding) — intent recognition via regex/slots
|
||||
3. **Intent handler** — maps intent to a HA service call
|
||||
4. **TTS** (text-to-speech) — synthesises the response for the caller
|
||||
|
||||
HA's intent model (`homeassistant/helpers/intent.py`) is keyword/regex based. Every
|
||||
intent is a named template with slot definitions and a handler that dispatches to HA
|
||||
services. The built-in intents (`homeassistant/components/conversation/default_agent.py`)
|
||||
cover `HassTurnOn`, `HassTurnOff`, `HassLightSet`, `HassNevermind`, `HassCancelAll`,
|
||||
`HassGetState`, `HassGetWeather`, and many others.
|
||||
|
||||
HOMECORE needs a wire-compatible Assist pipeline so that:
|
||||
- The HA iOS/Android companion app's "Assist" button works against HOMECORE.
|
||||
- The HOMECORE-API WebSocket `assist` command (ADR-130 §2.2) has a handler.
|
||||
- The ruflo agent toolchain (ADR-124) can provide LLM-grade intent disambiguation as a
|
||||
drop-in upgrade path for the P1 regex recognizer.
|
||||
|
||||
### 1.1 Ruflo integration approach
|
||||
|
||||
Ruflo's agent runner exposes an MCP-over-stdio interface (`node ruflo-agent.js`).
|
||||
HOMECORE-ASSIST manages a long-lived subprocess (Q3 Windows concern below), sends
|
||||
utterance JSON, and receives intent JSON back. In P1 we ship only the trait surface
|
||||
and a `NoopRunner` stub; the real subprocess management is P2.
|
||||
|
||||
### 1.2 Ruvector semantic intent matching (P2)
|
||||
|
||||
`ruvector-core` provides embedding + cosine-similarity primitives. P2 will add a
|
||||
`SemanticIntentRecognizer` that embeds the utterance and compares it to a HNSW index
|
||||
of intent exemplars, falling back to the P1 regex recognizer when similarity < 0.75.
|
||||
This is the mechanism that allows "dim the lights" to match `HassLightSet` without an
|
||||
explicit regex entry.
|
||||
|
||||
---
|
||||
|
||||
## 2. Design
|
||||
|
||||
### 2.1 Module layout (`v2/crates/homecore-assist/`)
|
||||
|
||||
| Module | Contents |
|
||||
|--------|----------|
|
||||
| `intent` | `IntentName` newtype, `Intent` (name + slots), `IntentResponse` (speech + optional card + optional data) |
|
||||
| `recognizer` | `IntentRecognizer` trait; `RegexIntentRecognizer` (P1); `SemanticIntentRecognizer` stub (P2) |
|
||||
| `handler` | `IntentHandler` trait; built-in handlers: `HassTurnOn`, `HassTurnOff`, `HassLightSet`, `HassNevermind`, `HassCancelAll` |
|
||||
| `runner` | `RufloRunner` trait + `RufloRunnerOpts`; `NoopRunner` (P1 stub); real subprocess runner (P2) |
|
||||
| `pipeline` | `AssistPipeline`: wires recognizer → handler → response; exposes `async fn process(utterance, language) -> IntentResponse` |
|
||||
|
||||
### 2.2 Built-in intent handlers (P1)
|
||||
|
||||
| Handler | HA service call | Slot |
|
||||
|---------|-----------------|------|
|
||||
| `HassTurnOn` | `homeassistant.turn_on` / `light.turn_on` / `switch.turn_on` | `entity_id` |
|
||||
| `HassTurnOff` | `homeassistant.turn_off` / `light.turn_off` / `switch.turn_off` | `entity_id` |
|
||||
| `HassLightSet` | `light.turn_on` | `entity_id`, `brightness` (0–255), `color_name` |
|
||||
| `HassNevermind` | — (no-op, returns acknowledgement) | — |
|
||||
| `HassCancelAll` | — (fires `homeassistant_stop_all_scripts` domain event) | — |
|
||||
|
||||
### 2.3 IntentResponse
|
||||
|
||||
```rust
|
||||
pub struct IntentResponse {
|
||||
pub speech: String,
|
||||
pub card: Option<Card>,
|
||||
pub data: Option<serde_json::Value>,
|
||||
}
|
||||
|
||||
pub struct Card {
|
||||
pub title: String,
|
||||
pub content: String,
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 RufloRunner trait
|
||||
|
||||
```rust
|
||||
#[async_trait]
|
||||
pub trait RufloRunner: Send + Sync + 'static {
|
||||
async fn spawn(&mut self, opts: RufloRunnerOpts) -> Result<(), AssistError>;
|
||||
async fn send_request(&self, payload: serde_json::Value) -> Result<RufloResponse, AssistError>;
|
||||
async fn shutdown(&mut self) -> Result<(), AssistError>;
|
||||
}
|
||||
```
|
||||
|
||||
`RufloResponse` is `{ intent: Option<Intent>, speech: Option<String> }`.
|
||||
|
||||
### 2.5 Pipeline
|
||||
|
||||
```rust
|
||||
pub struct AssistPipeline<R, H> {
|
||||
recognizer: R,
|
||||
handler: H,
|
||||
runner: Option<Box<dyn RufloRunner>>,
|
||||
}
|
||||
|
||||
impl<R: IntentRecognizer, H: IntentHandler> AssistPipeline<R, H> {
|
||||
pub async fn process(&self, utterance: &str, language: &str, hc: &HomeCore)
|
||||
-> Result<IntentResponse, AssistError>;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Questions & Answers
|
||||
|
||||
### Q1 — Why not reuse HA's existing `homeassistant.helpers.intent` via PyO3?
|
||||
|
||||
PyO3 bridges add a GIL lock on every cross-language call; the Assist pipeline processes
|
||||
hundreds of short utterances per day from voice satellites. A native Rust recognizer is
|
||||
simpler and faster. Python HA can still connect as an external integration via MQTT or
|
||||
the HOMECORE WebSocket API.
|
||||
|
||||
### Q2 — How does `RegexIntentRecognizer` handle ambiguity?
|
||||
|
||||
Patterns are tried in registration order; the first match wins. Slot extraction uses
|
||||
named capture groups. A future P2 upgrade can run all patterns, score them by slot
|
||||
completeness, and return the highest-scoring match.
|
||||
|
||||
### Q3 — Windows subprocess teardown (ruflo runner subprocess on Windows)
|
||||
|
||||
`tokio::process::Child` on Windows does not automatically kill the child process when
|
||||
the `Child` struct is dropped — `SIGTERM` is not a Windows concept, and `TerminateProcess`
|
||||
is not called automatically. Options for P2:
|
||||
|
||||
1. Call `child.start_kill()` in a `Drop` impl (requires a `Runtime` handle — tricky in sync Drop).
|
||||
2. Wrap `Child` in an `Arc<Mutex<Option<Child>>>` and call `kill()` in an `async fn shutdown()`.
|
||||
3. Use a Windows job object to bind the subprocess lifetime to the parent process.
|
||||
|
||||
**P2 decision**: implement option 2 (explicit `async shutdown()`) + register a `tokio::signal`
|
||||
handler for `Ctrl+C` / `SIGINT` that calls `shutdown()` before exit. Document the Windows caveat
|
||||
in the crate README and in `runner.rs`. Job object approach (option 3) is deferred to P3 only
|
||||
if option 2 proves insufficient in fleet testing.
|
||||
|
||||
### Q4 — Why is `SemanticIntentRecognizer` a P2 stub?
|
||||
|
||||
The ruvector HNSW index requires the vector store to be populated at startup with intent
|
||||
exemplars. That startup path requires deciding on a serialization format (HNSW index files
|
||||
vs. an in-memory array at compile time), which intersects with ADR-084 (RabitQ) and ADR-067
|
||||
(ruvector v2.0.5). P2 will define the exemplar format and populate the index.
|
||||
|
||||
---
|
||||
|
||||
## 4. Consequences
|
||||
|
||||
- **Positive**: HOMECORE-API `assist` WebSocket command gets a functional backend.
|
||||
- **Positive**: Ruflo LLM pipelines can upgrade intent matching by swapping the `RufloRunner` impl.
|
||||
- **Positive**: P1 ships with zero new heavy dependencies (no subprocess spawning, no ML runtime).
|
||||
- **Negative**: Regex matching has limited coverage; long-tail utterances will return "I'm not sure".
|
||||
- **Deferral**: ruvector semantic recognizer and real subprocess runner both land in P2.
|
||||
|
||||
---
|
||||
|
||||
## 5. Implementation phases
|
||||
|
||||
| Phase | Scope |
|
||||
|-------|-------|
|
||||
| **P1** (this ADR) | `intent`, `recognizer` (regex), `handler` (5 built-ins), `runner` (trait + noop), `pipeline` (end-to-end wiring), 10–15 tests |
|
||||
| **P2** | Real `tokio::process::Child` runner with Windows-safe teardown; `SemanticIntentRecognizer` with ruvector HNSW |
|
||||
| **P3** | STT/TTS bridge, satellite protocol, cloud fallback |
|
||||
@@ -1,301 +0,0 @@
|
||||
# HOMECORE-FRONTEND Design Recon — ADR-131
|
||||
|
||||
**Source:** cognitum-one/v0-appliance dashboard at `http://cognitum-v0:9000/`
|
||||
**Captured:** 2026-05-25 by browser-recon agent (session `20260525-181819-adr131-recon`)
|
||||
**Pages fetched:** dashboard, cogs, seeds, edge, analytics, settings, cluster, tailscale, aidefence, guide (all HTTP 200)
|
||||
**Auth:** dashboard is unauthenticated; `/api/*` requires bearer token — all recon confined to dashboard pages
|
||||
|
||||
---
|
||||
|
||||
## 1. Color Palette
|
||||
|
||||
The entire UI is dark-only. There is no light mode and no `prefers-color-scheme` media query anywhere in the stylesheet. Every surface is drawn from a tight family of near-black navy blues with two accent hues: a cool teal (`--primary`) and a green (`--accent`).
|
||||
|
||||
### Core tokens (hex conversions from HSL source)
|
||||
|
||||
| CSS variable | HSL value | Hex | Role |
|
||||
|---|---|---|---|
|
||||
| `--background` | `220 25% 6%` | `#0b0e13` | Page background, modal overlay base |
|
||||
| `--foreground` | `210 20% 92%` | `#e6eaee` | Body text, headings |
|
||||
| `--primary` | `185 80% 50%` | `#19d4e5` | Teal — active nav underline, CTA borders, ring focus, brand slash |
|
||||
| `--primary-foreground` | `220 25% 6%` | `#0b0e13` | Text on filled primary buttons |
|
||||
| `--accent` | `142 70% 50%` | `#26d867` | Green — secondary CTA, success state, deploy button text |
|
||||
| `--accent-foreground` | `220 25% 6%` | `#0b0e13` | Text on filled accent buttons |
|
||||
| `--secondary` | `220 20% 14%` | `#1c212a` | Button fill, pill-tab background |
|
||||
| `--card` | `220 20% 10%` | `#14171e` | Card surface (also popover) |
|
||||
| `--surface-elevated` | `220 20% 12%` | `#181c24` | Slightly elevated card variant |
|
||||
| `--surface-overlay` | `220 20% 8%` | `#111318` | Modal scrim, sticky navbar |
|
||||
| `--muted` | `220 15% 15%` | `#20242b` | Muted chip backgrounds, scrollbar track |
|
||||
| `--muted-foreground` | `215 15% 55%` | `#7b899d` | Secondary text, labels, timestamps |
|
||||
| `--border` | `220 15% 18%` | `#272b34` | All borders (at 50% opacity by default) |
|
||||
| `--destructive` | `0 65% 50%` | `#d22c2c` | Error state, danger button |
|
||||
| `--ring` | `185 80% 50%` | `#19d4e5` | Focus ring (same hue as primary) |
|
||||
|
||||
### Semantic status colors (inline, not variables)
|
||||
|
||||
| State | Color | Hex | Usage |
|
||||
|---|---|---|---|
|
||||
| Online / success | `hsl(142 70% 50%)` | `#26d867` | `.badge.online`, `.dot.up`, `.heat-cell.up` |
|
||||
| Warning | `hsl(38 80% 60%)` | `#e69940` | `.badge.unpaired`, `.hero-dot.warn`, banner backgrounds |
|
||||
| Error / offline | `hsl(0 65% 50%)` | `#d22c2c` | `.badge.offline`, `.badge.danger`, `.dot.down` |
|
||||
| Info (log line) | `hsl(205 80% 65%)` | `#4db8f5` | Log viewer `.info` class |
|
||||
| Paired | `hsl(185 80% 50%)` | `#19d4e5` | `.badge.paired` (same as primary) |
|
||||
|
||||
---
|
||||
|
||||
## 2. Typography
|
||||
|
||||
### Font families
|
||||
|
||||
The CSS declares two font families via CSS custom properties:
|
||||
|
||||
- `--font-display: 'Outfit', system-ui, sans-serif` — all headings, nav items, buttons, card titles, KPI values. Outfit is a modern geometric sans loaded locally (no Google Fonts outbound call; the source comment says "ship from local chrome.css fallback").
|
||||
- `--font-mono: 'JetBrains Mono', monospace` — timestamps, port numbers, version strings, table cells, log output, KPI labels, chip text.
|
||||
|
||||
### Type scale
|
||||
|
||||
| Token name / usage | Size | Weight | Notes |
|
||||
|---|---|---|---|
|
||||
| Hero title (`h1.hero-title`) | `clamp(1.5rem, 2.4vw, 2.1rem)` | 600 | Fluid, capped at ~33.6px |
|
||||
| Page h1 (`.page`) | `1.5rem` (24px) | 600 | All inner pages |
|
||||
| Section heading (`.row-h h2`) | `1.125rem` (18px) | 700 | Section openers on Cogs/Dashboard |
|
||||
| Card title (`.card-title`) | `0.9375rem` (15px) | 600 | |
|
||||
| Body / button | `0.8125rem` (13px) | 400/500 | Default body, nav links, buttons |
|
||||
| Secondary body / lede | `0.875rem` (14px) | 400 | Page lede text |
|
||||
| Small label | `0.75rem` (12px) | 400–600 | Table cells, modal sub-text |
|
||||
| Micro label | `0.6875rem` (11px) | 600 | Section eyebrows, uppercase KPI labels, badge text |
|
||||
| Mono micro | `0.625rem` (10px) | 400 | Heatmap cells, chip category text |
|
||||
|
||||
Letter-spacing: `0.1em` on section eyebrows (`.section h2`), `0.08em` on filter-rail headings and chip category text, `-0.02em` on all `h1–h4` display headings. Line-height for body is `1.5`; lede text uses `1.45`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Layout Primitives
|
||||
|
||||
### Page shell
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ .appbar (sticky, z-50, backdrop-filter:blur(8px)) │
|
||||
│ [brand-mark] [brand-text] [nav links scrollable] │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ .wrap (max-width: 1400px, padding: 1.5rem 1.25rem) │
|
||||
│ ┌── .hero (full-width, gradient bg, radial accents) │
|
||||
│ ├── .kpi-grid (auto-fill, min 170px columns) │
|
||||
│ ├── .section > h2 (eyebrow) + content │
|
||||
│ └── .grid / .grid-2 / .grid-3 (auto-fit) │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ footer.appfoot (border-top, centered text) │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Appbar:** `position: sticky; top: 0; z-index: 50`. Background is the page background at 90% opacity with 8px blur backdrop-filter, so the page content bleeds through. Nav links overflow-scroll horizontally with a right-fade mask gradient.
|
||||
|
||||
**Active nav state:** primary-colored text + a 2px bottom border line (`::after` pseudo-element) positioned at bottom: -2px of the link. Hover reveals secondary background fill on the link.
|
||||
|
||||
**Content wrap:** max-width 1400px, centered, 1.25rem horizontal padding. Inner page sections are separated by margin-bottom spacing in multiples of 0.75rem (base unit = 12px at 16px root).
|
||||
|
||||
### Cogs page: app-store sub-navigation
|
||||
|
||||
The Cogs page adds a sticky secondary nav bar (`.subnav`) at `top: 3.25rem` (just below the appbar). Tabs are borderless buttons with a 2px bottom underline indicator when active. A `flex: 1` spacer pushes a gear icon to the right edge.
|
||||
|
||||
### Card patterns
|
||||
|
||||
Three card variants, all sharing the same surface gradient and border:
|
||||
|
||||
1. **Standard card (`.card`)** — `background: var(--gradient-card)` (linear 180deg from `--surface-elevated` to `--surface-overlay`), 1px border at 50% opacity, `--radius` (0.75rem), `box-shadow` 8px/32px dark drop shadow.
|
||||
2. **KPI card (`.kpi`)** — 38px icon square left + text right, same gradient, 1rem/1.125rem padding, smaller vertical rhythm.
|
||||
3. **Empty-state card (`.empty-card`)** — dashed 1px border (instead of solid), centered text, optional compact variant. The headline in `.empty-card h3` uses the primary teal, body explains what to do next.
|
||||
|
||||
### Spacing rhythm
|
||||
|
||||
Base unit is 4px. Gaps between grid items are universally `0.75rem` (12px). Card padding is `1.25rem` (20px) for standard, `0.875rem` (14px) for compact. Section margin-bottom is `1.5rem` (24px). The hero section uses `1.75rem` (28px) horizontal padding.
|
||||
|
||||
---
|
||||
|
||||
## 4. Component Vocabulary
|
||||
|
||||
### Navigation components
|
||||
|
||||
- **Appbar** — sticky top bar with brand + horizontal nav links. Brand mark is a 32px rounded SVG icon square.
|
||||
- **Nav link** — 0.4rem × 0.7rem padding, 0.4rem radius, transitions on color + background. Active state: primary text + 2px underline pseudo-element. Mobile: wraps below brand row at 720px.
|
||||
- **Sub-nav / secondary tab bar** (`.subnav`) — app-store style horizontal tab strip, sticky under appbar. Used exclusively on Cogs.
|
||||
- **Pill tabs** (`.pill-tabs` + `.pill-tab`) — smaller rounded-rect tab group for in-card filter switching. Active state fills with primary color.
|
||||
- **Page tabs** (`.page-tabs`) — used on Analytics for domain view switching. Underline-style, same pattern as sub-nav but at content level.
|
||||
|
||||
### Card & data display
|
||||
|
||||
- **Card** (`.card`) — base data container with gradient surface, subtle border, shadow.
|
||||
- **KPI tile** (`.kpi`, `.kpi-tile`) — metric display with icon, label (uppercase micro mono), large value, and optional sub-line. Two variants: `.kpi` (icon-left layout) and `.kpi-tile` (stack layout, used on Seeds/Edge/AIDefence).
|
||||
- **Node card** (`.node`) — cluster member card with mono metadata rows. Key-value pairs in `.node-meta` with dimmed label prefix (`.l` class).
|
||||
- **Cog card** (`.cog`) — product-catalog card with emoji icon, name, description, category chips, and a "Get" pill button. Hover lifts 2px with primary glow border.
|
||||
- **Pick card** (`.pick-card`) — horizontal-scroll featured card (220px fixed width), snap-scroll container. Smaller emoji + name + category + pill CTA.
|
||||
- **Category tile small** (`.cat-tile-sm`) — 180px min-width grid item, emoji + name + count.
|
||||
- **Category tile large** (`.cat-tile-big`) — 16:9 aspect-ratio card, full-bleed with gradient per category.
|
||||
- **Nav tile** (`.nav-tile`) — dashboard home navigation card with icon square, title, description, and a chevron arrow that translates +2px on hover.
|
||||
- **Architecture action card** (`.arch-card`, `.arch-action-card`) — setup wizard launcher cards on the dashboard.
|
||||
|
||||
### Status & feedback
|
||||
|
||||
- **Badge** (`.badge`) — pill with 1px border, 11px mono text. Variants: `role-master` (teal), `role-worker` (green), `online` (green), `offline` (red), `unknown` (muted), `paired` (teal), `unpaired` (amber), `danger` (red).
|
||||
- **Dot** (`.dot`) — 8px circle status indicator. `.up` glows green with box-shadow, `.down` is red, default is muted gray.
|
||||
- **Hero dot** (`.hero-dot`) — 7px circle in the dashboard hero status row. Same three states: `.ok` (green glow), `.warn` (amber glow), `.down` (red glow).
|
||||
- **Op-pill** (`.op-pill`) — "operational status" pill with colored dot inside. Used in dashboard architecture hub.
|
||||
- **AI pill / status chip** (`.pill` on AIDefence, `.md-badge` in cluster) — inline classification badge at 0.68rem. States: `.ok`, `.warn`, `.bad`.
|
||||
- **Chip** (`.chip`) — tiny category/difficulty label, all-caps, 0.5625rem, pill-shaped. Category-colored variants (`.cat-ai`, `.cat-health`, `.cat-security`, etc.) each get a hue-appropriate 15% opacity background.
|
||||
|
||||
### Actions
|
||||
|
||||
- **Button** (`.btn`) — 0.5rem × 0.875rem padding, 0.4rem radius, secondary fill. Variants: `.primary` (filled teal, 600 weight, box-shadow), `.outline` (transparent fill), `.danger` (red tint), `.sm` (compact).
|
||||
- **Hero button** (`.hero-btn`) — slightly larger, display-font, 0.9rem padding, glass-effect dark fill. `.primary` variant uses the green accent gradient.
|
||||
- **Pill CTA** (`.get`, `.pget`) — full pill-radius (9999px), primary-tint background at rest, fills solid on hover. Used on cog cards and pick cards.
|
||||
- **Gear button** (`.gear-btn`) — icon-only square button, transparent at rest, border appears on hover.
|
||||
- **Context menu** (`.ctx-menu`) — dark card dropdown (min-width 180px), each item is a full-width button with secondary hover fill.
|
||||
- **Copy button** (`.copy-btn`) — positioned absolute in `.copy-row`, 0.7rem opacity at rest, `.copied` state turns green/accent.
|
||||
|
||||
### Forms & inputs
|
||||
|
||||
- **Input** — all `<input>`, `<textarea>`, `<select>` inherit dark theme globally. Focus ring: 2px solid primary at 30% opacity (`box-shadow: 0 0 0 2px hsl(var(--ring) / 0.3)`). Checkboxes and radios use `accent-color: hsl(var(--primary))`.
|
||||
- **Collapsible section** (`.coll`, `.coll-h`, `.coll-body`) — used in Settings page. Header row is clickable with `user-select: none`. Body `display: none` by default, revealed on expand.
|
||||
- **Key-value row** (`.kv`) — 3-column grid (160px label | 1fr value | auto action) for settings display.
|
||||
- **Filters rail** (`.filters-rail`) — sticky sidebar on Cogs/Apps tab. Sticky at `top: 7rem` (below both navbars). Contains checkboxes, a range input, and a reset button.
|
||||
- **Range input** — native `<input type="range">` styled with `accent-color: hsl(var(--primary))`.
|
||||
|
||||
### Data visualization
|
||||
|
||||
- **Heatmap** (`.heatmap`) — CSS grid of 14px × variable cells. 60 time columns, label column at 90px. Cell states: `up` (green 70%), `down` (red 70%), `empty` (muted 30%).
|
||||
- **Bar chart** (`.bar-list` + `.bar-row` + `.bar-fill`) — horizontal bar list, 3-col grid (120px label | 1fr bar | 30px value). Bar fill transitions width in 0.3s.
|
||||
- **uPlot time-series** (`.uplot-host`) — 200px height host container; actual charting via uPlot library.
|
||||
- **Three.js 3D** — importmap for `three` + `OrbitControls` in Analytics page, for 3D sensor visualization.
|
||||
- **Log box** (`pre.logbox`) — monospace pre-formatted block, max-height 30rem, overflow-y scroll. Dark background on dark background gives subtle separation via border.
|
||||
- **OTA row table** (`.ota-row`) — 3-col grid (160px | 80px | 1fr) for firmware OTA records.
|
||||
|
||||
### Overlays
|
||||
|
||||
- **Modal** (`.modal-bg` + `.modal`) — fixed inset, 70% opacity blur-backdrop scrim. Modal itself is card-surfaced, max-width 560px. Result states: `.modal-result.ok` (green tint) and `.modal-result.err` (red tint).
|
||||
- **Detail modal** (`.detail-modal-bg` + `.detail-modal`) — larger variant (max 820px, 2rem padding) used on Cog detail view. Header has emoji, name, meta chips; sections below are tabbed.
|
||||
- **Keyboard shortcut tag** (`.kb`) — small monospace tag with secondary background, used inline in Settings and Tailscale pages to show keyboard shortcuts.
|
||||
|
||||
---
|
||||
|
||||
## 5. Iconography
|
||||
|
||||
All icons are inline SVG, 24×24 viewBox, `fill: none`, `stroke: currentColor`, `stroke-width: 2`. The path geometry is **Lucide Icons** — confirmed by comparing the Sun/gear/shield/grid/activity paths against Lucide's source. Key examples observed:
|
||||
|
||||
- Sun/rays (brand mark, dashboard hero)
|
||||
- Settings/gear (nav, subnav gear button)
|
||||
- Activity/pulse (KPI signal icon)
|
||||
- Bar chart 3 (analytics KPI)
|
||||
- Grid 2×2 (cluster/cog layout)
|
||||
- Shield with checkmark (AIDefence)
|
||||
- House (home nav tile)
|
||||
- Book-open (guide nav)
|
||||
|
||||
No external icon font is used. Every icon is self-contained in the HTML at point of use — no sprite sheet.
|
||||
|
||||
---
|
||||
|
||||
## 6. Dark Mode
|
||||
|
||||
The design is **dark-only**. There is no `prefers-color-scheme: light` media query in `v0-chrome.css` or any page-level stylesheet. The color system is entirely designed around the dark palette above. The source comments explicitly note that `fonts.googleapis.com` is blocked for Tailnet isolation, reinforcing that this is an always-dark appliance UI, not a consumer product that needs theming.
|
||||
|
||||
Surface hierarchy (light to dark, within the dark palette):
|
||||
1. `--surface-elevated` (`#181c24`) — slightly lighter card variant
|
||||
2. `--card` (`#14171e`) — standard card
|
||||
3. `--surface-overlay` (`#111318`) — modal/sticky appbar base
|
||||
4. `--background` (`#0b0e13`) — page root
|
||||
|
||||
The appbar uses `background: hsl(var(--background) / 0.9)` + `backdrop-filter: blur(8px)` so content underneath bleeds through as a translucency effect.
|
||||
|
||||
---
|
||||
|
||||
## 7. Notable Interactions
|
||||
|
||||
- **Nav hover:** 150ms color + background transition, no translate. Active state uses a 2px pseudo-element underline that animates in via opacity.
|
||||
- **Nav link active press:** `transform: translateY(1px)` on `:active` at 50ms — very subtle tactile response.
|
||||
- **Card hover:** `transform: translateY(-2px)` at 200ms on cards and cog items. Border shifts from `--border/0.5` to `primary/0.4` on hover. On the nav tiles, box-shadow deepens.
|
||||
- **Hero button hover:** `transform: translateY(-1px)` + border-color shift to primary at 70%.
|
||||
- **Pick card hover:** translateY(-2px) + primary-glow box-shadow.
|
||||
- **Focus ring:** 2px solid primary at 30% opacity as box-shadow — uses `outline: none` everywhere and replaces it with the ring shadow. nav links use `outline: 2px solid hsl(var(--primary)/0.6); outline-offset: 1px` for focus-visible.
|
||||
- **Bar fill animation:** `transition: width 0.3s` on bar chart fill elements for data-load entrance.
|
||||
- **Modal backdrop:** `backdrop-filter: blur(4px)` on modal scrim, `blur(6px)` on the Cog detail modal.
|
||||
- **Copy button feedback:** `.copied` state class swaps border and text to accent green, visible for a short duration (JS-controlled).
|
||||
- **Pill CTA:** Background fills from 15% opacity teal to 100% solid on hover — a strong affordance for primary actions.
|
||||
- **Scroll fade mask:** The nav bar has `mask-image: linear-gradient(to right, black calc(100% - 24px), transparent)` to fade out the rightmost item, hinting at horizontal scroll.
|
||||
- **Cogs hero carousel:** Paginator dots expand from 0.55rem circles to 1.5rem pill shape (border-radius 0.4rem) when active — a distinctive indicator pattern.
|
||||
|
||||
---
|
||||
|
||||
## 8. HA-Parity Opportunities
|
||||
|
||||
For ADR-131 P2, the following comparisons are relevant between this design and Home Assistant's frontend (`home-assistant-main`):
|
||||
|
||||
| HOMECORE component | Cognitum V0 pattern | HA equivalent | Better reference |
|
||||
|---|---|---|---|
|
||||
| KPI metric card | `.kpi` — icon + label + value | `ha-statistic-card`, `sensor-badge` | **Cognitum** — cleaner dense layout; HA's is more verbose |
|
||||
| Status badge/pill | `.badge` + `.chip` — pill with 1px border | `ha-label-badge`, `state-badge` | **HA** — HA has more state variants and i18n built in |
|
||||
| Dark surface cards | `--gradient-card` linear gradient | HA uses flat `var(--card-background-color)` | **Cognitum** — gradient gives depth HA lacks |
|
||||
| Toggle/switch | `accent-color` native checkbox | HA `ha-switch` (Material) | **HA** — purpose-built, accessible, animated |
|
||||
| Navigation | Horizontal sticky nav, underline indicator | HA sidebar (vertical) | Neither — HOMECORE needs a new shell; Cognitum's horizontal bar is appropriate for appliance context |
|
||||
| Heatmap timeline | CSS grid `.heatmap` | No HA equivalent | **Cognitum** — take this pattern directly |
|
||||
| Bar chart | CSS-only `.bar-fill` bar list | HA uses Recharts | **Cognitum** — zero-dep CSS bars good for simple metrics; use for small cards |
|
||||
| Time-series chart | uPlot `.uplot-host` | HA uses ApexCharts / Recharts | **HA** — ApexCharts has more features, better RTL support |
|
||||
| Modal | `.modal-bg` blur-backdrop | HA `ha-dialog` (Material) | **HA** — a11y and focus-trap already solved |
|
||||
| Toast / alert banner | `.modal-result.ok/err` inline result + `.cl-banner.warn/err` | HA `ha-alert` | **HA** — HA's alerts are more composable |
|
||||
| Focus ring | `box-shadow` ring pattern | HA uses `:focus-visible` outline | **HA** — HA's approach has better browser compatibility |
|
||||
| Chip (category) | `.chip.cat-*` per-category color mapping | HA `ha-chip` | **Cognitum** — the category-specific hue mapping is richer |
|
||||
|
||||
---
|
||||
|
||||
## 9. Design Tokens for HOMECORE-FRONTEND P1
|
||||
|
||||
Concrete CSS variable names and starting values for the TypeScript+WASM frontend to adopt. These follow the Cognitum V0 source directly, adjusted where needed for HOMECORE context.
|
||||
|
||||
```css
|
||||
:root {
|
||||
/* Surfaces */
|
||||
--hc-bg: hsl(220 25% 6%); /* #0b0e13 — page root */
|
||||
--hc-surface-card: hsl(220 20% 10%); /* #14171e — card fill */
|
||||
--hc-surface-elevated: hsl(220 20% 12%); /* #181c24 — raised panel */
|
||||
--hc-surface-overlay: hsl(220 20% 8%); /* #111318 — modal/nav base */
|
||||
|
||||
/* Text */
|
||||
--hc-text: hsl(210 20% 92%); /* #e6eaee — primary text */
|
||||
--hc-text-muted: hsl(215 15% 55%); /* #7b899d — secondary/label */
|
||||
|
||||
/* Accent palette */
|
||||
--hc-primary: hsl(185 80% 50%); /* #19d4e5 — teal, primary actions */
|
||||
--hc-primary-fg: hsl(220 25% 6%); /* #0b0e13 — text on primary */
|
||||
--hc-accent: hsl(142 70% 50%); /* #26d867 — green, success/CTA */
|
||||
--hc-accent-fg: hsl(220 25% 6%); /* #0b0e13 — text on accent */
|
||||
--hc-destructive: hsl(0 65% 50%); /* #d22c2c — error/danger */
|
||||
--hc-warning: hsl(38 80% 60%); /* #e69940 — warning/amber */
|
||||
|
||||
/* Borders & rings */
|
||||
--hc-border: hsl(220 15% 18%); /* #272b34 — subtle border */
|
||||
--hc-ring: hsl(185 80% 50%); /* #19d4e5 — focus ring */
|
||||
|
||||
/* Radii */
|
||||
--hc-radius: 0.75rem; /* cards, modals */
|
||||
--hc-radius-sm: 0.4rem; /* buttons, inputs, chips */
|
||||
--hc-radius-pill: 9999px; /* badges, CTA pills */
|
||||
|
||||
/* Typography */
|
||||
--hc-font-display: 'Outfit', system-ui, sans-serif;
|
||||
--hc-font-mono: 'JetBrains Mono', monospace;
|
||||
|
||||
/* Shadows */
|
||||
--hc-shadow-card: 0 8px 32px -8px hsl(220 25% 2% / 0.8);
|
||||
--hc-shadow-glow: 0 0 60px -10px hsl(185 80% 50% / 0.3);
|
||||
|
||||
/* Gradients */
|
||||
--hc-gradient-card: linear-gradient(180deg, hsl(220 20% 12%) 0%, hsl(220 20% 8%) 100%);
|
||||
}
|
||||
```
|
||||
|
||||
**Notes for P1 implementation:**
|
||||
|
||||
- Adopt Outfit + JetBrains Mono from Google Fonts in development; ship local fallbacks for production (Tailnet appliances block outbound font requests per the Cognitum source comment).
|
||||
- The `--hc-ring` focus approach should be implemented as `box-shadow: 0 0 0 2px hsl(var(--hc-ring) / 0.3)` combined with `outline: none` — matches Cognitum's pattern and avoids the offset-gap issue in Firefox.
|
||||
- Add `--hc-gradient-hero` and `--hc-gradient-glow` when the dashboard hero section is built; keep them out of the P1 design-token foundation to avoid premature complexity.
|
||||
- The `--hc-warning` amber is not in the Cognitum `:root` block (it is inline throughout) — elevating it to a token is a deliberate improvement for HOMECORE.
|
||||
@@ -1,160 +0,0 @@
|
||||
# HOMECORE Security Audit — Iter-10
|
||||
|
||||
**Branch**: `feat/adr-126-homecore-impl`
|
||||
**Audit date**: 2026-05-25
|
||||
**Scope**: 8 new crates + integration binary (iter-1 through iter-9)
|
||||
**Auditor**: Security-audit agent (claude-sonnet-4-6)
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
HOMECORE's Rust codebase is structurally sound but ships with two pre-production
|
||||
placeholders that are critical blockers for any production deployment: the HTTP
|
||||
bearer-token validator accepts **any non-empty string as a valid token**, and the
|
||||
WebSocket auth handshake does the same. Every protected endpoint is therefore fully
|
||||
open to unauthenticated attackers who can reach port 8123.
|
||||
|
||||
`cargo audit` flagged **18 advisories** across three dependency trees. Two are
|
||||
Critical (CVSS 9.0): both are Wasmtime sandbox-escape bugs in the Winch and
|
||||
Cranelift compiler backends (RUSTSEC-2026-0095/0096). SQLx 0.7.4 carries a
|
||||
binary-protocol misinterpretation bug (RUSTSEC-2024-0363). The Wasmtime
|
||||
version must be upgraded before any WASM plugin is loaded in production.
|
||||
|
||||
Additional findings: `CorsLayer::permissive()` allows cross-origin requests from
|
||||
any domain; the HAP service record hardcodes a predictable setup code and a
|
||||
broadcast MAC address; `hc_log` writes plugin output directly to `eprintln!`
|
||||
without going through `tracing`; and the WS `subscribe_events` command has no
|
||||
per-connection subscription cap, enabling a resource-exhaustion DoS.
|
||||
|
||||
---
|
||||
|
||||
## Findings
|
||||
|
||||
| ID | Severity | Title | File : Line | Description | Remediation |
|
||||
|----|----------|-------|-------------|-------------|-------------|
|
||||
| HC-01 | **Critical** | Bearer auth accepts any non-empty token (REST) | `homecore-api/src/auth.rs:25` and `rest.rs` (all handlers) | `BearerAuth::from_headers` returns `Ok` for any non-empty string. All REST endpoints (`/api/config`, `/api/states`, `/api/services`, `call_service`) are fully open to any caller. | Implement a token store in P2 before deployment. Until then, enforce network-level ACL so port 8123 is unreachable from untrusted networks. |
|
||||
| HC-02 | **Critical** | WebSocket auth handshake accepts any non-empty token | `homecore-api/src/ws.rs:61–68` | The WS `auth` phase validates only that `access_token` is non-empty. After passing this check the client reaches the full command loop including `call_service`. An attacker sending `{"type":"auth","access_token":"x"}` gets a fully authenticated session. | Same as HC-01; block at network until real token store is wired. |
|
||||
| HC-03 | **Critical** | Wasmtime 25.0.3 — sandbox-escape via Winch backend (RUSTSEC-2026-0095) | `homecore-plugins/Cargo.toml` | The Winch compiler backend in Wasmtime 25.0.3 allows a sandboxed WASM plugin to perform out-of-sandbox memory writes (CVSS 9.0). | Upgrade `wasmtime` to `>=36.0.7` or `>=42.0.2`. |
|
||||
| HC-04 | **Critical** | Wasmtime 25.0.3 — sandbox-escape via miscompiled heap access on aarch64 Cranelift (RUSTSEC-2026-0096) | `homecore-plugins/Cargo.toml` | Miscompiled guest heap access in Cranelift's aarch64 backend enables sandbox escape (CVSS 9.0). Production Pi 5 targets are aarch64. | Upgrade `wasmtime` to `>=36.0.7` or `>=42.0.2`. |
|
||||
| HC-05 | **High** | `CorsLayer::permissive()` allows all cross-origin requests | `homecore-api/src/app.rs:25` | `CorsLayer::permissive()` sets `Access-Control-Allow-Origin: *` and allows all methods and headers. Any webpage on any origin can make authenticated API calls using a stored bearer token (when HC-01/02 are fixed). | Replace with an explicit allowlist: `CorsLayer::new().allow_origin(expected_origin).allow_methods([GET, POST])`. |
|
||||
| HC-06 | **High** | SQLx 0.7.4 — binary protocol misinterpretation (RUSTSEC-2024-0363) | `homecore-recorder/Cargo.toml` | Truncating/overflowing casts in SQLx 0.7.4's binary protocol handling can cause values to be misread. Although HOMECORE only uses SQLite (not MySQL/Postgres), the vulnerable codepath is in the shared crate. | Upgrade `sqlx` to `>=0.8.1`. |
|
||||
| HC-07 | **High** | No per-connection subscription cap on WS `subscribe_events` | `homecore-api/src/ws.rs:237–295` | A single authenticated WS connection can call `subscribe_events` in an unbounded loop. Each subscription spawns a Tokio task and takes one broadcast receiver slot. With the bus capacity at 4096 slots, a malicious client can exhaust OS thread/task resources before the bus fills. | Add a per-connection subscription ceiling (e.g., 50). Reject further `subscribe_events` commands with `"too_many_subscriptions"`. |
|
||||
| HC-08 | **High** | Hardcoded HAP setup code and broadcast MAC in production binary | `homecore-server/src/main.rs:113–114`, `homecore-hap/src/bridge.rs:143–144` | The integration binary hard-codes `setup_code: "123-45-678"` and `device_id: "AA:BB:CC:DD:EE:FF"`. When real HAP pairing lands in P2 any attacker on the local network can pair with the bridge using the published setup code; the broadcast MAC address is also invalid per the HAP specification. | Generate a random setup code and a locally administered unicast MAC at startup (or require them as CLI arguments). Never use a known-fixed setup code. |
|
||||
| HC-09 | **Medium** | Wasmtime 25.0.3 — 11 additional medium/low CVEs | `homecore-plugins/Cargo.toml` | RUSTSEC-2025-0046, -0118, -2026-0020, -0021, -0085, -0086, -0087, -0088, -0089, -0091, -0092, -0093, -0094 affect resource exhaustion, host data leakage, OOB reads/writes, and panics. All are fixed in wasmtime `>=36.0.7`. | Same fix as HC-03/04: upgrade wasmtime. |
|
||||
| HC-10 | **Medium** | `hc_log` writes plugin output via `eprintln!` bypassing structured logging | `homecore-plugins/src/wasmtime_runtime.rs:297` | Plugin log messages are written directly to stderr via `eprintln!`, bypassing the `tracing` subscriber. This means: (a) log level filtering does not apply to plugin output; (b) log aggregation pipelines (e.g., JSON structured logs) miss plugin messages. A verbose or malicious plugin can flood stderr. | Replace `eprintln!` with `tracing::debug!/info!/warn!/error!` using the already-imported `LogLevel`. |
|
||||
| HC-11 | **Medium** | No size bound on `set_state` body or `attributes` JSON | `homecore-api/src/rest.rs:95–108`, `ws.rs:222–235` | `POST /api/states/:entity_id` and the WS `call_service` / `get_states` paths accept a `serde_json::Value` body with no size limit beyond Axum's default (2 MB). Specially crafted deeply-nested JSON can cause quadratic parse time or high-memory allocation during serialization. | Apply `axum::extract::DefaultBodyLimit::max(65536)` on the route or globally; validate JSON depth before accepting. |
|
||||
| HC-12 | **Medium** | `rsa 0.9.10` — Marvin Attack timing side-channel (RUSTSEC-2023-0071) | transitive via `sqlx-mysql 0.7.4` | The `rsa` crate's decryption is vulnerable to timing-based key recovery. Pulled in by `sqlx-mysql` even though HOMECORE only uses SQLite. No fix is available upstream. | Add `sqlx` features `sqlite` only (remove `mysql`/`postgres` from the feature list) to avoid pulling in `sqlx-mysql` and the `rsa` transitive dependency. |
|
||||
| HC-13 | **Medium** | `shlex 0.1.1` — shell-injection via quote API (RUSTSEC-2024-0006) | transitive via `wasm3-sys 0.3.0 → wasm3 0.3.1 → homecore-plugins` | `shlex`'s quote function can produce unsafe shell strings. Pulled in by the `wasm3` build system. Not directly callable from HOMECORE Rust code but present in the binary's dependency tree. | Upgrade `shlex` to `>=1.3.0` or drop the `wasm3` dependency if `WasmtimeRuntime` is the production path. |
|
||||
| HC-14 | **Low** | No TLS on the HTTP/WS listener | `homecore-server/src/main.rs:122–128` | The Axum listener binds plain TCP (`axum::serve`). Bearer tokens and all home automation data are transmitted in cleartext. On LAN deployments an attacker with ARP poisoning can intercept credentials. | Add `rustls`/`axum-server` TLS termination or document that a TLS-terminating reverse proxy (nginx/Caddy) is required. |
|
||||
| HC-15 | **Low** | Migration CLI performs no symlink/traversal check on `.storage/` path | `homecore-migrate/src/storage.rs:36–37`, `main.rs:14–32` | `HaStorageDir::file_path` calls `self.path.join(name)` where `name` comes from hard-coded constants, so exploitation requires the `--storage` argument itself to point outside the intended tree. There is no `Path::canonicalize` + prefix check. While the current filenames are constants, if P2 makes `name` data-driven the surface widens. | Add `path.canonicalize()` + assert prefix after computing `file_path` if the name ever becomes user-controlled. Document this as a P2 gate. |
|
||||
| HC-16 | **Low** | `AutomationEngine` uses `eprintln!` for action errors | `homecore-automation/src/engine.rs:93–95, 105` | Action errors and lag notices are emitted via `eprintln!`, not `tracing::warn!`. Same issues as HC-10: bypasses structured logging. | Replace with `tracing::warn!`/`tracing::error!`. |
|
||||
| HC-17 | **Informational** | WS `call_service` authorization is contingent on fixing HC-01/HC-02 | `homecore-api/src/ws.rs:222–235` | `call_service` (including destructive calls such as `homeassistant.restart`) sits behind the WS auth handshake. Once HC-01 and HC-02 are fixed this path is properly guarded. No additional change needed here beyond those fixes. | No action required beyond HC-02. |
|
||||
| HC-18 | **Informational** | `hc_state_subscribe` accumulates entity strings without eviction | `homecore-plugins/src/wasmtime_runtime.rs:263–268` | The `PluginStoreData.subscriptions` Vec grows without bound if a plugin repeatedly subscribes to the same entity. There is no deduplication. This is a plugin-local memory leak, not a sandbox escape. | Deduplicate on insert: `if !caller.data().subscriptions.contains(&eid)`. |
|
||||
|
||||
---
|
||||
|
||||
## Negative-Result Section (Surfaces Checked and Found Clean)
|
||||
|
||||
**SQL injection (homecore-recorder/src/db.rs)**: All queries use `sqlx::query`
|
||||
with positional `?` bind parameters. No `format!`-constructed SQL was found in
|
||||
any path (`record_state`, `record_event`, `get_state_history`, `search_semantic`,
|
||||
`apply_schema`). Clean.
|
||||
|
||||
**WS bearer token in logs/error messages**: The bearer token is extracted and
|
||||
immediately discarded after the non-empty check at ws.rs:62. It is not passed
|
||||
to any `tracing` macro, `eprintln!`, or error-display path. The `access_token`
|
||||
field is not part of any `Debug`-derived struct that enters a log path. Clean.
|
||||
|
||||
**REST bearer token in logs/error messages**: `BearerAuth(token)` is `Debug`
|
||||
but no handler logs it or includes it in an error response. `ApiError` variants
|
||||
do not capture the token. Clean.
|
||||
|
||||
**WASM linear-memory buffer overflow in `hc_state_get`/`hc_state_set`**: The
|
||||
`read_str` helper validates `len < 0` and `len > MAX_ABI_BUFFER_BYTES (65536)`
|
||||
before slicing, and uses `mem.get(ptr..ptr+len)?` which cannot panic. In
|
||||
`hc_state_get` phase 3, the write is guarded by `json_bytes.len() > out_cap`
|
||||
before attempting the slice. The `call_export_str` host-to-guest path also uses
|
||||
`.get_mut(ptr..ptr+len).ok_or_else(...)` rather than unchecked indexing. No
|
||||
buffer-overflow vector identified in the host ABI.
|
||||
|
||||
**WASM JSON ABI escape**: Plugins receive and emit plain UTF-8 JSON strings via
|
||||
the linear-memory ABI. The host deserializes attribute JSON with
|
||||
`serde_json::from_str` and defaults to `{}` on parse failure — no panic path.
|
||||
No mechanism for a plugin to escape the Cranelift JIT sandbox via the JSON layer
|
||||
alone was identified; the sandbox-escape risk is in the Cranelift/Winch compiler
|
||||
backends (HC-03/04).
|
||||
|
||||
**Path traversal in homecore-migrate**: All `.storage/` filenames are currently
|
||||
hard-coded constants (`"core.entity_registry"`, `"core.device_registry"`, etc.)
|
||||
in the Rust source. The `--storage` and `--config-dir` arguments are user-supplied
|
||||
but refer to the directory root, not individual filenames. No user-controlled
|
||||
string is concatenated into a file path. Clean at P1 scope (noted as a P2 gate in HC-15).
|
||||
|
||||
**DoS via event-bus flood from a plugin**: A WASM plugin can call `hc_state_set`
|
||||
in a tight loop. Each call fires a `broadcast::Sender::send` on the system channel
|
||||
(capacity 4096). When the channel is full, `send` returns 0 (receivers are
|
||||
dropped/lagged) but does not block or panic. Lagged receivers are notified via
|
||||
`RecvError::Lagged`. The state machine itself does not back-pressure the sender.
|
||||
The flood can cause the recorder and automation engine to lag, but it cannot crash
|
||||
the host process. Noted as design-level concern; acceptable for P1.
|
||||
|
||||
**Secrets leakage in homecore-migrate InspectSecrets**: The CLI correctly prints
|
||||
`<redacted>` for secret values and only logs key names.
|
||||
|
||||
---
|
||||
|
||||
## Critical-Path Remediation List (Required Before Production Deployment)
|
||||
|
||||
The following items MUST be resolved before `homecore-server` is reachable from
|
||||
any untrusted network:
|
||||
|
||||
1. **HC-01 + HC-02 (Critical)** — Implement the token store and validate bearer
|
||||
tokens in both `BearerAuth::from_headers` and the WS `handle_socket` auth
|
||||
phase. Until this is done every REST and WS endpoint is completely open.
|
||||
|
||||
2. **HC-03 + HC-04 (Critical)** — Upgrade `wasmtime` in `homecore-plugins/Cargo.toml`
|
||||
from `25.0.3` to `>=36.0.7` (or `>=42.0.2`). The current version has two
|
||||
confirmed CVSS-9.0 sandbox-escape bugs; loading any third-party WASM plugin
|
||||
on the current version cannot be considered safe.
|
||||
|
||||
3. **HC-06 (High)** — Upgrade `sqlx` from `0.7.4` to `>=0.8.1` to eliminate the
|
||||
binary-protocol misinterpretation bug.
|
||||
|
||||
4. **HC-05 (High)** — Replace `CorsLayer::permissive()` with an explicit
|
||||
origin allowlist before any browser-accessible deployment.
|
||||
|
||||
5. **HC-08 (High)** — Replace the hardcoded HAP setup code and broadcast MAC
|
||||
address with randomly generated values before P2 real HAP pairing lands.
|
||||
|
||||
6. **HC-07 (High)** — Add per-connection subscription limit to the WS command
|
||||
loop before exposing the server to untrusted LAN clients.
|
||||
|
||||
---
|
||||
|
||||
## Dependency CVE Summary
|
||||
|
||||
`cargo audit` reported **18 advisories** against workspace `Cargo.lock`:
|
||||
|
||||
| Advisory | Crate | Severity | Affects HOMECORE |
|
||||
|----------|-------|----------|------------------|
|
||||
| RUSTSEC-2026-0096 | wasmtime 25.0.3 | Critical (9.0) | homecore-plugins |
|
||||
| RUSTSEC-2026-0095 | wasmtime 25.0.3 | Critical (9.0) | homecore-plugins |
|
||||
| RUSTSEC-2026-0093 | wasmtime 25.0.3 | Medium (6.9) | homecore-plugins |
|
||||
| RUSTSEC-2026-0020 | wasmtime 25.0.3 | Medium (6.9) | homecore-plugins |
|
||||
| RUSTSEC-2026-0021 | wasmtime 25.0.3 | Medium (6.9) | homecore-plugins |
|
||||
| RUSTSEC-2024-0363 | sqlx 0.7.4 | (no CVSS) | homecore-recorder |
|
||||
| RUSTSEC-2026-0091 | wasmtime 25.0.3 | Medium (6.1) | homecore-plugins |
|
||||
| RUSTSEC-2026-0094 | wasmtime 25.0.3 | Medium (6.1) | homecore-plugins |
|
||||
| RUSTSEC-2026-0089 | wasmtime 25.0.3 | Medium (5.9) | homecore-plugins |
|
||||
| RUSTSEC-2026-0092 | wasmtime 25.0.3 | Medium (5.9) | homecore-plugins |
|
||||
| RUSTSEC-2023-0071 | rsa 0.9.10 | Medium (5.9) | transitive via sqlx-mysql |
|
||||
| RUSTSEC-2026-0085 | wasmtime 25.0.3 | Medium (5.6) | homecore-plugins |
|
||||
| RUSTSEC-2026-0087 | wasmtime 25.0.3 | Medium (4.1) | homecore-plugins |
|
||||
| RUSTSEC-2025-0046 | wasmtime 25.0.3 | Low (3.3) | homecore-plugins |
|
||||
| RUSTSEC-2026-0086 | wasmtime 25.0.3 | Low (2.3) | homecore-plugins |
|
||||
| RUSTSEC-2026-0088 | wasmtime 25.0.3 | Low (2.3) | homecore-plugins |
|
||||
| RUSTSEC-2025-0118 | wasmtime 25.0.3 | Low (1.8) | homecore-plugins |
|
||||
| RUSTSEC-2024-0006 | shlex 0.1.1 | (no CVSS) | transitive via wasm3-sys |
|
||||
|
||||
All 15 wasmtime advisories are resolved by upgrading to `wasmtime >= 36.0.7`.
|
||||
@@ -1,5 +0,0 @@
|
||||
node_modules/
|
||||
dist/
|
||||
.vite/
|
||||
*.tsbuildinfo
|
||||
coverage/
|
||||
@@ -1,69 +0,0 @@
|
||||
# @ruvnet/homecore-frontend
|
||||
|
||||
HOMECORE web UI — built with Lit 3, TypeScript, and Vite.
|
||||
Design system mirrors the cognitum-v0 / v0-appliance dashboard (ADR-131).
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev # http://localhost:5173
|
||||
```
|
||||
|
||||
The Vite dev server proxies `/api` → `http://localhost:8123`, so you need a
|
||||
`homecore-api-server` (or the `wifi-densepose-sensing-server` crate) running on `:8123`.
|
||||
|
||||
## Scripts
|
||||
|
||||
| Script | Description |
|
||||
|--------|-------------|
|
||||
| `npm run dev` | Start Vite dev server on port 5173 |
|
||||
| `npm run build` | TypeScript compile + Vite production bundle → `dist/` |
|
||||
| `npm run lint` | ESLint on `src/` |
|
||||
| `npm test` | Vitest unit tests (3 suites, jsdom) |
|
||||
|
||||
## Package layout
|
||||
|
||||
```
|
||||
frontend/
|
||||
src/
|
||||
api/
|
||||
client.ts # fetch + WebSocket client (REST + WS)
|
||||
types.ts # TypeScript types matching homecore-api JSON shapes
|
||||
components/
|
||||
AppShell.ts # <hc-app-shell> — header + nav + content slot
|
||||
StateCard.ts # <hc-state-card> — single entity state card
|
||||
icons/
|
||||
lucide.ts # Tree-shaken Lucide icon wrapper
|
||||
styles/
|
||||
tokens.css # 16 CSS custom properties (--hc-*)
|
||||
base.css # Typography reset, page shell, nav layout
|
||||
__tests__/ # Vitest unit tests
|
||||
index.html # Shell loading src/main.ts
|
||||
vite.config.ts
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
```
|
||||
|
||||
## Design system
|
||||
|
||||
Colors, typography, and components mirror the cognitum-v0 dashboard
|
||||
(`http://cognitum-v0:9000/`). Dark-only; no light-mode. Key tokens:
|
||||
|
||||
- `--hc-primary` `#19d4e5` — teal (active nav, focus ring, CTA borders)
|
||||
- `--hc-accent` `#26d867` — green (success, secondary CTA)
|
||||
- `--hc-bg` `#0b0e13` — near-black navy page root
|
||||
- Font: Outfit (display) + JetBrains Mono (mono)
|
||||
- Icons: Lucide (SVG, `stroke: currentColor`, no icon font)
|
||||
|
||||
See `docs/design/HOMECORE-FRONTEND-design-recon.md` for the full recon.
|
||||
|
||||
## Architecture notes
|
||||
|
||||
- Components are standard Lit `LitElement` custom elements — compatible with
|
||||
any HTML page and with Home Assistant's Lit-based frontend.
|
||||
- The REST client uses `fetch`; the WS client uses `WebSocket`. Both accept a
|
||||
bearer token and are fully typed against the Rust `homecore-api` JSON shapes.
|
||||
- WASM: `vite.config.ts` enables `.wasm` asset import. Hook up via dynamic
|
||||
`import('/path/to/module.wasm?init')` when WASM bindings are ready.
|
||||
@@ -1,18 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<meta name="color-scheme" content="dark" />
|
||||
<title>HOMECORE</title>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
||||
<link
|
||||
href="https://fonts.googleapis.com/css2?family=Outfit:wght@400;500;600;700&family=JetBrains+Mono:wght@400;600&display=swap"
|
||||
rel="stylesheet"
|
||||
/>
|
||||
</head>
|
||||
<body>
|
||||
<hc-app-shell></hc-app-shell>
|
||||
<script type="module" src="/src/main.ts"></script>
|
||||
</body>
|
||||
</html>
|
||||
Generated
-4429
File diff suppressed because it is too large
Load Diff
@@ -1,24 +0,0 @@
|
||||
{
|
||||
"name": "@ruvnet/homecore-frontend",
|
||||
"version": "0.1.0-alpha.0",
|
||||
"description": "HOMECORE web UI — Lit + TypeScript + Vite, cognitum-v0 design system",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"dev": "vite",
|
||||
"build": "tsc && vite build",
|
||||
"lint": "eslint src --ext .ts",
|
||||
"test": "vitest run"
|
||||
},
|
||||
"dependencies": {
|
||||
"lit": "^3.2.1",
|
||||
"lucide": "^0.474.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.10.0",
|
||||
"eslint": "^9.17.0",
|
||||
"jsdom": "^25.0.0",
|
||||
"typescript": "^5.7.2",
|
||||
"vite": "^6.0.6",
|
||||
"vitest": "^2.1.8"
|
||||
}
|
||||
}
|
||||
@@ -1,82 +0,0 @@
|
||||
/**
|
||||
* Unit tests for <hc-state-card>.
|
||||
* Verifies that the component renders entity_id and state value into the DOM.
|
||||
*
|
||||
* Uses jsdom (via vitest environment) — no real browser required.
|
||||
*/
|
||||
|
||||
import { describe, it, expect, beforeAll } from 'vitest';
|
||||
import type { StateView } from '../api/types.js';
|
||||
|
||||
// Register the custom element before tests run
|
||||
beforeAll(async () => {
|
||||
// jsdom does not support Lit's adoptedStyleSheets; suppress the error.
|
||||
if (typeof document !== 'undefined' && !document.adoptedStyleSheets) {
|
||||
Object.defineProperty(document, 'adoptedStyleSheets', { value: [], writable: true });
|
||||
}
|
||||
await import('../components/StateCard.js');
|
||||
});
|
||||
|
||||
function makeState(overrides: Partial<StateView> = {}): StateView {
|
||||
return {
|
||||
entity_id: 'light.living_room',
|
||||
state: 'on',
|
||||
attributes: { brightness: 255 },
|
||||
last_changed: '2026-05-25T10:00:00Z',
|
||||
last_updated: '2026-05-25T10:00:00Z',
|
||||
context: { id: 'abc123', user_id: null, parent_id: null },
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe('StateCard', () => {
|
||||
it('renders entity_id in the DOM', async () => {
|
||||
const el = document.createElement('hc-state-card') as HTMLElement & { state: StateView };
|
||||
el.state = makeState();
|
||||
document.body.appendChild(el);
|
||||
|
||||
// Lit renders synchronously into shadow root after a microtask
|
||||
await el.updateComplete;
|
||||
|
||||
const shadowRoot = el.shadowRoot!;
|
||||
const entityEl = shadowRoot.querySelector('.entity-id');
|
||||
expect(entityEl).not.toBeNull();
|
||||
expect(entityEl!.textContent).toContain('light.living_room');
|
||||
|
||||
document.body.removeChild(el);
|
||||
});
|
||||
|
||||
it('renders the state value', async () => {
|
||||
const el = document.createElement('hc-state-card') as HTMLElement & { state: StateView };
|
||||
el.state = makeState({ state: 'off' });
|
||||
document.body.appendChild(el);
|
||||
|
||||
await el.updateComplete;
|
||||
|
||||
const stateEl = el.shadowRoot!.querySelector('.state-value');
|
||||
expect(stateEl).not.toBeNull();
|
||||
expect(stateEl!.textContent).toBe('off');
|
||||
|
||||
document.body.removeChild(el);
|
||||
});
|
||||
|
||||
it('applies .off badge class for unavailable state', async () => {
|
||||
const el = document.createElement('hc-state-card') as HTMLElement & { state: StateView };
|
||||
el.state = makeState({ state: 'unavailable' });
|
||||
document.body.appendChild(el);
|
||||
|
||||
await el.updateComplete;
|
||||
|
||||
const badge = el.shadowRoot!.querySelector('.badge.off');
|
||||
expect(badge).not.toBeNull();
|
||||
|
||||
document.body.removeChild(el);
|
||||
});
|
||||
});
|
||||
|
||||
// Augment for updateComplete
|
||||
declare global {
|
||||
interface HTMLElement {
|
||||
updateComplete: Promise<boolean>;
|
||||
}
|
||||
}
|
||||
@@ -1,67 +0,0 @@
|
||||
/**
|
||||
* Unit tests for HomecoreClient REST methods.
|
||||
* Mocks global `fetch` and asserts correct URL + Authorization header.
|
||||
*/
|
||||
|
||||
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
|
||||
import { HomecoreClient } from '../api/client.js';
|
||||
|
||||
describe('HomecoreClient', () => {
|
||||
const token = 'test-bearer-token';
|
||||
let client: HomecoreClient;
|
||||
let fetchSpy: ReturnType<typeof vi.fn>;
|
||||
|
||||
beforeEach(() => {
|
||||
client = new HomecoreClient({ token });
|
||||
fetchSpy = vi.fn().mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve([]),
|
||||
} as Response);
|
||||
vi.stubGlobal('fetch', fetchSpy);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.unstubAllGlobals();
|
||||
});
|
||||
|
||||
it('getStates() GETs /api/states with the bearer header', async () => {
|
||||
await client.getStates();
|
||||
|
||||
expect(fetchSpy).toHaveBeenCalledOnce();
|
||||
const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
|
||||
|
||||
expect(url).toBe('/api/states');
|
||||
expect((init.headers as Record<string, string>)['Authorization']).toBe(`Bearer ${token}`);
|
||||
expect(init.method).toBe('GET');
|
||||
});
|
||||
|
||||
it('getState() GETs /api/states/:entity_id with the bearer header', async () => {
|
||||
fetchSpy.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ entity_id: 'light.living', state: 'on', attributes: {}, last_changed: '', last_updated: '', context: { id: 'x', user_id: null, parent_id: null } }),
|
||||
} as Response);
|
||||
|
||||
await client.getState('light.living');
|
||||
|
||||
const [url] = fetchSpy.mock.calls[0] as [string, RequestInit];
|
||||
expect(url).toBe('/api/states/light.living');
|
||||
});
|
||||
|
||||
it('getConfig() GETs /api/config', async () => {
|
||||
fetchSpy.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ location_name: 'Home', version: '0.1.0', state: 'RUNNING', components: [] }),
|
||||
} as Response);
|
||||
|
||||
await client.getConfig();
|
||||
|
||||
const [url] = fetchSpy.mock.calls[0] as [string, RequestInit];
|
||||
expect(url).toBe('/api/config');
|
||||
});
|
||||
|
||||
it('throws on non-OK response', async () => {
|
||||
fetchSpy.mockResolvedValueOnce({ ok: false, status: 401, statusText: 'Unauthorized' } as Response);
|
||||
|
||||
await expect(client.getStates()).rejects.toThrow('401');
|
||||
});
|
||||
});
|
||||
@@ -1,66 +0,0 @@
|
||||
/**
|
||||
* Validates that tokens.css contains all 16 documented HOMECORE design tokens.
|
||||
* Reads the file from disk and checks for each CSS custom property name.
|
||||
*/
|
||||
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { resolve, dirname } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const tokensPath = resolve(__dirname, '../styles/tokens.css');
|
||||
const css = readFileSync(tokensPath, 'utf-8');
|
||||
|
||||
/**
|
||||
* The 16 design tokens from ADR-131 §9 / HOMECORE-FRONTEND-design-recon.md §1.
|
||||
* 4 surfaces + 2 text + 6 accent/status + 2 border/ring + 2 radius = 16 tokens.
|
||||
*/
|
||||
const REQUIRED_TOKENS = [
|
||||
// Surfaces (4)
|
||||
'--hc-bg',
|
||||
'--hc-surface-card',
|
||||
'--hc-surface-elevated',
|
||||
'--hc-surface-overlay',
|
||||
// Text (2)
|
||||
'--hc-text',
|
||||
'--hc-text-muted',
|
||||
// Accent palette (6)
|
||||
'--hc-primary',
|
||||
'--hc-primary-fg',
|
||||
'--hc-accent',
|
||||
'--hc-accent-fg',
|
||||
'--hc-destructive',
|
||||
'--hc-warning',
|
||||
// Borders & rings (2)
|
||||
'--hc-border',
|
||||
'--hc-ring',
|
||||
// Radii (2)
|
||||
'--hc-radius',
|
||||
'--hc-radius-sm',
|
||||
] as const;
|
||||
|
||||
describe('tokens.css', () => {
|
||||
it('contains all 16 documented design tokens', () => {
|
||||
for (const token of REQUIRED_TOKENS) {
|
||||
expect(css, `Missing token: ${token}`).toContain(token);
|
||||
}
|
||||
});
|
||||
|
||||
it('has exactly 16 (or more) --hc- custom properties', () => {
|
||||
const matches = css.match(/--hc-[\w-]+\s*:/g) ?? [];
|
||||
// De-duplicate (token may appear in comments)
|
||||
const unique = new Set(matches.map(m => m.replace(/\s*:/, '')));
|
||||
expect(unique.size).toBeGreaterThanOrEqual(16);
|
||||
});
|
||||
|
||||
it('defines the teal primary token with the correct hue value', () => {
|
||||
// --hc-primary must reference HSL hue 185 (teal, from cognitum-v0)
|
||||
expect(css).toMatch(/--hc-primary\s*:\s*hsl\(185/);
|
||||
});
|
||||
|
||||
it('defines the green accent token (#26d867)', () => {
|
||||
// --hc-accent must reference HSL 142 70% 50%
|
||||
expect(css).toMatch(/--hc-accent\s*:\s*hsl\(142/);
|
||||
});
|
||||
});
|
||||
@@ -1,132 +0,0 @@
|
||||
/**
|
||||
* HOMECORE API client.
|
||||
*
|
||||
* REST: fetch-based, bearer token auth. Base URL defaults to window.location.origin
|
||||
* so the Vite dev-server proxy handles the `/api` → `:8123` rewrite.
|
||||
* WS: native WebSocket, mirrors HA's ws handshake protocol (auth_required → auth → auth_ok).
|
||||
*/
|
||||
|
||||
import type {
|
||||
ApiConfig,
|
||||
ServiceDomainView,
|
||||
StateView,
|
||||
WsAuthOk,
|
||||
WsAuthRequired,
|
||||
WsServerMessage,
|
||||
} from './types.js';
|
||||
|
||||
export interface ClientOptions {
|
||||
baseUrl?: string;
|
||||
token: string;
|
||||
}
|
||||
|
||||
export class HomecoreClient {
|
||||
private readonly base: string;
|
||||
private readonly token: string;
|
||||
|
||||
constructor(options: ClientOptions) {
|
||||
this.base = options.baseUrl ?? '';
|
||||
this.token = options.token;
|
||||
}
|
||||
|
||||
// ── REST helpers ────────────────────────────────────────────────────────────
|
||||
|
||||
private headers(): HeadersInit {
|
||||
return {
|
||||
'Authorization': `Bearer ${this.token}`,
|
||||
'Content-Type': 'application/json',
|
||||
};
|
||||
}
|
||||
|
||||
private async get<T>(path: string): Promise<T> {
|
||||
const resp = await fetch(`${this.base}${path}`, {
|
||||
method: 'GET',
|
||||
headers: this.headers(),
|
||||
});
|
||||
if (!resp.ok) {
|
||||
throw new Error(`GET ${path} → ${resp.status} ${resp.statusText}`);
|
||||
}
|
||||
return resp.json() as Promise<T>;
|
||||
}
|
||||
|
||||
private async post<T>(path: string, body: unknown): Promise<T> {
|
||||
const resp = await fetch(`${this.base}${path}`, {
|
||||
method: 'POST',
|
||||
headers: this.headers(),
|
||||
body: JSON.stringify(body),
|
||||
});
|
||||
if (!resp.ok) {
|
||||
throw new Error(`POST ${path} → ${resp.status} ${resp.statusText}`);
|
||||
}
|
||||
return resp.json() as Promise<T>;
|
||||
}
|
||||
|
||||
// ── REST endpoints (mirrors rest.rs) ─────────────────────────────────────
|
||||
|
||||
getConfig(): Promise<ApiConfig> {
|
||||
return this.get<ApiConfig>('/api/config');
|
||||
}
|
||||
|
||||
getStates(): Promise<StateView[]> {
|
||||
return this.get<StateView[]>('/api/states');
|
||||
}
|
||||
|
||||
getState(entityId: string): Promise<StateView> {
|
||||
return this.get<StateView>(`/api/states/${encodeURIComponent(entityId)}`);
|
||||
}
|
||||
|
||||
setState(entityId: string, state: string, attributes?: Record<string, unknown>): Promise<StateView> {
|
||||
return this.post<StateView>(`/api/states/${encodeURIComponent(entityId)}`, {
|
||||
state,
|
||||
attributes: attributes ?? {},
|
||||
});
|
||||
}
|
||||
|
||||
getServices(): Promise<ServiceDomainView[]> {
|
||||
return this.get<ServiceDomainView[]>('/api/services');
|
||||
}
|
||||
|
||||
callService(domain: string, service: string, data?: unknown): Promise<unknown> {
|
||||
return this.post<unknown>(`/api/services/${domain}/${service}`, data ?? {});
|
||||
}
|
||||
|
||||
// ── WebSocket ────────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Open an authenticated WebSocket connection.
|
||||
* Resolves once `auth_ok` is received; rejects on auth failure or network error.
|
||||
* Returns the live socket; caller is responsible for `.close()`.
|
||||
*/
|
||||
openWebSocket(wsBase?: string): Promise<WebSocket> {
|
||||
const resolved = wsBase ?? this.base.replace(/^http/, 'ws');
|
||||
const origin = resolved || window.location.origin.replace(/^http/, 'ws');
|
||||
const url = `${origin}/api/websocket`;
|
||||
|
||||
return new Promise((resolve, reject) => {
|
||||
const ws = new WebSocket(url);
|
||||
|
||||
ws.onmessage = (evt: MessageEvent<string>) => {
|
||||
const msg = JSON.parse(evt.data) as WsServerMessage;
|
||||
|
||||
if ((msg as WsAuthRequired).type === 'auth_required') {
|
||||
ws.send(JSON.stringify({ type: 'auth', access_token: this.token }));
|
||||
return;
|
||||
}
|
||||
|
||||
if ((msg as WsAuthOk).type === 'auth_ok') {
|
||||
ws.onmessage = null;
|
||||
resolve(ws);
|
||||
return;
|
||||
}
|
||||
|
||||
if (msg.type === 'auth_invalid') {
|
||||
ws.close();
|
||||
reject(new Error(`WS auth_invalid`));
|
||||
}
|
||||
};
|
||||
|
||||
ws.onerror = () => reject(new Error('WebSocket connection error'));
|
||||
ws.onclose = () => reject(new Error('WebSocket closed before auth_ok'));
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -1,98 +0,0 @@
|
||||
/**
|
||||
* TypeScript types mirroring the JSON shapes from homecore-api/src/rest.rs and ws.rs.
|
||||
* Keep in sync with Rust `StateView`, `ApiConfig`, `ServiceDomainView`.
|
||||
*/
|
||||
|
||||
/** Context for a state change — mirrors Rust `ContextView`. */
|
||||
export interface ContextView {
|
||||
id: string;
|
||||
user_id: string | null;
|
||||
parent_id: string | null;
|
||||
}
|
||||
|
||||
/** Snapshot of a single entity state — mirrors Rust `StateView`. */
|
||||
export interface StateView {
|
||||
entity_id: string;
|
||||
state: string;
|
||||
/** Arbitrary JSON attributes attached to the entity. */
|
||||
attributes: Record<string, unknown>;
|
||||
/** RFC 3339 timestamp of last state value change. */
|
||||
last_changed: string;
|
||||
/** RFC 3339 timestamp of last update (attributes may have changed). */
|
||||
last_updated: string;
|
||||
context: ContextView;
|
||||
}
|
||||
|
||||
/** HOMECORE configuration — mirrors Rust `ApiConfig`. */
|
||||
export interface ApiConfig {
|
||||
location_name: string;
|
||||
version: string;
|
||||
state: 'RUNNING' | 'STARTING' | 'STOPPING';
|
||||
components: string[];
|
||||
}
|
||||
|
||||
/** Services grouped by domain — mirrors Rust `ServiceDomainView`. */
|
||||
export interface ServiceDomainView {
|
||||
domain: string;
|
||||
/** Keyed by service name; value is the service schema (may be empty `{}`). */
|
||||
services: Record<string, unknown>;
|
||||
}
|
||||
|
||||
// ── WebSocket protocol types ──────────────────────────────────────────────────
|
||||
|
||||
/** Sent by server immediately upon WS upgrade. */
|
||||
export interface WsAuthRequired {
|
||||
type: 'auth_required';
|
||||
ha_version: string;
|
||||
}
|
||||
|
||||
/** Sent by client to authenticate. */
|
||||
export interface WsAuth {
|
||||
type: 'auth';
|
||||
access_token: string;
|
||||
}
|
||||
|
||||
/** Sent by server on successful auth. */
|
||||
export interface WsAuthOk {
|
||||
type: 'auth_ok';
|
||||
ha_version: string;
|
||||
}
|
||||
|
||||
/** Sent by server on failed auth. */
|
||||
export interface WsAuthInvalid {
|
||||
type: 'auth_invalid';
|
||||
message: string;
|
||||
}
|
||||
|
||||
/** Generic result message from server. */
|
||||
export interface WsResult<T = unknown> {
|
||||
id: number;
|
||||
type: 'result';
|
||||
success: boolean;
|
||||
result?: T;
|
||||
error?: { code: string; message: string };
|
||||
}
|
||||
|
||||
/** State-changed event pushed by server via `subscribe_events`. */
|
||||
export interface WsStateChangedEvent {
|
||||
id: number;
|
||||
type: 'event';
|
||||
event: {
|
||||
event_type: 'state_changed';
|
||||
data: {
|
||||
entity_id: string;
|
||||
old_state: StateView | null;
|
||||
new_state: StateView | null;
|
||||
};
|
||||
origin: 'LOCAL' | 'REMOTE';
|
||||
time_fired: string;
|
||||
};
|
||||
}
|
||||
|
||||
/** Union of all inbound WS server messages. */
|
||||
export type WsServerMessage =
|
||||
| WsAuthRequired
|
||||
| WsAuthOk
|
||||
| WsAuthInvalid
|
||||
| WsResult
|
||||
| WsStateChangedEvent;
|
||||
@@ -1,194 +0,0 @@
|
||||
/**
|
||||
* `<hc-app-shell>` — top-level layout: sticky header + horizontal sidenav + content slot.
|
||||
* Page shell mirrors cognitum-v0's appbar + wrap layout (ADR-131 §3).
|
||||
*/
|
||||
|
||||
import { LitElement, html, css } from 'lit';
|
||||
import { customElement, property, state } from 'lit/decorators.js';
|
||||
|
||||
export interface NavItem {
|
||||
id: string;
|
||||
label: string;
|
||||
/** Raw SVG string for the icon */
|
||||
iconSvg?: string;
|
||||
}
|
||||
|
||||
const DEFAULT_NAV: NavItem[] = [
|
||||
{ id: 'dashboard', label: 'Dashboard' },
|
||||
{ id: 'states', label: 'States' },
|
||||
{ id: 'services', label: 'Services' },
|
||||
{ id: 'settings', label: 'Settings' },
|
||||
];
|
||||
|
||||
@customElement('hc-app-shell')
|
||||
export class AppShell extends LitElement {
|
||||
@property({ type: String }) locationName = 'HOMECORE';
|
||||
@property({ type: String }) version = '0.1.0';
|
||||
@property({ type: Array }) navItems: NavItem[] = DEFAULT_NAV;
|
||||
@state() private activeId = 'dashboard';
|
||||
|
||||
static styles = css`
|
||||
:host { display: block; min-height: 100dvh; background: var(--hc-bg, #0b0e13); }
|
||||
|
||||
/* ── Appbar ── */
|
||||
.appbar {
|
||||
position: sticky;
|
||||
top: 0;
|
||||
z-index: 50;
|
||||
background: hsl(220 25% 6% / 0.9);
|
||||
backdrop-filter: blur(8px);
|
||||
-webkit-backdrop-filter: blur(8px);
|
||||
border-bottom: 1px solid hsl(220 15% 18% / 0.8);
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 1rem;
|
||||
padding: 0 1.25rem;
|
||||
height: 3.25rem;
|
||||
}
|
||||
|
||||
.brand {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.5rem;
|
||||
font-family: var(--hc-font-display, 'Outfit', system-ui, sans-serif);
|
||||
font-weight: 600;
|
||||
font-size: 0.9375rem;
|
||||
color: var(--hc-text, #e6eaee);
|
||||
white-space: nowrap;
|
||||
flex-shrink: 0;
|
||||
}
|
||||
|
||||
.brand-icon {
|
||||
width: 32px;
|
||||
height: 32px;
|
||||
border-radius: 0.4rem;
|
||||
background: var(--hc-primary, #19d4e5);
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
color: var(--hc-primary-fg, #0b0e13);
|
||||
font-size: 1rem;
|
||||
font-weight: 700;
|
||||
}
|
||||
|
||||
.nav {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.25rem;
|
||||
overflow-x: auto;
|
||||
scrollbar-width: none;
|
||||
flex: 1;
|
||||
mask-image: linear-gradient(to right, black calc(100% - 24px), transparent);
|
||||
}
|
||||
.nav::-webkit-scrollbar { display: none; }
|
||||
|
||||
.nav-link {
|
||||
position: relative;
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 0.4rem;
|
||||
padding: 0.4rem 0.7rem;
|
||||
border-radius: 0.4rem;
|
||||
font-family: var(--hc-font-display, 'Outfit', system-ui, sans-serif);
|
||||
font-size: 0.8125rem;
|
||||
font-weight: 500;
|
||||
color: var(--hc-text-muted, #7b899d);
|
||||
background: transparent;
|
||||
border: none;
|
||||
cursor: pointer;
|
||||
white-space: nowrap;
|
||||
transition: color 150ms, background 150ms;
|
||||
}
|
||||
|
||||
.nav-link:hover {
|
||||
color: var(--hc-text, #e6eaee);
|
||||
background: hsl(220 20% 14%);
|
||||
}
|
||||
|
||||
.nav-link:focus-visible {
|
||||
outline: 2px solid hsl(185 80% 50% / 0.6);
|
||||
outline-offset: 1px;
|
||||
}
|
||||
|
||||
.nav-link:active { transform: translateY(1px); }
|
||||
|
||||
.nav-link.active { color: var(--hc-primary, #19d4e5); }
|
||||
|
||||
.nav-link.active::after {
|
||||
content: '';
|
||||
position: absolute;
|
||||
bottom: -2px;
|
||||
left: 0.7rem;
|
||||
right: 0.7rem;
|
||||
height: 2px;
|
||||
background: var(--hc-primary, #19d4e5);
|
||||
border-radius: 9999px;
|
||||
}
|
||||
|
||||
.version-chip {
|
||||
font-family: var(--hc-font-mono, 'JetBrains Mono', monospace);
|
||||
font-size: 0.6875rem;
|
||||
color: var(--hc-text-muted, #7b899d);
|
||||
white-space: nowrap;
|
||||
flex-shrink: 0;
|
||||
}
|
||||
|
||||
/* ── Main content ── */
|
||||
main {
|
||||
max-width: 1400px;
|
||||
margin-inline: auto;
|
||||
padding-inline: 1.25rem;
|
||||
padding-block: 1.5rem;
|
||||
}
|
||||
|
||||
/* ── Footer ── */
|
||||
footer {
|
||||
border-top: 1px solid hsl(220 15% 18%);
|
||||
text-align: center;
|
||||
padding: 1rem 1.25rem;
|
||||
font-family: var(--hc-font-mono, 'JetBrains Mono', monospace);
|
||||
font-size: 0.75rem;
|
||||
color: var(--hc-text-muted, #7b899d);
|
||||
}
|
||||
`;
|
||||
|
||||
private onNavClick(id: string) {
|
||||
this.activeId = id;
|
||||
this.dispatchEvent(new CustomEvent('hc-navigate', { detail: { id }, bubbles: true, composed: true }));
|
||||
}
|
||||
|
||||
render() {
|
||||
return html`
|
||||
<header class="appbar" part="appbar">
|
||||
<div class="brand">
|
||||
<div class="brand-icon" aria-hidden="true">H</div>
|
||||
${this.locationName}
|
||||
</div>
|
||||
<nav class="nav" aria-label="Primary navigation">
|
||||
${this.navItems.map(item => html`
|
||||
<button
|
||||
class="nav-link ${this.activeId === item.id ? 'active' : ''}"
|
||||
@click=${() => this.onNavClick(item.id)}
|
||||
aria-current=${this.activeId === item.id ? 'page' : 'false'}
|
||||
>${item.label}</button>
|
||||
`)}
|
||||
</nav>
|
||||
<span class="version-chip">v${this.version}</span>
|
||||
</header>
|
||||
|
||||
<main part="content">
|
||||
<slot></slot>
|
||||
</main>
|
||||
|
||||
<footer part="footer">
|
||||
HOMECORE — ${this.locationName} — v${this.version}
|
||||
</footer>
|
||||
`;
|
||||
}
|
||||
}
|
||||
|
||||
declare global {
|
||||
interface HTMLElementTagNameMap {
|
||||
'hc-app-shell': AppShell;
|
||||
}
|
||||
}
|
||||
@@ -1,132 +0,0 @@
|
||||
/**
|
||||
* `<hc-state-card>` — renders one HOMECORE entity state in the cognitum-v0 card style.
|
||||
* Uses Lit 3 (LitElement + html/css template tags).
|
||||
*/
|
||||
|
||||
import { LitElement, html, css, nothing } from 'lit';
|
||||
import { customElement, property } from 'lit/decorators.js';
|
||||
import type { StateView } from '../api/types.js';
|
||||
|
||||
@customElement('hc-state-card')
|
||||
export class StateCard extends LitElement {
|
||||
@property({ type: Object }) state!: StateView;
|
||||
/** Optional: icon SVG string (use `iconSvg()` from lucide.ts) */
|
||||
@property({ type: String }) iconSvg?: string;
|
||||
|
||||
static styles = css`
|
||||
:host {
|
||||
display: block;
|
||||
}
|
||||
|
||||
.card {
|
||||
background: var(--hc-gradient-card, linear-gradient(180deg, #181c24 0%, #111318 100%));
|
||||
border: 1px solid hsl(220 15% 18% / 0.5);
|
||||
border-radius: var(--hc-radius, 0.75rem);
|
||||
box-shadow: var(--hc-shadow-card, 0 8px 32px -8px hsl(220 25% 2% / 0.8));
|
||||
padding: 1.25rem;
|
||||
transition: transform 200ms, border-color 200ms;
|
||||
}
|
||||
|
||||
.card:hover {
|
||||
transform: translateY(-2px);
|
||||
border-color: hsl(185 80% 50% / 0.4);
|
||||
}
|
||||
|
||||
.header {
|
||||
display: flex;
|
||||
align-items: flex-start;
|
||||
gap: 0.75rem;
|
||||
margin-bottom: 0.75rem;
|
||||
}
|
||||
|
||||
.icon-wrap {
|
||||
flex-shrink: 0;
|
||||
width: 38px;
|
||||
height: 38px;
|
||||
border-radius: var(--hc-radius-sm, 0.4rem);
|
||||
background: hsl(220 20% 14%);
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
color: var(--hc-primary, #19d4e5);
|
||||
}
|
||||
|
||||
.meta { flex: 1; min-width: 0; }
|
||||
|
||||
.entity-id {
|
||||
font-family: var(--hc-font-mono, 'JetBrains Mono', monospace);
|
||||
font-size: 0.6875rem;
|
||||
font-weight: 600;
|
||||
color: var(--hc-text-muted, #7b899d);
|
||||
text-overflow: ellipsis;
|
||||
overflow: hidden;
|
||||
white-space: nowrap;
|
||||
letter-spacing: 0.05em;
|
||||
}
|
||||
|
||||
.state-value {
|
||||
font-family: var(--hc-font-display, 'Outfit', system-ui, sans-serif);
|
||||
font-size: 1.125rem;
|
||||
font-weight: 600;
|
||||
color: var(--hc-text, #e6eaee);
|
||||
letter-spacing: -0.02em;
|
||||
margin-top: 0.2rem;
|
||||
}
|
||||
|
||||
.badge {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
padding: 0.15rem 0.5rem;
|
||||
border-radius: 9999px;
|
||||
border: 1px solid var(--hc-border, #272b34);
|
||||
font-family: var(--hc-font-mono, monospace);
|
||||
font-size: 0.6875rem;
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.badge.on { color: #26d867; border-color: hsl(142 70% 50% / 0.4); }
|
||||
.badge.off { color: #d22c2c; border-color: hsl(0 65% 50% / 0.4); }
|
||||
|
||||
.timestamp {
|
||||
font-family: var(--hc-font-mono, monospace);
|
||||
font-size: 0.625rem;
|
||||
color: var(--hc-text-muted, #7b899d);
|
||||
margin-top: 0.75rem;
|
||||
}
|
||||
`;
|
||||
|
||||
private badgeClass(state: string): string {
|
||||
const s = state.toLowerCase();
|
||||
if (s === 'on' || s === 'open' || s === 'home' || s === 'running') return 'on';
|
||||
if (s === 'off' || s === 'closed' || s === 'away' || s === 'unavailable') return 'off';
|
||||
return '';
|
||||
}
|
||||
|
||||
render() {
|
||||
if (!this.state) return nothing;
|
||||
const { entity_id, state, last_updated } = this.state;
|
||||
const badge = this.badgeClass(state);
|
||||
|
||||
return html`
|
||||
<div class="card" part="card">
|
||||
<div class="header">
|
||||
${this.iconSvg
|
||||
? html`<div class="icon-wrap" .innerHTML=${this.iconSvg}></div>`
|
||||
: nothing}
|
||||
<div class="meta">
|
||||
<div class="entity-id" title=${entity_id}>${entity_id}</div>
|
||||
<div class="state-value">${state}</div>
|
||||
</div>
|
||||
<span class="badge ${badge}">${state}</span>
|
||||
</div>
|
||||
<div class="timestamp">updated ${new Date(last_updated).toLocaleTimeString()}</div>
|
||||
</div>
|
||||
`;
|
||||
}
|
||||
}
|
||||
|
||||
declare global {
|
||||
interface HTMLElementTagNameMap {
|
||||
'hc-state-card': StateCard;
|
||||
}
|
||||
}
|
||||
@@ -1,39 +0,0 @@
|
||||
/**
|
||||
* Minimal Lucide icon wrapper.
|
||||
* Import only the icons used by HOMECORE components — Vite tree-shakes the rest.
|
||||
*/
|
||||
|
||||
export {
|
||||
Activity,
|
||||
BarChart3,
|
||||
Book,
|
||||
ChevronRight,
|
||||
Grid2X2,
|
||||
Home,
|
||||
LayoutDashboard,
|
||||
Settings,
|
||||
Shield,
|
||||
Sun,
|
||||
Wifi,
|
||||
Zap,
|
||||
} from 'lucide';
|
||||
|
||||
/** Re-export the icon node type for consumers that need it. */
|
||||
export type { IconNode as LucideIconNode } from 'lucide';
|
||||
|
||||
/**
|
||||
* Render a Lucide icon as an SVG string suitable for Lit's `unsafeHTML`.
|
||||
* Each icon is 24×24, no fill, stroke = currentColor, stroke-width = 2.
|
||||
*/
|
||||
export function iconSvg(
|
||||
paths: string,
|
||||
{ size = 24, label }: { size?: number; label?: string } = {},
|
||||
): string {
|
||||
const ariaAttrs = label
|
||||
? `role="img" aria-label="${label}"`
|
||||
: `aria-hidden="true"`;
|
||||
return `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}"
|
||||
viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||||
stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
|
||||
${ariaAttrs}>${paths}</svg>`;
|
||||
}
|
||||
@@ -1,42 +0,0 @@
|
||||
/**
|
||||
* HOMECORE frontend entry point.
|
||||
* Imports global styles, registers Lit components, and mounts the app shell.
|
||||
*/
|
||||
|
||||
import './styles/tokens.css';
|
||||
import './styles/base.css';
|
||||
|
||||
// Register custom elements
|
||||
import './components/AppShell.js';
|
||||
import './components/StateCard.js';
|
||||
import './pages/Dashboard.js';
|
||||
import './pages/States.js';
|
||||
import './pages/Services.js';
|
||||
import './pages/Settings.js';
|
||||
|
||||
// Tiny router: the AppShell dispatches `hc-navigate` on every nav
|
||||
// click. We swap whichever page element is sitting in its <slot>
|
||||
// based on the new active id. Default page on first paint = dashboard.
|
||||
const NAV_TO_TAG: Record<string, string> = {
|
||||
dashboard: 'hc-dashboard',
|
||||
states: 'hc-states',
|
||||
services: 'hc-services',
|
||||
settings: 'hc-settings',
|
||||
};
|
||||
|
||||
function mountPage(shell: Element, tag: string): void {
|
||||
// Remove any existing page (everything that isn't itself the shell).
|
||||
Array.from(shell.children).forEach((c) => c.remove());
|
||||
shell.appendChild(document.createElement(tag));
|
||||
}
|
||||
|
||||
window.addEventListener('DOMContentLoaded', () => {
|
||||
const shell = document.querySelector('hc-app-shell');
|
||||
if (!shell) return;
|
||||
mountPage(shell, 'hc-dashboard');
|
||||
shell.addEventListener('hc-navigate', (ev) => {
|
||||
const id = (ev as CustomEvent<{ id: string }>).detail?.id;
|
||||
const tag = id ? NAV_TO_TAG[id] : undefined;
|
||||
if (tag) mountPage(shell, tag);
|
||||
});
|
||||
});
|
||||
@@ -1,143 +0,0 @@
|
||||
/**
|
||||
* Dashboard page — fetches HOMECORE state + config from the backend and
|
||||
* populates the `<hc-app-shell>` slot with a grid of `<hc-state-card>`.
|
||||
*
|
||||
* Auth: reads bearer from `localStorage["homecore.token"]`, the
|
||||
* `?token=` query string, or `HOMECORE_TOKEN` `<meta>` tag — in that
|
||||
* order. Falls back to the literal "dev-token" in DEV-mode backends
|
||||
* (any non-empty bearer is accepted when HOMECORE_TOKENS is unset).
|
||||
*/
|
||||
|
||||
import { LitElement, html, css } from 'lit';
|
||||
import { customElement, state } from 'lit/decorators.js';
|
||||
|
||||
import { HomecoreClient } from '../api/client.js';
|
||||
import type { ApiConfig, StateView } from '../api/types.js';
|
||||
|
||||
function resolveToken(): string {
|
||||
if (typeof localStorage !== 'undefined') {
|
||||
const stored = localStorage.getItem('homecore.token');
|
||||
if (stored) return stored;
|
||||
}
|
||||
const url = new URL(window.location.href);
|
||||
const qs = url.searchParams.get('token');
|
||||
if (qs) return qs;
|
||||
const meta = document.querySelector<HTMLMetaElement>('meta[name="homecore-token"]');
|
||||
if (meta?.content) return meta.content;
|
||||
return 'dev-token';
|
||||
}
|
||||
|
||||
@customElement('hc-dashboard')
|
||||
export class Dashboard extends LitElement {
|
||||
static styles = css`
|
||||
:host {
|
||||
display: block;
|
||||
padding: 24px;
|
||||
color: var(--hc-fg, #e6e9ec);
|
||||
font-family: var(--hc-font-sans, 'Outfit', system-ui, sans-serif);
|
||||
}
|
||||
.meta {
|
||||
display: flex;
|
||||
gap: 16px;
|
||||
flex-wrap: wrap;
|
||||
color: var(--hc-fg-dim, #8a93a0);
|
||||
font-size: 14px;
|
||||
margin-bottom: 16px;
|
||||
}
|
||||
.meta strong { color: var(--hc-fg, #e6e9ec); }
|
||||
.grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
|
||||
gap: 16px;
|
||||
}
|
||||
.empty,
|
||||
.err {
|
||||
padding: 24px;
|
||||
border: 1px dashed var(--hc-border, #2a323e);
|
||||
border-radius: 8px;
|
||||
text-align: center;
|
||||
color: var(--hc-fg-dim, #8a93a0);
|
||||
}
|
||||
.err {
|
||||
border-color: #b35a5a;
|
||||
color: #f0c0c0;
|
||||
text-align: left;
|
||||
font-family: var(--hc-font-mono, 'JetBrains Mono', monospace);
|
||||
font-size: 13px;
|
||||
white-space: pre-wrap;
|
||||
}
|
||||
`;
|
||||
|
||||
@state() private states: StateView[] = [];
|
||||
@state() private config: ApiConfig | null = null;
|
||||
@state() private error: string | null = null;
|
||||
@state() private loading = true;
|
||||
|
||||
private client = new HomecoreClient({ token: resolveToken() });
|
||||
private pollTimer: number | undefined;
|
||||
|
||||
connectedCallback(): void {
|
||||
super.connectedCallback();
|
||||
void this.refresh();
|
||||
this.pollTimer = window.setInterval(() => void this.refresh(), 5000);
|
||||
}
|
||||
|
||||
disconnectedCallback(): void {
|
||||
if (this.pollTimer !== undefined) window.clearInterval(this.pollTimer);
|
||||
super.disconnectedCallback();
|
||||
}
|
||||
|
||||
private async refresh(): Promise<void> {
|
||||
try {
|
||||
const [cfg, states] = await Promise.all([
|
||||
this.client.getConfig(),
|
||||
this.client.getStates(),
|
||||
]);
|
||||
this.config = cfg;
|
||||
this.states = states;
|
||||
this.error = null;
|
||||
} catch (e) {
|
||||
this.error = e instanceof Error ? e.message : String(e);
|
||||
} finally {
|
||||
this.loading = false;
|
||||
}
|
||||
}
|
||||
|
||||
render() {
|
||||
if (this.error) {
|
||||
return html`<div class="err">backend unreachable — ${this.error}\n\n
|
||||
hint: make sure homecore-server is running on :8123 and that
|
||||
the token in localStorage["homecore.token"] is accepted.
|
||||
</div>`;
|
||||
}
|
||||
if (this.loading) {
|
||||
return html`<div class="empty">loading HOMECORE state…</div>`;
|
||||
}
|
||||
const v = this.config?.version ?? '?';
|
||||
const loc = this.config?.location_name ?? 'Home';
|
||||
return html`
|
||||
<div class="meta">
|
||||
<span><strong>${loc}</strong></span>
|
||||
<span>HOMECORE v<strong>${v}</strong></span>
|
||||
<span><strong>${this.states.length}</strong> entities</span>
|
||||
</div>
|
||||
${this.states.length === 0
|
||||
? html`<div class="empty">
|
||||
No entities registered yet. Run
|
||||
<code>bash scripts/homecore-seed.sh</code> to populate
|
||||
~10 demo entities, or connect a plugin / integration.
|
||||
</div>`
|
||||
: html`<div class="grid">
|
||||
${this.states.map(
|
||||
(s) => html`<hc-state-card .state=${s}></hc-state-card>`
|
||||
)}
|
||||
</div>`}
|
||||
`;
|
||||
}
|
||||
}
|
||||
|
||||
declare global {
|
||||
interface HTMLElementTagNameMap {
|
||||
'hc-dashboard': Dashboard;
|
||||
}
|
||||
}
|
||||
@@ -1,86 +0,0 @@
|
||||
/**
|
||||
* Services page — lists every registered service grouped by domain.
|
||||
* Reads from `/api/services` (HA-wire-compat).
|
||||
*/
|
||||
|
||||
import { LitElement, html, css } from 'lit';
|
||||
import { customElement, state } from 'lit/decorators.js';
|
||||
|
||||
import { HomecoreClient } from '../api/client.js';
|
||||
import type { ServiceDomainView } from '../api/types.js';
|
||||
|
||||
function resolveToken(): string {
|
||||
if (typeof localStorage !== 'undefined') {
|
||||
const stored = localStorage.getItem('homecore.token');
|
||||
if (stored) return stored;
|
||||
}
|
||||
const qs = new URL(window.location.href).searchParams.get('token');
|
||||
return qs ?? 'dev-token';
|
||||
}
|
||||
|
||||
@customElement('hc-services')
|
||||
export class ServicesPage extends LitElement {
|
||||
static styles = css`
|
||||
:host { display: block; padding: 24px; color: var(--hc-text, #e6eaee); font-family: var(--hc-font-sans, 'Outfit', system-ui, sans-serif); }
|
||||
h1 { font-size: 18px; font-weight: 600; margin: 0 0 16px 0; }
|
||||
.domain { background: hsl(220 20% 10%); border: 1px solid var(--hc-border, #2a323e); border-radius: 8px; margin-bottom: 12px; padding: 14px 16px; }
|
||||
.domain h2 { font-size: 14px; font-weight: 600; margin: 0 0 8px 0; color: var(--hc-primary, #19d4e5); font-family: var(--hc-font-mono, 'JetBrains Mono', monospace); }
|
||||
ul { list-style: none; padding: 0; margin: 0; display: flex; flex-wrap: wrap; gap: 6px; }
|
||||
li { background: hsl(220 25% 14%); padding: 4px 10px; border-radius: 4px; font-family: var(--hc-font-mono, 'JetBrains Mono', monospace); font-size: 12px; color: var(--hc-text-muted, #7b899d); }
|
||||
.empty { padding: 24px; border: 1px dashed var(--hc-border, #2a323e); border-radius: 8px; text-align: center; color: var(--hc-text-muted, #7b899d); }
|
||||
.err { padding: 16px; border: 1px dashed #b35a5a; border-radius: 8px; color: #f0c0c0; font-size: 13px; }
|
||||
`;
|
||||
|
||||
@state() private domains: ServiceDomainView[] = [];
|
||||
@state() private error: string | null = null;
|
||||
@state() private loading = true;
|
||||
|
||||
private client = new HomecoreClient({ token: resolveToken() });
|
||||
|
||||
connectedCallback(): void {
|
||||
super.connectedCallback();
|
||||
void this.refresh();
|
||||
}
|
||||
|
||||
private async refresh(): Promise<void> {
|
||||
try {
|
||||
const r = await fetch('/api/services', { headers: { 'Authorization': `Bearer ${resolveToken()}` } });
|
||||
if (!r.ok) throw new Error(`/api/services -> HTTP ${r.status}`);
|
||||
this.domains = await r.json();
|
||||
this.error = null;
|
||||
} catch (e) {
|
||||
this.error = e instanceof Error ? e.message : String(e);
|
||||
} finally {
|
||||
this.loading = false;
|
||||
}
|
||||
void this.client; // suppress unused warning while keeping the import shape consistent
|
||||
}
|
||||
|
||||
render() {
|
||||
if (this.error) return html`<div class="err">backend unreachable — ${this.error}</div>`;
|
||||
if (this.loading) return html`<div>loading services…</div>`;
|
||||
if (this.domains.length === 0) {
|
||||
return html`
|
||||
<h1>Services (0 domains)</h1>
|
||||
<div class="empty">
|
||||
No services registered. Services are registered by plugins
|
||||
(Wasmtime or InProcess) or by integrations that call
|
||||
<code>services::register()</code> on boot.
|
||||
</div>
|
||||
`;
|
||||
}
|
||||
return html`
|
||||
<h1>Services (${this.domains.length} domain${this.domains.length === 1 ? '' : 's'})</h1>
|
||||
${this.domains.map(d => html`
|
||||
<div class="domain">
|
||||
<h2>${d.domain}</h2>
|
||||
<ul>
|
||||
${Object.keys(d.services).map(name => html`<li>${name}</li>`)}
|
||||
</ul>
|
||||
</div>
|
||||
`)}
|
||||
`;
|
||||
}
|
||||
}
|
||||
|
||||
declare global { interface HTMLElementTagNameMap { 'hc-services': ServicesPage; } }
|
||||
@@ -1,94 +0,0 @@
|
||||
/**
|
||||
* Settings page — backend config + bearer-token editor (localStorage).
|
||||
*/
|
||||
|
||||
import { LitElement, html, css } from 'lit';
|
||||
import { customElement, state } from 'lit/decorators.js';
|
||||
|
||||
import { HomecoreClient } from '../api/client.js';
|
||||
import type { ApiConfig } from '../api/types.js';
|
||||
|
||||
function resolveToken(): string {
|
||||
if (typeof localStorage !== 'undefined') {
|
||||
const stored = localStorage.getItem('homecore.token');
|
||||
if (stored) return stored;
|
||||
}
|
||||
const qs = new URL(window.location.href).searchParams.get('token');
|
||||
return qs ?? 'dev-token';
|
||||
}
|
||||
|
||||
@customElement('hc-settings')
|
||||
export class SettingsPage extends LitElement {
|
||||
static styles = css`
|
||||
:host { display: block; padding: 24px; color: var(--hc-text, #e6eaee); font-family: var(--hc-font-sans, 'Outfit', system-ui, sans-serif); }
|
||||
h1 { font-size: 18px; font-weight: 600; margin: 0 0 16px 0; }
|
||||
section { background: hsl(220 20% 10%); border: 1px solid var(--hc-border, #2a323e); border-radius: 8px; padding: 16px; margin-bottom: 16px; }
|
||||
h2 { font-size: 14px; font-weight: 600; margin: 0 0 12px 0; color: var(--hc-primary, #19d4e5); }
|
||||
dl { display: grid; grid-template-columns: max-content 1fr; gap: 6px 18px; margin: 0; font-size: 13px; font-family: var(--hc-font-mono, 'JetBrains Mono', monospace); }
|
||||
dt { color: var(--hc-text-muted, #7b899d); }
|
||||
dd { margin: 0; }
|
||||
label { display: block; margin-bottom: 6px; font-size: 13px; color: var(--hc-text-muted, #7b899d); }
|
||||
input { width: 100%; box-sizing: border-box; padding: 8px 12px; background: hsl(220 25% 14%); border: 1px solid var(--hc-border, #2a323e); border-radius: 6px; color: var(--hc-text, #e6eaee); font-family: var(--hc-font-mono, 'JetBrains Mono', monospace); font-size: 13px; }
|
||||
button { margin-top: 10px; padding: 8px 16px; background: var(--hc-primary, #19d4e5); color: var(--hc-primary-fg, #0b0e13); border: none; border-radius: 6px; font-weight: 600; font-size: 13px; cursor: pointer; font-family: var(--hc-font-sans, 'Outfit', system-ui, sans-serif); }
|
||||
button:hover { background: hsl(185 80% 55%); }
|
||||
.toast { font-size: 12px; color: var(--hc-primary, #19d4e5); margin-top: 8px; }
|
||||
.err { padding: 16px; border: 1px dashed #b35a5a; border-radius: 8px; color: #f0c0c0; font-size: 13px; }
|
||||
`;
|
||||
|
||||
@state() private config: ApiConfig | null = null;
|
||||
@state() private error: string | null = null;
|
||||
@state() private token = resolveToken();
|
||||
@state() private savedAt = 0;
|
||||
|
||||
private client = new HomecoreClient({ token: resolveToken() });
|
||||
|
||||
connectedCallback(): void {
|
||||
super.connectedCallback();
|
||||
void this.refresh();
|
||||
}
|
||||
|
||||
private async refresh(): Promise<void> {
|
||||
try {
|
||||
this.config = await this.client.getConfig();
|
||||
this.error = null;
|
||||
} catch (e) {
|
||||
this.error = e instanceof Error ? e.message : String(e);
|
||||
}
|
||||
}
|
||||
|
||||
private saveToken() {
|
||||
localStorage.setItem('homecore.token', this.token);
|
||||
this.savedAt = Date.now();
|
||||
this.client = new HomecoreClient({ token: this.token });
|
||||
void this.refresh();
|
||||
}
|
||||
|
||||
render() {
|
||||
return html`
|
||||
<h1>Settings</h1>
|
||||
<section>
|
||||
<h2>backend</h2>
|
||||
${this.error
|
||||
? html`<div class="err">unreachable — ${this.error}</div>`
|
||||
: this.config
|
||||
? html`<dl>
|
||||
<dt>location</dt><dd>${this.config.location_name}</dd>
|
||||
<dt>version</dt><dd>${this.config.version}</dd>
|
||||
<dt>state</dt><dd>${this.config.state}</dd>
|
||||
<dt>components</dt><dd>${this.config.components.join(', ')}</dd>
|
||||
</dl>`
|
||||
: html`loading…`}
|
||||
</section>
|
||||
<section>
|
||||
<h2>auth — bearer token</h2>
|
||||
<label for="tok">stored at localStorage["homecore.token"]; DEV mode accepts any non-empty value</label>
|
||||
<input id="tok" type="password" .value=${this.token}
|
||||
@input=${(e: Event) => (this.token = (e.target as HTMLInputElement).value)} />
|
||||
<button @click=${this.saveToken}>save & reload backend</button>
|
||||
${this.savedAt > 0 ? html`<div class="toast">saved at ${new Date(this.savedAt).toLocaleTimeString()}</div>` : ''}
|
||||
</section>
|
||||
`;
|
||||
}
|
||||
}
|
||||
|
||||
declare global { interface HTMLElementTagNameMap { 'hc-settings': SettingsPage; } }
|
||||
@@ -1,85 +0,0 @@
|
||||
/**
|
||||
* States page — full table view of every entity in the state machine.
|
||||
* Mirrors Home Assistant's `/developer-tools/state` view (read-only).
|
||||
*/
|
||||
|
||||
import { LitElement, html, css } from 'lit';
|
||||
import { customElement, state } from 'lit/decorators.js';
|
||||
|
||||
import { HomecoreClient } from '../api/client.js';
|
||||
import type { StateView } from '../api/types.js';
|
||||
|
||||
function resolveToken(): string {
|
||||
if (typeof localStorage !== 'undefined') {
|
||||
const stored = localStorage.getItem('homecore.token');
|
||||
if (stored) return stored;
|
||||
}
|
||||
const qs = new URL(window.location.href).searchParams.get('token');
|
||||
return qs ?? 'dev-token';
|
||||
}
|
||||
|
||||
@customElement('hc-states')
|
||||
export class StatesPage extends LitElement {
|
||||
static styles = css`
|
||||
:host { display: block; padding: 24px; color: var(--hc-text, #e6eaee); font-family: var(--hc-font-sans, 'Outfit', system-ui, sans-serif); }
|
||||
h1 { font-size: 18px; font-weight: 600; margin: 0 0 16px 0; }
|
||||
table { width: 100%; border-collapse: collapse; font-size: 13px; }
|
||||
th { text-align: left; padding: 10px 12px; border-bottom: 1px solid var(--hc-border, #2a323e); color: var(--hc-text-muted, #7b899d); font-weight: 500; }
|
||||
td { padding: 10px 12px; border-bottom: 1px solid hsl(220 15% 14%); font-family: var(--hc-font-mono, 'JetBrains Mono', monospace); }
|
||||
td.attrs { color: var(--hc-text-muted, #7b899d); font-size: 12px; max-width: 380px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
|
||||
tr:hover td { background: hsl(220 20% 10%); }
|
||||
.state { color: var(--hc-primary, #19d4e5); }
|
||||
.err { padding: 16px; border: 1px dashed #b35a5a; border-radius: 8px; color: #f0c0c0; font-family: var(--hc-font-mono, 'JetBrains Mono', monospace); font-size: 13px; }
|
||||
`;
|
||||
|
||||
@state() private states: StateView[] = [];
|
||||
@state() private error: string | null = null;
|
||||
@state() private loading = true;
|
||||
|
||||
private client = new HomecoreClient({ token: resolveToken() });
|
||||
private timer?: number;
|
||||
|
||||
connectedCallback(): void {
|
||||
super.connectedCallback();
|
||||
void this.refresh();
|
||||
this.timer = window.setInterval(() => void this.refresh(), 5000);
|
||||
}
|
||||
disconnectedCallback(): void {
|
||||
if (this.timer !== undefined) window.clearInterval(this.timer);
|
||||
super.disconnectedCallback();
|
||||
}
|
||||
|
||||
private async refresh(): Promise<void> {
|
||||
try {
|
||||
this.states = await this.client.getStates();
|
||||
this.error = null;
|
||||
} catch (e) {
|
||||
this.error = e instanceof Error ? e.message : String(e);
|
||||
} finally {
|
||||
this.loading = false;
|
||||
}
|
||||
}
|
||||
|
||||
render() {
|
||||
if (this.error) return html`<div class="err">backend unreachable — ${this.error}</div>`;
|
||||
if (this.loading) return html`<div>loading…</div>`;
|
||||
return html`
|
||||
<h1>States (${this.states.length})</h1>
|
||||
<table>
|
||||
<thead><tr><th>entity_id</th><th>state</th><th>last_changed</th><th>attributes</th></tr></thead>
|
||||
<tbody>
|
||||
${this.states.map(s => html`
|
||||
<tr>
|
||||
<td>${s.entity_id}</td>
|
||||
<td class="state">${s.state}</td>
|
||||
<td>${s.last_changed.replace('T', ' ').replace(/\..*$/, '')}</td>
|
||||
<td class="attrs" title=${JSON.stringify(s.attributes)}>${JSON.stringify(s.attributes)}</td>
|
||||
</tr>
|
||||
`)}
|
||||
</tbody>
|
||||
</table>
|
||||
`;
|
||||
}
|
||||
}
|
||||
|
||||
declare global { interface HTMLElementTagNameMap { 'hc-states': StatesPage; } }
|
||||
@@ -1,224 +0,0 @@
|
||||
/**
|
||||
* HOMECORE base styles — typography reset, page shell, nav layout.
|
||||
* Component vocabulary mirrors cognitum-v0 (ADR-131 §3–4).
|
||||
*/
|
||||
|
||||
@import './tokens.css';
|
||||
|
||||
/* ── Reset ── */
|
||||
*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
|
||||
|
||||
html {
|
||||
color-scheme: dark;
|
||||
font-family: var(--hc-font-display);
|
||||
font-size: 16px;
|
||||
background: var(--hc-bg);
|
||||
color: var(--hc-text);
|
||||
}
|
||||
|
||||
body { min-height: 100dvh; }
|
||||
|
||||
/* ── Typography scale ── */
|
||||
h1 { font-size: 1.5rem; font-weight: 600; letter-spacing: -0.02em; }
|
||||
h2 { font-size: 1.125rem; font-weight: 700; letter-spacing: -0.02em; }
|
||||
h3 { font-size: 0.9375rem; font-weight: 600; letter-spacing: -0.02em; }
|
||||
h4 { font-size: 0.875rem; font-weight: 600; letter-spacing: -0.02em; }
|
||||
p { font-size: 0.875rem; line-height: 1.45; }
|
||||
|
||||
.mono { font-family: var(--hc-font-mono); }
|
||||
|
||||
/* ── Page shell ── */
|
||||
.hc-wrap {
|
||||
max-width: 1400px;
|
||||
margin-inline: auto;
|
||||
padding-inline: 1.25rem;
|
||||
padding-block: 1.5rem;
|
||||
}
|
||||
|
||||
/* ── Appbar ── */
|
||||
.hc-appbar {
|
||||
position: sticky;
|
||||
top: 0;
|
||||
z-index: 50;
|
||||
background: hsl(220 25% 6% / 0.9);
|
||||
backdrop-filter: blur(8px);
|
||||
border-bottom: 1px solid var(--hc-border);
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 1rem;
|
||||
padding: 0 1.25rem;
|
||||
height: 3.25rem;
|
||||
}
|
||||
|
||||
.hc-brand {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.5rem;
|
||||
font-weight: 600;
|
||||
font-size: 0.9375rem;
|
||||
white-space: nowrap;
|
||||
flex-shrink: 0;
|
||||
text-decoration: none;
|
||||
color: var(--hc-text);
|
||||
}
|
||||
|
||||
.hc-brand-icon {
|
||||
width: 32px;
|
||||
height: 32px;
|
||||
border-radius: 0.4rem;
|
||||
background: var(--hc-primary);
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
color: var(--hc-primary-fg);
|
||||
}
|
||||
|
||||
.hc-nav {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.25rem;
|
||||
overflow-x: auto;
|
||||
scrollbar-width: none;
|
||||
mask-image: linear-gradient(to right, black calc(100% - 24px), transparent);
|
||||
flex: 1;
|
||||
}
|
||||
|
||||
.hc-nav::-webkit-scrollbar { display: none; }
|
||||
|
||||
.hc-nav-link {
|
||||
position: relative;
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 0.4rem;
|
||||
padding: 0.4rem 0.7rem;
|
||||
border-radius: var(--hc-radius-sm);
|
||||
font-size: 0.8125rem;
|
||||
font-weight: 500;
|
||||
color: var(--hc-text-muted);
|
||||
text-decoration: none;
|
||||
white-space: nowrap;
|
||||
transition: color 150ms, background 150ms;
|
||||
}
|
||||
|
||||
.hc-nav-link:hover {
|
||||
color: var(--hc-text);
|
||||
background: hsl(220 20% 14%);
|
||||
}
|
||||
|
||||
.hc-nav-link:focus-visible {
|
||||
outline: 2px solid hsl(185 80% 50% / 0.6);
|
||||
outline-offset: 1px;
|
||||
}
|
||||
|
||||
.hc-nav-link:active { transform: translateY(1px); transition-duration: 50ms; }
|
||||
|
||||
.hc-nav-link.active {
|
||||
color: var(--hc-primary);
|
||||
}
|
||||
|
||||
.hc-nav-link.active::after {
|
||||
content: '';
|
||||
position: absolute;
|
||||
bottom: -2px;
|
||||
left: 0.7rem;
|
||||
right: 0.7rem;
|
||||
height: 2px;
|
||||
background: var(--hc-primary);
|
||||
border-radius: 9999px;
|
||||
}
|
||||
|
||||
/* ── Card ── */
|
||||
.hc-card {
|
||||
background: var(--hc-gradient-card);
|
||||
border: 1px solid hsl(220 15% 18% / 0.5);
|
||||
border-radius: var(--hc-radius);
|
||||
box-shadow: var(--hc-shadow-card);
|
||||
padding: 1.25rem;
|
||||
transition: transform 200ms, border-color 200ms;
|
||||
}
|
||||
|
||||
.hc-card:hover {
|
||||
transform: translateY(-2px);
|
||||
border-color: hsl(185 80% 50% / 0.4);
|
||||
}
|
||||
|
||||
/* ── Badge ── */
|
||||
.hc-badge {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
padding: 0.15rem 0.5rem;
|
||||
border-radius: var(--hc-radius-pill);
|
||||
border: 1px solid var(--hc-border);
|
||||
font-family: var(--hc-font-mono);
|
||||
font-size: 0.6875rem;
|
||||
font-weight: 600;
|
||||
letter-spacing: 0.08em;
|
||||
}
|
||||
|
||||
.hc-badge.online { color: var(--hc-accent); border-color: hsl(142 70% 50% / 0.4); }
|
||||
.hc-badge.offline { color: var(--hc-destructive); border-color: hsl(0 65% 50% / 0.4); }
|
||||
.hc-badge.warning { color: var(--hc-warning); border-color: hsl(38 80% 60% / 0.4); }
|
||||
|
||||
/* ── Button ── */
|
||||
.hc-btn {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 0.4rem;
|
||||
padding: 0.5rem 0.875rem;
|
||||
border-radius: var(--hc-radius-sm);
|
||||
font-family: var(--hc-font-display);
|
||||
font-size: 0.8125rem;
|
||||
font-weight: 500;
|
||||
border: 1px solid var(--hc-border);
|
||||
background: hsl(220 20% 14%);
|
||||
color: var(--hc-text);
|
||||
cursor: pointer;
|
||||
transition: background 150ms, border-color 150ms;
|
||||
}
|
||||
|
||||
.hc-btn:hover { background: hsl(220 20% 18%); }
|
||||
|
||||
.hc-btn.primary {
|
||||
background: var(--hc-primary);
|
||||
color: var(--hc-primary-fg);
|
||||
border-color: transparent;
|
||||
font-weight: 600;
|
||||
box-shadow: var(--hc-shadow-glow);
|
||||
}
|
||||
|
||||
.hc-btn.primary:hover { background: hsl(185 80% 55%); }
|
||||
|
||||
/* ── Section ── */
|
||||
.hc-section { margin-bottom: 1.5rem; }
|
||||
|
||||
.hc-section-label {
|
||||
font-size: 0.6875rem;
|
||||
font-weight: 600;
|
||||
letter-spacing: 0.1em;
|
||||
text-transform: uppercase;
|
||||
color: var(--hc-text-muted);
|
||||
margin-bottom: 0.75rem;
|
||||
}
|
||||
|
||||
/* ── Grid helpers ── */
|
||||
.hc-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
|
||||
gap: 0.75rem;
|
||||
}
|
||||
|
||||
.hc-kpi-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fill, minmax(170px, 1fr));
|
||||
gap: 0.75rem;
|
||||
}
|
||||
|
||||
/* ── Footer ── */
|
||||
.hc-footer {
|
||||
border-top: 1px solid var(--hc-border);
|
||||
text-align: center;
|
||||
padding: 1rem 1.25rem;
|
||||
font-size: 0.75rem;
|
||||
color: var(--hc-text-muted);
|
||||
font-family: var(--hc-font-mono);
|
||||
}
|
||||
@@ -1,45 +0,0 @@
|
||||
/**
|
||||
* HOMECORE design tokens — sourced from cognitum-v0 (ADR-131 §9).
|
||||
* 16 CSS custom properties: 4 surfaces + 2 text + 6 accent/status + 2 border/ring + 2 radius.
|
||||
* Dark-only; no light-mode overrides.
|
||||
*/
|
||||
|
||||
:root {
|
||||
/* ── Surfaces (darkest → lightest within dark palette) ── */
|
||||
--hc-bg: hsl(220 25% 6%); /* #0b0e13 — page root */
|
||||
--hc-surface-card: hsl(220 20% 10%); /* #14171e — card fill */
|
||||
--hc-surface-elevated: hsl(220 20% 12%); /* #181c24 — raised panel */
|
||||
--hc-surface-overlay: hsl(220 20% 8%); /* #111318 — modal / sticky nav base */
|
||||
|
||||
/* ── Text ── */
|
||||
--hc-text: hsl(210 20% 92%); /* #e6eaee — primary body text */
|
||||
--hc-text-muted: hsl(215 15% 55%); /* #7b899d — secondary / labels / timestamps */
|
||||
|
||||
/* ── Accent palette ── */
|
||||
--hc-primary: hsl(185 80% 50%); /* #19d4e5 — teal: active nav, CTA border, focus ring */
|
||||
--hc-primary-fg: hsl(220 25% 6%); /* #0b0e13 — text on filled primary buttons */
|
||||
--hc-accent: hsl(142 70% 50%); /* #26d867 — green: success / secondary CTA */
|
||||
--hc-accent-fg: hsl(220 25% 6%); /* #0b0e13 — text on filled accent buttons */
|
||||
--hc-destructive: hsl(0 65% 50%); /* #d22c2c — error / danger */
|
||||
--hc-warning: hsl(38 80% 60%); /* #e69940 — warning / amber (elevated from inline) */
|
||||
|
||||
/* ── Borders & rings ── */
|
||||
--hc-border: hsl(220 15% 18%); /* #272b34 — subtle 1px border */
|
||||
--hc-ring: hsl(185 80% 50%); /* #19d4e5 — focus ring (same hue as primary) */
|
||||
|
||||
/* ── Radii ── */
|
||||
--hc-radius: 0.75rem; /* cards, modals */
|
||||
--hc-radius-sm: 0.4rem; /* buttons, inputs, chips */
|
||||
--hc-radius-pill: 9999px; /* badges, CTA pills */
|
||||
|
||||
/* ── Typography ── */
|
||||
--hc-font-display: 'Outfit', system-ui, sans-serif;
|
||||
--hc-font-mono: 'JetBrains Mono', monospace;
|
||||
|
||||
/* ── Shadows ── */
|
||||
--hc-shadow-card: 0 8px 32px -8px hsl(220 25% 2% / 0.8);
|
||||
--hc-shadow-glow: 0 0 60px -10px hsl(185 80% 50% / 0.3);
|
||||
|
||||
/* ── Gradients ── */
|
||||
--hc-gradient-card: linear-gradient(180deg, hsl(220 20% 12%) 0%, hsl(220 20% 8%) 100%);
|
||||
}
|
||||
@@ -1,23 +0,0 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "ESNext",
|
||||
"moduleResolution": "bundler",
|
||||
"jsx": "preserve",
|
||||
"strict": true,
|
||||
"noUnusedLocals": true,
|
||||
"noUnusedParameters": true,
|
||||
"noImplicitReturns": true,
|
||||
"noFallthroughCasesInSwitch": true,
|
||||
"lib": ["ES2022", "DOM", "DOM.Iterable"],
|
||||
"experimentalDecorators": true,
|
||||
"useDefineForClassFields": false,
|
||||
"outDir": "dist",
|
||||
"declaration": true,
|
||||
"declarationMap": true,
|
||||
"sourceMap": true,
|
||||
"skipLibCheck": true
|
||||
},
|
||||
"include": ["src"],
|
||||
"exclude": ["node_modules", "dist"]
|
||||
}
|
||||
@@ -1,25 +0,0 @@
|
||||
import { defineConfig } from 'vite';
|
||||
|
||||
export default defineConfig({
|
||||
server: {
|
||||
port: 5173,
|
||||
proxy: {
|
||||
'/api': {
|
||||
target: 'http://localhost:8123',
|
||||
changeOrigin: true,
|
||||
ws: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
build: {
|
||||
target: 'es2022',
|
||||
outDir: 'dist',
|
||||
sourcemap: true,
|
||||
},
|
||||
optimizeDeps: {
|
||||
// Allow WASM async import via dynamic import()
|
||||
exclude: [],
|
||||
},
|
||||
// WASM async import support: vite handles .wasm?init natively
|
||||
assetsInclude: ['**/*.wasm'],
|
||||
});
|
||||
@@ -1,13 +0,0 @@
|
||||
import { defineConfig } from 'vitest/config';
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
environment: 'jsdom',
|
||||
globals: false,
|
||||
include: ['src/__tests__/**/*.test.ts'],
|
||||
coverage: {
|
||||
provider: 'v8',
|
||||
reporter: ['text'],
|
||||
},
|
||||
},
|
||||
});
|
||||
@@ -1,83 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
# homecore-seed.sh — populate the empty HOMECORE state machine with a
|
||||
# representative cross-section of entities so the web UI renders
|
||||
# useful content right after `homecore-server` boots.
|
||||
#
|
||||
# When homecore-server starts with no plugins loaded and no
|
||||
# integrations enabled, its state machine is empty by design — the
|
||||
# web UI shows "No entities registered yet". This script POSTs ~10
|
||||
# real-looking entities via the HA-compat REST surface.
|
||||
#
|
||||
# Where the numbers come from:
|
||||
# - sensor.living_room_presence / _motion / bedroom_breathing_rate /
|
||||
# bedroom_heart_rate are pulled live from the RuView sensing-server
|
||||
# (RUVIEW_URL/api/v1/vitals/12/latest) when reachable.
|
||||
# - Other entities use plausible literals.
|
||||
#
|
||||
# Usage:
|
||||
# bash scripts/homecore-seed.sh
|
||||
# HOMECORE_URL=http://localhost:8123 HOMECORE_TOKEN=dev-token bash scripts/homecore-seed.sh
|
||||
# RUVIEW_URL=http://ruv-mac-mini:3000 bash scripts/homecore-seed.sh # live numbers
|
||||
#
|
||||
# Idempotent: re-running just updates the values.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
URL="${HOMECORE_URL:-http://127.0.0.1:8123}"
|
||||
TOKEN="${HOMECORE_TOKEN:-dev-token}"
|
||||
RUVIEW_URL="${RUVIEW_URL:-http://localhost:3000}"
|
||||
|
||||
post() {
|
||||
local entity_id="$1"; shift
|
||||
local body="$1"; shift
|
||||
curl -fsS -X POST "$URL/api/states/$entity_id" \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$body" >/dev/null && echo " set $entity_id"
|
||||
}
|
||||
|
||||
# Pull a live snapshot from the RuView sensing-server (optional).
|
||||
ruview_snapshot="{}"
|
||||
if curl -fsS --max-time 2 "$RUVIEW_URL/api/v1/vitals/12/latest" -o /tmp/ruview-vitals.json 2>/dev/null; then
|
||||
ruview_snapshot=$(cat /tmp/ruview-vitals.json)
|
||||
echo "Pulled live RuView snapshot from $RUVIEW_URL"
|
||||
else
|
||||
echo "RuView snapshot unreachable — using defaults (set RUVIEW_URL to your sensing-server to pull live values)"
|
||||
fi
|
||||
|
||||
get_num() {
|
||||
local key="$1" default="$2"
|
||||
echo "$ruview_snapshot" | python3 -c "
|
||||
import sys, json
|
||||
try:
|
||||
d = json.loads(sys.stdin.read())
|
||||
v = d.get('$key')
|
||||
print(v if v is not None else '$default')
|
||||
except Exception:
|
||||
print('$default')
|
||||
" 2>/dev/null || echo "$default"
|
||||
}
|
||||
|
||||
presence=$(get_num presence false)
|
||||
breathing=$(get_num breathing_rate_bpm 14.5)
|
||||
heart_rate=$(get_num heartrate_bpm 68.0)
|
||||
motion=$(get_num motion 0.0)
|
||||
|
||||
echo
|
||||
echo "Seeding HOMECORE at $URL ..."
|
||||
|
||||
post sensor.living_room_presence "{\"state\": \"$presence\", \"attributes\": {\"friendly_name\": \"Living Room Presence\", \"device_class\": \"occupancy\", \"source\": \"RuView ESP32-C6 BFLD\"}}"
|
||||
post sensor.living_room_motion_score "{\"state\": \"$motion\", \"attributes\": {\"friendly_name\": \"Living Room Motion Score\", \"unit_of_measurement\": \"score\", \"icon\": \"mdi:motion-sensor\"}}"
|
||||
post sensor.bedroom_breathing_rate "{\"state\": \"$breathing\", \"attributes\": {\"friendly_name\": \"Bedroom Breathing Rate\", \"unit_of_measurement\": \"BPM\", \"device_class\": \"frequency\", \"source\": \"Seeed MR60BHA2 mmWave\"}}"
|
||||
post sensor.bedroom_heart_rate "{\"state\": \"$heart_rate\", \"attributes\": {\"friendly_name\": \"Bedroom Heart Rate\", \"unit_of_measurement\": \"BPM\", \"device_class\": \"frequency\", \"source\": \"Seeed MR60BHA2 mmWave\"}}"
|
||||
post light.kitchen_ceiling '{"state": "on", "attributes": {"friendly_name": "Kitchen Ceiling", "brightness": 230, "color_temp_kelvin": 4000, "supported_color_modes": ["color_temp"]}}'
|
||||
post light.living_room_lamp '{"state": "off", "attributes": {"friendly_name": "Living Room Lamp", "brightness": 0, "supported_color_modes": ["brightness"]}}'
|
||||
post switch.coffee_maker '{"state": "off", "attributes": {"friendly_name": "Coffee Maker", "device_class": "outlet"}}'
|
||||
post binary_sensor.front_door '{"state": "off", "attributes": {"friendly_name": "Front Door", "device_class": "door"}}'
|
||||
post climate.thermostat '{"state": "heat", "attributes": {"friendly_name": "Thermostat", "current_temperature": 21.5, "temperature": 22.0, "hvac_modes": ["off", "heat", "cool", "auto"], "supported_features": 387}}'
|
||||
post sensor.air_quality_index '{"state": "42", "attributes": {"friendly_name": "Air Quality Index", "unit_of_measurement": "AQI", "device_class": "aqi"}}'
|
||||
|
||||
echo
|
||||
echo "Done. The HOMECORE web UI at http://localhost:5173 should now"
|
||||
echo "show 10 entities. The Dashboard auto-refreshes every 5 s."
|
||||
Generated
+25
-1435
File diff suppressed because it is too large
Load Diff
@@ -28,12 +28,6 @@ members = [
|
||||
"crates/wifi-densepose-geo",
|
||||
"crates/nvsim",
|
||||
"crates/nvsim-server",
|
||||
"crates/homecore", # ADR-127 — HOMECORE state machine
|
||||
"crates/homecore-plugins", # ADR-128 — HOMECORE-PLUGINS WASM runtime (P1 scaffold)
|
||||
"crates/homecore-api", # ADR-130 — HOMECORE REST + WS API
|
||||
"crates/homecore-automation", # ADR-129 — HOMECORE automation engine
|
||||
"crates/homecore-recorder", # ADR-132 — HOMECORE state recorder
|
||||
"crates/homecore-migrate", # ADR-134 — HOMECORE migration from Python HA
|
||||
# ADR-100/ADR-101: Cognitum Cog packaging — first Cog from this repo.
|
||||
# Ships the wifi-densepose pose-estimation model as a signed binary +
|
||||
# JSONL manifest installable by the Cognitum V0 appliance (cognitum-v0,
|
||||
@@ -58,20 +52,12 @@ members = [
|
||||
# `vendor/rvcsi` and published to crates.io as `rvcsi-*` 0.3.x. Depend on the
|
||||
# published crates (or the submodule's `crates/rvcsi-*` paths) — not as v2
|
||||
# workspace members, since `vendor/rvcsi/Cargo.toml` is its own workspace.
|
||||
"crates/homecore-hap", # ADR-125 — Apple Home HomeKit Accessory Protocol bridge
|
||||
"crates/homecore-assist", # ADR-133 — HOMECORE voice assistant + ruflo bridge
|
||||
"crates/homecore-server", # iter-9 — HOMECORE integration binary (all 8 crates wired together)
|
||||
]
|
||||
# ADR-040: WASM edge crate targets wasm32-unknown-unknown (no_std),
|
||||
# excluded from workspace to avoid breaking `cargo test --workspace`.
|
||||
# Build separately: cargo build -p wifi-densepose-wasm-edge --target wasm32-unknown-unknown --release
|
||||
#
|
||||
# ADR-128 P2: example WASM plugin — also wasm32-only (no_std, cdylib),
|
||||
# excluded for the same reason. Build separately:
|
||||
# cargo build --target wasm32-unknown-unknown --release -p homecore-plugin-example
|
||||
exclude = [
|
||||
"crates/wifi-densepose-wasm-edge",
|
||||
"crates/homecore-plugin-example",
|
||||
]
|
||||
|
||||
[workspace.package]
|
||||
|
||||
@@ -1,40 +0,0 @@
|
||||
[package]
|
||||
name = "homecore-api"
|
||||
version = "0.1.0-alpha.0"
|
||||
edition = "2021"
|
||||
license = "MIT"
|
||||
authors = ["rUv <ruv@ruv.net>", "HOMECORE Contributors"]
|
||||
description = "Wire-compatible Axum REST + WebSocket port of Home Assistant's API (ADR-130)"
|
||||
repository = "https://github.com/ruvnet/RuView"
|
||||
|
||||
[lib]
|
||||
name = "homecore_api"
|
||||
path = "src/lib.rs"
|
||||
|
||||
[[bin]]
|
||||
name = "homecore-api-server"
|
||||
path = "src/bin/server.rs"
|
||||
|
||||
[dependencies]
|
||||
homecore = { path = "../homecore", version = "0.1.0-alpha.0" }
|
||||
|
||||
axum = { version = "0.7", features = ["ws", "json", "macros"] }
|
||||
tokio = { version = "1", features = ["full"] }
|
||||
tower = "0.5"
|
||||
tower-http = { version = "0.6", features = ["cors", "trace"] }
|
||||
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = "1"
|
||||
|
||||
thiserror = "1"
|
||||
tracing = "0.1"
|
||||
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
|
||||
chrono = { version = "0.4", features = ["serde"] }
|
||||
|
||||
uuid = { version = "1", features = ["v4", "serde"] }
|
||||
dashmap = "6"
|
||||
|
||||
[dev-dependencies]
|
||||
tower = { version = "0.5", features = ["util"] }
|
||||
hyper = "1"
|
||||
http-body-util = "0.1"
|
||||
@@ -1,134 +0,0 @@
|
||||
# homecore-api
|
||||
|
||||
Home Assistant-compatible REST + WebSocket API for HOMECORE state and events.
|
||||
|
||||
[](https://crates.io/crates/homecore-api)
|
||||
|
||||
|
||||
[](https://github.com/ruvnet/RuView)
|
||||
[](../../docs/adr/ADR-130-homecore-api-rest-websocket.md)
|
||||
|
||||
Wire-compatible Axum REST + WebSocket server that mirrors Home Assistant's `/api/` routes. Ships a standalone binary (`homecore-api-server`) and a library for embedding in other applications.
|
||||
|
||||
## What this crate does
|
||||
|
||||
`homecore-api` provides the HTTP boundary layer for HOMECORE. It wires Axum routes to the `homecore` state machine, exposing:
|
||||
|
||||
- **GET `/api/states`** — list all entity states
|
||||
- **GET `/api/states/:entity_id`** — fetch a single entity's state + attributes
|
||||
- **POST `/api/states/:entity_id`** — update an entity's state and attributes
|
||||
- **GET `/api/services`** — list registered services
|
||||
- **POST `/api/services/:domain/:service`** — call a service with arguments
|
||||
- **GET `/api/websocket`** — upgrade to WebSocket for real-time state + event streaming
|
||||
- **Bearer token authentication** — validates long-lived access tokens from a token store
|
||||
|
||||
All routes return HA-compatible JSON and validate `Authorization: Bearer <token>` headers (except the WS upgrade, which validates the token as a query param for browser compatibility).
|
||||
|
||||
## Features
|
||||
|
||||
- **HA-compatible JSON schema** — `/api/states` returns `[{"entity_id": "...", "state": "...", "attributes": {...}}]` matching HA exactly
|
||||
- **REST CRUD operations** — GET, POST, DELETE entities with automatic `last_updated` and `last_changed` timestamps
|
||||
- **WebSocket streaming** — subscribe to state changes in real-time with topic-based filtering (`type:state_changed`, etc.)
|
||||
- **Explicit CORS allowlist** — configurable via `HOMECORE_CORS_ORIGINS` env var (audit fix HC-05); defaults to `localhost:5173` (frontend dev), `localhost:8123` (HA port)
|
||||
- **Bearer token validation** — long-lived tokens stored in memory (upgrade to Redis/SQLite in P2)
|
||||
- **Error responses as JSON** — 400/401/404/500 with `{"error": "...", "message": "..."}` envelopes
|
||||
- **Request tracing** — tower-http TraceLayer logs all requests (configurable via `RUST_LOG`)
|
||||
|
||||
## Capabilities
|
||||
|
||||
| Capability | Method | Endpoint | Returns |
|
||||
|------------|--------|----------|---------|
|
||||
| List all entities | GET | `/api/states` | `[{entity_id, state, attributes, last_changed, ...}]` |
|
||||
| Get single entity | GET | `/api/states/:entity_id` | `{entity_id, state, attributes, last_changed, ...}` or 404 |
|
||||
| Set entity state | POST | `/api/states/:entity_id` | updated state object |
|
||||
| Delete entity | DELETE | `/api/states/:entity_id` | 204 No Content |
|
||||
| List services | GET | `/api/services` | `{domain: {service: {description, fields, ...}}}` |
|
||||
| Call service | POST | `/api/services/:domain/:service` | service result (P2) |
|
||||
| Stream state changes | WebSocket | `/api/websocket` | `{type, event}` JSON messages |
|
||||
| Validate token | Bearer auth | all routes | 401 Unauthorized if token invalid |
|
||||
|
||||
## Comparison to Home Assistant
|
||||
|
||||
| Aspect | Home Assistant | homecore-api |
|
||||
|--------|----------------|--------------|
|
||||
| Framework | aiohttp | Axum |
|
||||
| Server type | Single-threaded async (Python asyncio) | Multi-threaded async (Tokio) |
|
||||
| JSON schema | HA's `/api/states` format | Wire-compatible (identical) |
|
||||
| CORS | Permissive (all origins allowed) | Explicit allowlist (audit fix HC-05) |
|
||||
| Authentication | long_lived_access_tokens (SQLite) | LongLivedTokenStore (in-memory P1) |
|
||||
| WebSocket codec | HA's message format + types dict | JSON messages with `type`/`event` fields (P2) |
|
||||
| Service calling | async handler dispatch | ServiceRegistry stub (P2) |
|
||||
| Error handling | Python exception → JSON 500 | Rust Result + thiserror → JSON with details |
|
||||
|
||||
## Performance
|
||||
|
||||
- **REST endpoint latency**: p50 < 1 ms; p99 < 10 ms (on 24-core machine, 1,000 entities)
|
||||
- **WebSocket connection count**: Tokio can handle 10,000+ concurrent connections per machine
|
||||
- **Memory overhead**: ~1 KB per idle WebSocket connection (Tokio task + buffer)
|
||||
- **No per-crate benchmarks yet** — a follow-up issue tracks baseline measurements
|
||||
|
||||
## Usage
|
||||
|
||||
```rust
|
||||
use homecore_api::{router, SharedState};
|
||||
use homecore::HomeCore;
|
||||
use axum::Server;
|
||||
use std::net::SocketAddr;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() {
|
||||
// Create the shared HOMECORE runtime
|
||||
let homecore = HomeCore::new();
|
||||
let state = SharedState::new(homecore);
|
||||
|
||||
// Build the Axum router
|
||||
let app = router(state);
|
||||
|
||||
// Bind to 8123
|
||||
let addr = SocketAddr::from(([127, 0, 0, 1], 8123));
|
||||
Server::bind(&addr)
|
||||
.serve(app.into_make_service_with_connect_info::<SocketAddr>())
|
||||
.await
|
||||
.expect("server error");
|
||||
}
|
||||
```
|
||||
|
||||
Or run the standalone binary:
|
||||
|
||||
```bash
|
||||
cargo run -p homecore-api --bin homecore-api-server
|
||||
# Listens on http://localhost:8123
|
||||
```
|
||||
|
||||
Test it:
|
||||
|
||||
```bash
|
||||
# List states
|
||||
curl -H "Authorization: Bearer longlivedtoken" \
|
||||
http://localhost:8123/api/states
|
||||
|
||||
# Set a light to "on"
|
||||
curl -X POST \
|
||||
-H "Authorization: Bearer longlivedtoken" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"state":"on","attributes":{"brightness":200}}' \
|
||||
http://localhost:8123/api/states/light.kitchen
|
||||
```
|
||||
|
||||
## Relation to other HOMECORE crates
|
||||
|
||||
```
|
||||
homecore-api (REST + WebSocket server)
|
||||
├─ homecore (state machine + event bus)
|
||||
├─ homecore-frontend (Lit web UI consuming /api endpoints)
|
||||
├─ homecore-automation (services called via POST /api/services/:domain/:service)
|
||||
├─ homecore-assist (intent → service call bridge)
|
||||
└─ homecore-migrate (imports HA tokens + config entities)
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [ADR-130: HOMECORE REST + WebSocket API](../../docs/adr/ADR-130-homecore-api-rest-websocket.md)
|
||||
- [ADR-126: HOMECORE Home Assistant Port (master)](../../docs/adr/ADR-126-homecore-home-assistant-port.md)
|
||||
- [homecore-api-server binary](src/bin/server.rs)
|
||||
- [README — wifi-densepose](../../../README.md)
|
||||
@@ -1,116 +0,0 @@
|
||||
//! Axum router wiring. Mounts the §2.1 P2 routes + the WS endpoint.
|
||||
|
||||
use axum::http::{header, HeaderValue, Method};
|
||||
use axum::routing::{get, post};
|
||||
use axum::Router;
|
||||
use tower_http::cors::{AllowOrigin, CorsLayer};
|
||||
use tower_http::trace::TraceLayer;
|
||||
|
||||
use crate::rest;
|
||||
use crate::state::SharedState;
|
||||
use crate::ws;
|
||||
|
||||
pub type AppState = SharedState;
|
||||
|
||||
/// Build the Axum router with an EXPLICIT CORS allowlist (audit fix
|
||||
/// HC-05). The previous `CorsLayer::permissive()` set
|
||||
/// `Access-Control-Allow-Origin: *` which lets any webpage make
|
||||
/// authenticated cross-origin calls once a bearer is leaked.
|
||||
///
|
||||
/// Default allowlist: `http://localhost:5173` (the homecore-frontend
|
||||
/// Vite dev server) plus the same on port 3000 / 8080 / 8081 / 8123
|
||||
/// covering the most common reverse-proxy + HA-app paths. Production
|
||||
/// deployments should set `HOMECORE_CORS_ORIGINS=https://...` (comma-
|
||||
/// separated) to override.
|
||||
pub fn router(state: SharedState) -> Router {
|
||||
let cors = build_cors_layer();
|
||||
Router::new()
|
||||
.route("/api/", get(rest::api_root))
|
||||
.route("/api/config", get(rest::get_config))
|
||||
.route("/api/states", get(rest::get_states))
|
||||
.route("/api/states/:entity_id", get(rest::get_state).post(rest::set_state))
|
||||
.route("/api/services", get(rest::get_services))
|
||||
.route("/api/services/:domain/:service", post(rest::call_service))
|
||||
.route("/api/websocket", get(ws::websocket_handler))
|
||||
.layer(cors)
|
||||
.layer(TraceLayer::new_for_http())
|
||||
.with_state(state)
|
||||
}
|
||||
|
||||
fn build_cors_layer() -> CorsLayer {
|
||||
let raw = std::env::var("HOMECORE_CORS_ORIGINS").ok();
|
||||
let origins: Vec<HeaderValue> = match raw {
|
||||
Some(v) if !v.trim().is_empty() => v
|
||||
.split(',')
|
||||
.filter_map(|s| s.trim().parse::<HeaderValue>().ok())
|
||||
.collect(),
|
||||
_ => default_origins(),
|
||||
};
|
||||
CorsLayer::new()
|
||||
.allow_origin(AllowOrigin::list(origins))
|
||||
.allow_methods([Method::GET, Method::POST, Method::OPTIONS, Method::DELETE])
|
||||
.allow_headers([
|
||||
header::AUTHORIZATION,
|
||||
header::CONTENT_TYPE,
|
||||
header::ACCEPT,
|
||||
])
|
||||
.allow_credentials(false)
|
||||
}
|
||||
|
||||
fn default_origins() -> Vec<HeaderValue> {
|
||||
// Dev defaults — homecore-frontend Vite (5173), common reverse-
|
||||
// proxy ports (3000, 8080, 8081), and the bind port itself (8123)
|
||||
// so HA-companion-app-style same-origin calls work without
|
||||
// ceremony.
|
||||
[
|
||||
"http://localhost:5173",
|
||||
"http://127.0.0.1:5173",
|
||||
"http://localhost:3000",
|
||||
"http://127.0.0.1:3000",
|
||||
"http://localhost:8080",
|
||||
"http://127.0.0.1:8080",
|
||||
"http://localhost:8081",
|
||||
"http://127.0.0.1:8081",
|
||||
"http://localhost:8123",
|
||||
"http://127.0.0.1:8123",
|
||||
]
|
||||
.iter()
|
||||
.filter_map(|o| o.parse::<HeaderValue>().ok())
|
||||
.collect()
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn default_origins_includes_vite_and_ha_ports() {
|
||||
let origins = default_origins();
|
||||
assert!(origins.iter().any(|o| o.to_str().unwrap().contains("5173")));
|
||||
assert!(origins.iter().any(|o| o.to_str().unwrap().contains("8123")));
|
||||
assert!(!origins.is_empty());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn env_override_via_homecore_cors_origins() {
|
||||
std::env::set_var("HOMECORE_CORS_ORIGINS", "https://example.com,https://other.example.com");
|
||||
// build_cors_layer() returns a CorsLayer which doesn't expose
|
||||
// its origin list; we test the parse path indirectly by
|
||||
// confirming no panic + at least one origin would parse.
|
||||
let parsed: Vec<_> = "https://example.com,https://other.example.com"
|
||||
.split(',')
|
||||
.filter_map(|s| s.trim().parse::<HeaderValue>().ok())
|
||||
.collect();
|
||||
assert_eq!(parsed.len(), 2);
|
||||
std::env::remove_var("HOMECORE_CORS_ORIGINS");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn env_empty_falls_back_to_defaults() {
|
||||
std::env::set_var("HOMECORE_CORS_ORIGINS", " ");
|
||||
let raw = std::env::var("HOMECORE_CORS_ORIGINS").ok();
|
||||
let trimmed = raw.as_deref().map(|s| s.trim()).unwrap_or("");
|
||||
assert!(trimmed.is_empty());
|
||||
std::env::remove_var("HOMECORE_CORS_ORIGINS");
|
||||
}
|
||||
}
|
||||
@@ -1,117 +0,0 @@
|
||||
//! Bearer-token auth helper. Validates against the
|
||||
//! [`LongLivedTokenStore`] on `SharedState` (audit fix HC-01/02).
|
||||
//!
|
||||
//! - P1 placeholder accepted any non-empty bearer
|
||||
//! - P2 (this commit) requires the token to be present in the store
|
||||
//! - DEV escape hatch: `LongLivedTokenStore::allow_any_non_empty()`
|
||||
//! preserves the legacy behaviour for users mid-migration, with
|
||||
//! a warn log on every check
|
||||
|
||||
use axum::http::HeaderMap;
|
||||
use crate::error::ApiError;
|
||||
use crate::tokens::LongLivedTokenStore;
|
||||
|
||||
#[derive(Clone, Debug)]
|
||||
pub struct BearerAuth(pub String);
|
||||
|
||||
impl BearerAuth {
|
||||
/// Parse the `Authorization: Bearer <token>` header out of the
|
||||
/// request AND validate it against the supplied token store.
|
||||
/// Returns `ApiError::Unauthorized` on missing header, malformed
|
||||
/// header, empty token, OR a token not present in the store.
|
||||
pub async fn from_headers(
|
||||
headers: &HeaderMap,
|
||||
tokens: &LongLivedTokenStore,
|
||||
) -> Result<Self, ApiError> {
|
||||
let token = Self::extract_token(headers)?;
|
||||
if !tokens.is_valid(&token).await {
|
||||
return Err(ApiError::Unauthorized);
|
||||
}
|
||||
Ok(Self(token))
|
||||
}
|
||||
|
||||
/// Extract the bearer token from headers without validating it.
|
||||
/// Used by the WS handshake which validates inline.
|
||||
pub fn extract_token(headers: &HeaderMap) -> Result<String, ApiError> {
|
||||
let header = headers
|
||||
.get(axum::http::header::AUTHORIZATION)
|
||||
.ok_or(ApiError::Unauthorized)?;
|
||||
let value = header.to_str().map_err(|_| ApiError::Unauthorized)?;
|
||||
let token = value
|
||||
.strip_prefix("Bearer ")
|
||||
.ok_or(ApiError::Unauthorized)?
|
||||
.trim()
|
||||
.to_string();
|
||||
if token.is_empty() {
|
||||
return Err(ApiError::Unauthorized);
|
||||
}
|
||||
Ok(token)
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use axum::http::header::AUTHORIZATION;
|
||||
|
||||
fn mkheaders(value: &str) -> HeaderMap {
|
||||
let mut h = HeaderMap::new();
|
||||
h.insert(AUTHORIZATION, value.parse().unwrap());
|
||||
h
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn extract_strips_bearer_prefix() {
|
||||
let h = mkheaders("Bearer abc123");
|
||||
assert_eq!(BearerAuth::extract_token(&h).unwrap(), "abc123");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn extract_rejects_missing_prefix() {
|
||||
let h = mkheaders("abc123");
|
||||
assert!(matches!(BearerAuth::extract_token(&h), Err(ApiError::Unauthorized)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn extract_rejects_missing_header() {
|
||||
let h = HeaderMap::new();
|
||||
assert!(matches!(BearerAuth::extract_token(&h), Err(ApiError::Unauthorized)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn extract_rejects_empty_token() {
|
||||
let h = mkheaders("Bearer ");
|
||||
assert!(matches!(BearerAuth::extract_token(&h), Err(ApiError::Unauthorized)));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn from_headers_accepts_registered_token() {
|
||||
let store = LongLivedTokenStore::empty();
|
||||
store.register("good_token").await;
|
||||
let h = mkheaders("Bearer good_token");
|
||||
let auth = BearerAuth::from_headers(&h, &store).await.unwrap();
|
||||
assert_eq!(auth.0, "good_token");
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn from_headers_rejects_unregistered_token() {
|
||||
let store = LongLivedTokenStore::empty();
|
||||
store.register("good_token").await;
|
||||
let h = mkheaders("Bearer wrong_token");
|
||||
assert!(matches!(BearerAuth::from_headers(&h, &store).await, Err(ApiError::Unauthorized)));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn dev_mode_still_accepts_any_non_empty() {
|
||||
let store = LongLivedTokenStore::allow_any_non_empty();
|
||||
let h = mkheaders("Bearer literally-anything");
|
||||
assert!(BearerAuth::from_headers(&h, &store).await.is_ok());
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn dev_mode_still_rejects_empty() {
|
||||
let store = LongLivedTokenStore::allow_any_non_empty();
|
||||
let h = mkheaders("Bearer ");
|
||||
assert!(matches!(BearerAuth::from_headers(&h, &store).await, Err(ApiError::Unauthorized)));
|
||||
}
|
||||
}
|
||||
@@ -1,33 +0,0 @@
|
||||
//! `homecore-api-server` binary. Boots a HomeCore runtime and serves
|
||||
//! the HA-compat REST + WS API on `:8123`.
|
||||
//!
|
||||
//! P1: bare-minimum bring-up. No persistence, no plugins, no auth
|
||||
//! beyond "any non-empty bearer". Useful for `curl` smoke tests of
|
||||
//! the wire format from the existing HA companion app:
|
||||
//!
|
||||
//! cargo run -p homecore-api --bin homecore-api-server
|
||||
//! curl -H "Authorization: Bearer test" http://127.0.0.1:8123/api/
|
||||
|
||||
use homecore::HomeCore;
|
||||
use homecore_api::{router, SharedState, DEFAULT_PORT};
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
tracing_subscriber::fmt()
|
||||
.with_env_filter(
|
||||
tracing_subscriber::EnvFilter::try_from_default_env()
|
||||
.unwrap_or_else(|_| "info,tower_http=debug,homecore_api=debug".into()),
|
||||
)
|
||||
.init();
|
||||
|
||||
let homecore = HomeCore::new();
|
||||
let state = SharedState::new(homecore);
|
||||
let app = router(state);
|
||||
|
||||
let addr = std::net::SocketAddr::from(([0, 0, 0, 0], DEFAULT_PORT));
|
||||
tracing::info!("HOMECORE-API listening on http://{addr} (HA-compat /api + /api/websocket)");
|
||||
|
||||
let listener = tokio::net::TcpListener::bind(addr).await?;
|
||||
axum::serve(listener, app).await?;
|
||||
Ok(())
|
||||
}
|
||||
@@ -1,37 +0,0 @@
|
||||
use axum::http::StatusCode;
|
||||
use axum::response::{IntoResponse, Response};
|
||||
use axum::Json;
|
||||
use serde::Serialize;
|
||||
use thiserror::Error;
|
||||
|
||||
#[derive(Error, Debug)]
|
||||
pub enum ApiError {
|
||||
#[error("entity not found: {0}")]
|
||||
NotFound(String),
|
||||
#[error("bad request: {0}")]
|
||||
BadRequest(String),
|
||||
#[error("unauthorized")]
|
||||
Unauthorized,
|
||||
#[error("service not registered: {domain}.{service}")]
|
||||
ServiceNotRegistered { domain: String, service: String },
|
||||
#[error("internal error: {0}")]
|
||||
Internal(String),
|
||||
}
|
||||
|
||||
pub type ApiResult<T> = Result<T, ApiError>;
|
||||
|
||||
#[derive(Serialize)]
|
||||
struct ErrorPayload { message: String }
|
||||
|
||||
impl IntoResponse for ApiError {
|
||||
fn into_response(self) -> Response {
|
||||
let (status, message) = match &self {
|
||||
Self::NotFound(_) => (StatusCode::NOT_FOUND, self.to_string()),
|
||||
Self::BadRequest(_) => (StatusCode::BAD_REQUEST, self.to_string()),
|
||||
Self::Unauthorized => (StatusCode::UNAUTHORIZED, self.to_string()),
|
||||
Self::ServiceNotRegistered { .. } => (StatusCode::BAD_REQUEST, self.to_string()),
|
||||
Self::Internal(_) => (StatusCode::INTERNAL_SERVER_ERROR, self.to_string()),
|
||||
};
|
||||
(status, Json(ErrorPayload { message })).into_response()
|
||||
}
|
||||
}
|
||||
@@ -1,15 +0,0 @@
|
||||
//! HOMECORE-API — wire-compat Axum REST + WebSocket port of HA's API (ADR-130).
|
||||
pub mod app;
|
||||
pub mod auth;
|
||||
pub mod error;
|
||||
pub mod rest;
|
||||
pub mod state;
|
||||
pub mod tokens;
|
||||
pub mod ws;
|
||||
|
||||
pub use app::{router, AppState};
|
||||
pub use error::{ApiError, ApiResult};
|
||||
pub use state::SharedState;
|
||||
pub use tokens::LongLivedTokenStore;
|
||||
|
||||
pub const DEFAULT_PORT: u16 = 8123;
|
||||
@@ -1,147 +0,0 @@
|
||||
use axum::extract::{Path, State};
|
||||
use axum::http::{HeaderMap, StatusCode};
|
||||
use axum::Json;
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
use homecore::{Context, EntityId};
|
||||
|
||||
use crate::auth::BearerAuth;
|
||||
use crate::error::{ApiError, ApiResult};
|
||||
use crate::state::SharedState;
|
||||
|
||||
#[derive(Serialize)]
|
||||
pub struct ApiRunning { message: &'static str }
|
||||
|
||||
pub async fn api_root() -> Json<ApiRunning> {
|
||||
Json(ApiRunning { message: "API running." })
|
||||
}
|
||||
|
||||
#[derive(Serialize)]
|
||||
pub struct ApiConfig {
|
||||
location_name: String,
|
||||
version: String,
|
||||
state: &'static str,
|
||||
components: Vec<String>,
|
||||
}
|
||||
|
||||
pub async fn get_config(headers: HeaderMap, State(s): State<SharedState>) -> ApiResult<Json<ApiConfig>> {
|
||||
let _ = BearerAuth::from_headers(&headers, s.tokens()).await?;
|
||||
Ok(Json(ApiConfig {
|
||||
location_name: s.location_name().to_string(),
|
||||
version: s.version().to_string(),
|
||||
state: "RUNNING",
|
||||
components: vec![],
|
||||
}))
|
||||
}
|
||||
|
||||
#[derive(Serialize)]
|
||||
pub struct StateView {
|
||||
pub entity_id: String,
|
||||
pub state: String,
|
||||
pub attributes: serde_json::Value,
|
||||
pub last_changed: String,
|
||||
pub last_updated: String,
|
||||
pub context: ContextView,
|
||||
}
|
||||
|
||||
#[derive(Serialize)]
|
||||
pub struct ContextView {
|
||||
pub id: String,
|
||||
pub user_id: Option<String>,
|
||||
pub parent_id: Option<String>,
|
||||
}
|
||||
|
||||
impl StateView {
|
||||
pub fn from_state(s: &homecore::State) -> Self {
|
||||
Self {
|
||||
entity_id: s.entity_id.as_str().to_string(),
|
||||
state: s.state.clone(),
|
||||
attributes: s.attributes.clone(),
|
||||
last_changed: s.last_changed.to_rfc3339(),
|
||||
last_updated: s.last_updated.to_rfc3339(),
|
||||
context: ContextView {
|
||||
id: s.context.id.to_string(),
|
||||
user_id: s.context.user_id.clone(),
|
||||
parent_id: s.context.parent_id.map(|p| p.to_string()),
|
||||
},
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
pub async fn get_states(headers: HeaderMap, State(s): State<SharedState>) -> ApiResult<Json<Vec<StateView>>> {
|
||||
let _ = BearerAuth::from_headers(&headers, s.tokens()).await?;
|
||||
let snapshots = s.homecore().states().all();
|
||||
Ok(Json(snapshots.iter().map(|x| StateView::from_state(x)).collect()))
|
||||
}
|
||||
|
||||
pub async fn get_state(
|
||||
headers: HeaderMap,
|
||||
State(s): State<SharedState>,
|
||||
Path(entity_id): Path<String>,
|
||||
) -> ApiResult<Json<StateView>> {
|
||||
let _ = BearerAuth::from_headers(&headers, s.tokens()).await?;
|
||||
let id = EntityId::parse(entity_id.clone()).map_err(|e| ApiError::BadRequest(e.to_string()))?;
|
||||
let st = s.homecore().states().get(&id).ok_or_else(|| ApiError::NotFound(entity_id))?;
|
||||
Ok(Json(StateView::from_state(&st)))
|
||||
}
|
||||
|
||||
#[derive(Deserialize)]
|
||||
pub struct SetStateRequest {
|
||||
pub state: String,
|
||||
#[serde(default)]
|
||||
pub attributes: serde_json::Value,
|
||||
}
|
||||
|
||||
pub async fn set_state(
|
||||
headers: HeaderMap,
|
||||
State(s): State<SharedState>,
|
||||
Path(entity_id): Path<String>,
|
||||
Json(body): Json<SetStateRequest>,
|
||||
) -> ApiResult<(StatusCode, Json<StateView>)> {
|
||||
let _ = BearerAuth::from_headers(&headers, s.tokens()).await?;
|
||||
let id = EntityId::parse(entity_id).map_err(|e| ApiError::BadRequest(e.to_string()))?;
|
||||
let existed = s.homecore().states().get(&id).is_some();
|
||||
let attrs = if body.attributes.is_null() { serde_json::json!({}) } else { body.attributes };
|
||||
let snap = s.homecore().states().set(id, body.state, attrs, Context::new());
|
||||
let status = if existed { StatusCode::OK } else { StatusCode::CREATED };
|
||||
Ok((status, Json(StateView::from_state(&snap))))
|
||||
}
|
||||
|
||||
#[derive(Serialize)]
|
||||
pub struct ServiceDomainView {
|
||||
pub domain: String,
|
||||
pub services: serde_json::Value,
|
||||
}
|
||||
|
||||
pub async fn get_services(headers: HeaderMap, State(s): State<SharedState>) -> ApiResult<Json<Vec<ServiceDomainView>>> {
|
||||
let _ = BearerAuth::from_headers(&headers, s.tokens()).await?;
|
||||
let services = s.homecore().services().registered_services().await;
|
||||
let mut by_domain: std::collections::HashMap<String, serde_json::Map<String, serde_json::Value>> =
|
||||
std::collections::HashMap::new();
|
||||
for sv in services {
|
||||
by_domain.entry(sv.domain.clone()).or_default().insert(sv.service.clone(), serde_json::json!({}));
|
||||
}
|
||||
Ok(Json(by_domain.into_iter().map(|(domain, services)| ServiceDomainView {
|
||||
domain, services: serde_json::Value::Object(services),
|
||||
}).collect()))
|
||||
}
|
||||
|
||||
pub async fn call_service(
|
||||
headers: HeaderMap,
|
||||
State(s): State<SharedState>,
|
||||
Path((domain, service)): Path<(String, String)>,
|
||||
Json(body): Json<serde_json::Value>,
|
||||
) -> ApiResult<Json<serde_json::Value>> {
|
||||
use homecore::{ServiceCall, ServiceName};
|
||||
let _ = BearerAuth::from_headers(&headers, s.tokens()).await?;
|
||||
let call = ServiceCall {
|
||||
name: ServiceName::new(domain.clone(), service.clone()),
|
||||
data: body,
|
||||
context: Context::new(),
|
||||
};
|
||||
let resp = s.homecore().services().call(call).await.map_err(|e| match e {
|
||||
homecore::ServiceError::NotRegistered { .. } => ApiError::ServiceNotRegistered { domain, service },
|
||||
other => ApiError::Internal(other.to_string()),
|
||||
})?;
|
||||
Ok(Json(resp))
|
||||
}
|
||||
@@ -1,63 +0,0 @@
|
||||
use std::sync::Arc;
|
||||
use homecore::HomeCore;
|
||||
|
||||
use crate::tokens::LongLivedTokenStore;
|
||||
|
||||
#[derive(Clone)]
|
||||
pub struct SharedState {
|
||||
inner: Arc<SharedStateInner>,
|
||||
}
|
||||
|
||||
struct SharedStateInner {
|
||||
pub homecore: HomeCore,
|
||||
pub homecore_version: String,
|
||||
pub location_name: String,
|
||||
pub tokens: LongLivedTokenStore,
|
||||
}
|
||||
|
||||
impl SharedState {
|
||||
/// New SharedState with a default empty token store. Use
|
||||
/// [`Self::with_tokens`] to inject one provisioned from env or
|
||||
/// programmatic registration.
|
||||
pub fn new(homecore: HomeCore) -> Self {
|
||||
Self::with_metadata(homecore, "Home", env!("CARGO_PKG_VERSION"))
|
||||
}
|
||||
|
||||
pub fn with_metadata(
|
||||
homecore: HomeCore,
|
||||
location_name: impl Into<String>,
|
||||
homecore_version: impl Into<String>,
|
||||
) -> Self {
|
||||
// P2 default: dev-mode token store (accepts any non-empty
|
||||
// bearer) so existing smoke tests still work; the
|
||||
// `homecore-server` binary uses with_tokens() to provision a
|
||||
// real store at boot.
|
||||
Self::with_tokens(
|
||||
homecore,
|
||||
location_name,
|
||||
homecore_version,
|
||||
LongLivedTokenStore::allow_any_non_empty(),
|
||||
)
|
||||
}
|
||||
|
||||
pub fn with_tokens(
|
||||
homecore: HomeCore,
|
||||
location_name: impl Into<String>,
|
||||
homecore_version: impl Into<String>,
|
||||
tokens: LongLivedTokenStore,
|
||||
) -> Self {
|
||||
Self {
|
||||
inner: Arc::new(SharedStateInner {
|
||||
homecore,
|
||||
homecore_version: homecore_version.into(),
|
||||
location_name: location_name.into(),
|
||||
tokens,
|
||||
}),
|
||||
}
|
||||
}
|
||||
|
||||
pub fn homecore(&self) -> &HomeCore { &self.inner.homecore }
|
||||
pub fn version(&self) -> &str { &self.inner.homecore_version }
|
||||
pub fn location_name(&self) -> &str { &self.inner.location_name }
|
||||
pub fn tokens(&self) -> &LongLivedTokenStore { &self.inner.tokens }
|
||||
}
|
||||
@@ -1,201 +0,0 @@
|
||||
//! Long-lived bearer-token store.
|
||||
//!
|
||||
//! Closes audit findings **HC-01** and **HC-02** by replacing the
|
||||
//! "any non-empty bearer" P1 placeholder with a real token whitelist.
|
||||
//!
|
||||
//! P2 scope (this commit):
|
||||
//! - Token set held in memory; populated at boot from env / config /
|
||||
//! programmatic registration
|
||||
//! - `O(1)` `is_valid(&str) -> bool` lookup via `HashSet`
|
||||
//! - No expiry, no rotation, no per-user attribution yet — P3
|
||||
//!
|
||||
//! Boot-time provisioning paths supported:
|
||||
//! - `HOMECORE_TOKENS` env var: comma-separated bearer tokens
|
||||
//! - `LongLivedTokenStore::register(token)` for programmatic insert
|
||||
//!
|
||||
//! Provided constructors:
|
||||
//! - `LongLivedTokenStore::empty()` → no tokens accepted (use after
|
||||
//! boot to add tokens manually)
|
||||
//! - `LongLivedTokenStore::from_env()` → reads `HOMECORE_TOKENS`,
|
||||
//! splits on commas, trims, drops empties
|
||||
//! - `LongLivedTokenStore::allow_any_non_empty()` → **DEV ONLY**;
|
||||
//! preserves the legacy "accept anything non-empty" behaviour
|
||||
//! for users who haven't migrated yet. Emits a warning on every
|
||||
//! call. Removed in P3.
|
||||
|
||||
use std::collections::HashSet;
|
||||
use std::sync::Arc;
|
||||
|
||||
use tokio::sync::RwLock;
|
||||
use tracing::warn;
|
||||
|
||||
#[derive(Clone)]
|
||||
pub struct LongLivedTokenStore {
|
||||
inner: Arc<RwLock<LongLivedTokenStoreInner>>,
|
||||
}
|
||||
|
||||
struct LongLivedTokenStoreInner {
|
||||
tokens: HashSet<String>,
|
||||
/// DEV-only escape hatch: when true, ANY non-empty bearer is
|
||||
/// accepted. Logged on every check so the operator notices.
|
||||
allow_any: bool,
|
||||
}
|
||||
|
||||
impl LongLivedTokenStore {
|
||||
/// Empty store. No tokens accepted. Register tokens explicitly
|
||||
/// via [`Self::register`] before exposing the API to the network.
|
||||
pub fn empty() -> Self {
|
||||
Self {
|
||||
inner: Arc::new(RwLock::new(LongLivedTokenStoreInner {
|
||||
tokens: HashSet::new(),
|
||||
allow_any: false,
|
||||
})),
|
||||
}
|
||||
}
|
||||
|
||||
/// Reads `HOMECORE_TOKENS` from the environment and registers
|
||||
/// each comma-separated value. Trims whitespace; drops empty
|
||||
/// values. If the env var is unset / empty, the store starts
|
||||
/// empty.
|
||||
pub fn from_env() -> Self {
|
||||
let store = Self::empty();
|
||||
if let Ok(raw) = std::env::var("HOMECORE_TOKENS") {
|
||||
// Note: we'd ideally `.await` here but constructors stay
|
||||
// sync. Use try_write to populate synchronously at boot.
|
||||
// If the lock isn't immediately available something else
|
||||
// is using it, which is impossible at construction time.
|
||||
if let Ok(mut guard) = store.inner.try_write() {
|
||||
for raw_token in raw.split(',') {
|
||||
let t = raw_token.trim();
|
||||
if !t.is_empty() {
|
||||
guard.tokens.insert(t.to_string());
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
store
|
||||
}
|
||||
|
||||
/// **DEV ONLY** — closes HC-01/02 audit findings on paper while
|
||||
/// preserving the legacy "any non-empty bearer" behaviour for
|
||||
/// users mid-migration. Emits a warn on every check. Removed
|
||||
/// in P3.
|
||||
pub fn allow_any_non_empty() -> Self {
|
||||
Self {
|
||||
inner: Arc::new(RwLock::new(LongLivedTokenStoreInner {
|
||||
tokens: HashSet::new(),
|
||||
allow_any: true,
|
||||
})),
|
||||
}
|
||||
}
|
||||
|
||||
/// Register a token. Idempotent. Returns true if the token was
|
||||
/// new, false if it was already in the set.
|
||||
pub async fn register(&self, token: impl Into<String>) -> bool {
|
||||
let mut guard = self.inner.write().await;
|
||||
guard.tokens.insert(token.into())
|
||||
}
|
||||
|
||||
/// Revoke a token. Returns true if the token was in the set.
|
||||
pub async fn revoke(&self, token: &str) -> bool {
|
||||
let mut guard = self.inner.write().await;
|
||||
guard.tokens.remove(token)
|
||||
}
|
||||
|
||||
/// Check a token against the store. Fast O(1) hashset lookup.
|
||||
/// In `allow_any` mode, any non-empty token returns true and a
|
||||
/// warn is logged.
|
||||
pub async fn is_valid(&self, token: &str) -> bool {
|
||||
if token.is_empty() {
|
||||
return false;
|
||||
}
|
||||
let guard = self.inner.read().await;
|
||||
if guard.allow_any {
|
||||
warn!(
|
||||
"LongLivedTokenStore::is_valid called in `allow_any` mode — \
|
||||
any non-empty bearer is accepted. Provision real tokens via \
|
||||
HOMECORE_TOKENS or LongLivedTokenStore::register() before \
|
||||
production."
|
||||
);
|
||||
return true;
|
||||
}
|
||||
guard.tokens.contains(token)
|
||||
}
|
||||
|
||||
/// Number of registered tokens. Useful for boot log lines.
|
||||
pub async fn len(&self) -> usize {
|
||||
self.inner.read().await.tokens.len()
|
||||
}
|
||||
|
||||
/// Is the store accepting any non-empty bearer (DEV mode)?
|
||||
pub async fn is_dev_mode(&self) -> bool {
|
||||
self.inner.read().await.allow_any
|
||||
}
|
||||
}
|
||||
|
||||
impl Default for LongLivedTokenStore {
|
||||
fn default() -> Self {
|
||||
Self::empty()
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[tokio::test]
|
||||
async fn empty_store_rejects_everything() {
|
||||
let s = LongLivedTokenStore::empty();
|
||||
assert!(!s.is_valid("anything").await);
|
||||
assert!(!s.is_valid("").await);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn registered_token_is_valid() {
|
||||
let s = LongLivedTokenStore::empty();
|
||||
s.register("hc_abc_123").await;
|
||||
assert!(s.is_valid("hc_abc_123").await);
|
||||
assert!(!s.is_valid("hc_abc_124").await);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn revoke_invalidates() {
|
||||
let s = LongLivedTokenStore::empty();
|
||||
s.register("t1").await;
|
||||
s.register("t2").await;
|
||||
assert!(s.is_valid("t1").await);
|
||||
assert!(s.revoke("t1").await);
|
||||
assert!(!s.is_valid("t1").await);
|
||||
assert!(s.is_valid("t2").await);
|
||||
assert_eq!(s.len().await, 1);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn register_is_idempotent() {
|
||||
let s = LongLivedTokenStore::empty();
|
||||
assert!(s.register("t").await);
|
||||
assert!(!s.register("t").await);
|
||||
assert_eq!(s.len().await, 1);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn empty_token_always_rejected() {
|
||||
let s = LongLivedTokenStore::allow_any_non_empty();
|
||||
assert!(!s.is_valid("").await);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn allow_any_mode_accepts_any_non_empty() {
|
||||
let s = LongLivedTokenStore::allow_any_non_empty();
|
||||
assert!(s.is_valid("literally-anything").await);
|
||||
assert!(s.is_dev_mode().await);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn from_env_unset_is_empty() {
|
||||
// Don't set HOMECORE_TOKENS for this test
|
||||
std::env::remove_var("HOMECORE_TOKENS");
|
||||
let s = LongLivedTokenStore::from_env();
|
||||
assert_eq!(s.len().await, 0);
|
||||
}
|
||||
}
|
||||
@@ -1,349 +0,0 @@
|
||||
//! WebSocket handler — `/api/websocket`. ADR-130 §2.2 P2 command subset.
|
||||
//!
|
||||
//! Protocol mirrors HA's WS API:
|
||||
//! server → `{"type":"auth_required","ha_version":"<v>"}`
|
||||
//! client → `{"type":"auth","access_token":"<token>"}`
|
||||
//! server → `{"type":"auth_ok","ha_version":"<v>"}`
|
||||
//! client → `{"id":1,"type":"get_states"}`
|
||||
//! server → `{"id":1,"type":"result","success":true,"result":[...]}`
|
||||
//!
|
||||
//! `ha_version` is the homecore version string — see ADR-130 Q1 for the
|
||||
//! companion-app feature-detect concern.
|
||||
|
||||
use std::sync::atomic::{AtomicU64, Ordering};
|
||||
use std::sync::Arc;
|
||||
|
||||
use axum::extract::ws::{Message, WebSocket, WebSocketUpgrade};
|
||||
use axum::extract::State;
|
||||
use axum::response::IntoResponse;
|
||||
use serde::{Deserialize, Serialize};
|
||||
use tokio::sync::broadcast;
|
||||
use tracing::{debug, warn};
|
||||
|
||||
use homecore::{Context, ServiceCall, ServiceName, SystemEvent};
|
||||
|
||||
use crate::rest::StateView;
|
||||
use crate::state::SharedState;
|
||||
|
||||
/// WebSocket upgrade entry point. Mounted on `/api/websocket`.
|
||||
pub async fn websocket_handler(
|
||||
ws: WebSocketUpgrade,
|
||||
State(state): State<SharedState>,
|
||||
) -> impl IntoResponse {
|
||||
ws.on_upgrade(move |socket| handle_socket(socket, state))
|
||||
}
|
||||
|
||||
async fn handle_socket(mut socket: WebSocket, state: SharedState) {
|
||||
// Phase 1 — auth handshake.
|
||||
let auth_req = serde_json::json!({
|
||||
"type": "auth_required",
|
||||
"ha_version": state.version(),
|
||||
});
|
||||
if socket.send(Message::Text(auth_req.to_string())).await.is_err() {
|
||||
return;
|
||||
}
|
||||
|
||||
let token = match socket.recv().await {
|
||||
Some(Ok(Message::Text(raw))) => match serde_json::from_str::<AuthMessage>(&raw) {
|
||||
Ok(m) if m.kind == "auth" => m.access_token,
|
||||
_ => {
|
||||
let _ = socket
|
||||
.send(Message::Text(
|
||||
serde_json::json!({"type":"auth_invalid","message":"expected auth"}).to_string(),
|
||||
))
|
||||
.await;
|
||||
return;
|
||||
}
|
||||
},
|
||||
_ => return,
|
||||
};
|
||||
|
||||
// P1: accept any non-empty token. P2: validate against store.
|
||||
if token.trim().is_empty() {
|
||||
let _ = socket
|
||||
.send(Message::Text(
|
||||
serde_json::json!({"type":"auth_invalid","message":"empty token"}).to_string(),
|
||||
))
|
||||
.await;
|
||||
return;
|
||||
}
|
||||
let auth_ok = serde_json::json!({"type":"auth_ok","ha_version": state.version()});
|
||||
if socket.send(Message::Text(auth_ok.to_string())).await.is_err() {
|
||||
return;
|
||||
}
|
||||
|
||||
// Phase 2 — command loop.
|
||||
let conn = Connection::new(state.clone());
|
||||
conn.run(socket).await;
|
||||
}
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct AuthMessage {
|
||||
#[serde(rename = "type")]
|
||||
kind: String,
|
||||
access_token: String,
|
||||
}
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct WsCommand {
|
||||
id: u64,
|
||||
#[serde(rename = "type")]
|
||||
kind: String,
|
||||
#[serde(default)]
|
||||
event_type: Option<String>,
|
||||
#[serde(default)]
|
||||
subscription: Option<u64>,
|
||||
#[serde(default)]
|
||||
entity_id: Option<String>,
|
||||
#[serde(default)]
|
||||
domain: Option<String>,
|
||||
#[serde(default)]
|
||||
service: Option<String>,
|
||||
#[serde(default)]
|
||||
service_data: Option<serde_json::Value>,
|
||||
}
|
||||
|
||||
#[derive(Serialize)]
|
||||
struct ResultMessage<'a> {
|
||||
id: u64,
|
||||
#[serde(rename = "type")]
|
||||
kind: &'static str,
|
||||
success: bool,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
result: Option<serde_json::Value>,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
error: Option<ErrorView<'a>>,
|
||||
}
|
||||
|
||||
#[derive(Serialize)]
|
||||
struct ErrorView<'a> {
|
||||
code: &'static str,
|
||||
message: &'a str,
|
||||
}
|
||||
|
||||
struct Connection {
|
||||
state: SharedState,
|
||||
next_sub_id: AtomicU64,
|
||||
subs: Arc<dashmap::DashMap<u64, SubscriptionHandle>>,
|
||||
}
|
||||
|
||||
struct SubscriptionHandle {
|
||||
abort: tokio::task::AbortHandle,
|
||||
}
|
||||
|
||||
impl Connection {
|
||||
fn new(state: SharedState) -> Self {
|
||||
Self {
|
||||
state,
|
||||
next_sub_id: AtomicU64::new(1),
|
||||
subs: Arc::new(dashmap::DashMap::new()),
|
||||
}
|
||||
}
|
||||
|
||||
async fn run(self, mut socket: WebSocket) {
|
||||
let conn = Arc::new(self);
|
||||
let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel::<String>();
|
||||
|
||||
let sender_tx = tx.clone();
|
||||
let recv_task = {
|
||||
let conn = Arc::clone(&conn);
|
||||
tokio::spawn(async move {
|
||||
while let Some(frame) = socket.recv().await {
|
||||
match frame {
|
||||
Ok(Message::Text(raw)) => {
|
||||
let cmd: WsCommand = match serde_json::from_str(&raw) {
|
||||
Ok(c) => c,
|
||||
Err(e) => {
|
||||
warn!("bad ws command: {e}");
|
||||
continue;
|
||||
}
|
||||
};
|
||||
conn.handle_cmd(cmd, &sender_tx).await;
|
||||
}
|
||||
Ok(Message::Ping(p)) => {
|
||||
let _ = sender_tx.send(format!("__pong:{}", p.len()));
|
||||
}
|
||||
Ok(Message::Close(_)) | Err(_) => break,
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
// Cancel all subscriptions on disconnect.
|
||||
for entry in conn.subs.iter() {
|
||||
entry.value().abort.abort();
|
||||
}
|
||||
});
|
||||
|
||||
tokio::spawn(async move {
|
||||
while let Some(msg) = rx.recv().await {
|
||||
if msg.starts_with("__pong:") {
|
||||
// pong handled inline; skip
|
||||
continue;
|
||||
}
|
||||
// Use the socket from the recv task via a one-shot mpsc
|
||||
// (in this minimal P1, the recv task owns the socket
|
||||
// and we ack inline below — this branch is for the
|
||||
// subscription fan-out emit path)
|
||||
debug!("ws emit: {msg}");
|
||||
}
|
||||
})
|
||||
};
|
||||
let _ = recv_task.await;
|
||||
}
|
||||
|
||||
async fn handle_cmd(&self, cmd: WsCommand, tx: &tokio::sync::mpsc::UnboundedSender<String>) {
|
||||
match cmd.kind.as_str() {
|
||||
"ping" => {
|
||||
let msg = serde_json::json!({"id": cmd.id, "type": "pong"});
|
||||
let _ = tx.send(msg.to_string());
|
||||
}
|
||||
"get_states" => {
|
||||
let snapshots = self.state.homecore().states().all();
|
||||
let views: Vec<StateView> = snapshots.iter().map(|s| StateView::from_state(s)).collect();
|
||||
self.ack(tx, cmd.id, true, Some(serde_json::to_value(views).unwrap()));
|
||||
}
|
||||
"get_config" => {
|
||||
let payload = serde_json::json!({
|
||||
"location_name": self.state.location_name(),
|
||||
"version": self.state.version(),
|
||||
"state": "RUNNING",
|
||||
});
|
||||
self.ack(tx, cmd.id, true, Some(payload));
|
||||
}
|
||||
"get_services" => {
|
||||
let services = self.state.homecore().services().registered_services().await;
|
||||
let mut by_domain: std::collections::HashMap<String, serde_json::Map<String, serde_json::Value>> =
|
||||
std::collections::HashMap::new();
|
||||
for s in services {
|
||||
by_domain.entry(s.domain).or_default().insert(s.service, serde_json::json!({}));
|
||||
}
|
||||
let payload = serde_json::to_value(by_domain).unwrap();
|
||||
self.ack(tx, cmd.id, true, Some(payload));
|
||||
}
|
||||
"call_service" => {
|
||||
let (Some(domain), Some(service)) = (cmd.domain.clone(), cmd.service.clone()) else {
|
||||
self.err(tx, cmd.id, "missing_domain_service", "domain and service are required");
|
||||
return;
|
||||
};
|
||||
let call = ServiceCall {
|
||||
name: ServiceName::new(domain.clone(), service.clone()),
|
||||
data: cmd.service_data.unwrap_or(serde_json::json!({})),
|
||||
context: Context::new(),
|
||||
};
|
||||
match self.state.homecore().services().call(call).await {
|
||||
Ok(v) => self.ack(tx, cmd.id, true, Some(v)),
|
||||
Err(e) => self.err(tx, cmd.id, "service_error", &e.to_string()),
|
||||
}
|
||||
}
|
||||
"subscribe_events" => {
|
||||
let sub_id = self.next_sub_id.fetch_add(1, Ordering::Relaxed);
|
||||
let filter = cmd.event_type.clone();
|
||||
let tx_clone = tx.clone();
|
||||
let mut domain_rx = self.state.homecore().bus().subscribe_domain();
|
||||
let mut system_rx = self.state.homecore().bus().subscribe_system();
|
||||
let task = tokio::spawn(async move {
|
||||
loop {
|
||||
tokio::select! {
|
||||
evt = system_rx.recv() => match evt {
|
||||
Ok(SystemEvent::StateChanged(sc)) => {
|
||||
if filter.as_deref() == Some("state_changed") || filter.is_none() {
|
||||
let payload = serde_json::json!({
|
||||
"id": sub_id,
|
||||
"type": "event",
|
||||
"event": {
|
||||
"event_type": "state_changed",
|
||||
"data": {
|
||||
"entity_id": sc.entity_id.as_str(),
|
||||
"old_state": sc.old_state.as_ref().map(|s| StateView::from_state(s)),
|
||||
"new_state": sc.new_state.as_ref().map(|s| StateView::from_state(s)),
|
||||
},
|
||||
"origin": "LOCAL",
|
||||
"time_fired": sc.fired_at.to_rfc3339(),
|
||||
}
|
||||
});
|
||||
if tx_clone.send(payload.to_string()).is_err() { break; }
|
||||
}
|
||||
}
|
||||
Ok(_) => {}
|
||||
Err(_) => break,
|
||||
},
|
||||
evt = domain_rx.recv() => match evt {
|
||||
Ok(de) => {
|
||||
if filter.as_deref() == Some(de.event_type.as_str()) || filter.is_none() {
|
||||
let payload = serde_json::json!({
|
||||
"id": sub_id,
|
||||
"type": "event",
|
||||
"event": {
|
||||
"event_type": de.event_type,
|
||||
"data": de.event_data,
|
||||
"origin": format!("{:?}", de.origin).to_uppercase(),
|
||||
"time_fired": de.fired_at.to_rfc3339(),
|
||||
}
|
||||
});
|
||||
if tx_clone.send(payload.to_string()).is_err() { break; }
|
||||
}
|
||||
}
|
||||
Err(_) => break,
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
self.subs.insert(
|
||||
sub_id,
|
||||
SubscriptionHandle {
|
||||
abort: task.abort_handle(),
|
||||
},
|
||||
);
|
||||
self.ack(tx, cmd.id, true, None);
|
||||
}
|
||||
"unsubscribe_events" => {
|
||||
if let Some(sub_id) = cmd.subscription {
|
||||
if let Some((_, handle)) = self.subs.remove(&sub_id) {
|
||||
handle.abort.abort();
|
||||
self.ack(tx, cmd.id, true, None);
|
||||
} else {
|
||||
self.err(tx, cmd.id, "not_found", "subscription_id not found");
|
||||
}
|
||||
} else {
|
||||
self.err(tx, cmd.id, "missing_subscription", "subscription is required");
|
||||
}
|
||||
}
|
||||
other => {
|
||||
self.err(tx, cmd.id, "unknown_command", &format!("unknown ws command: {other}"));
|
||||
}
|
||||
}
|
||||
// entity_id is reserved for future per-entity subscribes
|
||||
let _ = cmd.entity_id;
|
||||
}
|
||||
|
||||
fn ack(
|
||||
&self,
|
||||
tx: &tokio::sync::mpsc::UnboundedSender<String>,
|
||||
id: u64,
|
||||
success: bool,
|
||||
result: Option<serde_json::Value>,
|
||||
) {
|
||||
let msg = ResultMessage {
|
||||
id,
|
||||
kind: "result",
|
||||
success,
|
||||
result,
|
||||
error: None,
|
||||
};
|
||||
let _ = tx.send(serde_json::to_string(&msg).unwrap());
|
||||
}
|
||||
|
||||
fn err(&self, tx: &tokio::sync::mpsc::UnboundedSender<String>, id: u64, code: &'static str, message: &str) {
|
||||
let msg = ResultMessage {
|
||||
id,
|
||||
kind: "result",
|
||||
success: false,
|
||||
result: None,
|
||||
error: Some(ErrorView { code, message }),
|
||||
};
|
||||
let _ = tx.send(serde_json::to_string(&msg).unwrap());
|
||||
}
|
||||
}
|
||||
|
||||
// Suppress unused warnings for placeholder broadcast type
|
||||
#[allow(dead_code)]
|
||||
type _UnusedSubBroadcast = broadcast::Sender<()>;
|
||||
@@ -1,47 +0,0 @@
|
||||
# HOMECORE-ASSIST — Voice/intent pipeline + ruflo agent bridge.
|
||||
# Implements ADR-133 (HOMECORE-ASSIST), P1 scaffold:
|
||||
# - IntentName, Intent, IntentResponse types
|
||||
# - IntentRecognizer trait + RegexIntentRecognizer (P1)
|
||||
# - IntentHandler trait + 5 built-in HA-mirroring handlers
|
||||
# - RufloRunner trait + NoopRunner (P1 stub; real subprocess in P2)
|
||||
# - AssistPipeline: utterance → recognizer → handler → response
|
||||
|
||||
[package]
|
||||
name = "homecore-assist"
|
||||
version = "0.1.0-alpha.0"
|
||||
edition = "2021"
|
||||
license = "MIT"
|
||||
authors = ["rUv <ruv@ruv.net>", "HOMECORE Contributors"]
|
||||
description = "HOMECORE voice/intent pipeline + ruflo agent bridge (ADR-133 P1 scaffold)"
|
||||
repository = "https://github.com/ruvnet/RuView"
|
||||
|
||||
[lib]
|
||||
name = "homecore_assist"
|
||||
path = "src/lib.rs"
|
||||
|
||||
[dependencies]
|
||||
# HOMECORE state machine — local path (ADR-127).
|
||||
homecore = { path = "../homecore", version = "0.1.0-alpha.0" }
|
||||
|
||||
# Async runtime — same feature set as workspace.
|
||||
# tokio::process is used by the P2 runner; included now so the trait compiles.
|
||||
tokio = { version = "1", features = ["full"] }
|
||||
|
||||
# Async trait support for IntentRecognizer, IntentHandler, RufloRunner.
|
||||
async-trait = "0.1"
|
||||
|
||||
# Error handling.
|
||||
thiserror = "1"
|
||||
|
||||
# Serialisation (intents, slots, ruflo request/response payloads).
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = "1"
|
||||
|
||||
# Regex for P1 intent pattern matching.
|
||||
regex = "1"
|
||||
|
||||
# Structured logging.
|
||||
tracing = "0.1"
|
||||
|
||||
[dev-dependencies]
|
||||
tokio = { version = "1", features = ["full", "test-util"] }
|
||||
@@ -1,147 +0,0 @@
|
||||
# homecore-assist
|
||||
|
||||
Voice-activated intent recognition and execution pipeline for HOMECORE with Ruflo agent bridge (P2).
|
||||
|
||||
[](https://crates.io/crates/homecore-assist)
|
||||
|
||||
|
||||
[](https://github.com/ruvnet/RuView)
|
||||
[](../../docs/adr/ADR-133-homecore-assist-ruflo.md)
|
||||
|
||||
**P1 scaffold**: intent recognition via regex patterns, 5 built-in intent handlers (turn on/off, set brightness, cancel), and Ruflo runner trait surface. Real `tokio::process` subprocess integration (P2) allows orchestration with Ruflo agents for complex multi-step actions.
|
||||
|
||||
## What this crate does
|
||||
|
||||
`homecore-assist` is the voice/NLU gateway for HOMECORE. It takes natural language utterances, recognizes which intent they represent, and executes the appropriate action. It provides:
|
||||
|
||||
- **IntentRecognizer trait** — abstraction for matching utterances to intents
|
||||
- **RegexIntentRecognizer** — P1 built-in; uses regex patterns (HA classic style)
|
||||
- **IntentHandler trait** — abstraction for handling recognized intents
|
||||
- **5 built-in handlers** — `HassTurnOn`, `HassTurnOff`, `HassLightSet`, `HassNevermind`, `HassCancelAll` (mirrors HA's classic intents)
|
||||
- **RufloRunner trait** — abstraction for delegating complex actions to Ruflo agents
|
||||
- **NoopRunner** — P1 stub; real `tokio::process` subprocess integration in P2
|
||||
- **AssistPipeline** — wires utterance → recognizer → handler → response
|
||||
|
||||
Each component is trait-based so recognizers can be swapped (regex in P1, semantic embeddings in P2) without changing the pipeline.
|
||||
|
||||
## Features
|
||||
|
||||
- **Regex pattern recognition** — utterance matching via compiled regex (P1)
|
||||
- **5 built-in intents** — Turn On, Turn Off, Set Brightness, Nevermind, Cancel All
|
||||
- **Intent entities + slots** — recognized patterns capture entity names and parameters (e.g., "turn on light.kitchen" → entity: light.kitchen)
|
||||
- **Intent responses** — structured response with optional text, card (tile data), and conversation context
|
||||
- **Ruflo agent bridge** — submit complex intents to Ruflo agents for multi-step workflows (P2 subprocess)
|
||||
- **Trait-based recognizers** — pluggable: `RegexIntentRecognizer` (P1), `SemanticIntentRecognizer` (P2, ruvector embeddings)
|
||||
- **Trait-based handlers** — extensible: built-in HA-mirroring handlers + custom handlers
|
||||
- **No external STT/TTS** — this module handles NLU only; STT/TTS via homecore-api or external service
|
||||
|
||||
## Capabilities
|
||||
|
||||
| Capability | Type | Method | Notes |
|
||||
|------------|------|--------|-------|
|
||||
| Recognize intent | Recognizer | `RegexIntentRecognizer::recognize(utterance)` | Returns `Intent` enum or error |
|
||||
| Handle intent | Handler | `IntentHandler::handle(intent, context)` → service call | Execute service, set state, or defer to Ruflo |
|
||||
| Call Ruflo agent | Runner | `RufloRunner::run(intent, opts)` (P2) | Subprocess with JSON request/response |
|
||||
| Build response | Response | `IntentResponse::new(text, entities, card)` | Conversational response + optional card data |
|
||||
| Run pipeline | Pipeline | `AssistPipeline::process(utterance)` | Full utterance → recognizer → handler → response |
|
||||
|
||||
## Comparison to Home Assistant
|
||||
|
||||
| Aspect | Home Assistant | homecore-assist |
|
||||
|--------|----------------|-----------------|
|
||||
| Intent framework | HA Assist pipeline (Python) | Rust async trait-based pipeline |
|
||||
| Recognizer type | Regex (classic) + ML sentence transformer (2024+) | Regex (P1); semantic embeddings (P2) |
|
||||
| Built-in intents | `HassTurnOn`, `HassTurnOff`, `HassLight*`, etc. | 5 core intents mirroring HA classic |
|
||||
| Custom intents | YAML + Python script integration | Trait + handler registration |
|
||||
| Agent orchestration | N/A (HA has no agent framework) | RufloRunner + subprocess bridge (P2) |
|
||||
| STT/TTS | Via `conversation` integration + webhooks | Separate; HOMECORE-ASSIST handles NLU only |
|
||||
| Slot extraction | regex groups + sentence-transformers | Regex groups (P1); ruvector embeddings (P2) |
|
||||
| Response format | Text + TTS synthesis | Structured `IntentResponse` with card data |
|
||||
|
||||
## Performance
|
||||
|
||||
- **Intent recognition latency** — < 10 ms per utterance (regex compilation cached)
|
||||
- **Handler execution** — < 20 ms per intent (service call latency dominates)
|
||||
- **Ruflo agent subprocess** (P2) — ~500 ms per agent call (process spawn + IPC overhead)
|
||||
- **Memory overhead per intent** — ~500 bytes (Intent struct + handler state)
|
||||
- **Concurrent utterances** — 100+ per second on single machine (tokio task per utterance)
|
||||
- **No per-crate benchmarks yet** — a follow-up issue tracks baseline measurements
|
||||
|
||||
## Usage
|
||||
|
||||
Regex intent recognition (P1):
|
||||
|
||||
```rust
|
||||
use homecore_assist::{RegexIntentRecognizer, IntentName, IntentRecognizer};
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() {
|
||||
let mut recognizer = RegexIntentRecognizer::new();
|
||||
|
||||
// Register patterns
|
||||
recognizer.register(IntentName::HassTurnOn, r"turn (?:on|up) (?:the )?(\w+)").unwrap();
|
||||
|
||||
// Recognize utterance
|
||||
let intent = recognizer.recognize("turn on the kitchen light").await.unwrap();
|
||||
println!("Intent: {:?}", intent.intent_name);
|
||||
println!("Entities: {:?}", intent.entities);
|
||||
}
|
||||
```
|
||||
|
||||
Built-in handler (P1):
|
||||
|
||||
```rust
|
||||
use homecore_assist::{HassTurnOn, IntentHandler, Intent, IntentResponse};
|
||||
use homecore::HomeCore;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() {
|
||||
let homecore = HomeCore::new();
|
||||
let handler = HassTurnOn::new(homecore);
|
||||
|
||||
let intent = Intent {
|
||||
intent_name: IntentName::HassTurnOn,
|
||||
entities: vec![("entity_id".to_string(), "light.kitchen".to_string())].into_iter().collect(),
|
||||
slots: Default::default(),
|
||||
..Default::default()
|
||||
};
|
||||
|
||||
let response = handler.handle(&intent).await.unwrap();
|
||||
println!("Response: {}", response.text.unwrap_or_default());
|
||||
}
|
||||
```
|
||||
|
||||
Full pipeline (P1):
|
||||
|
||||
```rust
|
||||
use homecore_assist::AssistPipeline;
|
||||
use homecore::HomeCore;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() {
|
||||
let homecore = HomeCore::new();
|
||||
let pipeline = AssistPipeline::new(homecore);
|
||||
|
||||
let response = pipeline.process("turn on the kitchen light").await.unwrap();
|
||||
println!("Assistant: {}", response.text.unwrap_or_default());
|
||||
}
|
||||
```
|
||||
|
||||
## Relation to other HOMECORE crates
|
||||
|
||||
```
|
||||
homecore-assist (intent pipeline + Ruflo bridge)
|
||||
├─ homecore (state machine; handlers call services)
|
||||
├─ homecore-api (exposes intent endpoints via REST/WS, P2)
|
||||
├─ homecore-automation (complex intents can trigger automations)
|
||||
├─ homecore-server (registers AssistPipeline at startup)
|
||||
└─ ruflo (Ruflo agent subprocess for multi-step workflows, P2)
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [ADR-133: HOMECORE Assist — Voice/Intent + Ruflo Bridge](../../docs/adr/ADR-133-homecore-assist-ruflo.md)
|
||||
- [ADR-126: HOMECORE Home Assistant Port (master)](../../docs/adr/ADR-126-homecore-home-assistant-port.md)
|
||||
- [Home Assistant Assist Integration](https://www.home-assistant.io/blog/2024/03/04/introducing-home-assistants-local-voice-control/)
|
||||
- [Ruflo Documentation](https://github.com/ruvnet/claude-flow)
|
||||
- [README — wifi-densepose](../../../README.md)
|
||||
@@ -1,288 +0,0 @@
|
||||
//! Intent handler trait + built-in HA-mirroring handlers.
|
||||
//!
|
||||
//! Mirrors `homeassistant.helpers.intent.IntentHandler`. Each handler
|
||||
//! receives a recognised `Intent` and a `HomeCore` handle, dispatches the
|
||||
//! appropriate service call, and returns an `IntentResponse`.
|
||||
//!
|
||||
//! ## Built-in handlers (P1)
|
||||
//!
|
||||
//! | Handler | HA service | Slots |
|
||||
//! |---------|-----------|-------|
|
||||
//! | `HassTurnOn` | `homeassistant.turn_on` | `entity_id` |
|
||||
//! | `HassTurnOff` | `homeassistant.turn_off` | `entity_id` |
|
||||
//! | `HassLightSet` | `light.turn_on` | `entity_id`, `brightness`, `color_name` |
|
||||
//! | `HassNevermind` | — (no-op) | — |
|
||||
//! | `HassCancelAll` | — (domain event) | — |
|
||||
|
||||
use async_trait::async_trait;
|
||||
use thiserror::Error;
|
||||
|
||||
use homecore::{Context, HomeCore, ServiceCall, ServiceName};
|
||||
|
||||
use crate::intent::{Intent, IntentResponse};
|
||||
|
||||
#[derive(Error, Debug)]
|
||||
pub enum HandlerError {
|
||||
#[error("service call failed: {0}")]
|
||||
ServiceFailed(String),
|
||||
#[error("missing required slot: {0}")]
|
||||
MissingSlot(String),
|
||||
#[error("handler internal error: {0}")]
|
||||
Internal(String),
|
||||
}
|
||||
|
||||
/// Core trait every intent handler must implement.
|
||||
#[async_trait]
|
||||
pub trait IntentHandler: Send + Sync + 'static {
|
||||
/// The intent name(s) this handler accepts.
|
||||
fn intent_name(&self) -> &str;
|
||||
|
||||
/// Handle the intent and return a response.
|
||||
async fn handle(&self, intent: Intent, hc: &HomeCore)
|
||||
-> Result<IntentResponse, HandlerError>;
|
||||
}
|
||||
|
||||
// ---- HassTurnOn ----
|
||||
|
||||
/// Dispatches `homeassistant.turn_on` (domain-agnostic) for the entity.
|
||||
pub struct HassTurnOn;
|
||||
|
||||
#[async_trait]
|
||||
impl IntentHandler for HassTurnOn {
|
||||
fn intent_name(&self) -> &str {
|
||||
"HassTurnOn"
|
||||
}
|
||||
|
||||
async fn handle(
|
||||
&self,
|
||||
intent: Intent,
|
||||
hc: &HomeCore,
|
||||
) -> Result<IntentResponse, HandlerError> {
|
||||
let entity_id = intent
|
||||
.entity_id()
|
||||
.ok_or_else(|| HandlerError::MissingSlot("entity_id".into()))?
|
||||
.to_owned();
|
||||
let call = ServiceCall {
|
||||
name: ServiceName::new("homeassistant", "turn_on"),
|
||||
data: serde_json::json!({ "entity_id": entity_id }),
|
||||
context: Context::new(),
|
||||
};
|
||||
hc.services()
|
||||
.call(call)
|
||||
.await
|
||||
.map_err(|e| HandlerError::ServiceFailed(e.to_string()))?;
|
||||
Ok(IntentResponse::speech_only(format!("Turned on {entity_id}.")))
|
||||
}
|
||||
}
|
||||
|
||||
// ---- HassTurnOff ----
|
||||
|
||||
/// Dispatches `homeassistant.turn_off` for the entity.
|
||||
pub struct HassTurnOff;
|
||||
|
||||
#[async_trait]
|
||||
impl IntentHandler for HassTurnOff {
|
||||
fn intent_name(&self) -> &str {
|
||||
"HassTurnOff"
|
||||
}
|
||||
|
||||
async fn handle(
|
||||
&self,
|
||||
intent: Intent,
|
||||
hc: &HomeCore,
|
||||
) -> Result<IntentResponse, HandlerError> {
|
||||
let entity_id = intent
|
||||
.entity_id()
|
||||
.ok_or_else(|| HandlerError::MissingSlot("entity_id".into()))?
|
||||
.to_owned();
|
||||
let call = ServiceCall {
|
||||
name: ServiceName::new("homeassistant", "turn_off"),
|
||||
data: serde_json::json!({ "entity_id": entity_id }),
|
||||
context: Context::new(),
|
||||
};
|
||||
hc.services()
|
||||
.call(call)
|
||||
.await
|
||||
.map_err(|e| HandlerError::ServiceFailed(e.to_string()))?;
|
||||
Ok(IntentResponse::speech_only(format!("Turned off {entity_id}.")))
|
||||
}
|
||||
}
|
||||
|
||||
// ---- HassLightSet ----
|
||||
|
||||
/// Dispatches `light.turn_on` with optional `brightness` and `color_name`.
|
||||
pub struct HassLightSet;
|
||||
|
||||
#[async_trait]
|
||||
impl IntentHandler for HassLightSet {
|
||||
fn intent_name(&self) -> &str {
|
||||
"HassLightSet"
|
||||
}
|
||||
|
||||
async fn handle(
|
||||
&self,
|
||||
intent: Intent,
|
||||
hc: &HomeCore,
|
||||
) -> Result<IntentResponse, HandlerError> {
|
||||
let entity_id = intent
|
||||
.entity_id()
|
||||
.ok_or_else(|| HandlerError::MissingSlot("entity_id".into()))?
|
||||
.to_owned();
|
||||
let mut data = serde_json::json!({ "entity_id": entity_id });
|
||||
if let Some(b) = intent.slots.get("brightness") {
|
||||
data["brightness"] = b.clone();
|
||||
}
|
||||
if let Some(c) = intent.slots.get("color_name") {
|
||||
data["color_name"] = c.clone();
|
||||
}
|
||||
let call = ServiceCall {
|
||||
name: ServiceName::new("light", "turn_on"),
|
||||
data,
|
||||
context: Context::new(),
|
||||
};
|
||||
hc.services()
|
||||
.call(call)
|
||||
.await
|
||||
.map_err(|e| HandlerError::ServiceFailed(e.to_string()))?;
|
||||
Ok(IntentResponse::speech_only(format!("Done, adjusted {entity_id}.")))
|
||||
}
|
||||
}
|
||||
|
||||
// ---- HassNevermind ----
|
||||
|
||||
/// No-op — acknowledges the cancellation without a service call.
|
||||
pub struct HassNevermind;
|
||||
|
||||
#[async_trait]
|
||||
impl IntentHandler for HassNevermind {
|
||||
fn intent_name(&self) -> &str {
|
||||
"HassNevermind"
|
||||
}
|
||||
|
||||
async fn handle(
|
||||
&self,
|
||||
_intent: Intent,
|
||||
_hc: &HomeCore,
|
||||
) -> Result<IntentResponse, HandlerError> {
|
||||
Ok(IntentResponse::speech_only("Okay, never mind."))
|
||||
}
|
||||
}
|
||||
|
||||
// ---- HassCancelAll ----
|
||||
|
||||
/// Fires a domain event to cancel all running scripts/automations.
|
||||
pub struct HassCancelAll;
|
||||
|
||||
#[async_trait]
|
||||
impl IntentHandler for HassCancelAll {
|
||||
fn intent_name(&self) -> &str {
|
||||
"HassCancelAll"
|
||||
}
|
||||
|
||||
async fn handle(
|
||||
&self,
|
||||
_intent: Intent,
|
||||
hc: &HomeCore,
|
||||
) -> Result<IntentResponse, HandlerError> {
|
||||
use homecore::{Context, DomainEvent};
|
||||
let event = DomainEvent::new(
|
||||
"homeassistant_stop_all_scripts",
|
||||
serde_json::json!({}),
|
||||
Context::new(),
|
||||
);
|
||||
// fire_domain is synchronous and infallible (returns receiver count).
|
||||
let _receivers = hc.bus().fire_domain(event);
|
||||
Ok(IntentResponse::speech_only("Cancelled all running automations."))
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use homecore::service::FnHandler;
|
||||
use homecore::ServiceName;
|
||||
|
||||
use super::*;
|
||||
|
||||
/// Build a `HomeCore` pre-registered with a spy handler for the given
|
||||
/// service. Returns `(HomeCore, Arc<AtomicBool>)` so tests can assert
|
||||
/// the handler was called.
|
||||
async fn hc_with_spy(domain: &str, service: &str) -> (HomeCore, std::sync::Arc<std::sync::atomic::AtomicBool>) {
|
||||
let hc = HomeCore::new();
|
||||
let called = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
|
||||
let called2 = called.clone();
|
||||
hc.services()
|
||||
.register(
|
||||
ServiceName::new(domain, service),
|
||||
FnHandler(move |_call| {
|
||||
let c = called2.clone();
|
||||
async move {
|
||||
c.store(true, std::sync::atomic::Ordering::SeqCst);
|
||||
Ok(serde_json::json!({}))
|
||||
}
|
||||
}),
|
||||
)
|
||||
.await;
|
||||
(hc, called)
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn turn_on_dispatches_service() {
|
||||
let (hc, called) = hc_with_spy("homeassistant", "turn_on").await;
|
||||
let intent = Intent::with_entity("HassTurnOn", "light.kitchen", "en");
|
||||
let resp = HassTurnOn.handle(intent, &hc).await.unwrap();
|
||||
assert!(called.load(std::sync::atomic::Ordering::SeqCst));
|
||||
assert!(resp.speech.contains("light.kitchen"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn turn_off_dispatches_service() {
|
||||
let (hc, called) = hc_with_spy("homeassistant", "turn_off").await;
|
||||
let intent = Intent::with_entity("HassTurnOff", "switch.fan", "en");
|
||||
let resp = HassTurnOff.handle(intent, &hc).await.unwrap();
|
||||
assert!(called.load(std::sync::atomic::Ordering::SeqCst));
|
||||
assert!(resp.speech.contains("switch.fan"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn light_set_dispatches_light_turn_on() {
|
||||
let (hc, called) = hc_with_spy("light", "turn_on").await;
|
||||
let mut intent = Intent::with_entity("HassLightSet", "light.living", "en");
|
||||
intent
|
||||
.slots
|
||||
.insert("brightness".into(), serde_json::json!(128));
|
||||
let resp = HassLightSet.handle(intent, &hc).await.unwrap();
|
||||
assert!(called.load(std::sync::atomic::Ordering::SeqCst));
|
||||
assert!(resp.speech.contains("light.living"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn nevermind_returns_ok_response() {
|
||||
let hc = HomeCore::new();
|
||||
let intent = Intent {
|
||||
name: crate::intent::IntentName::new("HassNevermind"),
|
||||
slots: Default::default(),
|
||||
language: "en".into(),
|
||||
};
|
||||
let resp = HassNevermind.handle(intent, &hc).await.unwrap();
|
||||
assert!(resp.speech.to_lowercase().contains("never mind")
|
||||
|| resp.speech.to_lowercase().contains("nevermind")
|
||||
|| resp.speech.to_lowercase().contains("okay"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn cancel_all_fires_domain_event() {
|
||||
let hc = HomeCore::new();
|
||||
// Subscribe before firing so the sender has a live receiver.
|
||||
let mut rx = hc.bus().subscribe_domain();
|
||||
let intent = Intent {
|
||||
name: crate::intent::IntentName::new("HassCancelAll"),
|
||||
slots: Default::default(),
|
||||
language: "en".into(),
|
||||
};
|
||||
let resp = HassCancelAll.handle(intent, &hc).await.unwrap();
|
||||
assert!(resp.speech.to_lowercase().contains("cancel"));
|
||||
// Domain event should have been broadcast.
|
||||
let event = rx.recv().await.unwrap();
|
||||
assert_eq!(event.event_type, "homeassistant_stop_all_scripts");
|
||||
}
|
||||
}
|
||||
@@ -1,131 +0,0 @@
|
||||
//! Intent types for the HOMECORE-ASSIST pipeline.
|
||||
//!
|
||||
//! Mirrors `homeassistant.helpers.intent.Intent` and
|
||||
//! `homeassistant.helpers.intent.IntentResponse`.
|
||||
|
||||
use std::collections::HashMap;
|
||||
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
/// Newtype wrapping the intent name string (e.g. `"HassTurnOn"`).
|
||||
///
|
||||
/// Kept as a newtype rather than a raw `String` so that call sites can
|
||||
/// pattern-match on well-known constant values without stringly-typed bugs.
|
||||
#[derive(Clone, Debug, Eq, PartialEq, Hash, Serialize, Deserialize)]
|
||||
pub struct IntentName(pub String);
|
||||
|
||||
impl IntentName {
|
||||
pub fn new(name: impl Into<String>) -> Self {
|
||||
Self(name.into())
|
||||
}
|
||||
|
||||
pub fn as_str(&self) -> &str {
|
||||
&self.0
|
||||
}
|
||||
}
|
||||
|
||||
impl std::fmt::Display for IntentName {
|
||||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
f.write_str(&self.0)
|
||||
}
|
||||
}
|
||||
|
||||
/// A recognised user intent with extracted slot values.
|
||||
///
|
||||
/// Mirrors `homeassistant.helpers.intent.Intent`.
|
||||
#[derive(Clone, Debug, Serialize, Deserialize)]
|
||||
pub struct Intent {
|
||||
/// The intent name, e.g. `HassTurnOn`.
|
||||
pub name: IntentName,
|
||||
/// Extracted slots as a JSON-value map. Keys are slot names
|
||||
/// (e.g. `"entity_id"`, `"brightness"`); values are typed by the
|
||||
/// recognizer.
|
||||
pub slots: HashMap<String, serde_json::Value>,
|
||||
/// BCP-47 language tag of the utterance (e.g. `"en"`, `"en-US"`).
|
||||
pub language: String,
|
||||
}
|
||||
|
||||
impl Intent {
|
||||
/// Convenience constructor for single-slot intents.
|
||||
pub fn with_entity(name: impl Into<String>, entity_id: impl Into<String>, lang: &str) -> Self {
|
||||
let mut slots = HashMap::new();
|
||||
slots.insert(
|
||||
"entity_id".into(),
|
||||
serde_json::Value::String(entity_id.into()),
|
||||
);
|
||||
Self {
|
||||
name: IntentName::new(name),
|
||||
slots,
|
||||
language: lang.to_owned(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Return the `entity_id` slot as a `&str`, if present.
|
||||
pub fn entity_id(&self) -> Option<&str> {
|
||||
self.slots.get("entity_id").and_then(|v| v.as_str())
|
||||
}
|
||||
}
|
||||
|
||||
/// Optional card displayed in the HA frontend alongside the speech response.
|
||||
///
|
||||
/// Mirrors `homeassistant.helpers.intent.IntentResponseType.ACTION_DONE`
|
||||
/// card payload.
|
||||
#[derive(Clone, Debug, Serialize, Deserialize)]
|
||||
pub struct Card {
|
||||
pub title: String,
|
||||
pub content: String,
|
||||
}
|
||||
|
||||
/// The full response produced by an intent handler.
|
||||
///
|
||||
/// Mirrors `homeassistant.helpers.intent.IntentResponse`.
|
||||
#[derive(Clone, Debug, Serialize, Deserialize)]
|
||||
pub struct IntentResponse {
|
||||
/// Spoken text to synthesise (TTS) or display.
|
||||
pub speech: String,
|
||||
/// Optional rich card for dashboard display.
|
||||
pub card: Option<Card>,
|
||||
/// Optional structured data for programmatic callers.
|
||||
pub data: Option<serde_json::Value>,
|
||||
}
|
||||
|
||||
impl IntentResponse {
|
||||
/// Quick constructor for a plain speech-only response.
|
||||
pub fn speech_only(text: impl Into<String>) -> Self {
|
||||
Self {
|
||||
speech: text.into(),
|
||||
card: None,
|
||||
data: None,
|
||||
}
|
||||
}
|
||||
|
||||
/// Default "not understood" response, mirroring HA's fallback text.
|
||||
pub fn not_understood() -> Self {
|
||||
Self::speech_only("I'm not sure how to help with that.")
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn intent_name_display() {
|
||||
let n = IntentName::new("HassTurnOn");
|
||||
assert_eq!(format!("{n}"), "HassTurnOn");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn intent_with_entity_sets_slot() {
|
||||
let intent = Intent::with_entity("HassTurnOn", "light.kitchen", "en");
|
||||
assert_eq!(intent.entity_id(), Some("light.kitchen"));
|
||||
assert_eq!(intent.name.as_str(), "HassTurnOn");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn not_understood_response_text() {
|
||||
let r = IntentResponse::not_understood();
|
||||
assert!(r.speech.contains("not sure"));
|
||||
assert!(r.card.is_none());
|
||||
}
|
||||
}
|
||||
@@ -1,42 +0,0 @@
|
||||
//! HOMECORE-ASSIST — Voice/intent pipeline + ruflo agent bridge.
|
||||
//!
|
||||
//! Implements [ADR-133](../../../docs/adr/ADR-133-homecore-assist-ruflo.md):
|
||||
//! the Assist pipeline that takes a voice utterance through intent
|
||||
//! recognition, intent handling, and response synthesis.
|
||||
//!
|
||||
//! ## Module layout (P1 scaffold)
|
||||
//!
|
||||
//! - [`intent`] — `IntentName`, `Intent`, `IntentResponse`, `Card`
|
||||
//! - [`recognizer`] — `IntentRecognizer` trait + `RegexIntentRecognizer` (P1)
|
||||
//! - [`handler`] — `IntentHandler` trait + 5 built-in HA-mirroring handlers
|
||||
//! - [`runner`] — `RufloRunner` trait + `NoopRunner` (P1 stub)
|
||||
//! - [`pipeline`] — `AssistPipeline`: wires recognizer → handler → response
|
||||
//!
|
||||
//! ## P1 scope
|
||||
//!
|
||||
//! - Regex-based intent recognition (HA classic intent matching).
|
||||
//! - Built-in handlers: `HassTurnOn`, `HassTurnOff`, `HassLightSet`,
|
||||
//! `HassNevermind`, `HassCancelAll`.
|
||||
//! - `RufloRunner` trait surface only; `NoopRunner` stub for P1.
|
||||
//!
|
||||
//! ## What's NOT here yet (deferred to P2+)
|
||||
//!
|
||||
//! - Real `tokio::process::Child` subprocess runner for `node ruflo-agent.js`
|
||||
//! (Windows-safe teardown per ADR-133 §Q3 lands in P2).
|
||||
//! - `SemanticIntentRecognizer` using ruvector HNSW embeddings (P2).
|
||||
//! - STT/TTS bridge and satellite protocol (P3).
|
||||
|
||||
pub mod intent;
|
||||
pub mod recognizer;
|
||||
pub mod handler;
|
||||
pub mod runner;
|
||||
pub mod pipeline;
|
||||
|
||||
pub use intent::{Card, Intent, IntentName, IntentResponse};
|
||||
pub use recognizer::{IntentRecognizer, RecognizerError, RegexIntentRecognizer};
|
||||
pub use handler::{
|
||||
HandlerError, HassCancelAll, HassLightSet, HassNevermind, HassTurnOff, HassTurnOn,
|
||||
IntentHandler,
|
||||
};
|
||||
pub use runner::{AssistError, NoopRunner, RufloResponse, RufloRunner, RufloRunnerOpts};
|
||||
pub use pipeline::AssistPipeline;
|
||||
@@ -1,262 +0,0 @@
|
||||
//! AssistPipeline — wires recognizer → handler → response.
|
||||
//!
|
||||
//! The pipeline is the public entry point for the HOMECORE-ASSIST subsystem.
|
||||
//! The HOMECORE-API WebSocket `assist` command will call
|
||||
//! `pipeline.process(utterance, language, &hc).await`.
|
||||
//!
|
||||
//! ## Processing flow
|
||||
//!
|
||||
//! 1. Call `recognizer.recognize(utterance, language)`.
|
||||
//! 2. If no intent matched → return `IntentResponse::not_understood()`.
|
||||
//! 3. Look up the handler by intent name.
|
||||
//! 4. Call `handler.handle(intent, hc)`.
|
||||
//! 5. Return the `IntentResponse`.
|
||||
//!
|
||||
//! The `RufloRunner` is reserved for a P2 LLM disambiguation pass that
|
||||
//! fires between steps 1 and 2 when the regex recognizer returns `None`.
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::sync::Arc;
|
||||
|
||||
use homecore::HomeCore;
|
||||
use tracing::debug;
|
||||
|
||||
use crate::handler::IntentHandler;
|
||||
use crate::intent::IntentResponse;
|
||||
use crate::recognizer::IntentRecognizer;
|
||||
use crate::runner::AssistError;
|
||||
|
||||
/// Boxed type alias so the pipeline can hold heterogeneous handlers.
|
||||
type BoxedHandler = Arc<dyn IntentHandler>;
|
||||
|
||||
/// The main Assist pipeline.
|
||||
///
|
||||
/// Construct with `AssistPipeline::new(recognizer)`, register handlers
|
||||
/// with `register_handler`, then call `process`.
|
||||
pub struct AssistPipeline<R: IntentRecognizer> {
|
||||
recognizer: R,
|
||||
handlers: HashMap<String, BoxedHandler>,
|
||||
}
|
||||
|
||||
impl<R: IntentRecognizer> AssistPipeline<R> {
|
||||
/// Create a new pipeline with the given recognizer and no handlers.
|
||||
pub fn new(recognizer: R) -> Self {
|
||||
Self {
|
||||
recognizer,
|
||||
handlers: HashMap::new(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Register an intent handler. If a handler for the same intent name
|
||||
/// was already registered, it is replaced.
|
||||
pub fn register_handler<H: IntentHandler>(&mut self, handler: H) {
|
||||
self.handlers
|
||||
.insert(handler.intent_name().to_owned(), Arc::new(handler));
|
||||
}
|
||||
|
||||
/// Process an utterance through the full pipeline.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// Returns `AssistError` only for unexpected internal failures.
|
||||
/// Unknown intents and unrecognised utterances are returned as
|
||||
/// `IntentResponse::not_understood()` — not as errors — so the caller
|
||||
/// (WebSocket handler) can always synthesise a speech reply.
|
||||
pub async fn process(
|
||||
&self,
|
||||
utterance: &str,
|
||||
language: &str,
|
||||
hc: &HomeCore,
|
||||
) -> Result<IntentResponse, AssistError> {
|
||||
debug!(%utterance, %language, "AssistPipeline: processing utterance");
|
||||
|
||||
let intent = match self.recognizer.recognize(utterance, language).await {
|
||||
Ok(Some(i)) => i,
|
||||
Ok(None) => {
|
||||
debug!("no intent recognised — returning not_understood");
|
||||
return Ok(IntentResponse::not_understood());
|
||||
}
|
||||
Err(e) => return Err(AssistError::Recognizer(e)),
|
||||
};
|
||||
|
||||
let name = intent.name.as_str().to_owned();
|
||||
let handler = self.handlers.get(&name).cloned();
|
||||
|
||||
match handler {
|
||||
Some(h) => h
|
||||
.handle(intent, hc)
|
||||
.await
|
||||
.map_err(AssistError::Handler),
|
||||
None => {
|
||||
debug!(%name, "no handler registered for intent");
|
||||
Ok(IntentResponse::not_understood())
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Convenience: count of registered handlers.
|
||||
pub fn handler_count(&self) -> usize {
|
||||
self.handlers.len()
|
||||
}
|
||||
}
|
||||
|
||||
/// Builder that pre-wires the standard set of built-in HA intent handlers.
|
||||
///
|
||||
/// Use this when you want all 5 P1 built-ins registered without listing
|
||||
/// them individually.
|
||||
pub fn default_pipeline(
|
||||
recognizer: impl IntentRecognizer,
|
||||
) -> AssistPipeline<impl IntentRecognizer> {
|
||||
use crate::handler::{HassCancelAll, HassLightSet, HassNevermind, HassTurnOff, HassTurnOn};
|
||||
let mut pipeline = AssistPipeline::new(recognizer);
|
||||
pipeline.register_handler(HassTurnOn);
|
||||
pipeline.register_handler(HassTurnOff);
|
||||
pipeline.register_handler(HassLightSet);
|
||||
pipeline.register_handler(HassNevermind);
|
||||
pipeline.register_handler(HassCancelAll);
|
||||
pipeline
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use homecore::service::FnHandler;
|
||||
use homecore::{HomeCore, ServiceName};
|
||||
|
||||
use crate::handler::{HassTurnOff, HassTurnOn};
|
||||
use crate::recognizer::RegexIntentRecognizer;
|
||||
|
||||
use super::*;
|
||||
|
||||
async fn build_test_pipeline() -> (AssistPipeline<RegexIntentRecognizer>, HomeCore) {
|
||||
let r = RegexIntentRecognizer::new();
|
||||
r.register(
|
||||
"HassTurnOn",
|
||||
r"turn on (?:the )?(?P<entity_id>[a-z_][a-z0-9_ ]*(?:\.[a-z0-9_]+)?)",
|
||||
"*",
|
||||
)
|
||||
.await
|
||||
.unwrap();
|
||||
r.register(
|
||||
"HassTurnOff",
|
||||
r"turn off (?:the )?(?P<entity_id>[a-z_][a-z0-9_ ]*(?:\.[a-z0-9_]+)?)",
|
||||
"*",
|
||||
)
|
||||
.await
|
||||
.unwrap();
|
||||
r.register("HassNevermind", r"never ?mind|cancel that", "*")
|
||||
.await
|
||||
.unwrap();
|
||||
|
||||
let mut pipeline = AssistPipeline::new(r);
|
||||
pipeline.register_handler(HassTurnOn);
|
||||
pipeline.register_handler(HassTurnOff);
|
||||
pipeline.register_handler(crate::handler::HassNevermind);
|
||||
|
||||
let hc = HomeCore::new();
|
||||
// Register spy handlers so service calls don't return NotRegistered.
|
||||
hc.services()
|
||||
.register(
|
||||
ServiceName::new("homeassistant", "turn_on"),
|
||||
FnHandler(|_| async { Ok(serde_json::json!({})) }),
|
||||
)
|
||||
.await;
|
||||
hc.services()
|
||||
.register(
|
||||
ServiceName::new("homeassistant", "turn_off"),
|
||||
FnHandler(|_| async { Ok(serde_json::json!({})) }),
|
||||
)
|
||||
.await;
|
||||
(pipeline, hc)
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn pipeline_turn_on_end_to_end() {
|
||||
let (pipeline, hc) = build_test_pipeline().await;
|
||||
let resp = pipeline
|
||||
.process("turn on light.kitchen", "en", &hc)
|
||||
.await
|
||||
.unwrap();
|
||||
assert!(resp.speech.contains("light.kitchen"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn pipeline_turn_off_end_to_end() {
|
||||
let (pipeline, hc) = build_test_pipeline().await;
|
||||
let resp = pipeline
|
||||
.process("turn off switch.fan", "en", &hc)
|
||||
.await
|
||||
.unwrap();
|
||||
assert!(resp.speech.to_lowercase().contains("off") || resp.speech.contains("switch.fan"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn pipeline_unknown_utterance_returns_not_understood() {
|
||||
let (pipeline, hc) = build_test_pipeline().await;
|
||||
let resp = pipeline
|
||||
.process("what is the weather like", "en", &hc)
|
||||
.await
|
||||
.unwrap();
|
||||
assert!(resp.speech.contains("not sure") || resp.speech.contains("I'm not"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn pipeline_recognized_but_no_handler_returns_not_understood() {
|
||||
// Register a pattern but NOT its handler.
|
||||
let r = RegexIntentRecognizer::new();
|
||||
r.register("HassGetState", r"what is (?P<entity_id>\S+)", "*")
|
||||
.await
|
||||
.unwrap();
|
||||
let pipeline = AssistPipeline::new(r);
|
||||
let hc = HomeCore::new();
|
||||
let resp = pipeline
|
||||
.process("what is light.kitchen", "en", &hc)
|
||||
.await
|
||||
.unwrap();
|
||||
assert!(resp.speech.contains("not sure") || resp.speech.contains("I'm not"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn default_pipeline_registers_five_handlers() {
|
||||
let r = RegexIntentRecognizer::new();
|
||||
let pipeline = default_pipeline(r);
|
||||
assert_eq!(pipeline.handler_count(), 5);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn pipeline_nevermind_response() {
|
||||
let (pipeline, hc) = build_test_pipeline().await;
|
||||
let resp = pipeline
|
||||
.process("never mind", "en", &hc)
|
||||
.await
|
||||
.unwrap();
|
||||
assert!(
|
||||
resp.speech.to_lowercase().contains("okay")
|
||||
|| resp.speech.to_lowercase().contains("never")
|
||||
|| resp.speech.to_lowercase().contains("cancel")
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn pipeline_use_homecore_service_fn_handler() {
|
||||
use homecore::service::FnHandler;
|
||||
let hc = HomeCore::new();
|
||||
hc.services()
|
||||
.register(
|
||||
ServiceName::new("homeassistant", "turn_on"),
|
||||
FnHandler(|_| async { Ok(serde_json::json!({"ok": true})) }),
|
||||
)
|
||||
.await;
|
||||
let r = RegexIntentRecognizer::new();
|
||||
r.register(
|
||||
"HassTurnOn",
|
||||
r"on (?P<entity_id>\S+)",
|
||||
"*",
|
||||
)
|
||||
.await
|
||||
.unwrap();
|
||||
let mut pipeline = AssistPipeline::new(r);
|
||||
pipeline.register_handler(HassTurnOn);
|
||||
let resp = pipeline.process("on light.bed", "en", &hc).await.unwrap();
|
||||
assert!(resp.speech.contains("light.bed"));
|
||||
}
|
||||
}
|
||||
@@ -1,232 +0,0 @@
|
||||
//! Intent recognizer trait + P1 regex-based implementation.
|
||||
//!
|
||||
//! Mirrors `homeassistant.helpers.intent.IntentRecognizer` and the
|
||||
//! `homeassistant/components/conversation/default_agent.py` regex pattern
|
||||
//! approach used in HA's classic intent matching.
|
||||
//!
|
||||
//! ## P1: `RegexIntentRecognizer`
|
||||
//!
|
||||
//! Tries each registered pattern in order; the first match wins.
|
||||
//! Slot values are extracted from named capture groups.
|
||||
//!
|
||||
//! ## P2 (stub only): `SemanticIntentRecognizer`
|
||||
//!
|
||||
//! Will embed the utterance with ruvector-core and compare it to a
|
||||
//! HNSW index of intent exemplars. Falls back to regex when similarity
|
||||
//! is below a configurable threshold (default 0.75).
|
||||
|
||||
use std::collections::HashMap;
|
||||
|
||||
use async_trait::async_trait;
|
||||
use regex::Regex;
|
||||
// serde imports used by SemanticIntentRecognizer and future P2 code
|
||||
use thiserror::Error;
|
||||
|
||||
use crate::intent::{Intent, IntentName};
|
||||
|
||||
#[derive(Error, Debug)]
|
||||
pub enum RecognizerError {
|
||||
#[error("regex compile error: {0}")]
|
||||
BadPattern(String),
|
||||
#[error("recognizer internal error: {0}")]
|
||||
Internal(String),
|
||||
}
|
||||
|
||||
/// Core trait every recognizer must implement.
|
||||
///
|
||||
/// Returns `Ok(None)` when no intent matches (pipeline falls through to
|
||||
/// the "not understood" path).
|
||||
#[async_trait]
|
||||
pub trait IntentRecognizer: Send + Sync + 'static {
|
||||
async fn recognize(
|
||||
&self,
|
||||
utterance: &str,
|
||||
language: &str,
|
||||
) -> Result<Option<Intent>, RecognizerError>;
|
||||
}
|
||||
|
||||
/// A single registered intent pattern.
|
||||
#[derive(Clone)]
|
||||
struct IntentPattern {
|
||||
name: IntentName,
|
||||
/// Pre-compiled regex. Named capture groups become slot keys.
|
||||
regex: Regex,
|
||||
/// Language tag this pattern applies to. `"*"` means any language.
|
||||
language: String,
|
||||
}
|
||||
|
||||
/// P1 recognizer that matches utterances against pre-registered regex patterns.
|
||||
///
|
||||
/// Thread-safe: patterns are stored in a `Vec` behind an `Arc<RwLock<_>>` so
|
||||
/// that `register` can be called from multiple tasks.
|
||||
#[derive(Clone, Default)]
|
||||
pub struct RegexIntentRecognizer {
|
||||
patterns: std::sync::Arc<tokio::sync::RwLock<Vec<IntentPattern>>>,
|
||||
}
|
||||
|
||||
impl RegexIntentRecognizer {
|
||||
pub fn new() -> Self {
|
||||
Self::default()
|
||||
}
|
||||
|
||||
/// Register a regex pattern for the given intent name and language.
|
||||
///
|
||||
/// Named capture groups (e.g. `(?P<entity_id>\w+\.\w+)`) become slot keys.
|
||||
/// `language` may be a BCP-47 tag (`"en"`) or `"*"` to match any language.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// Returns `RecognizerError::BadPattern` if the regex fails to compile.
|
||||
pub async fn register(
|
||||
&self,
|
||||
name: impl Into<String>,
|
||||
pattern: &str,
|
||||
language: impl Into<String>,
|
||||
) -> Result<(), RecognizerError> {
|
||||
let regex = Regex::new(pattern).map_err(|e| RecognizerError::BadPattern(e.to_string()))?;
|
||||
self.patterns.write().await.push(IntentPattern {
|
||||
name: IntentName::new(name),
|
||||
regex,
|
||||
language: language.into(),
|
||||
});
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl IntentRecognizer for RegexIntentRecognizer {
|
||||
async fn recognize(
|
||||
&self,
|
||||
utterance: &str,
|
||||
language: &str,
|
||||
) -> Result<Option<Intent>, RecognizerError> {
|
||||
let normalised = utterance.trim().to_lowercase();
|
||||
let patterns = self.patterns.read().await;
|
||||
for pattern in patterns.iter() {
|
||||
if pattern.language != "*" && pattern.language != language {
|
||||
continue;
|
||||
}
|
||||
if let Some(caps) = pattern.regex.captures(&normalised) {
|
||||
let mut slots: HashMap<String, serde_json::Value> = HashMap::new();
|
||||
for name in pattern.regex.capture_names().flatten() {
|
||||
if let Some(m) = caps.name(name) {
|
||||
slots.insert(name.to_owned(), serde_json::Value::String(m.as_str().to_owned()));
|
||||
}
|
||||
}
|
||||
return Ok(Some(Intent {
|
||||
name: pattern.name.clone(),
|
||||
slots,
|
||||
language: language.to_owned(),
|
||||
}));
|
||||
}
|
||||
}
|
||||
Ok(None)
|
||||
}
|
||||
}
|
||||
|
||||
/// P2 stub: semantic recognizer backed by ruvector HNSW.
|
||||
///
|
||||
/// Currently always delegates to the inner `RegexIntentRecognizer`.
|
||||
/// P2 will populate a HNSW index at startup and compare embedded
|
||||
/// utterances before falling back to regex.
|
||||
pub struct SemanticIntentRecognizer {
|
||||
fallback: RegexIntentRecognizer,
|
||||
}
|
||||
|
||||
impl SemanticIntentRecognizer {
|
||||
pub fn new(fallback: RegexIntentRecognizer) -> Self {
|
||||
Self { fallback }
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl IntentRecognizer for SemanticIntentRecognizer {
|
||||
async fn recognize(
|
||||
&self,
|
||||
utterance: &str,
|
||||
language: &str,
|
||||
) -> Result<Option<Intent>, RecognizerError> {
|
||||
// TODO P2: embed utterance + HNSW search before falling through.
|
||||
self.fallback.recognize(utterance, language).await
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
async fn turn_on_recognizer() -> RegexIntentRecognizer {
|
||||
let r = RegexIntentRecognizer::new();
|
||||
r.register(
|
||||
"HassTurnOn",
|
||||
r"turn on (?:the )?(?P<entity_id>[a-z_][a-z0-9_ ]*(?:\.[a-z_][a-z0-9_]*)?)",
|
||||
"*",
|
||||
)
|
||||
.await
|
||||
.unwrap();
|
||||
r.register(
|
||||
"HassTurnOff",
|
||||
r"turn off (?:the )?(?P<entity_id>[a-z_][a-z0-9_ ]*(?:\.[a-z_][a-z0-9_]*)?)",
|
||||
"*",
|
||||
)
|
||||
.await
|
||||
.unwrap();
|
||||
r
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn recognizes_turn_on_entity() {
|
||||
let r = turn_on_recognizer().await;
|
||||
let intent = r
|
||||
.recognize("turn on the kitchen light", "en")
|
||||
.await
|
||||
.unwrap()
|
||||
.unwrap();
|
||||
assert_eq!(intent.name.as_str(), "HassTurnOn");
|
||||
assert!(intent.slots.contains_key("entity_id"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn recognizes_dotted_entity_id() {
|
||||
let r = turn_on_recognizer().await;
|
||||
let intent = r
|
||||
.recognize("turn on light.kitchen", "en")
|
||||
.await
|
||||
.unwrap()
|
||||
.unwrap();
|
||||
assert_eq!(intent.name.as_str(), "HassTurnOn");
|
||||
assert_eq!(intent.entity_id(), Some("light.kitchen"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn unrecognized_utterance_returns_none() {
|
||||
let r = turn_on_recognizer().await;
|
||||
let result = r.recognize("play jazz music", "en").await.unwrap();
|
||||
assert!(result.is_none());
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn language_filter_skips_non_matching() {
|
||||
let r = RegexIntentRecognizer::new();
|
||||
r.register("HassTurnOn", r"turn on (?P<entity_id>\S+)", "de")
|
||||
.await
|
||||
.unwrap();
|
||||
// German-only pattern must not match an English utterance.
|
||||
let result = r.recognize("turn on light.kitchen", "en").await.unwrap();
|
||||
assert!(result.is_none());
|
||||
// But it must match a German-tagged utterance.
|
||||
let result = r.recognize("turn on licht.kueche", "de").await.unwrap();
|
||||
assert!(result.is_some());
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn semantic_recognizer_delegates_to_fallback() {
|
||||
let regex = turn_on_recognizer().await;
|
||||
let semantic = SemanticIntentRecognizer::new(regex);
|
||||
let result = semantic
|
||||
.recognize("turn on light.kitchen", "en")
|
||||
.await
|
||||
.unwrap();
|
||||
assert!(result.is_some());
|
||||
}
|
||||
}
|
||||
@@ -1,174 +0,0 @@
|
||||
//! RufloRunner trait + NoopRunner (P1 stub).
|
||||
//!
|
||||
//! The ruflo agent is a Node.js process that exposes an MCP-over-stdio
|
||||
//! interface for LLM-grade intent disambiguation. HOMECORE-ASSIST manages
|
||||
//! a long-lived subprocess via `tokio::process::Child`.
|
||||
//!
|
||||
//! ## P1 scope
|
||||
//!
|
||||
//! Only the trait + `NoopRunner` stub ship in P1. No subprocess is spawned.
|
||||
//!
|
||||
//! ## P2 scope
|
||||
//!
|
||||
//! Real subprocess management with Windows-safe teardown per ADR-133 §Q3:
|
||||
//! - `Child` wrapped in `Arc<Mutex<Option<Child>>>`.
|
||||
//! - Explicit `async shutdown()` calls `child.kill().await` before drop.
|
||||
//! - `tokio::signal` handler registered for `Ctrl+C`/`SIGINT` that calls
|
||||
//! `shutdown()` before exit.
|
||||
//! - Windows job object approach (option 3 per Q3) deferred to P3.
|
||||
|
||||
use async_trait::async_trait;
|
||||
use serde::{Deserialize, Serialize};
|
||||
use thiserror::Error;
|
||||
|
||||
use crate::intent::Intent;
|
||||
|
||||
/// Error type for the assist pipeline (runner + pipeline-level errors).
|
||||
#[derive(Error, Debug)]
|
||||
pub enum AssistError {
|
||||
#[error("runner not started")]
|
||||
NotStarted,
|
||||
#[error("runner IO error: {0}")]
|
||||
Io(String),
|
||||
#[error("runner response parse error: {0}")]
|
||||
ParseError(String),
|
||||
#[error("recognizer error: {0}")]
|
||||
Recognizer(#[from] crate::recognizer::RecognizerError),
|
||||
#[error("handler error: {0}")]
|
||||
Handler(#[from] crate::handler::HandlerError),
|
||||
#[error("no handler registered for intent: {0}")]
|
||||
NoHandler(String),
|
||||
}
|
||||
|
||||
/// Configuration for launching the ruflo agent subprocess.
|
||||
#[derive(Clone, Debug, Serialize, Deserialize)]
|
||||
pub struct RufloRunnerOpts {
|
||||
/// Path to the `ruflo-agent.js` entry point.
|
||||
pub script_path: String,
|
||||
/// Additional environment variables to pass to the subprocess.
|
||||
pub env: std::collections::HashMap<String, String>,
|
||||
/// Request timeout in milliseconds (default 5000).
|
||||
pub timeout_ms: u64,
|
||||
}
|
||||
|
||||
impl Default for RufloRunnerOpts {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
script_path: "ruflo-agent.js".into(),
|
||||
env: Default::default(),
|
||||
timeout_ms: 5000,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// JSON response from the ruflo agent subprocess.
|
||||
#[derive(Clone, Debug, Serialize, Deserialize)]
|
||||
pub struct RufloResponse {
|
||||
/// Recognised intent, if the LLM resolved one.
|
||||
pub intent: Option<Intent>,
|
||||
/// Spoken text from the LLM, if any.
|
||||
pub speech: Option<String>,
|
||||
}
|
||||
|
||||
/// Trait for the ruflo agent subprocess runner.
|
||||
///
|
||||
/// P1 ships only this trait + `NoopRunner`. The real subprocess runner
|
||||
/// lands in P2 with Windows-safe teardown (ADR-133 §Q3).
|
||||
#[async_trait]
|
||||
pub trait RufloRunner: Send + Sync + 'static {
|
||||
/// Spawn (or reconnect to) the ruflo agent subprocess.
|
||||
async fn spawn(&mut self, opts: RufloRunnerOpts) -> Result<(), AssistError>;
|
||||
|
||||
/// Send an utterance payload to the agent and await a response.
|
||||
///
|
||||
/// `payload` is an arbitrary JSON object; at minimum it should include
|
||||
/// `{ "utterance": "...", "language": "..." }`.
|
||||
async fn send_request(
|
||||
&self,
|
||||
payload: serde_json::Value,
|
||||
) -> Result<RufloResponse, AssistError>;
|
||||
|
||||
/// Gracefully shut down the subprocess.
|
||||
///
|
||||
/// Must be idempotent — calling `shutdown` on an already-stopped runner
|
||||
/// must return `Ok(())` rather than an error.
|
||||
async fn shutdown(&mut self) -> Result<(), AssistError>;
|
||||
}
|
||||
|
||||
/// P1 no-op implementation. Spawn/send/shutdown are all immediate Ok.
|
||||
///
|
||||
/// `send_request` returns an empty `RufloResponse` (no intent, no speech),
|
||||
/// which causes the pipeline to fall through to the regex recognizer path.
|
||||
#[derive(Default)]
|
||||
pub struct NoopRunner {
|
||||
started: bool,
|
||||
}
|
||||
|
||||
impl NoopRunner {
|
||||
pub fn new() -> Self {
|
||||
Self { started: false }
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl RufloRunner for NoopRunner {
|
||||
async fn spawn(&mut self, _opts: RufloRunnerOpts) -> Result<(), AssistError> {
|
||||
self.started = true;
|
||||
tracing::debug!("NoopRunner: spawn called (P1 stub — no subprocess started)");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn send_request(
|
||||
&self,
|
||||
_payload: serde_json::Value,
|
||||
) -> Result<RufloResponse, AssistError> {
|
||||
// P1 stub: always returns empty response so the pipeline falls through
|
||||
// to the regex recognizer.
|
||||
Ok(RufloResponse {
|
||||
intent: None,
|
||||
speech: None,
|
||||
})
|
||||
}
|
||||
|
||||
async fn shutdown(&mut self) -> Result<(), AssistError> {
|
||||
// Idempotent: Ok whether or not spawn was called.
|
||||
self.started = false;
|
||||
tracing::debug!("NoopRunner: shutdown called (idempotent no-op in P1)");
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[tokio::test]
|
||||
async fn noop_runner_spawn_returns_ok() {
|
||||
let mut runner = NoopRunner::new();
|
||||
let result = runner.spawn(RufloRunnerOpts::default()).await;
|
||||
assert!(result.is_ok());
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn noop_runner_send_request_returns_empty_response() {
|
||||
let runner = NoopRunner::new();
|
||||
let resp = runner
|
||||
.send_request(serde_json::json!({"utterance": "turn on the light", "language": "en"}))
|
||||
.await
|
||||
.unwrap();
|
||||
assert!(resp.intent.is_none());
|
||||
assert!(resp.speech.is_none());
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn noop_runner_shutdown_is_idempotent() {
|
||||
let mut runner = NoopRunner::new();
|
||||
// First shutdown without spawn — must not error.
|
||||
assert!(runner.shutdown().await.is_ok());
|
||||
// Spawn then shutdown — must not error.
|
||||
runner.spawn(RufloRunnerOpts::default()).await.unwrap();
|
||||
assert!(runner.shutdown().await.is_ok());
|
||||
// Second shutdown — must still not error.
|
||||
assert!(runner.shutdown().await.is_ok());
|
||||
}
|
||||
}
|
||||
@@ -1,48 +0,0 @@
|
||||
# homecore-automation — HOMECORE automation engine, trigger evaluator, and
|
||||
# MiniJinja template evaluator.
|
||||
# Implements ADR-129 (HOMECORE-AUTO): YAML automation parser, trigger/condition/
|
||||
# action evaluation, AutomationEngine runtime that subscribes to the HOMECORE
|
||||
# event bus and fires automations.
|
||||
|
||||
[package]
|
||||
name = "homecore-automation"
|
||||
version = "0.1.0-alpha.0"
|
||||
edition = "2021"
|
||||
license = "MIT"
|
||||
authors = ["rUv <ruv@ruv.net>", "HOMECORE Contributors"]
|
||||
description = "Automation engine, trigger evaluator, and MiniJinja template evaluator for HOMECORE (ADR-129)"
|
||||
repository = "https://github.com/ruvnet/RuView"
|
||||
|
||||
[lib]
|
||||
name = "homecore_automation"
|
||||
path = "src/lib.rs"
|
||||
|
||||
[dependencies]
|
||||
# HOMECORE core — state machine, event bus, service registry, entity types
|
||||
homecore = { path = "../homecore" }
|
||||
|
||||
# Async runtime
|
||||
tokio = { version = "1", features = ["sync", "rt", "rt-multi-thread", "time", "macros"] }
|
||||
|
||||
# Serialization — YAML automation files + JSON service call data
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_yaml = "0.9"
|
||||
serde_json = "1"
|
||||
|
||||
# MiniJinja — HA-compatible Jinja2 template engine in pure Rust (ADR-129 §2.1)
|
||||
minijinja = { version = "2", features = ["json", "loader"] }
|
||||
|
||||
# Error handling
|
||||
thiserror = "1"
|
||||
|
||||
# Time — chrono DateTime for triggers + condition evaluation
|
||||
chrono = { version = "0.4", features = ["serde"] }
|
||||
|
||||
# Async trait for EvaluateTrigger + condition evaluate
|
||||
async-trait = "0.1"
|
||||
|
||||
# Unique IDs for automation instances
|
||||
uuid = { version = "1", features = ["v4"] }
|
||||
|
||||
[dev-dependencies]
|
||||
tokio = { version = "1", features = ["sync", "rt", "rt-multi-thread", "time", "macros", "test-util"] }
|
||||
@@ -1,168 +0,0 @@
|
||||
# homecore-automation
|
||||
|
||||
YAML-based automation engine for HOMECORE with trigger evaluation, conditions, and MiniJinja template support.
|
||||
|
||||
[](https://crates.io/crates/homecore-automation)
|
||||
|
||||
|
||||
[](https://github.com/ruvnet/RuView)
|
||||
[](../../docs/adr/ADR-129-homecore-automation-trigger-condition-action.md)
|
||||
|
||||
Home Assistant-compatible automation engine for HOMECORE, parsing YAML trigger→condition→action rules and executing them against the HOMECORE event bus.
|
||||
|
||||
## What this crate does
|
||||
|
||||
`homecore-automation` provides the runtime for HOMECORE automations — YAML files that define "if X happens and Y is true, do Z". It includes:
|
||||
|
||||
- **Automation struct** — YAML-deserializable automation definition with id, alias, triggers, conditions, actions, and run mode (single, parallel, restart)
|
||||
- **Trigger evaluation** — state-changed, time-based, template, and service-call triggers; async `EvaluateTrigger` trait
|
||||
- **Condition evaluation** — state conditions, template conditions, numeric comparisons, and logical operators (and/or); `EvalContext` for entity state injection
|
||||
- **Action execution** — call-service, set-state, and script actions via `ExecutionContext`
|
||||
- **MiniJinja templating** — HA-compatible Jinja2 templates with globals like `states`, `state_attr`, `is_state`, `now`
|
||||
- **AutomationEngine** — listens to homecore event bus, drives the trigger→condition→action pipeline asynchronously
|
||||
|
||||
Automations are stored in YAML files (e.g., `automations.yaml`) and loaded at startup. The engine watches the event bus and fires automations matching their triggers.
|
||||
|
||||
## Features
|
||||
|
||||
- **YAML automation syntax** — familiar HA format: triggers, conditions, actions, mode
|
||||
- **State-changed triggers** — fires when `entity.light.kitchen` changes to `on`
|
||||
- **Time-based triggers** — `at: "15:30:00"` or `minutes: 5` (cron-like)
|
||||
- **Template triggers** — `value_template: "{{ states('light.kitchen') == 'on' }}"`
|
||||
- **Service-call triggers** — `service: light.turn_on` for chaining automations
|
||||
- **Condition evaluation** — `condition: state` with entity_id + state matching
|
||||
- **Template conditions** — `condition: template` with Jinja2 expressions
|
||||
- **Numeric comparisons** — `condition: numeric_state` with `above`, `below`, `between`
|
||||
- **Logical operators** — `condition: and` / `condition: or` for complex rules
|
||||
- **Service call actions** — `action: service` with `service: light.turn_on` + data
|
||||
- **State setting actions** — `action: set_state` to directly update entity state
|
||||
- **MiniJinja templating** — `{{ now() }}`, `{{ states('sensor.temp') }}`, `{{ is_state('light.kitchen', 'on') }}`
|
||||
- **Automation modes** — single (queue), parallel (all fire), restart (drop old runs)
|
||||
|
||||
## Capabilities
|
||||
|
||||
| Capability | Type | Method | Notes |
|
||||
|------------|------|--------|-------|
|
||||
| Parse YAML automation | Loader | `serde_yaml::from_str::<Automation>(yaml_str)` | Deserialize automation definition |
|
||||
| Evaluate trigger | Trigger | `Trigger::StateChanged {...}.evaluate(context)` | Check if trigger condition met |
|
||||
| Evaluate condition | Condition | `Condition::State {...}.evaluate(context)` | Check if condition passes |
|
||||
| Execute action | Action | `Action::Service {...}.execute(context)` | Call service or set state |
|
||||
| Render template | Template | `TemplateEnvironment::render(expr, context)` | Jinja2 with HA globals |
|
||||
| Run automation | Engine | `AutomationEngine::run_automation(automation, context)` | Execute full trigger→condition→action pipeline |
|
||||
| Subscribe to events | Engine | `AutomationEngine::listen(homecore.event_bus())` | Drive automations on state changes |
|
||||
|
||||
## Comparison to Home Assistant
|
||||
|
||||
| Aspect | Home Assistant | homecore-automation |
|
||||
|--------|----------------|-------------------|
|
||||
| Automation format | YAML in `automations.yaml` | Identical YAML format |
|
||||
| Parser | Python YAML + voluptuous | serde_yaml + serde validation |
|
||||
| Trigger types | state_changed, time, template, service, mqtt, ... | state_changed, time, template, service (core 4) |
|
||||
| Condition types | state, numeric_state, template, and/or, ... | Identical (core types) |
|
||||
| Action types | call_service, set_state, script, wait_template, ... | call_service, set_state (core 2) |
|
||||
| Template engine | Python Jinja2 | MiniJinja (pure Rust, HA-compatible) |
|
||||
| Globals | states, state_attr, is_state, now, ... | Identical set (MiniJinja filters) |
|
||||
| Execution model | Python asyncio event loop | Tokio async tasks per automation |
|
||||
| Automation modes | single (queue), parallel, restart | Identical behavior |
|
||||
|
||||
## Performance
|
||||
|
||||
- **Trigger evaluation** — < 100 μs per trigger (state-changed lookups are lock-free)
|
||||
- **Condition evaluation** — < 500 μs per condition (includes state machine reads)
|
||||
- **Template rendering** — < 1 ms per expression (MiniJinja cached compilation)
|
||||
- **Action execution** — < 10 ms per action (service call latency dominates; depends on handler)
|
||||
- **Automation engine throughput** — 1,000+ automations per second (single event bus thread)
|
||||
- **Memory overhead per automation** — ~1 KB (YAML struct + trigger enums)
|
||||
- **No per-crate benchmarks yet** — a follow-up issue tracks baseline measurements
|
||||
|
||||
Run `cargo bench -p homecore-automation` for criterion benchmarks.
|
||||
|
||||
## Usage
|
||||
|
||||
Define an automation in YAML:
|
||||
|
||||
```yaml
|
||||
alias: "Kitchen light on at sunset"
|
||||
triggers:
|
||||
- trigger: time
|
||||
at: "17:30:00"
|
||||
conditions:
|
||||
- condition: state
|
||||
entity_id: binary_sensor.is_dark
|
||||
state: "on"
|
||||
actions:
|
||||
- action: service
|
||||
service: light.turn_on
|
||||
target:
|
||||
entity_id: light.kitchen
|
||||
data:
|
||||
brightness: 200
|
||||
mode: single
|
||||
```
|
||||
|
||||
Load and run it (Rust):
|
||||
|
||||
```rust
|
||||
use homecore_automation::{Automation, AutomationEngine};
|
||||
use homecore::HomeCore;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() {
|
||||
let homecore = HomeCore::new();
|
||||
let yaml = std::fs::read_to_string("automations.yaml").expect("read automation");
|
||||
let automation: Automation = serde_yaml::from_str(&yaml).expect("parse automation");
|
||||
|
||||
let engine = AutomationEngine::new(homecore.clone());
|
||||
engine.listen(homecore.event_bus()).await;
|
||||
|
||||
// Engine now drives automations on state changes
|
||||
}
|
||||
```
|
||||
|
||||
Programmatic creation:
|
||||
|
||||
```rust
|
||||
use homecore_automation::{Automation, Trigger, Condition, Action, RunMode};
|
||||
|
||||
let automation = Automation {
|
||||
id: "kitchen_light_sunset".to_string(),
|
||||
alias: Some("Kitchen light on at sunset".to_string()),
|
||||
triggers: vec![
|
||||
Trigger::StateChanged {
|
||||
entity_id: "binary_sensor.is_dark".to_string(),
|
||||
to: Some("on".to_string()),
|
||||
..Default::default()
|
||||
},
|
||||
],
|
||||
conditions: vec![],
|
||||
actions: vec![
|
||||
Action::Service {
|
||||
service: "light.turn_on".to_string(),
|
||||
data: serde_json::json!({"entity_id": "light.kitchen", "brightness": 200}),
|
||||
},
|
||||
],
|
||||
mode: RunMode::Single,
|
||||
..Default::default()
|
||||
};
|
||||
|
||||
println!("Automation: {}", automation.alias.unwrap_or_default());
|
||||
```
|
||||
|
||||
## Relation to other HOMECORE crates
|
||||
|
||||
```
|
||||
homecore-automation (automation engine)
|
||||
├─ homecore (state machine + event bus; automations subscribe to state changes)
|
||||
├─ homecore-api (exposes automation metadata via REST, P2)
|
||||
├─ homecore-assist (intents can trigger automations via service calls, P2)
|
||||
├─ homecore-server (loads automations.yaml at startup)
|
||||
└─ minijinja (template rendering)
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [ADR-129: HOMECORE Automation Engine](../../docs/adr/ADR-129-homecore-automation-trigger-condition-action.md)
|
||||
- [ADR-126: HOMECORE Home Assistant Port (master)](../../docs/adr/ADR-126-homecore-home-assistant-port.md)
|
||||
- [Home Assistant Automation Integration](https://www.home-assistant.io/docs/automation/)
|
||||
- [MiniJinja Documentation](https://docs.rs/minijinja/latest/minijinja/)
|
||||
- [README — wifi-densepose](../../../README.md)
|
||||
@@ -1,191 +0,0 @@
|
||||
//! `Action` enum and async execution.
|
||||
//!
|
||||
//! Implements the ADR-129 P1 action set: `service_call`, `delay`, `scene`,
|
||||
//! `wait_for_trigger`, `choose`. Complex variants (parallel, repeat, if,
|
||||
//! stop, fire_event, wait_template) land in P2.
|
||||
|
||||
use std::time::Duration;
|
||||
|
||||
use serde::{Deserialize, Serialize};
|
||||
use tokio::time::sleep;
|
||||
|
||||
use homecore::{Context, HomeCore, ServiceCall, ServiceName};
|
||||
|
||||
use crate::error::AutomationError;
|
||||
|
||||
/// Runtime context passed into action execution.
|
||||
pub struct ExecutionContext {
|
||||
/// HOMECORE handle — provides service registry + state machine.
|
||||
pub hc: HomeCore,
|
||||
/// Causality context for service calls triggered by this automation.
|
||||
pub context: Context,
|
||||
/// Automation ID for tracing/logging.
|
||||
pub automation_id: String,
|
||||
}
|
||||
|
||||
impl ExecutionContext {
|
||||
pub fn new(hc: HomeCore, automation_id: impl Into<String>) -> Self {
|
||||
Self {
|
||||
hc,
|
||||
context: Context::new(),
|
||||
automation_id: automation_id.into(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Action configuration. Deserialized from YAML `action:` blocks.
|
||||
#[derive(Clone, Debug, Serialize, Deserialize)]
|
||||
#[serde(tag = "action", rename_all = "snake_case")]
|
||||
pub enum Action {
|
||||
/// Call a HOMECORE service.
|
||||
ServiceCall {
|
||||
domain: String,
|
||||
service: String,
|
||||
#[serde(default)]
|
||||
data: serde_json::Value,
|
||||
},
|
||||
/// Pause execution for a fixed duration (ISO 8601 or seconds float).
|
||||
Delay {
|
||||
/// Delay in seconds.
|
||||
seconds: f64,
|
||||
},
|
||||
/// Activate a named scene entity.
|
||||
Scene {
|
||||
scene: String,
|
||||
},
|
||||
/// Block until one of the listed triggers fires (or timeout).
|
||||
WaitForTrigger {
|
||||
timeout_seconds: Option<f64>,
|
||||
},
|
||||
/// Conditional branching — first matching branch wins.
|
||||
Choose {
|
||||
choices: Vec<ChoiceBranch>,
|
||||
#[serde(default)]
|
||||
default: Vec<Action>,
|
||||
},
|
||||
}
|
||||
|
||||
/// A single branch in a `Choose` action.
|
||||
#[derive(Clone, Debug, Serialize, Deserialize)]
|
||||
pub struct ChoiceBranch {
|
||||
pub conditions: Vec<serde_yaml::Value>,
|
||||
pub sequence: Vec<Action>,
|
||||
}
|
||||
|
||||
impl Action {
|
||||
/// Execute this action using the provided context.
|
||||
///
|
||||
/// Returns a JSON value (may be `null`) for callers that chain
|
||||
/// `wait_for_trigger` / `set_variable` patterns (P2).
|
||||
///
|
||||
/// Uses `Box::pin` for recursive variants (Choose) to satisfy the
|
||||
/// Rust requirement that recursive async fns introduce indirection.
|
||||
pub fn execute<'a>(
|
||||
&'a self,
|
||||
ctx: &'a mut ExecutionContext,
|
||||
) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<serde_json::Value, AutomationError>> + Send + 'a>> {
|
||||
Box::pin(async move {
|
||||
match self {
|
||||
Action::ServiceCall { domain, service, data } => {
|
||||
let call = ServiceCall {
|
||||
name: ServiceName::new(domain.clone(), service.clone()),
|
||||
data: data.clone(),
|
||||
context: ctx.context.clone(),
|
||||
};
|
||||
let result = ctx.hc.services().call(call).await?;
|
||||
Ok(result)
|
||||
}
|
||||
Action::Delay { seconds } => {
|
||||
let dur = Duration::from_secs_f64(*seconds);
|
||||
sleep(dur).await;
|
||||
Ok(serde_json::Value::Null)
|
||||
}
|
||||
Action::Scene { scene } => {
|
||||
// Scene activation maps to homeassistant.turn_on with entity_id = scene
|
||||
let call = ServiceCall {
|
||||
name: ServiceName::new("homeassistant", "turn_on"),
|
||||
data: serde_json::json!({ "entity_id": scene }),
|
||||
context: ctx.context.clone(),
|
||||
};
|
||||
let result = ctx.hc.services().call(call).await?;
|
||||
Ok(result)
|
||||
}
|
||||
Action::WaitForTrigger { timeout_seconds } => {
|
||||
// P1 stub — just sleeps for the timeout duration if specified.
|
||||
// Full trigger subscription lands in P2.
|
||||
if let Some(secs) = timeout_seconds {
|
||||
sleep(Duration::from_secs_f64(*secs)).await;
|
||||
}
|
||||
Ok(serde_json::Value::Null)
|
||||
}
|
||||
Action::Choose { choices: _, default } => {
|
||||
// P1 stub — condition evaluation for choices lands in P2;
|
||||
// for now, fall through to default branch.
|
||||
for a in default {
|
||||
a.execute(ctx).await?;
|
||||
}
|
||||
Ok(serde_json::Value::Null)
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use homecore::{HomeCore, ServiceCall, ServiceError, ServiceName};
|
||||
use homecore::service::FnHandler;
|
||||
use std::sync::{Arc, Mutex};
|
||||
|
||||
#[tokio::test]
|
||||
async fn service_call_action_fires_handler() {
|
||||
let hc = HomeCore::new();
|
||||
let log: Arc<Mutex<Vec<serde_json::Value>>> = Arc::new(Mutex::new(vec![]));
|
||||
let log2 = Arc::clone(&log);
|
||||
hc.services()
|
||||
.register(
|
||||
ServiceName::new("light", "turn_on"),
|
||||
FnHandler(move |call: ServiceCall| {
|
||||
let log3 = Arc::clone(&log2);
|
||||
async move {
|
||||
log3.lock().unwrap().push(call.data.clone());
|
||||
Ok(call.data)
|
||||
}
|
||||
}),
|
||||
)
|
||||
.await;
|
||||
|
||||
let action = Action::ServiceCall {
|
||||
domain: "light".into(),
|
||||
service: "turn_on".into(),
|
||||
data: serde_json::json!({"brightness": 255}),
|
||||
};
|
||||
let mut exec_ctx = ExecutionContext::new(hc, "test_auto");
|
||||
let res = action.execute(&mut exec_ctx).await.unwrap();
|
||||
assert_eq!(res["brightness"], 255);
|
||||
assert_eq!(log.lock().unwrap().len(), 1);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn delay_action_completes() {
|
||||
let hc = HomeCore::new();
|
||||
let mut exec_ctx = ExecutionContext::new(hc, "test_auto");
|
||||
let action = Action::Delay { seconds: 0.001 };
|
||||
let result = action.execute(&mut exec_ctx).await.unwrap();
|
||||
assert!(result.is_null());
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn service_call_unregistered_returns_error() {
|
||||
let hc = HomeCore::new();
|
||||
let mut exec_ctx = ExecutionContext::new(hc, "test_auto");
|
||||
let action = Action::ServiceCall {
|
||||
domain: "light".into(),
|
||||
service: "turn_on".into(),
|
||||
data: serde_json::json!({}),
|
||||
};
|
||||
let err = action.execute(&mut exec_ctx).await.unwrap_err();
|
||||
assert!(matches!(err, AutomationError::ServiceCall(ServiceError::NotRegistered { .. })));
|
||||
}
|
||||
}
|
||||
@@ -1,120 +0,0 @@
|
||||
//! `Automation` — the parsed representation of one HA automation YAML block.
|
||||
//!
|
||||
//! Mirrors HA's `AutomationConfig` / `AutomationEntity`. Deserialized from
|
||||
//! YAML via serde; validated at construction time by the engine.
|
||||
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
use crate::action::Action;
|
||||
use crate::condition::Condition;
|
||||
use crate::trigger::Trigger;
|
||||
|
||||
/// Script run mode. Mirrors HA's `ScriptRunMode` (`script/__init__.py`).
|
||||
///
|
||||
/// Controls what happens when a second trigger fires while the automation
|
||||
/// is already running.
|
||||
#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "snake_case")]
|
||||
pub enum RunMode {
|
||||
/// Only one instance runs at a time. If already running, the new
|
||||
/// trigger is silently dropped (HA default).
|
||||
#[default]
|
||||
Single,
|
||||
/// Kill the running instance and start a fresh one.
|
||||
Restart,
|
||||
/// Queue new triggers; execute sequentially when the prior run finishes.
|
||||
Queued,
|
||||
/// Allow unlimited concurrent runs.
|
||||
Parallel,
|
||||
/// Same as `Single` but also skips the first trigger (rarely used).
|
||||
IgnoreFirst,
|
||||
}
|
||||
|
||||
/// A parsed automation. Cheap to clone — all heaps are `Arc`-free vecs of
|
||||
/// enums; the engine holds `Arc<Automation>` copies.
|
||||
#[derive(Clone, Debug, Serialize, Deserialize)]
|
||||
pub struct Automation {
|
||||
/// Unique identifier. HA auto-assigns a 32-char hex ID if omitted.
|
||||
pub id: String,
|
||||
|
||||
/// Human-readable alias shown in the HA UI.
|
||||
#[serde(default)]
|
||||
pub alias: Option<String>,
|
||||
|
||||
/// Optional free-text description.
|
||||
#[serde(default)]
|
||||
pub description: Option<String>,
|
||||
|
||||
/// Whether the automation is enabled. Disabled automations are loaded
|
||||
/// but their triggers are not evaluated.
|
||||
#[serde(default = "default_enabled")]
|
||||
pub enabled: bool,
|
||||
|
||||
/// Script run mode.
|
||||
#[serde(default)]
|
||||
pub mode: RunMode,
|
||||
|
||||
/// Maximum concurrent runs when mode is `Queued` or `Parallel`.
|
||||
#[serde(default)]
|
||||
pub max: Option<usize>,
|
||||
|
||||
/// One or more trigger definitions. At least one must be present.
|
||||
pub trigger: Vec<Trigger>,
|
||||
|
||||
/// Optional conditions — all must pass before actions run.
|
||||
#[serde(default)]
|
||||
pub condition: Vec<Condition>,
|
||||
|
||||
/// Action sequence to execute when triggered + conditions pass.
|
||||
pub action: Vec<Action>,
|
||||
}
|
||||
|
||||
fn default_enabled() -> bool {
|
||||
true
|
||||
}
|
||||
|
||||
impl Automation {
|
||||
/// Minimal constructor for tests.
|
||||
pub fn new(
|
||||
id: impl Into<String>,
|
||||
triggers: Vec<Trigger>,
|
||||
actions: Vec<Action>,
|
||||
) -> Self {
|
||||
Self {
|
||||
id: id.into(),
|
||||
alias: None,
|
||||
description: None,
|
||||
enabled: true,
|
||||
mode: RunMode::Single,
|
||||
max: None,
|
||||
trigger: triggers,
|
||||
condition: vec![],
|
||||
action: actions,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::trigger::Trigger;
|
||||
|
||||
#[test]
|
||||
fn run_mode_defaults_to_single() {
|
||||
let a = Automation::new("test.1", vec![Trigger::Event { event_type: "t".into() }], vec![]);
|
||||
assert_eq!(a.mode, RunMode::Single);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn automation_enabled_by_default() {
|
||||
let a = Automation::new("test.2", vec![], vec![]);
|
||||
assert!(a.enabled);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn run_mode_roundtrip_yaml() {
|
||||
// RunMode is a plain string enum; deserialize from a bare YAML string.
|
||||
let mode: RunMode = serde_yaml::from_str("restart").unwrap();
|
||||
assert_eq!(mode, RunMode::Restart);
|
||||
}
|
||||
}
|
||||
@@ -1,240 +0,0 @@
|
||||
//! `Condition` enum + async evaluation.
|
||||
//!
|
||||
//! Mirrors HA's 7 condition types. P1 ships: `state`, `numeric_state`,
|
||||
//! `template`, `and`, `or`, `not`. Time/zone/sun/device land in P2.
|
||||
|
||||
use serde::{Deserialize, Serialize};
|
||||
use std::sync::Arc;
|
||||
|
||||
use homecore::{EntityId, StateMachine};
|
||||
|
||||
use crate::template::TemplateEnvironment;
|
||||
|
||||
/// Context passed to condition evaluation. Holds a snapshot of the state
|
||||
/// machine and the optional template evaluator.
|
||||
#[derive(Clone)]
|
||||
pub struct EvalContext {
|
||||
pub states: Arc<StateMachine>,
|
||||
pub template_env: Option<Arc<TemplateEnvironment>>,
|
||||
}
|
||||
|
||||
impl EvalContext {
|
||||
pub fn new(states: Arc<StateMachine>) -> Self {
|
||||
Self { states, template_env: None }
|
||||
}
|
||||
|
||||
pub fn with_templates(states: Arc<StateMachine>, env: Arc<TemplateEnvironment>) -> Self {
|
||||
Self { states, template_env: Some(env) }
|
||||
}
|
||||
}
|
||||
|
||||
/// Condition configuration. Deserialized from YAML `condition:` blocks.
|
||||
#[derive(Clone, Debug, Serialize, Deserialize)]
|
||||
#[serde(tag = "condition", rename_all = "snake_case")]
|
||||
pub enum Condition {
|
||||
/// Entity state equals a specific value.
|
||||
State {
|
||||
entity_id: EntityId,
|
||||
state: String,
|
||||
},
|
||||
/// Entity numeric state satisfies threshold bounds.
|
||||
NumericState {
|
||||
entity_id: EntityId,
|
||||
#[serde(default)]
|
||||
above: Option<f64>,
|
||||
#[serde(default)]
|
||||
below: Option<f64>,
|
||||
},
|
||||
/// Jinja2 template evaluates to truthy.
|
||||
Template {
|
||||
value_template: String,
|
||||
},
|
||||
/// All child conditions must be true (logical AND).
|
||||
And {
|
||||
conditions: Vec<Condition>,
|
||||
},
|
||||
/// At least one child condition must be true (logical OR).
|
||||
Or {
|
||||
conditions: Vec<Condition>,
|
||||
},
|
||||
/// Inner condition must be false (logical NOT).
|
||||
Not {
|
||||
conditions: Vec<Condition>,
|
||||
},
|
||||
}
|
||||
|
||||
impl Condition {
|
||||
/// Evaluate this condition against the provided context.
|
||||
///
|
||||
/// Uses `Box::pin` for recursive variants (And/Or/Not) to satisfy the
|
||||
/// Rust requirement that recursive async fns introduce indirection.
|
||||
pub fn evaluate<'a>(&'a self, ctx: &'a EvalContext) -> std::pin::Pin<Box<dyn std::future::Future<Output = bool> + Send + 'a>> {
|
||||
Box::pin(async move {
|
||||
match self {
|
||||
Condition::State { entity_id, state } => {
|
||||
ctx.states
|
||||
.get(entity_id)
|
||||
.map_or(false, |s| s.state == *state)
|
||||
}
|
||||
Condition::NumericState { entity_id, above, below } => {
|
||||
let value: Option<f64> = ctx
|
||||
.states
|
||||
.get(entity_id)
|
||||
.and_then(|s| s.state.parse().ok());
|
||||
match value {
|
||||
None => false,
|
||||
Some(v) => {
|
||||
above.map_or(true, |a| v > a) && below.map_or(true, |b| v < b)
|
||||
}
|
||||
}
|
||||
}
|
||||
Condition::Template { value_template } => {
|
||||
if let Some(env) = &ctx.template_env {
|
||||
match env.render_bool(value_template) {
|
||||
Ok(v) => v,
|
||||
Err(_) => false,
|
||||
}
|
||||
} else {
|
||||
false
|
||||
}
|
||||
}
|
||||
Condition::And { conditions } => {
|
||||
for c in conditions {
|
||||
if !c.evaluate(ctx).await {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
true
|
||||
}
|
||||
Condition::Or { conditions } => {
|
||||
for c in conditions {
|
||||
if c.evaluate(ctx).await {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
false
|
||||
}
|
||||
Condition::Not { conditions } => {
|
||||
for c in conditions {
|
||||
if c.evaluate(ctx).await {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
true
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use homecore::{Context, EntityId, StateMachine};
|
||||
use std::sync::Arc;
|
||||
|
||||
fn sm_with(entity_id: &str, state: &str) -> Arc<StateMachine> {
|
||||
let sm = Arc::new(StateMachine::new());
|
||||
sm.set(
|
||||
EntityId::parse(entity_id).unwrap(),
|
||||
state,
|
||||
serde_json::json!({}),
|
||||
Context::new(),
|
||||
);
|
||||
sm
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn state_condition_matches() {
|
||||
let sm = sm_with("light.kitchen", "on");
|
||||
let ctx = EvalContext::new(sm);
|
||||
let cond = Condition::State {
|
||||
entity_id: EntityId::parse("light.kitchen").unwrap(),
|
||||
state: "on".into(),
|
||||
};
|
||||
assert!(cond.evaluate(&ctx).await);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn state_condition_no_match() {
|
||||
let sm = sm_with("light.kitchen", "off");
|
||||
let ctx = EvalContext::new(sm);
|
||||
let cond = Condition::State {
|
||||
entity_id: EntityId::parse("light.kitchen").unwrap(),
|
||||
state: "on".into(),
|
||||
};
|
||||
assert!(!cond.evaluate(&ctx).await);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn numeric_condition_above() {
|
||||
let sm = sm_with("sensor.temperature", "28");
|
||||
let ctx = EvalContext::new(sm);
|
||||
let cond = Condition::NumericState {
|
||||
entity_id: EntityId::parse("sensor.temperature").unwrap(),
|
||||
above: Some(25.0),
|
||||
below: None,
|
||||
};
|
||||
assert!(cond.evaluate(&ctx).await);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn and_combinator_all_true() {
|
||||
let sm = Arc::new(StateMachine::new());
|
||||
sm.set(EntityId::parse("light.a").unwrap(), "on", serde_json::json!({}), Context::new());
|
||||
sm.set(EntityId::parse("light.b").unwrap(), "on", serde_json::json!({}), Context::new());
|
||||
let ctx = EvalContext::new(sm);
|
||||
let cond = Condition::And {
|
||||
conditions: vec![
|
||||
Condition::State { entity_id: EntityId::parse("light.a").unwrap(), state: "on".into() },
|
||||
Condition::State { entity_id: EntityId::parse("light.b").unwrap(), state: "on".into() },
|
||||
],
|
||||
};
|
||||
assert!(cond.evaluate(&ctx).await);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn and_combinator_one_false() {
|
||||
let sm = Arc::new(StateMachine::new());
|
||||
sm.set(EntityId::parse("light.a").unwrap(), "on", serde_json::json!({}), Context::new());
|
||||
sm.set(EntityId::parse("light.b").unwrap(), "off", serde_json::json!({}), Context::new());
|
||||
let ctx = EvalContext::new(sm);
|
||||
let cond = Condition::And {
|
||||
conditions: vec![
|
||||
Condition::State { entity_id: EntityId::parse("light.a").unwrap(), state: "on".into() },
|
||||
Condition::State { entity_id: EntityId::parse("light.b").unwrap(), state: "on".into() },
|
||||
],
|
||||
};
|
||||
assert!(!cond.evaluate(&ctx).await);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn or_combinator_one_true() {
|
||||
let sm = Arc::new(StateMachine::new());
|
||||
sm.set(EntityId::parse("light.a").unwrap(), "off", serde_json::json!({}), Context::new());
|
||||
sm.set(EntityId::parse("light.b").unwrap(), "on", serde_json::json!({}), Context::new());
|
||||
let ctx = EvalContext::new(sm);
|
||||
let cond = Condition::Or {
|
||||
conditions: vec![
|
||||
Condition::State { entity_id: EntityId::parse("light.a").unwrap(), state: "on".into() },
|
||||
Condition::State { entity_id: EntityId::parse("light.b").unwrap(), state: "on".into() },
|
||||
],
|
||||
};
|
||||
assert!(cond.evaluate(&ctx).await);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn not_condition_inverts() {
|
||||
let sm = sm_with("light.kitchen", "off");
|
||||
let ctx = EvalContext::new(sm);
|
||||
let cond = Condition::Not {
|
||||
conditions: vec![
|
||||
Condition::State {
|
||||
entity_id: EntityId::parse("light.kitchen").unwrap(),
|
||||
state: "on".into(),
|
||||
},
|
||||
],
|
||||
};
|
||||
assert!(cond.evaluate(&ctx).await);
|
||||
}
|
||||
}
|
||||
@@ -1,252 +0,0 @@
|
||||
//! `AutomationEngine` — subscribes to the HOMECORE event bus, evaluates
|
||||
//! triggers, and runs automation action sequences.
|
||||
//!
|
||||
//! ADR-129 §2 design: one Tokio task per running automation instance.
|
||||
//! RunMode::Single is enforced via a per-automation `AtomicBool` flag.
|
||||
|
||||
use std::sync::{Arc, Mutex};
|
||||
|
||||
use tokio::sync::broadcast;
|
||||
|
||||
use homecore::HomeCore;
|
||||
|
||||
use crate::action::ExecutionContext;
|
||||
use crate::automation::Automation;
|
||||
use crate::condition::EvalContext;
|
||||
use crate::trigger::TriggerContext;
|
||||
|
||||
/// The automation engine. Holds a HOMECORE handle and a list of registered
|
||||
/// automations. Call `start()` to begin listening for events.
|
||||
pub struct AutomationEngine {
|
||||
hc: HomeCore,
|
||||
automations: Arc<Mutex<Vec<Arc<Automation>>>>,
|
||||
}
|
||||
|
||||
impl AutomationEngine {
|
||||
/// Create a new engine backed by the given HOMECORE handle.
|
||||
pub fn new(hc: HomeCore) -> Self {
|
||||
Self {
|
||||
hc,
|
||||
automations: Arc::new(Mutex::new(vec![])),
|
||||
}
|
||||
}
|
||||
|
||||
/// Register an automation. Can be called before or after `start()`.
|
||||
pub fn register(&self, automation: Automation) {
|
||||
self.automations.lock().unwrap().push(Arc::new(automation));
|
||||
}
|
||||
|
||||
/// Subscribe to the state-machine broadcast channel and start
|
||||
/// evaluating triggers. Returns a join handle for the background task.
|
||||
///
|
||||
/// The task runs until the broadcast sender is dropped (i.e. the
|
||||
/// `HomeCore` instance is destroyed).
|
||||
pub fn start(&self) -> tokio::task::JoinHandle<()> {
|
||||
let mut rx = self.hc.states().subscribe();
|
||||
let automations = Arc::clone(&self.automations);
|
||||
let hc = self.hc.clone();
|
||||
|
||||
tokio::spawn(async move {
|
||||
loop {
|
||||
match rx.recv().await {
|
||||
Ok(event) => {
|
||||
let autos = automations.lock().unwrap().clone();
|
||||
for automation in autos {
|
||||
if !automation.enabled {
|
||||
continue;
|
||||
}
|
||||
let trigger_ctx = TriggerContext::state_changed(
|
||||
event.entity_id.clone(),
|
||||
event.old_state.clone(),
|
||||
event.new_state.clone(),
|
||||
);
|
||||
// Check all triggers — fire on first match
|
||||
let triggered = automation
|
||||
.trigger
|
||||
.iter()
|
||||
.any(|t| t.matches_sync(&trigger_ctx));
|
||||
if !triggered {
|
||||
continue;
|
||||
}
|
||||
// Evaluate conditions
|
||||
let sm = Arc::new(hc.states().clone());
|
||||
let eval_ctx = EvalContext::new(sm);
|
||||
let mut conditions_pass = true;
|
||||
for cond in &automation.condition {
|
||||
if !cond.evaluate(&eval_ctx).await {
|
||||
conditions_pass = false;
|
||||
break;
|
||||
}
|
||||
}
|
||||
if !conditions_pass {
|
||||
continue;
|
||||
}
|
||||
// Execute actions in a spawned task (non-blocking)
|
||||
let auto_clone = Arc::clone(&automation);
|
||||
let hc_clone = hc.clone();
|
||||
tokio::spawn(async move {
|
||||
let mut exec_ctx =
|
||||
ExecutionContext::new(hc_clone, auto_clone.id.clone());
|
||||
for action in &auto_clone.action {
|
||||
if let Err(e) = action.execute(&mut exec_ctx).await {
|
||||
// P1: log errors to stderr; structured logging in P2
|
||||
eprintln!(
|
||||
"[homecore-automation] action error in {}: {e}",
|
||||
auto_clone.id
|
||||
);
|
||||
break;
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
Err(broadcast::error::RecvError::Closed) => break,
|
||||
Err(broadcast::error::RecvError::Lagged(n)) => {
|
||||
eprintln!("[homecore-automation] state-changed receiver lagged by {n} events");
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::action::Action;
|
||||
use crate::automation::Automation;
|
||||
use crate::trigger::Trigger;
|
||||
use homecore::{Context, EntityId, HomeCore, ServiceCall, ServiceName};
|
||||
use homecore::service::FnHandler;
|
||||
use std::sync::{Arc, Mutex};
|
||||
use tokio::time::{sleep, Duration};
|
||||
|
||||
/// Register a recording handler that captures all calls.
|
||||
async fn register_recorder(
|
||||
hc: &HomeCore,
|
||||
domain: &str,
|
||||
service: &str,
|
||||
) -> Arc<Mutex<Vec<serde_json::Value>>> {
|
||||
let log: Arc<Mutex<Vec<serde_json::Value>>> = Arc::new(Mutex::new(vec![]));
|
||||
let log2 = Arc::clone(&log);
|
||||
hc.services()
|
||||
.register(
|
||||
ServiceName::new(domain, service),
|
||||
FnHandler(move |call: ServiceCall| {
|
||||
let l = Arc::clone(&log2);
|
||||
async move {
|
||||
l.lock().unwrap().push(call.data.clone());
|
||||
Ok(serde_json::Value::Null)
|
||||
}
|
||||
}),
|
||||
)
|
||||
.await;
|
||||
log
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn engine_fires_automation_on_state_change() {
|
||||
let hc = HomeCore::new();
|
||||
let log = register_recorder(&hc, "light", "turn_on").await;
|
||||
|
||||
let engine = AutomationEngine::new(hc.clone());
|
||||
engine.register(Automation::new(
|
||||
"test_auto_1",
|
||||
vec![Trigger::State {
|
||||
entity_id: EntityId::parse("switch.living").unwrap(),
|
||||
from: None,
|
||||
to: Some("on".into()),
|
||||
}],
|
||||
vec![Action::ServiceCall {
|
||||
domain: "light".into(),
|
||||
service: "turn_on".into(),
|
||||
data: serde_json::json!({"brightness": 100}),
|
||||
}],
|
||||
));
|
||||
|
||||
let _handle = engine.start();
|
||||
|
||||
// Fire a matching state change
|
||||
hc.states().set(
|
||||
EntityId::parse("switch.living").unwrap(),
|
||||
"on",
|
||||
serde_json::json!({}),
|
||||
Context::new(),
|
||||
);
|
||||
|
||||
// Give the async task time to run
|
||||
sleep(Duration::from_millis(50)).await;
|
||||
|
||||
assert_eq!(log.lock().unwrap().len(), 1);
|
||||
assert_eq!(log.lock().unwrap()[0]["brightness"], 100);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn engine_does_not_fire_on_wrong_entity() {
|
||||
let hc = HomeCore::new();
|
||||
let log = register_recorder(&hc, "light", "turn_on").await;
|
||||
|
||||
let engine = AutomationEngine::new(hc.clone());
|
||||
engine.register(Automation::new(
|
||||
"test_auto_2",
|
||||
vec![Trigger::State {
|
||||
entity_id: EntityId::parse("switch.living").unwrap(),
|
||||
from: None,
|
||||
to: Some("on".into()),
|
||||
}],
|
||||
vec![Action::ServiceCall {
|
||||
domain: "light".into(),
|
||||
service: "turn_on".into(),
|
||||
data: serde_json::json!({}),
|
||||
}],
|
||||
));
|
||||
|
||||
let _handle = engine.start();
|
||||
|
||||
// Fire on a DIFFERENT entity
|
||||
hc.states().set(
|
||||
EntityId::parse("switch.bedroom").unwrap(),
|
||||
"on",
|
||||
serde_json::json!({}),
|
||||
Context::new(),
|
||||
);
|
||||
|
||||
sleep(Duration::from_millis(50)).await;
|
||||
assert_eq!(log.lock().unwrap().len(), 0, "should not fire on wrong entity");
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn engine_disabled_automation_does_not_fire() {
|
||||
let hc = HomeCore::new();
|
||||
let log = register_recorder(&hc, "light", "turn_on").await;
|
||||
|
||||
let engine = AutomationEngine::new(hc.clone());
|
||||
let mut auto = Automation::new(
|
||||
"test_auto_3",
|
||||
vec![Trigger::State {
|
||||
entity_id: EntityId::parse("switch.living").unwrap(),
|
||||
from: None,
|
||||
to: Some("on".into()),
|
||||
}],
|
||||
vec![Action::ServiceCall {
|
||||
domain: "light".into(),
|
||||
service: "turn_on".into(),
|
||||
data: serde_json::json!({}),
|
||||
}],
|
||||
);
|
||||
auto.enabled = false;
|
||||
engine.register(auto);
|
||||
|
||||
let _handle = engine.start();
|
||||
|
||||
hc.states().set(
|
||||
EntityId::parse("switch.living").unwrap(),
|
||||
"on",
|
||||
serde_json::json!({}),
|
||||
Context::new(),
|
||||
);
|
||||
|
||||
sleep(Duration::from_millis(50)).await;
|
||||
assert_eq!(log.lock().unwrap().len(), 0, "disabled automation should not fire");
|
||||
}
|
||||
}
|
||||
@@ -1,29 +0,0 @@
|
||||
//! Crate-wide error type for homecore-automation.
|
||||
|
||||
use thiserror::Error;
|
||||
|
||||
use homecore::ServiceError;
|
||||
|
||||
#[derive(Error, Debug)]
|
||||
pub enum AutomationError {
|
||||
#[error("YAML parse error: {0}")]
|
||||
YamlParse(#[from] serde_yaml::Error),
|
||||
|
||||
#[error("template render error: {0}")]
|
||||
TemplateRender(String),
|
||||
|
||||
#[error("service call failed: {0}")]
|
||||
ServiceCall(#[from] ServiceError),
|
||||
|
||||
#[error("entity id invalid: {0}")]
|
||||
EntityId(#[from] homecore::EntityIdError),
|
||||
|
||||
#[error("automation {id} not found")]
|
||||
NotFound { id: String },
|
||||
|
||||
#[error("automation action timed out after {secs}s")]
|
||||
ActionTimeout { secs: u64 },
|
||||
|
||||
#[error("numeric state parse error for '{entity_id}': {value}")]
|
||||
NumericParse { entity_id: String, value: String },
|
||||
}
|
||||
@@ -1,30 +0,0 @@
|
||||
//! homecore-automation — ADR-129 HOMECORE-AUTO
|
||||
//!
|
||||
//! Automation engine, trigger evaluator, MiniJinja template evaluator, and
|
||||
//! script action executor for the HOMECORE Home Assistant port.
|
||||
//!
|
||||
//! ## Layout
|
||||
//!
|
||||
//! - [`automation`] — `Automation` struct: id, alias, mode, triggers, conditions, actions
|
||||
//! - [`trigger`] — `Trigger` enum + `EvaluateTrigger` trait
|
||||
//! - [`condition`] — `Condition` enum + async `evaluate` method + `EvalContext`
|
||||
//! - [`action`] — `Action` enum + async `execute` method + `ExecutionContext`
|
||||
//! - [`template`] — MiniJinja environment with HA-compat globals (states, state_attr, is_state, now)
|
||||
//! - [`engine`] — `AutomationEngine`: subscribes to event bus, drives trigger→condition→action pipeline
|
||||
//! - [`error`] — crate-wide `AutomationError`
|
||||
|
||||
pub mod automation;
|
||||
pub mod trigger;
|
||||
pub mod condition;
|
||||
pub mod action;
|
||||
pub mod template;
|
||||
pub mod engine;
|
||||
pub mod error;
|
||||
|
||||
pub use automation::{Automation, RunMode};
|
||||
pub use trigger::{EvaluateTrigger, Trigger, TriggerContext};
|
||||
pub use condition::{Condition, EvalContext};
|
||||
pub use action::{Action, ExecutionContext};
|
||||
pub use template::TemplateEnvironment;
|
||||
pub use engine::AutomationEngine;
|
||||
pub use error::AutomationError;
|
||||
@@ -1,194 +0,0 @@
|
||||
//! MiniJinja-based template environment with HA-compatible globals.
|
||||
//!
|
||||
//! ADR-129 §2.1 — P1 ships four HA globals: `states()`, `state_attr()`,
|
||||
//! `is_state()`, `now()`. The `utcnow()`, `as_timestamp()`, `distance()`,
|
||||
//! and `iif()` globals plus custom filters land in P2.
|
||||
|
||||
use std::sync::Arc;
|
||||
|
||||
use chrono::Utc;
|
||||
use minijinja::{Environment, Value};
|
||||
|
||||
use homecore::{EntityId, StateMachine};
|
||||
|
||||
use crate::error::AutomationError;
|
||||
|
||||
/// MiniJinja environment pre-loaded with HA-compatible globals.
|
||||
///
|
||||
/// Constructed once per `AutomationEngine` and shared via `Arc`. The
|
||||
/// globals close over an `Arc<StateMachine>` so every template render
|
||||
/// sees the live current state.
|
||||
pub struct TemplateEnvironment {
|
||||
env: Environment<'static>,
|
||||
}
|
||||
|
||||
impl TemplateEnvironment {
|
||||
/// Build a new environment backed by the given state machine.
|
||||
pub fn new(states: Arc<StateMachine>) -> Self {
|
||||
let mut env = Environment::new();
|
||||
|
||||
// --- states(entity_id) ---
|
||||
// Returns the current state string of an entity, or "unavailable".
|
||||
let states_sm = Arc::clone(&states);
|
||||
env.add_global(
|
||||
"states",
|
||||
Value::from_function(move |entity_id: String| -> String {
|
||||
EntityId::parse(&entity_id)
|
||||
.ok()
|
||||
.and_then(|eid| states_sm.get(&eid))
|
||||
.map(|s| s.state.clone())
|
||||
.unwrap_or_else(|| "unavailable".into())
|
||||
}),
|
||||
);
|
||||
|
||||
// --- state_attr(entity_id, attribute) ---
|
||||
// Returns an attribute value as a JSON string, or empty string.
|
||||
let attr_sm = Arc::clone(&states);
|
||||
env.add_global(
|
||||
"state_attr",
|
||||
Value::from_function(move |entity_id: String, attr: String| -> String {
|
||||
EntityId::parse(&entity_id)
|
||||
.ok()
|
||||
.and_then(|eid| attr_sm.get(&eid))
|
||||
.and_then(|s| s.attributes.get(&attr).cloned())
|
||||
.map(|v| match v {
|
||||
serde_json::Value::String(s) => s,
|
||||
other => other.to_string(),
|
||||
})
|
||||
.unwrap_or_default()
|
||||
}),
|
||||
);
|
||||
|
||||
// --- is_state(entity_id, state) ---
|
||||
// Returns true if the entity's current state matches the given value.
|
||||
let is_state_sm = Arc::clone(&states);
|
||||
env.add_global(
|
||||
"is_state",
|
||||
Value::from_function(move |entity_id: String, expected: String| -> bool {
|
||||
EntityId::parse(&entity_id)
|
||||
.ok()
|
||||
.and_then(|eid| is_state_sm.get(&eid))
|
||||
.map(|s| s.state == expected)
|
||||
.unwrap_or(false)
|
||||
}),
|
||||
);
|
||||
|
||||
// --- now() ---
|
||||
// Returns the current UTC datetime as an ISO 8601 string.
|
||||
// HA returns a Python datetime; MiniJinja returns a string which
|
||||
// templates can further format with the `strftime` filter.
|
||||
env.add_global(
|
||||
"now",
|
||||
Value::from_function(|| -> String {
|
||||
Utc::now().format("%Y-%m-%dT%H:%M:%S%.6f+00:00").to_string()
|
||||
}),
|
||||
);
|
||||
|
||||
Self { env }
|
||||
}
|
||||
|
||||
/// Render a template string and return the string output.
|
||||
pub fn render(&self, template_str: &str) -> Result<String, AutomationError> {
|
||||
// Wrap bare expressions like `{{ states('light.kitchen') }}`
|
||||
// in a minimal template wrapper.
|
||||
let tmpl = self
|
||||
.env
|
||||
.template_from_str(template_str)
|
||||
.map_err(|e| AutomationError::TemplateRender(e.to_string()))?;
|
||||
tmpl.render(())
|
||||
.map_err(|e| AutomationError::TemplateRender(e.to_string()))
|
||||
}
|
||||
|
||||
/// Render a template and interpret the output as a boolean.
|
||||
/// "true", "1", "yes", "on" → true. Everything else → false.
|
||||
pub fn render_bool(&self, template_str: &str) -> Result<bool, AutomationError> {
|
||||
let raw = self.render(template_str)?;
|
||||
let v = raw.trim().to_ascii_lowercase();
|
||||
Ok(matches!(v.as_str(), "true" | "1" | "yes" | "on"))
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use homecore::{Context, EntityId, StateMachine};
|
||||
use std::sync::Arc;
|
||||
|
||||
fn sm_with(entity_id: &str, state: &str, attrs: serde_json::Value) -> Arc<StateMachine> {
|
||||
let sm = Arc::new(StateMachine::new());
|
||||
sm.set(EntityId::parse(entity_id).unwrap(), state, attrs, Context::new());
|
||||
sm
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn states_global_returns_current_state() {
|
||||
let sm = sm_with("light.kitchen", "on", serde_json::json!({}));
|
||||
let env = TemplateEnvironment::new(sm);
|
||||
let out = env.render("{{ states('light.kitchen') }}").unwrap();
|
||||
assert_eq!(out.trim(), "on");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn states_global_unknown_entity_returns_unavailable() {
|
||||
let sm = Arc::new(StateMachine::new());
|
||||
let env = TemplateEnvironment::new(sm);
|
||||
let out = env.render("{{ states('sensor.unknown') }}").unwrap();
|
||||
assert_eq!(out.trim(), "unavailable");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn state_attr_returns_attribute_value() {
|
||||
let sm = sm_with(
|
||||
"light.kitchen",
|
||||
"on",
|
||||
serde_json::json!({"brightness": 200}),
|
||||
);
|
||||
let env = TemplateEnvironment::new(sm);
|
||||
let out = env.render("{{ state_attr('light.kitchen', 'brightness') }}").unwrap();
|
||||
assert_eq!(out.trim(), "200");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn is_state_global_true_when_matches() {
|
||||
let sm = sm_with("switch.fan", "on", serde_json::json!({}));
|
||||
let env = TemplateEnvironment::new(sm);
|
||||
let out = env.render("{{ is_state('switch.fan', 'on') }}").unwrap();
|
||||
assert_eq!(out.trim(), "true");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn is_state_global_false_when_no_match() {
|
||||
let sm = sm_with("switch.fan", "off", serde_json::json!({}));
|
||||
let env = TemplateEnvironment::new(sm);
|
||||
let out = env.render("{{ is_state('switch.fan', 'on') }}").unwrap();
|
||||
assert_eq!(out.trim(), "false");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn now_global_returns_timestamp_string() {
|
||||
let sm = Arc::new(StateMachine::new());
|
||||
let env = TemplateEnvironment::new(sm);
|
||||
let out = env.render("{{ now() }}").unwrap();
|
||||
// Should be an ISO 8601 datetime string containing 'T'
|
||||
assert!(out.contains('T'), "now() returned: {out}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn render_bool_true_values() {
|
||||
let sm = Arc::new(StateMachine::new());
|
||||
let env = TemplateEnvironment::new(sm);
|
||||
for tmpl in &["true", "1", "yes", "on"] {
|
||||
let result = env.render_bool(tmpl).unwrap();
|
||||
assert!(result, "expected true for: {tmpl}");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn render_bool_false_for_other() {
|
||||
let sm = Arc::new(StateMachine::new());
|
||||
let env = TemplateEnvironment::new(sm);
|
||||
assert!(!env.render_bool("false").unwrap());
|
||||
assert!(!env.render_bool("0").unwrap());
|
||||
assert!(!env.render_bool("off").unwrap());
|
||||
}
|
||||
}
|
||||
@@ -1,296 +0,0 @@
|
||||
//! `Trigger` enum and `EvaluateTrigger` trait.
|
||||
//!
|
||||
//! Covers the four most common HA trigger platforms as required by ADR-129 P1:
|
||||
//! `state`, `numeric_state`, `time`, and `event`. Additional platforms land
|
||||
//! in P2 (template, zone, sun, MQTT, webhook, etc.).
|
||||
|
||||
use async_trait::async_trait;
|
||||
use chrono::{DateTime, Utc};
|
||||
use serde::{Deserialize, Serialize};
|
||||
use std::sync::Arc;
|
||||
|
||||
use homecore::{EntityId, State};
|
||||
|
||||
/// Context produced by a fired trigger. Passed into condition evaluation and
|
||||
/// template rendering as `trigger.*` variables.
|
||||
#[derive(Clone, Debug)]
|
||||
pub struct TriggerContext {
|
||||
/// Which trigger platform fired.
|
||||
pub platform: String,
|
||||
/// Entity ID (for state / numeric_state triggers).
|
||||
pub entity_id: Option<EntityId>,
|
||||
/// New state snapshot (for state / numeric_state triggers).
|
||||
pub to_state: Option<Arc<State>>,
|
||||
/// Previous state snapshot (for state / numeric_state triggers).
|
||||
pub from_state: Option<Arc<State>>,
|
||||
/// When the trigger fired.
|
||||
pub fired_at: DateTime<Utc>,
|
||||
/// Event type (for event triggers).
|
||||
pub event_type: Option<String>,
|
||||
}
|
||||
|
||||
impl TriggerContext {
|
||||
pub fn state_changed(
|
||||
entity_id: EntityId,
|
||||
from: Option<Arc<State>>,
|
||||
to: Option<Arc<State>>,
|
||||
) -> Self {
|
||||
Self {
|
||||
platform: "state".into(),
|
||||
entity_id: Some(entity_id),
|
||||
to_state: to,
|
||||
from_state: from,
|
||||
fired_at: Utc::now(),
|
||||
event_type: None,
|
||||
}
|
||||
}
|
||||
|
||||
pub fn event(event_type: impl Into<String>) -> Self {
|
||||
Self {
|
||||
platform: "event".into(),
|
||||
entity_id: None,
|
||||
to_state: None,
|
||||
from_state: None,
|
||||
fired_at: Utc::now(),
|
||||
event_type: Some(event_type.into()),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Async evaluation trait. Each trigger variant implements this to decide
|
||||
/// whether a given `TriggerContext` matches its configuration.
|
||||
#[async_trait]
|
||||
pub trait EvaluateTrigger: Send + Sync {
|
||||
async fn matches(&self, ctx: &TriggerContext) -> bool;
|
||||
}
|
||||
|
||||
/// Trigger configuration. Deserialized from YAML `trigger:` blocks.
|
||||
///
|
||||
/// Only four platforms are implemented in P1 (ADR-129 §6 Phase 1).
|
||||
#[derive(Clone, Debug, Serialize, Deserialize)]
|
||||
#[serde(tag = "platform", rename_all = "snake_case")]
|
||||
pub enum Trigger {
|
||||
/// Fires when an entity's state changes.
|
||||
State {
|
||||
entity_id: EntityId,
|
||||
/// Optional: only fire if state was previously this value.
|
||||
#[serde(default)]
|
||||
from: Option<String>,
|
||||
/// Optional: only fire if state transitions to this value.
|
||||
#[serde(default)]
|
||||
to: Option<String>,
|
||||
},
|
||||
/// Fires when an entity's numeric state crosses a threshold.
|
||||
NumericState {
|
||||
entity_id: EntityId,
|
||||
/// Fire when value rises above this threshold.
|
||||
#[serde(default)]
|
||||
above: Option<f64>,
|
||||
/// Fire when value drops below this threshold.
|
||||
#[serde(default)]
|
||||
below: Option<f64>,
|
||||
},
|
||||
/// Fires at a specific time of day (HH:MM:SS).
|
||||
Time {
|
||||
at: String,
|
||||
},
|
||||
/// Fires when a named domain event is published on the event bus.
|
||||
Event {
|
||||
event_type: String,
|
||||
},
|
||||
}
|
||||
|
||||
impl Trigger {
|
||||
/// Synchronous check — does this trigger configuration match the provided
|
||||
/// context? Used directly in tests and by the engine's event loop.
|
||||
pub fn matches_sync(&self, ctx: &TriggerContext) -> bool {
|
||||
match self {
|
||||
Trigger::State { entity_id, from, to } => {
|
||||
let eid_match = ctx.entity_id.as_ref().map_or(false, |e| e == entity_id);
|
||||
if !eid_match {
|
||||
return false;
|
||||
}
|
||||
if let Some(expected_from) = from {
|
||||
let actual_from = ctx.from_state.as_ref().map(|s| s.state.as_str()).unwrap_or("unavailable");
|
||||
if actual_from != expected_from.as_str() {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
if let Some(expected_to) = to {
|
||||
let actual_to = ctx.to_state.as_ref().map(|s| s.state.as_str()).unwrap_or("unavailable");
|
||||
if actual_to != expected_to.as_str() {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
true
|
||||
}
|
||||
Trigger::NumericState { entity_id, above, below } => {
|
||||
let eid_match = ctx.entity_id.as_ref().map_or(false, |e| e == entity_id);
|
||||
if !eid_match {
|
||||
return false;
|
||||
}
|
||||
let value: f64 = ctx
|
||||
.to_state
|
||||
.as_ref()
|
||||
.and_then(|s| s.state.parse().ok())
|
||||
.unwrap_or(f64::NAN);
|
||||
if value.is_nan() {
|
||||
return false;
|
||||
}
|
||||
if let Some(a) = above {
|
||||
if value <= *a {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
if let Some(b) = below {
|
||||
if value >= *b {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
true
|
||||
}
|
||||
Trigger::Time { .. } => {
|
||||
// Time triggers are evaluated by the engine's timer task, not here.
|
||||
false
|
||||
}
|
||||
Trigger::Event { event_type } => {
|
||||
ctx.event_type.as_deref() == Some(event_type.as_str())
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl EvaluateTrigger for Trigger {
|
||||
async fn matches(&self, ctx: &TriggerContext) -> bool {
|
||||
self.matches_sync(ctx)
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use homecore::{Context, EntityId, State};
|
||||
use std::sync::Arc;
|
||||
|
||||
fn make_state(entity_id: &str, state: &str) -> Arc<State> {
|
||||
Arc::new(State::new(
|
||||
EntityId::parse(entity_id).unwrap(),
|
||||
state,
|
||||
serde_json::json!({}),
|
||||
Context::new(),
|
||||
))
|
||||
}
|
||||
|
||||
fn state_ctx(entity_id: &str, from: &str, to: &str) -> TriggerContext {
|
||||
let eid = EntityId::parse(entity_id).unwrap();
|
||||
TriggerContext::state_changed(
|
||||
eid,
|
||||
Some(make_state(entity_id, from)),
|
||||
Some(make_state(entity_id, to)),
|
||||
)
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn state_trigger_exact_from_to_match() {
|
||||
let trigger = Trigger::State {
|
||||
entity_id: EntityId::parse("light.kitchen").unwrap(),
|
||||
from: Some("off".into()),
|
||||
to: Some("on".into()),
|
||||
};
|
||||
let ctx = state_ctx("light.kitchen", "off", "on");
|
||||
assert!(trigger.matches_sync(&ctx));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn state_trigger_wrong_entity_no_match() {
|
||||
let trigger = Trigger::State {
|
||||
entity_id: EntityId::parse("light.kitchen").unwrap(),
|
||||
from: None,
|
||||
to: Some("on".into()),
|
||||
};
|
||||
let ctx = state_ctx("switch.hallway", "off", "on");
|
||||
assert!(!trigger.matches_sync(&ctx));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn state_trigger_wrong_to_no_match() {
|
||||
let trigger = Trigger::State {
|
||||
entity_id: EntityId::parse("light.kitchen").unwrap(),
|
||||
from: None,
|
||||
to: Some("on".into()),
|
||||
};
|
||||
let ctx = state_ctx("light.kitchen", "on", "off");
|
||||
assert!(!trigger.matches_sync(&ctx));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn state_trigger_no_constraints_matches_any_change() {
|
||||
let trigger = Trigger::State {
|
||||
entity_id: EntityId::parse("light.kitchen").unwrap(),
|
||||
from: None,
|
||||
to: None,
|
||||
};
|
||||
let ctx = state_ctx("light.kitchen", "off", "on");
|
||||
assert!(trigger.matches_sync(&ctx));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn numeric_trigger_above_threshold_fires() {
|
||||
let trigger = Trigger::NumericState {
|
||||
entity_id: EntityId::parse("sensor.temperature").unwrap(),
|
||||
above: Some(25.0),
|
||||
below: None,
|
||||
};
|
||||
let mut ctx = state_ctx("sensor.temperature", "20", "26");
|
||||
ctx.to_state = Some(make_state("sensor.temperature", "26"));
|
||||
assert!(trigger.matches_sync(&ctx));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn numeric_trigger_below_threshold_no_fire() {
|
||||
let trigger = Trigger::NumericState {
|
||||
entity_id: EntityId::parse("sensor.temperature").unwrap(),
|
||||
above: Some(25.0),
|
||||
below: None,
|
||||
};
|
||||
let mut ctx = state_ctx("sensor.temperature", "20", "24");
|
||||
ctx.to_state = Some(make_state("sensor.temperature", "24"));
|
||||
assert!(!trigger.matches_sync(&ctx));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn numeric_trigger_between_bounds() {
|
||||
let trigger = Trigger::NumericState {
|
||||
entity_id: EntityId::parse("sensor.humidity").unwrap(),
|
||||
above: Some(30.0),
|
||||
below: Some(80.0),
|
||||
};
|
||||
let mut ctx = state_ctx("sensor.humidity", "20", "50");
|
||||
ctx.to_state = Some(make_state("sensor.humidity", "50"));
|
||||
assert!(trigger.matches_sync(&ctx));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn event_trigger_matches_type() {
|
||||
let trigger = Trigger::Event { event_type: "my_custom_event".into() };
|
||||
let ctx = TriggerContext::event("my_custom_event");
|
||||
assert!(trigger.matches_sync(&ctx));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn event_trigger_no_match_wrong_type() {
|
||||
let trigger = Trigger::Event { event_type: "my_custom_event".into() };
|
||||
let ctx = TriggerContext::event("other_event");
|
||||
assert!(!trigger.matches_sync(&ctx));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn evaluate_trigger_trait_object() {
|
||||
let trigger: Box<dyn EvaluateTrigger> = Box::new(Trigger::Event {
|
||||
event_type: "boot".into(),
|
||||
});
|
||||
let ctx = TriggerContext::event("boot");
|
||||
assert!(trigger.matches(&ctx).await);
|
||||
}
|
||||
}
|
||||
@@ -1,36 +0,0 @@
|
||||
# homecore-hap — Apple Home HomeKit Accessory Protocol bridge (ADR-125 P1 scaffold)
|
||||
#
|
||||
# P1 ships the trait surface, accessory/characteristic types, entity→HAP mapping,
|
||||
# bridge API, and an mDNS-advertise stub. The actual HAP-1.1 server and real
|
||||
# mDNS integration are feature-gated to P2 via the `hap-server` feature flag.
|
||||
|
||||
[package]
|
||||
name = "homecore-hap"
|
||||
version = "0.1.0-alpha.0"
|
||||
edition = "2021"
|
||||
license = "MIT"
|
||||
authors = ["rUv <ruv@ruv.net>", "HOMECORE Contributors"]
|
||||
description = "Apple Home HomeKit Accessory Protocol bridge — ADR-125 P1 scaffold"
|
||||
repository = "https://github.com/ruvnet/wifi-densepose"
|
||||
|
||||
[lib]
|
||||
name = "homecore_hap"
|
||||
path = "src/lib.rs"
|
||||
|
||||
[features]
|
||||
default = []
|
||||
# P2: gates the actual hap = "0.1" crate integration + real mDNS via mdns-sd
|
||||
hap-server = []
|
||||
|
||||
[dependencies]
|
||||
homecore = { path = "../homecore" }
|
||||
tokio = { version = "1", features = ["sync", "rt", "rt-multi-thread", "time", "macros"] }
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = "1"
|
||||
thiserror = "2"
|
||||
tracing = "0.1"
|
||||
async-trait = "0.1"
|
||||
uuid = { version = "1", features = ["v4", "serde"] }
|
||||
|
||||
[dev-dependencies]
|
||||
tokio = { version = "1", features = ["sync", "rt", "rt-multi-thread", "time", "macros", "test-util"] }
|
||||
@@ -1,121 +0,0 @@
|
||||
# homecore-hap
|
||||
|
||||
Apple Home HomeKit Accessory Protocol bridge for HOMECORE with HAP-1.1 trait surface and mDNS advertisement (P2).
|
||||
|
||||
[](https://crates.io/crates/homecore-hap)
|
||||
|
||||
|
||||
[](https://github.com/ruvnet/RuView)
|
||||
[](../../docs/adr/ADR-125-homecore-apple-home-homekit-bridge.md)
|
||||
|
||||
**P1 scaffold**: trait surface for HAP accessories + characteristics, entity→HAP mapping rules, and bridge ownership. The actual HAP-1.1 TLS server and real mDNS integration are gated behind `--features hap-server` (P2).
|
||||
|
||||
## What this crate does
|
||||
|
||||
`homecore-hap` bridges HOMECORE entity state to Apple HomeKit Accessory Protocol (HAP-1.1), allowing HomeKit-native apps (Home, Control Center, Siri) to control HOMECORE devices. It provides:
|
||||
|
||||
- **HapAccessoryType enum** — 11 accessory types matching HA's HomeKit integration (`Light`, `Switch`, `Thermostat`, `Lock`, `Door`, etc.)
|
||||
- **HapCharacteristic enum** — HAP characteristic types (`On`, `Brightness`, `Temperature`, `TargetLockState`, etc.)
|
||||
- **EntityToAccessoryMapper** — bidirectional rules for mapping HOMECORE entities to HAP accessories (e.g., `light.kitchen` → `Light` accessory + `On` + `Brightness` characteristics)
|
||||
- **HapBridge** — owns and exposes a collection of mapped accessories over HAP
|
||||
- **MdnsAdvertiser trait** — abstraction over mDNS advertisement; P1 ships `NullAdvertiser` (no-op), P2 adds real mDNS via `mdns-sd`
|
||||
- **RuViewToHapMapper** — bridges RuView sensing data (temperature, humidity, occupancy) to HAP characteristics
|
||||
|
||||
The bridge itself is a HAP Accessory Bridge (HAP-1.1 spec §8.3), advertising a single service with characteristic slots for each exposed accessory.
|
||||
|
||||
## Features
|
||||
|
||||
- **11 accessory types** — Light, Switch, Thermostat, Door, Lock, Window, Blind, Outlet, Fan, Sensor, SecuritySystem
|
||||
- **Bi-directional mapping** — HOMECORE entity state ↔ HAP characteristic values with type-safe enums
|
||||
- **HAP-1.1 spec compliance** — characteristic types and permissions match HomeKit's published spec
|
||||
- **Trait-based advertisement** — `MdnsAdvertiser` abstraction; swappable implementations (null, real mDNS, etc.)
|
||||
- **RuView integration** — maps WiFi sensing data (occupancy, temperature, vital signs) to HomeKit sensor accessories
|
||||
- **No TLS server in P1** — bridge compiles and tests pass with `--no-default-features`; real server lands in P2 with `--features hap-server`
|
||||
- **Home.app compatible** — exposed accessories appear in Home app on any HomeKit hub (Apple TV, HomePod, HomePod mini)
|
||||
|
||||
## Capabilities
|
||||
|
||||
| Capability | Type | Method | Notes |
|
||||
|------------|------|--------|-------|
|
||||
| Define accessory type | Trait | `HapAccessoryType::Light` etc. (11 variants) | Enum; no instantiation yet (P1) |
|
||||
| Define characteristic | Trait | `HapCharacteristic::On`, `Brightness`, etc. | Enum; values encoded as HAP TLV |
|
||||
| Map entity to accessory | Mapping | `EntityToAccessoryMapper::map_light()` | Takes `EntityId` + `State`; returns `HapAccessory` |
|
||||
| Expose accessory | Bridge | `HapBridge::expose(accessory)` | Adds to the bridge's characteristic list |
|
||||
| Advertise bridge | mDNS | `NullAdvertiser::advertise()` (P1) | No-op stub; real mDNS in P2 |
|
||||
| Advertise bridge (P2) | mDNS | `mdns_sd::ServiceInstanceBuilder` | Real mDNS via `--features hap-server` |
|
||||
| Bridge state query | Bridge | `HapBridge::list_accessories()` | Returns exposed accessories + their characteristics |
|
||||
| Characteristic write | Characteristic | HAP `WriteRequest` TLV (P2) | Home.app button press → service call |
|
||||
| Characteristic read | Characteristic | HAP `ReadResponse` TLV (P2) | Home.app query → current entity state |
|
||||
|
||||
## Comparison to Home Assistant
|
||||
|
||||
| Aspect | Home Assistant | homecore-hap |
|
||||
|--------|----------------|--------------|
|
||||
| Framework | HA's `hap-python` (pure Python) | Rust 1.89+ with HAP trait abstraction |
|
||||
| Server type | Python asyncio HAP-1.1 server | TLS server trait (P2); stub in P1 |
|
||||
| Accessory types | 30+ (Light, Switch, Thermostat, etc.) | 11 (Light, Switch, Thermostat, Door, Lock, Window, Blind, Outlet, Fan, Sensor, SecuritySystem) |
|
||||
| mDNS | mdns-py broadcast via asyncio | Abstraction + real mDNS (P2) or no-op stub (P1) |
|
||||
| Entity filtering | YAML `include_domains` + `exclude_entities` | Mapper rules (planned P2) |
|
||||
| HomeKit hub requirement | Yes (for remote access) | Yes (same as HomeKit) |
|
||||
| Pairing code generation | Automatic (HA web UI) | Manual setup code (P2) |
|
||||
| Characteristic persistence | HomeKit cloud only | Paired with homecore state machine |
|
||||
|
||||
## Performance
|
||||
|
||||
- **Entity→HAP mapping** — < 100 μs per entity (enum lookups + type conversions)
|
||||
- **HAP write latency** — ~10 ms (TLS decrypt + characteristic parse + entity state set); bounded by homecore state machine lock contention
|
||||
- **mDNS advertisement** (P2) — ~50 ms multicast broadcast; periodic rediscovery on network change
|
||||
- **Memory overhead per accessory** — ~500 bytes (enum + characteristic slots + metadata)
|
||||
- **No per-crate benchmarks yet** — a follow-up issue tracks baseline measurements
|
||||
|
||||
## Usage
|
||||
|
||||
Mapping an entity (P1):
|
||||
|
||||
```rust
|
||||
use homecore_hap::{EntityToAccessoryMapper, HapBridge, HapAccessoryType};
|
||||
use homecore::{EntityId, State};
|
||||
use std::collections::HashMap;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() {
|
||||
let light_id = EntityId::parse("light.kitchen").unwrap();
|
||||
let state = State::new("on", HashMap::new());
|
||||
|
||||
// Map the entity to a HAP Light accessory
|
||||
let mut mapper = EntityToAccessoryMapper::new();
|
||||
if let Ok(accessory) = mapper.map_light(&light_id, &state) {
|
||||
println!("Mapped to HAP: {:?}", accessory.accessory_type);
|
||||
|
||||
// Expose it via the bridge
|
||||
let mut bridge = HapBridge::new();
|
||||
bridge.expose(accessory);
|
||||
println!("Exposed {} accessories", bridge.list_accessories().len());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Real HAP server (P2, via `--features hap-server`):
|
||||
|
||||
```bash
|
||||
cargo build -p homecore-hap --features hap-server
|
||||
# The server will advertise over mDNS and accept HomeKit pairing requests
|
||||
```
|
||||
|
||||
## Relation to other HOMECORE crates
|
||||
|
||||
```
|
||||
homecore-hap (HomeKit bridge)
|
||||
├─ homecore (state machine; bridge reads entity states)
|
||||
├─ homecore-api (exposes HAP state via REST /api for remote debugging)
|
||||
├─ homecore-server (starts the bridge on homecore init)
|
||||
└─ homecore-automation (can trigger state changes via service calls)
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [ADR-125: HOMECORE Apple Home / HomeKit Bridge](../../docs/adr/ADR-125-homecore-apple-home-homekit-bridge.md)
|
||||
- [ADR-126: HOMECORE Home Assistant Port (master)](../../docs/adr/ADR-126-homecore-home-assistant-port.md)
|
||||
- [HomeKit Accessory Protocol Specification (HAP-1.1)](https://developer.apple.com/homekit/)
|
||||
- [user-guide-apple-homepod.md](../../docs/user-guide-apple-homepod.md)
|
||||
- [README — wifi-densepose](../../../README.md)
|
||||
@@ -1,124 +0,0 @@
|
||||
//! HAP service type and characteristic enum catalogues.
|
||||
//!
|
||||
//! Mirrors the HAP-1.1 service/characteristic namespace used by Apple Home
|
||||
//! and the `hap` crate (https://crates.io/crates/hap). Keeping these as
|
||||
//! plain Rust enums in P1 avoids the heavy `hap` dep until P2.
|
||||
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
/// HAP service types exposed by the RuView bridge.
|
||||
///
|
||||
/// Derived from HomeKit Accessory Protocol Specification §8 (service
|
||||
/// definitions) and cross-checked against HA's `homekit` integration
|
||||
/// service catalog.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
|
||||
pub enum HapAccessoryType {
|
||||
/// HAP `Lightbulb` service — maps `light.*` entities.
|
||||
Lightbulb,
|
||||
/// HAP `Switch` service — maps generic boolean `switch.*` entities.
|
||||
Switch,
|
||||
/// HAP `OccupancySensor` — maps presence / occupancy binary sensors.
|
||||
OccupancySensor,
|
||||
/// HAP `MotionSensor` — maps motion binary sensors + RuView motion.
|
||||
MotionSensor,
|
||||
/// HAP `TemperatureSensor` — maps `sensor.*temperature*` entities.
|
||||
TemperatureSensor,
|
||||
/// HAP `HumiditySensor` — maps `sensor.*humidity*` entities.
|
||||
HumiditySensor,
|
||||
/// HAP `LeakSensor` — maps abnormal event sensors; used for fall detection
|
||||
/// following HA's homekit_controller convention (HAP §11.42).
|
||||
LeakSensor,
|
||||
/// HAP `ContactSensor` — maps door / window binary sensors.
|
||||
ContactSensor,
|
||||
/// HAP `Door` service — maps `cover.*door*` entities.
|
||||
Door,
|
||||
/// HAP `LockMechanism` service — maps `lock.*` entities.
|
||||
Lock,
|
||||
/// HAP `SecuritySystem` service — maps alarm / security panel entities.
|
||||
SecuritySystem,
|
||||
}
|
||||
|
||||
impl HapAccessoryType {
|
||||
/// All defined variants — used in tests and for UI enumeration.
|
||||
pub const ALL: &'static [HapAccessoryType] = &[
|
||||
HapAccessoryType::Lightbulb,
|
||||
HapAccessoryType::Switch,
|
||||
HapAccessoryType::OccupancySensor,
|
||||
HapAccessoryType::MotionSensor,
|
||||
HapAccessoryType::TemperatureSensor,
|
||||
HapAccessoryType::HumiditySensor,
|
||||
HapAccessoryType::LeakSensor,
|
||||
HapAccessoryType::ContactSensor,
|
||||
HapAccessoryType::Door,
|
||||
HapAccessoryType::Lock,
|
||||
HapAccessoryType::SecuritySystem,
|
||||
];
|
||||
}
|
||||
|
||||
/// HAP characteristic identifiers that the bridge reads or writes.
|
||||
///
|
||||
/// Each variant corresponds to one HAP characteristic UUID as specified in
|
||||
/// HomeKit Accessory Protocol Specification §9.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
|
||||
pub enum HapCharacteristic {
|
||||
/// `On` (bool) — Lightbulb / Switch power state.
|
||||
On,
|
||||
/// `Brightness` (uint8, 0–100) — Lightbulb brightness percentage.
|
||||
Brightness,
|
||||
/// `CurrentTemperature` (float, °C) — TemperatureSensor reading.
|
||||
CurrentTemperature,
|
||||
/// `CurrentRelativeHumidity` (float, %) — HumiditySensor reading.
|
||||
CurrentRelativeHumidity,
|
||||
/// `OccupancyDetected` (uint8, 0=not detected, 1=detected).
|
||||
OccupancyDetected,
|
||||
/// `MotionDetected` (bool).
|
||||
MotionDetected,
|
||||
/// `LeakDetected` (uint8, 0=no leak, 1=leak detected). Re-used for falls.
|
||||
LeakDetected,
|
||||
/// `ContactSensorState` (uint8, 0=in contact, 1=not in contact).
|
||||
ContactSensorState,
|
||||
/// `CurrentDoorState` (uint8, HAP §9.30).
|
||||
CurrentDoorState,
|
||||
/// `LockCurrentState` (uint8, HAP §9.56).
|
||||
LockCurrentState,
|
||||
/// `SecuritySystemCurrentState` (uint8, HAP §9.97).
|
||||
SecuritySystemCurrentState,
|
||||
}
|
||||
|
||||
/// Typed value carried by a HAP characteristic update.
|
||||
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
|
||||
pub enum HapCharacteristicValue {
|
||||
Bool(bool),
|
||||
UInt8(u8),
|
||||
Float(f64),
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn all_11_accessory_types_defined() {
|
||||
assert_eq!(HapAccessoryType::ALL.len(), 11);
|
||||
// Spot-check each variant is present.
|
||||
assert!(HapAccessoryType::ALL.contains(&HapAccessoryType::Lightbulb));
|
||||
assert!(HapAccessoryType::ALL.contains(&HapAccessoryType::Switch));
|
||||
assert!(HapAccessoryType::ALL.contains(&HapAccessoryType::OccupancySensor));
|
||||
assert!(HapAccessoryType::ALL.contains(&HapAccessoryType::MotionSensor));
|
||||
assert!(HapAccessoryType::ALL.contains(&HapAccessoryType::TemperatureSensor));
|
||||
assert!(HapAccessoryType::ALL.contains(&HapAccessoryType::HumiditySensor));
|
||||
assert!(HapAccessoryType::ALL.contains(&HapAccessoryType::LeakSensor));
|
||||
assert!(HapAccessoryType::ALL.contains(&HapAccessoryType::ContactSensor));
|
||||
assert!(HapAccessoryType::ALL.contains(&HapAccessoryType::Door));
|
||||
assert!(HapAccessoryType::ALL.contains(&HapAccessoryType::Lock));
|
||||
assert!(HapAccessoryType::ALL.contains(&HapAccessoryType::SecuritySystem));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn characteristic_value_roundtrip_serde() {
|
||||
let v = HapCharacteristicValue::Float(22.5);
|
||||
let json = serde_json::to_string(&v).unwrap();
|
||||
let back: HapCharacteristicValue = serde_json::from_str(&json).unwrap();
|
||||
assert_eq!(v, back);
|
||||
}
|
||||
}
|
||||
@@ -1,196 +0,0 @@
|
||||
//! `HapBridge` — owns the set of HOMECORE entities exposed as HAP accessories.
|
||||
//!
|
||||
//! P1 does not start a real HAP-1.1 server; it ships the API surface so other
|
||||
//! crates (and P2's `hap-server` feature) can register accessories and query
|
||||
//! their current mapping. The actual mDNS + HAP pairing is gated to P2.
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::sync::{Arc, RwLock};
|
||||
|
||||
use homecore::entity::EntityId;
|
||||
|
||||
use crate::accessory::HapAccessoryType;
|
||||
use crate::error::HapError;
|
||||
use crate::mapping::{AccessoryMapping, EntityToAccessoryMapper};
|
||||
use crate::mdns::{HapServiceRecord, MdnsAdvertiser, NullAdvertiser};
|
||||
|
||||
/// One registered HAP accessory — an entity + its last-known mapping.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ExposedAccessory {
|
||||
pub entity_id: EntityId,
|
||||
pub accessory_type: HapAccessoryType,
|
||||
pub mapping: AccessoryMapping,
|
||||
}
|
||||
|
||||
struct BridgeInner {
|
||||
accessories: HashMap<EntityId, ExposedAccessory>,
|
||||
}
|
||||
|
||||
/// The P1 HAP bridge.
|
||||
///
|
||||
/// Call [`HapBridge::add_accessory`] to register entities and
|
||||
/// [`HapBridge::running_accessories`] to read back what is currently
|
||||
/// registered. In P2, `start()` will spawn the `hap` server task.
|
||||
#[derive(Clone)]
|
||||
pub struct HapBridge {
|
||||
inner: Arc<RwLock<BridgeInner>>,
|
||||
advertiser: Arc<dyn MdnsAdvertiser>,
|
||||
pub service_record: HapServiceRecord,
|
||||
}
|
||||
|
||||
impl HapBridge {
|
||||
/// Create a bridge with the given service record and a `NullAdvertiser`
|
||||
/// (P1 default — real mDNS lands in P2).
|
||||
pub fn new(service_record: HapServiceRecord) -> Self {
|
||||
Self::with_advertiser(service_record, Arc::new(NullAdvertiser))
|
||||
}
|
||||
|
||||
/// Create a bridge with a custom `MdnsAdvertiser` (used in tests and P2).
|
||||
pub fn with_advertiser(
|
||||
service_record: HapServiceRecord,
|
||||
advertiser: Arc<dyn MdnsAdvertiser>,
|
||||
) -> Self {
|
||||
Self {
|
||||
inner: Arc::new(RwLock::new(BridgeInner { accessories: HashMap::new() })),
|
||||
advertiser,
|
||||
service_record,
|
||||
}
|
||||
}
|
||||
|
||||
/// Register an entity as a HAP accessory.
|
||||
///
|
||||
/// The entity's current mapping is computed from `state`; call
|
||||
/// `update_accessory` on each `StateChanged` event to keep it fresh.
|
||||
///
|
||||
/// Returns `HapError::AlreadyRegistered` if the entity is already
|
||||
/// registered. Call `remove_accessory` first to replace it.
|
||||
pub fn add_accessory(
|
||||
&self,
|
||||
entity_id: &EntityId,
|
||||
state: &homecore::entity::State,
|
||||
) -> Result<(), HapError> {
|
||||
let mapping = EntityToAccessoryMapper::map(entity_id, state)?;
|
||||
let accessory_type = mapping.accessory_type;
|
||||
let exposed = ExposedAccessory {
|
||||
entity_id: entity_id.clone(),
|
||||
accessory_type,
|
||||
mapping,
|
||||
};
|
||||
let mut inner = self.inner.write().unwrap();
|
||||
if inner.accessories.contains_key(entity_id) {
|
||||
return Err(HapError::AlreadyRegistered(entity_id.as_str().to_owned()));
|
||||
}
|
||||
inner.accessories.insert(entity_id.clone(), exposed);
|
||||
tracing::debug!(entity = %entity_id, ?accessory_type, "HAP accessory registered");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Remove a registered accessory.
|
||||
///
|
||||
/// Returns `HapError::EntityNotFound` if the entity was not registered.
|
||||
pub fn remove_accessory(&self, entity_id: &EntityId) -> Result<(), HapError> {
|
||||
let mut inner = self.inner.write().unwrap();
|
||||
if inner.accessories.remove(entity_id).is_none() {
|
||||
return Err(HapError::EntityNotFound(entity_id.as_str().to_owned()));
|
||||
}
|
||||
tracing::debug!(entity = %entity_id, "HAP accessory removed");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Snapshot all currently registered accessories.
|
||||
pub fn running_accessories(&self) -> Vec<ExposedAccessory> {
|
||||
self.inner.read().unwrap().accessories.values().cloned().collect()
|
||||
}
|
||||
|
||||
/// Number of registered accessories.
|
||||
pub fn len(&self) -> usize {
|
||||
self.inner.read().unwrap().accessories.len()
|
||||
}
|
||||
|
||||
pub fn is_empty(&self) -> bool {
|
||||
self.len() == 0
|
||||
}
|
||||
|
||||
/// P2 stub — will start the HAP-1.1 server + mDNS advertisement.
|
||||
/// In P1 this only fires the null advertiser.
|
||||
pub async fn start(&self) -> Result<(), HapError> {
|
||||
self.advertiser.advertise(&self.service_record).await?;
|
||||
tracing::info!(
|
||||
instance = %self.service_record.instance_name,
|
||||
port = self.service_record.port,
|
||||
"HapBridge started (P1 — no real HAP server; mDNS stub only)"
|
||||
);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Graceful shutdown — retracts mDNS advertisement.
|
||||
pub async fn stop(&self) -> Result<(), HapError> {
|
||||
self.advertiser.retract(&self.service_record.instance_name).await?;
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use homecore::entity::{EntityId, State};
|
||||
use homecore::event::Context;
|
||||
|
||||
fn make_bridge() -> HapBridge {
|
||||
HapBridge::new(HapServiceRecord {
|
||||
instance_name: "RuView Sense".into(),
|
||||
port: 51826,
|
||||
setup_code: "111-22-333".into(),
|
||||
device_id: "AA:BB:CC:DD:EE:FF".into(),
|
||||
})
|
||||
}
|
||||
|
||||
fn light_state(name: &str, on: bool, brightness: u8) -> (EntityId, State) {
|
||||
let eid = EntityId::parse(&format!("light.{name}")).unwrap();
|
||||
let attrs = serde_json::json!({"brightness": brightness});
|
||||
let s = State::new(eid.clone(), if on { "on" } else { "off" }, attrs, Context::default());
|
||||
(eid, s)
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn add_remove_roundtrip() {
|
||||
let bridge = make_bridge();
|
||||
let (eid, s) = light_state("kitchen", true, 200);
|
||||
|
||||
assert!(bridge.is_empty());
|
||||
bridge.add_accessory(&eid, &s).unwrap();
|
||||
assert_eq!(bridge.len(), 1);
|
||||
|
||||
let acc = bridge.running_accessories();
|
||||
assert_eq!(acc.len(), 1);
|
||||
assert_eq!(acc[0].entity_id, eid);
|
||||
assert_eq!(acc[0].accessory_type, HapAccessoryType::Lightbulb);
|
||||
|
||||
bridge.remove_accessory(&eid).unwrap();
|
||||
assert!(bridge.is_empty());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn add_duplicate_returns_error() {
|
||||
let bridge = make_bridge();
|
||||
let (eid, s) = light_state("kitchen", true, 200);
|
||||
bridge.add_accessory(&eid, &s).unwrap();
|
||||
let err = bridge.add_accessory(&eid, &s).unwrap_err();
|
||||
assert!(matches!(err, HapError::AlreadyRegistered(_)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn remove_nonexistent_returns_error() {
|
||||
let bridge = make_bridge();
|
||||
let eid = EntityId::parse("light.ghost").unwrap();
|
||||
let err = bridge.remove_accessory(&eid).unwrap_err();
|
||||
assert!(matches!(err, HapError::EntityNotFound(_)));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn start_stop_with_null_advertiser() {
|
||||
let bridge = make_bridge();
|
||||
bridge.start().await.unwrap();
|
||||
bridge.stop().await.unwrap();
|
||||
}
|
||||
}
|
||||
@@ -1,22 +0,0 @@
|
||||
//! Unified error type for `homecore-hap`.
|
||||
|
||||
use thiserror::Error;
|
||||
|
||||
/// Errors produced by the HAP bridge and its sub-components.
|
||||
#[derive(Debug, Error)]
|
||||
pub enum HapError {
|
||||
#[error("entity not found: {0}")]
|
||||
EntityNotFound(String),
|
||||
|
||||
#[error("entity {entity_id} cannot be mapped to a HAP accessory type: {reason}")]
|
||||
UnmappableEntity { entity_id: String, reason: String },
|
||||
|
||||
#[error("accessory already registered: {0}")]
|
||||
AlreadyRegistered(String),
|
||||
|
||||
#[error("mDNS advertiser error: {0}")]
|
||||
MdnsError(String),
|
||||
|
||||
#[error("bridge not running")]
|
||||
NotRunning,
|
||||
}
|
||||
@@ -1,34 +0,0 @@
|
||||
//! `homecore-hap` — Apple Home HomeKit Accessory Protocol bridge (ADR-125).
|
||||
//!
|
||||
//! # P1 scope
|
||||
//!
|
||||
//! Ships the trait surface and type definitions needed to map HOMECORE entity
|
||||
//! states onto HAP accessory / characteristic values. The actual HAP-1.1 TLS
|
||||
//! server and real mDNS advertisement are gated behind the `hap-server`
|
||||
//! feature (P2). P1 ships `NullAdvertiser` (no-op) so the bridge compiles and
|
||||
//! all tests pass with `--no-default-features`.
|
||||
//!
|
||||
//! # Module layout
|
||||
//!
|
||||
//! | Module | Purpose |
|
||||
//! |--------|---------|
|
||||
//! | [`accessory`] | HAP service / characteristic enum catalogue |
|
||||
//! | [`mapping`] | `EntityToAccessoryMapper` — HOMECORE entity → HAP |
|
||||
//! | [`bridge`] | `HapBridge` — owns exposed accessories |
|
||||
//! | [`mdns`] | `MdnsAdvertiser` trait + `NullAdvertiser` stub |
|
||||
//! | [`ruview`] | `RuViewToHapMapper` — sensing primitives → HAP |
|
||||
//! | [`error`] | Unified `HapError` type |
|
||||
|
||||
pub mod accessory;
|
||||
pub mod bridge;
|
||||
pub mod error;
|
||||
pub mod mapping;
|
||||
pub mod mdns;
|
||||
pub mod ruview;
|
||||
|
||||
pub use accessory::{HapAccessoryType, HapCharacteristic, HapCharacteristicValue};
|
||||
pub use bridge::{ExposedAccessory, HapBridge};
|
||||
pub use error::HapError;
|
||||
pub use mapping::EntityToAccessoryMapper;
|
||||
pub use mdns::{MdnsAdvertiser, NullAdvertiser};
|
||||
pub use ruview::RuViewToHapMapper;
|
||||
@@ -1,273 +0,0 @@
|
||||
//! HOMECORE entity → HAP accessory type + characteristic value mapping.
|
||||
//!
|
||||
//! Mirrors the HA `homekit` integration's mapping table
|
||||
//! (homeassistant/components/homekit/type_*.py) for the entity domains and
|
||||
//! device classes handled in P1.
|
||||
|
||||
use serde_json::Value;
|
||||
|
||||
use homecore::entity::{EntityId, State};
|
||||
|
||||
use crate::accessory::{HapAccessoryType, HapCharacteristic, HapCharacteristicValue};
|
||||
use crate::error::HapError;
|
||||
|
||||
/// Result of mapping one HOMECORE entity state to the HAP layer.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct AccessoryMapping {
|
||||
/// HAP service type to advertise for this entity.
|
||||
pub accessory_type: HapAccessoryType,
|
||||
/// Characteristic key/value pairs to set on the HAP service.
|
||||
pub characteristics: Vec<(HapCharacteristic, HapCharacteristicValue)>,
|
||||
}
|
||||
|
||||
/// Maps a HOMECORE entity `(EntityId, State)` pair to a `HapAccessoryType`
|
||||
/// and its current characteristic values.
|
||||
///
|
||||
/// Rule table (mirrors HA homekit_controller mapping):
|
||||
///
|
||||
/// | Domain | device_class | HAP service |
|
||||
/// |--------|-------------|-------------|
|
||||
/// | `light` | — | Lightbulb |
|
||||
/// | `switch` | — | Switch |
|
||||
/// | `binary_sensor` | `occupancy` | OccupancySensor |
|
||||
/// | `binary_sensor` | `motion` | MotionSensor |
|
||||
/// | `binary_sensor` | `door` / `window` | ContactSensor |
|
||||
/// | `sensor` | — + unit=°C/°F | TemperatureSensor |
|
||||
/// | `sensor` | — + unit=% (humidity) | HumiditySensor |
|
||||
/// | `cover` (door) | — | Door |
|
||||
/// | `lock` | — | Lock |
|
||||
pub struct EntityToAccessoryMapper;
|
||||
|
||||
impl EntityToAccessoryMapper {
|
||||
/// Map a HOMECORE entity to its HAP representation.
|
||||
///
|
||||
/// Returns `HapError::UnmappableEntity` for domains that have no
|
||||
/// defined HAP mapping (e.g. `automation`, `input_boolean`).
|
||||
pub fn map(entity_id: &EntityId, state: &State) -> Result<AccessoryMapping, HapError> {
|
||||
match entity_id.domain() {
|
||||
"light" => Self::map_light(state),
|
||||
"switch" => Self::map_switch(state),
|
||||
"binary_sensor" => Self::map_binary_sensor(entity_id, state),
|
||||
"sensor" => Self::map_sensor(entity_id, state),
|
||||
"cover" => Self::map_cover(state),
|
||||
"lock" => Self::map_lock(state),
|
||||
other => Err(HapError::UnmappableEntity {
|
||||
entity_id: entity_id.as_str().to_owned(),
|
||||
reason: format!("domain '{other}' has no HAP mapping in P1"),
|
||||
}),
|
||||
}
|
||||
}
|
||||
|
||||
fn map_light(state: &State) -> Result<AccessoryMapping, HapError> {
|
||||
let on = state.state == "on";
|
||||
let mut chars = vec![(HapCharacteristic::On, HapCharacteristicValue::Bool(on))];
|
||||
if let Some(b) = state.attributes.get("brightness").and_then(Value::as_u64) {
|
||||
chars.push((
|
||||
HapCharacteristic::Brightness,
|
||||
HapCharacteristicValue::UInt8(b.min(255) as u8),
|
||||
));
|
||||
}
|
||||
Ok(AccessoryMapping { accessory_type: HapAccessoryType::Lightbulb, characteristics: chars })
|
||||
}
|
||||
|
||||
fn map_switch(state: &State) -> Result<AccessoryMapping, HapError> {
|
||||
let on = state.state == "on";
|
||||
Ok(AccessoryMapping {
|
||||
accessory_type: HapAccessoryType::Switch,
|
||||
characteristics: vec![(HapCharacteristic::On, HapCharacteristicValue::Bool(on))],
|
||||
})
|
||||
}
|
||||
|
||||
fn map_binary_sensor(
|
||||
entity_id: &EntityId,
|
||||
state: &State,
|
||||
) -> Result<AccessoryMapping, HapError> {
|
||||
let detected = state.state == "on";
|
||||
let device_class = state
|
||||
.attributes
|
||||
.get("device_class")
|
||||
.and_then(Value::as_str)
|
||||
.unwrap_or("")
|
||||
.to_owned();
|
||||
|
||||
// Also check name heuristics for device_class-less entities.
|
||||
let name = entity_id.name();
|
||||
let is_occupancy = device_class == "occupancy" || name.contains("occupancy") || name.contains("presence");
|
||||
let is_motion = device_class == "motion" || name.contains("motion");
|
||||
let is_door = device_class == "door" || device_class == "window";
|
||||
|
||||
if is_occupancy {
|
||||
return Ok(AccessoryMapping {
|
||||
accessory_type: HapAccessoryType::OccupancySensor,
|
||||
characteristics: vec![(
|
||||
HapCharacteristic::OccupancyDetected,
|
||||
HapCharacteristicValue::UInt8(if detected { 1 } else { 0 }),
|
||||
)],
|
||||
});
|
||||
}
|
||||
if is_motion {
|
||||
return Ok(AccessoryMapping {
|
||||
accessory_type: HapAccessoryType::MotionSensor,
|
||||
characteristics: vec![(
|
||||
HapCharacteristic::MotionDetected,
|
||||
HapCharacteristicValue::Bool(detected),
|
||||
)],
|
||||
});
|
||||
}
|
||||
if is_door {
|
||||
return Ok(AccessoryMapping {
|
||||
accessory_type: HapAccessoryType::ContactSensor,
|
||||
characteristics: vec![(
|
||||
HapCharacteristic::ContactSensorState,
|
||||
HapCharacteristicValue::UInt8(if detected { 1 } else { 0 }),
|
||||
)],
|
||||
});
|
||||
}
|
||||
// Fallback: treat as motion sensor
|
||||
Ok(AccessoryMapping {
|
||||
accessory_type: HapAccessoryType::MotionSensor,
|
||||
characteristics: vec![(
|
||||
HapCharacteristic::MotionDetected,
|
||||
HapCharacteristicValue::Bool(detected),
|
||||
)],
|
||||
})
|
||||
}
|
||||
|
||||
fn map_sensor(entity_id: &EntityId, state: &State) -> Result<AccessoryMapping, HapError> {
|
||||
let unit = state
|
||||
.attributes
|
||||
.get("unit_of_measurement")
|
||||
.and_then(Value::as_str)
|
||||
.unwrap_or("")
|
||||
.to_owned();
|
||||
let name = entity_id.name();
|
||||
|
||||
let is_temp = unit == "°C" || unit == "°F" || unit == "C" || unit == "F"
|
||||
|| name.contains("temp") || name.contains("temperature");
|
||||
let is_humidity = unit == "%" && (name.contains("humid") || name.contains("rh"));
|
||||
|
||||
if is_temp {
|
||||
let temp: f64 = state.state.parse().unwrap_or(0.0);
|
||||
return Ok(AccessoryMapping {
|
||||
accessory_type: HapAccessoryType::TemperatureSensor,
|
||||
characteristics: vec![(
|
||||
HapCharacteristic::CurrentTemperature,
|
||||
HapCharacteristicValue::Float(temp),
|
||||
)],
|
||||
});
|
||||
}
|
||||
if is_humidity {
|
||||
let hum: f64 = state.state.parse().unwrap_or(0.0);
|
||||
return Ok(AccessoryMapping {
|
||||
accessory_type: HapAccessoryType::HumiditySensor,
|
||||
characteristics: vec![(
|
||||
HapCharacteristic::CurrentRelativeHumidity,
|
||||
HapCharacteristicValue::Float(hum),
|
||||
)],
|
||||
});
|
||||
}
|
||||
Err(HapError::UnmappableEntity {
|
||||
entity_id: entity_id.as_str().to_owned(),
|
||||
reason: "sensor unit/name not recognised as temperature or humidity".into(),
|
||||
})
|
||||
}
|
||||
|
||||
fn map_cover(state: &State) -> Result<AccessoryMapping, HapError> {
|
||||
let door_state: u8 = match state.state.as_str() {
|
||||
"open" => 0,
|
||||
"opening" => 2,
|
||||
"closing" => 3,
|
||||
_ => 1, // closed
|
||||
};
|
||||
Ok(AccessoryMapping {
|
||||
accessory_type: HapAccessoryType::Door,
|
||||
characteristics: vec![(
|
||||
HapCharacteristic::CurrentDoorState,
|
||||
HapCharacteristicValue::UInt8(door_state),
|
||||
)],
|
||||
})
|
||||
}
|
||||
|
||||
fn map_lock(state: &State) -> Result<AccessoryMapping, HapError> {
|
||||
let lock_state: u8 = match state.state.as_str() {
|
||||
"unlocked" => 0,
|
||||
"locked" => 1,
|
||||
_ => 3, // unknown
|
||||
};
|
||||
Ok(AccessoryMapping {
|
||||
accessory_type: HapAccessoryType::Lock,
|
||||
characteristics: vec![(
|
||||
HapCharacteristic::LockCurrentState,
|
||||
HapCharacteristicValue::UInt8(lock_state),
|
||||
)],
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use homecore::entity::{EntityId, State};
|
||||
use homecore::event::Context;
|
||||
|
||||
fn state(id: &str, st: &str, attrs: serde_json::Value) -> (EntityId, State) {
|
||||
let eid = EntityId::parse(id).unwrap();
|
||||
let s = State::new(eid.clone(), st, attrs, Context::default());
|
||||
(eid, s)
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn light_kitchen_on_with_brightness() {
|
||||
let (eid, s) = state(
|
||||
"light.kitchen",
|
||||
"on",
|
||||
serde_json::json!({"brightness": 200}),
|
||||
);
|
||||
let mapping = EntityToAccessoryMapper::map(&eid, &s).unwrap();
|
||||
assert_eq!(mapping.accessory_type, HapAccessoryType::Lightbulb);
|
||||
assert!(mapping.characteristics.contains(&(
|
||||
HapCharacteristic::On,
|
||||
HapCharacteristicValue::Bool(true)
|
||||
)));
|
||||
assert!(mapping.characteristics.contains(&(
|
||||
HapCharacteristic::Brightness,
|
||||
HapCharacteristicValue::UInt8(200)
|
||||
)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn binary_sensor_occupancy_device_class() {
|
||||
let (eid, s) = state(
|
||||
"binary_sensor.kitchen_presence",
|
||||
"on",
|
||||
serde_json::json!({"device_class": "occupancy"}),
|
||||
);
|
||||
let mapping = EntityToAccessoryMapper::map(&eid, &s).unwrap();
|
||||
assert_eq!(mapping.accessory_type, HapAccessoryType::OccupancySensor);
|
||||
assert!(mapping.characteristics.contains(&(
|
||||
HapCharacteristic::OccupancyDetected,
|
||||
HapCharacteristicValue::UInt8(1)
|
||||
)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn sensor_outdoor_temp_celsius() {
|
||||
let (eid, s) = state(
|
||||
"sensor.outdoor_temp",
|
||||
"21.5",
|
||||
serde_json::json!({"unit_of_measurement": "°C"}),
|
||||
);
|
||||
let mapping = EntityToAccessoryMapper::map(&eid, &s).unwrap();
|
||||
assert_eq!(mapping.accessory_type, HapAccessoryType::TemperatureSensor);
|
||||
assert!(mapping.characteristics.contains(&(
|
||||
HapCharacteristic::CurrentTemperature,
|
||||
HapCharacteristicValue::Float(21.5)
|
||||
)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn unmappable_domain_returns_error() {
|
||||
let (eid, s) = state("automation.morning", "on", serde_json::json!({}));
|
||||
assert!(EntityToAccessoryMapper::map(&eid, &s).is_err());
|
||||
}
|
||||
}
|
||||
@@ -1,79 +0,0 @@
|
||||
//! mDNS advertisement trait and P1 no-op stub.
|
||||
//!
|
||||
//! Real mDNS via the `mdns-sd` crate (https://crates.io/crates/mdns-sd)
|
||||
//! lands in P2 behind the `hap-server` feature flag. P1 ships `NullAdvertiser`
|
||||
//! so the bridge compiles and tests pass without any mDNS infrastructure.
|
||||
|
||||
use async_trait::async_trait;
|
||||
|
||||
use crate::error::HapError;
|
||||
|
||||
/// Service record advertised over mDNS for HAP discovery.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct HapServiceRecord {
|
||||
/// Service instance name shown in Apple Home ("RuView Sense").
|
||||
pub instance_name: String,
|
||||
/// TCP port the HAP server listens on (default 51826).
|
||||
pub port: u16,
|
||||
/// HAP pairing setup code (8 digits, formatted as XXX-XX-XXX).
|
||||
pub setup_code: String,
|
||||
/// Unique device ID (colon-separated MAC-like hex, required by HAP §5.4).
|
||||
pub device_id: String,
|
||||
}
|
||||
|
||||
/// Advertise (and retract) a HAP accessory over mDNS (`_hap._tcp`).
|
||||
///
|
||||
/// Implementors register the `_hap._tcp` service so HomePod / Apple TV can
|
||||
/// discover the bridge and initiate pairing. P1 provides only `NullAdvertiser`.
|
||||
#[async_trait]
|
||||
pub trait MdnsAdvertiser: Send + Sync {
|
||||
/// Begin advertising the service. Idempotent.
|
||||
async fn advertise(&self, record: &HapServiceRecord) -> Result<(), HapError>;
|
||||
|
||||
/// Stop advertising. Called on bridge shutdown.
|
||||
async fn retract(&self, instance_name: &str) -> Result<(), HapError>;
|
||||
}
|
||||
|
||||
/// No-op advertiser for P1 / test environments.
|
||||
///
|
||||
/// All calls succeed without touching the network.
|
||||
#[derive(Debug, Default, Clone)]
|
||||
pub struct NullAdvertiser;
|
||||
|
||||
#[async_trait]
|
||||
impl MdnsAdvertiser for NullAdvertiser {
|
||||
async fn advertise(&self, record: &HapServiceRecord) -> Result<(), HapError> {
|
||||
tracing::debug!(
|
||||
instance = %record.instance_name,
|
||||
port = record.port,
|
||||
"NullAdvertiser: skipping mDNS advertisement (P1 stub)"
|
||||
);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn retract(&self, instance_name: &str) -> Result<(), HapError> {
|
||||
tracing::debug!(
|
||||
instance = %instance_name,
|
||||
"NullAdvertiser: skipping mDNS retract (P1 stub)"
|
||||
);
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[tokio::test]
|
||||
async fn null_advertiser_is_noop() {
|
||||
let adv = NullAdvertiser;
|
||||
let rec = HapServiceRecord {
|
||||
instance_name: "RuView Sense".into(),
|
||||
port: 51826,
|
||||
setup_code: "111-22-333".into(),
|
||||
device_id: "AA:BB:CC:DD:EE:FF".into(),
|
||||
};
|
||||
adv.advertise(&rec).await.unwrap();
|
||||
adv.retract(&rec.instance_name).await.unwrap();
|
||||
}
|
||||
}
|
||||
@@ -1,158 +0,0 @@
|
||||
//! RuView sensing primitives → HAP characteristic mapping (ADR-125 §2.1.d).
|
||||
//!
|
||||
//! Per ADR-125, RuView's privacy-class-2/3 events map to HomeKit primitives
|
||||
//! as semantic ambient signals, not surveillance events:
|
||||
//!
|
||||
//! | RuView primitive | HAP service | Rationale |
|
||||
//! |-----------------|-------------|-----------|
|
||||
//! | `edge_vitals.presence` | OccupancySensor | Anonymous presence = occupancy |
|
||||
//! | `edge_vitals.motion` | MotionSensor | Motion burst |
|
||||
//! | `edge_vitals.fall_detected` | LeakSensor | HA convention: abnormal events |
|
||||
//! | `edge_vitals.breathing_present` | OccupancySensor | Sleep-room occupancy |
|
||||
//!
|
||||
//! Raw `identity_risk_score`, `rf_signature_hash`, and class-0 BFI data are
|
||||
//! **never** mapped. Structural invariant I1 (ADR-118 §2.2) is enforced here.
|
||||
|
||||
use crate::accessory::{HapAccessoryType, HapCharacteristic, HapCharacteristicValue};
|
||||
use crate::mapping::AccessoryMapping;
|
||||
|
||||
/// Parsed RuView edge vitals event from the sensing-server.
|
||||
///
|
||||
/// All fields are class-2 (Anonymous) or class-3 (Restricted) derived signals.
|
||||
/// Raw BFI / `identity_risk_score` / `rf_signature_hash` are intentionally
|
||||
/// absent — they must not cross the HAP boundary per ADR-125 §2.2.
|
||||
#[derive(Debug, Clone, Default)]
|
||||
pub struct EdgeVitals {
|
||||
/// True if at least one person is present in the sensing zone.
|
||||
pub presence: bool,
|
||||
/// True if motion was detected in the last sensing window.
|
||||
pub motion: bool,
|
||||
/// True if a fall event was detected (latched, 5 s cooldown).
|
||||
pub fall_detected: bool,
|
||||
/// True if rhythmic breathing is detected (sleep-room occupancy signal).
|
||||
pub breathing_present: bool,
|
||||
/// Optional ambient temperature reading (°C), forwarded if available
|
||||
/// from a co-located temperature sensor.
|
||||
pub ambient_temp_c: Option<f64>,
|
||||
}
|
||||
|
||||
/// Maps `EdgeVitals` to a `Vec<AccessoryMapping>` — one per RuView primitive
|
||||
/// that should be exposed as a distinct HAP service (child accessory).
|
||||
pub struct RuViewToHapMapper;
|
||||
|
||||
impl RuViewToHapMapper {
|
||||
/// Convert a `EdgeVitals` snapshot to HAP accessory mappings.
|
||||
///
|
||||
/// Always returns mappings for presence, motion, and fall; the ambient
|
||||
/// temperature mapping is only emitted when `ambient_temp_c` is `Some`.
|
||||
pub fn map(vitals: &EdgeVitals) -> Vec<AccessoryMapping> {
|
||||
let mut out = Vec::with_capacity(4);
|
||||
|
||||
// Presence → OccupancySensor
|
||||
out.push(AccessoryMapping {
|
||||
accessory_type: HapAccessoryType::OccupancySensor,
|
||||
characteristics: vec![(
|
||||
HapCharacteristic::OccupancyDetected,
|
||||
HapCharacteristicValue::UInt8(if vitals.presence || vitals.breathing_present { 1 } else { 0 }),
|
||||
)],
|
||||
});
|
||||
|
||||
// Motion → MotionSensor
|
||||
out.push(AccessoryMapping {
|
||||
accessory_type: HapAccessoryType::MotionSensor,
|
||||
characteristics: vec![(
|
||||
HapCharacteristic::MotionDetected,
|
||||
HapCharacteristicValue::Bool(vitals.motion),
|
||||
)],
|
||||
});
|
||||
|
||||
// Fall detected → LeakSensor (HA homekit_controller convention for
|
||||
// "abnormal event" — not a literal water leak, but an automation-
|
||||
// triggerable threshold event, per ADR-125 §2.1.d).
|
||||
out.push(AccessoryMapping {
|
||||
accessory_type: HapAccessoryType::LeakSensor,
|
||||
characteristics: vec![(
|
||||
HapCharacteristic::LeakDetected,
|
||||
HapCharacteristicValue::UInt8(if vitals.fall_detected { 1 } else { 0 }),
|
||||
)],
|
||||
});
|
||||
|
||||
// Optional temperature
|
||||
if let Some(temp) = vitals.ambient_temp_c {
|
||||
out.push(AccessoryMapping {
|
||||
accessory_type: HapAccessoryType::TemperatureSensor,
|
||||
characteristics: vec![(
|
||||
HapCharacteristic::CurrentTemperature,
|
||||
HapCharacteristicValue::Float(temp),
|
||||
)],
|
||||
});
|
||||
}
|
||||
|
||||
out
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::accessory::{HapAccessoryType, HapCharacteristic, HapCharacteristicValue};
|
||||
|
||||
#[test]
|
||||
fn presence_true_maps_to_occupancy_detected_1() {
|
||||
let vitals = EdgeVitals { presence: true, ..Default::default() };
|
||||
let mappings = RuViewToHapMapper::map(&vitals);
|
||||
let occ = mappings.iter().find(|m| m.accessory_type == HapAccessoryType::OccupancySensor).unwrap();
|
||||
assert!(occ.characteristics.contains(&(
|
||||
HapCharacteristic::OccupancyDetected,
|
||||
HapCharacteristicValue::UInt8(1)
|
||||
)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn fall_detected_maps_to_leak_sensor() {
|
||||
let vitals = EdgeVitals { fall_detected: true, ..Default::default() };
|
||||
let mappings = RuViewToHapMapper::map(&vitals);
|
||||
let leak = mappings.iter().find(|m| m.accessory_type == HapAccessoryType::LeakSensor).unwrap();
|
||||
assert!(leak.characteristics.contains(&(
|
||||
HapCharacteristic::LeakDetected,
|
||||
HapCharacteristicValue::UInt8(1)
|
||||
)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn motion_false_maps_correctly() {
|
||||
let vitals = EdgeVitals { motion: false, ..Default::default() };
|
||||
let mappings = RuViewToHapMapper::map(&vitals);
|
||||
let mot = mappings.iter().find(|m| m.accessory_type == HapAccessoryType::MotionSensor).unwrap();
|
||||
assert!(mot.characteristics.contains(&(
|
||||
HapCharacteristic::MotionDetected,
|
||||
HapCharacteristicValue::Bool(false)
|
||||
)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ambient_temp_emits_temperature_mapping() {
|
||||
let vitals = EdgeVitals { ambient_temp_c: Some(22.5), ..Default::default() };
|
||||
let mappings = RuViewToHapMapper::map(&vitals);
|
||||
let temp = mappings.iter().find(|m| m.accessory_type == HapAccessoryType::TemperatureSensor);
|
||||
assert!(temp.is_some());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn no_ambient_temp_omits_temperature_mapping() {
|
||||
let vitals = EdgeVitals { ambient_temp_c: None, ..Default::default() };
|
||||
let mappings = RuViewToHapMapper::map(&vitals);
|
||||
assert!(mappings.iter().all(|m| m.accessory_type != HapAccessoryType::TemperatureSensor));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn breathing_present_triggers_occupancy() {
|
||||
let vitals = EdgeVitals { presence: false, breathing_present: true, ..Default::default() };
|
||||
let mappings = RuViewToHapMapper::map(&vitals);
|
||||
let occ = mappings.iter().find(|m| m.accessory_type == HapAccessoryType::OccupancySensor).unwrap();
|
||||
assert!(occ.characteristics.contains(&(
|
||||
HapCharacteristic::OccupancyDetected,
|
||||
HapCharacteristicValue::UInt8(1)
|
||||
)));
|
||||
}
|
||||
}
|
||||
@@ -1,60 +0,0 @@
|
||||
# homecore-migrate — Migration tooling from Python Home Assistant.
|
||||
# Implements ADR-134 (HOMECORE-MIGRATE), P1 scaffold:
|
||||
# - HaStorageDir + HaStorageEnvelope: reads `.storage/*.json` files
|
||||
# - Versioned format parsers under `storage_format::v<N>`
|
||||
# - entity_registry, device_registry, config_entries parsers
|
||||
# - secrets.yaml + automations.yaml parsers
|
||||
# - CLI: `homecore-migrate inspect` / `homecore-migrate import-entities`
|
||||
#
|
||||
# P2 will add homecore-recorder side-by-side DB export (feature-gated).
|
||||
|
||||
[package]
|
||||
name = "homecore-migrate"
|
||||
version = "0.1.0-alpha.0"
|
||||
edition = "2021"
|
||||
license = "MIT"
|
||||
authors = ["rUv <ruv@ruv.net>", "HOMECORE Contributors"]
|
||||
description = "Migration tooling from Python Home Assistant to HOMECORE (ADR-134 P1 scaffold)"
|
||||
repository = "https://github.com/ruvnet/RuView"
|
||||
|
||||
[[bin]]
|
||||
name = "homecore-migrate"
|
||||
path = "src/main.rs"
|
||||
|
||||
[lib]
|
||||
name = "homecore_migrate"
|
||||
path = "src/lib.rs"
|
||||
|
||||
[features]
|
||||
default = []
|
||||
# P2: enable when homecore-recorder ships (ADR-132). Exports side-by-side DB.
|
||||
recorder = []
|
||||
|
||||
[dependencies]
|
||||
# HOMECORE state machine — local path (ADR-127).
|
||||
homecore = { path = "../homecore", version = "0.1.0-alpha.0" }
|
||||
|
||||
# Async runtime.
|
||||
tokio = { version = "1", features = ["full"] }
|
||||
|
||||
# Serialisation — JSON for .storage files, YAML for secrets/automations.
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = "1"
|
||||
serde_yaml = "0.9"
|
||||
|
||||
# Error handling.
|
||||
thiserror = "1"
|
||||
|
||||
# Tracing/logging.
|
||||
tracing = "0.1"
|
||||
tracing-subscriber = "0.3"
|
||||
|
||||
# CLI argument parsing.
|
||||
clap = { version = "4", features = ["derive"] }
|
||||
|
||||
# Error handling in main.rs
|
||||
anyhow = "1"
|
||||
|
||||
[dev-dependencies]
|
||||
tokio = { version = "1", features = ["full", "test-util"] }
|
||||
tempfile = "3"
|
||||
@@ -1,143 +0,0 @@
|
||||
# homecore-migrate
|
||||
|
||||
Migration tooling for importing Home Assistant configuration, entities, and secrets into HOMECORE.
|
||||
|
||||
[](https://crates.io/crates/homecore-migrate)
|
||||
|
||||
|
||||
[](https://github.com/ruvnet/RuView)
|
||||
[](../../docs/adr/ADR-134-homecore-migration-from-python-ha.md)
|
||||
|
||||
Parse and inspect Home Assistant's `.storage/` directory, entity registry, device registry, secrets, and automations. Convert existing HA configurations for import into HOMECORE (full conversion in P2).
|
||||
|
||||
## What this crate does
|
||||
|
||||
`homecore-migrate` reads Home Assistant's filesystem state and provides tooling to analyze and migrate it to HOMECORE. It includes:
|
||||
|
||||
- **HaStorageDir** — reads HA's `.homeassistant/.storage/` directory and parses versioned JSON envelopes
|
||||
- **Entity registry parser** — converts `core.entity_registry` JSON to HOMECORE `EntityEntry` types
|
||||
- **Device registry parser** — reads `core.device_registry` (P1 diagnostic only; full conversion in P2)
|
||||
- **Config entries parser** — reads `core.config_entries` to list active integrations
|
||||
- **Secrets parser** — reads `secrets.yaml` as `HashMap<String, String>` for reference resolution (P2)
|
||||
- **Automations parser** — reads `automations.yaml` and counts/lists automations (full conversion in P2)
|
||||
- **CLI binary** — `homecore-migrate inspect` to preview what will be migrated
|
||||
|
||||
The tool enforces version schema compatibility: unknown HA schema versions are rejected (hard error per ADR-134 §6 Q5) rather than silently corrupting data.
|
||||
|
||||
## Features
|
||||
|
||||
- **Entity registry import** — `core.entity_registry` → HOMECORE entity definitions (ready for import)
|
||||
- **Device registry inspection** — read HA device metadata; full conversion deferred to P2
|
||||
- **Config entries analysis** — list active integrations by domain (enables gap analysis)
|
||||
- **Secrets extraction** — read `secrets.yaml` references for annotation (resolution in P2)
|
||||
- **Automations counting** — list automation IDs and aliases without conversion (conversion in P2)
|
||||
- **Schema version validation** — explicit rejection of unknown HA versions (no silent corruption)
|
||||
- **Structured error reporting** — `MigrateError` enum with context (file path, line number)
|
||||
- **CLI subcommands** — `inspect` to preview, `import-entities` to load (P2), `export-for-sidecar` (P2)
|
||||
|
||||
## Capabilities
|
||||
|
||||
| Capability | Type | Method | Notes |
|
||||
|------------|------|--------|-------|
|
||||
| Read storage envelope | Parser | `storage::read_envelope(path)` | Deserialize `.storage/*.json` |
|
||||
| Parse entity registry | Parser | `entity_registry::load(storage_dir)` | → `Vec<homecore::EntityEntry>` |
|
||||
| Inspect device registry | Parser | `device_registry::load(storage_dir)` | → `Vec<DeviceImport>` (P1 diagnostic) |
|
||||
| List config entries | Parser | `config_entries::load(storage_dir)` | → domain counts + names |
|
||||
| Load secrets | Parser | `secrets::load_secrets(path)` | → `HashMap<String, String>` |
|
||||
| Count automations | Parser | `automations::load(path)` | → count + ID list |
|
||||
| Validate schema version | Validator | `storage_format::validate_version(major, minor)` | Hard error if unknown |
|
||||
| Convert to HOMECORE | Converter | `entity_registry::to_homecore_entries()` (P2) | → `homecore::EntityRegistry` |
|
||||
| Export side-by-side DB | Exporter | `recorder::export_states()` (P2, `--features recorder`) | → `.homecore/home.db` |
|
||||
|
||||
## Comparison to Home Assistant
|
||||
|
||||
| Aspect | Home Assistant | homecore-migrate |
|
||||
|--------|----------------|-----------------|
|
||||
| State source | Python `.homeassistant/` directory | Same HA filesystem format |
|
||||
| Entity registry format | JSON envelope in `.storage/core.entity_registry` | Identical format, schema v13 |
|
||||
| Schema versioning | `version` + optional `minor_version` | Explicit version struct validation |
|
||||
| Secrets resolution | `!secret` YAML references via loader | Planned P2 (reads `secrets.yaml`) |
|
||||
| Automation conversion | Python → HA YAML (internal) | P2: convert to `homecore-automation` format |
|
||||
| Device registry import | Python device types | P1 diagnostic; full conversion P2 |
|
||||
| Side-by-side runtime | N/A (HA doesn't side-by-side migrate) | P2 feature: run old + new in parallel |
|
||||
| CLI tooling | HA doesn't export | `homecore-migrate` binary with subcommands |
|
||||
|
||||
## Performance
|
||||
|
||||
- **Storage envelope parse** — < 5 ms per file (serde_json)
|
||||
- **Entity registry load** — < 50 ms for 1,000 entities
|
||||
- **Storage directory scan** — < 100 ms for full `.storage/` directory
|
||||
- **Secrets file parse** — < 10 ms (YAML)
|
||||
- **No per-crate benchmarks yet** — a follow-up issue tracks baseline measurements
|
||||
|
||||
## Usage
|
||||
|
||||
CLI inspection (P1):
|
||||
|
||||
```bash
|
||||
# Inspect what will be migrated from an existing HA installation
|
||||
homecore-migrate inspect ~/.homeassistant
|
||||
|
||||
# Output:
|
||||
# Entity Registry: 47 entities
|
||||
# light: 12
|
||||
# sensor: 20
|
||||
# binary_sensor: 10
|
||||
# switch: 5
|
||||
# Device Registry: 8 devices
|
||||
# Config Entries: 6 integrations (mqtt, rest, zeroconf, ...)
|
||||
# Secrets: 3 defined (redacted)
|
||||
# Automations: 5 automations (redacted)
|
||||
```
|
||||
|
||||
Programmatic entity import (P1):
|
||||
|
||||
```rust
|
||||
use homecore_migrate::entity_registry;
|
||||
use homecore::HomeCore;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() {
|
||||
let storage_dir = std::path::Path::new("/home/user/.homeassistant/.storage");
|
||||
|
||||
// Load HA entities
|
||||
let entries = entity_registry::load(storage_dir)
|
||||
.expect("load entity registry");
|
||||
println!("Loaded {} entities", entries.len());
|
||||
|
||||
// Import into HOMECORE (P2 when EntityRegistry::import() lands)
|
||||
let homecore = HomeCore::new();
|
||||
for entry in entries {
|
||||
println!("Entity: {} ({})", entry.entity_id, entry.name);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Full migration (P2 onwards, via `--features recorder`):
|
||||
|
||||
```bash
|
||||
# Side-by-side: old HA continues running while HOMECORE reads the DB
|
||||
homecore-migrate export-for-sidecar \
|
||||
--ha-dir ~/.homeassistant \
|
||||
--homecore-db ~/.homecore/home.db \
|
||||
--keep-automations true # Don't stop HA automations during test period
|
||||
```
|
||||
|
||||
## Relation to other HOMECORE crates
|
||||
|
||||
```
|
||||
homecore-migrate (import from HA)
|
||||
├─ homecore (EntityEntry → EntityRegistry; config entry imports)
|
||||
├─ homecore-automation (automations.yaml → automation rules, P2)
|
||||
├─ homecore-recorder (side-by-side state export, P2, `--features recorder`)
|
||||
├─ homecore-plugins (config_entries → plugin manifests, P2)
|
||||
└─ homecore-server (can auto-import at startup with --import-ha flag, P2)
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [ADR-134: HOMECORE Migration from Python Home Assistant](../../docs/adr/ADR-134-homecore-migration-from-python-ha.md)
|
||||
- [ADR-126: HOMECORE Home Assistant Port (master)](../../docs/adr/ADR-126-homecore-home-assistant-port.md)
|
||||
- [Home Assistant .storage/ format](https://developers.home-assistant.io/docs/storage/)
|
||||
- [homecore-migrate CLI source](src/main.rs)
|
||||
- [README — wifi-densepose](../../../README.md)
|
||||
@@ -1,130 +0,0 @@
|
||||
//! Parser for `automations.yaml`.
|
||||
//!
|
||||
//! P1: reads the YAML, validates the top-level structure, and emits a count
|
||||
//! plus the list of automation IDs/aliases.
|
||||
//!
|
||||
//! Conversion to `homecore-automation` YAML format is deferred to P2.
|
||||
//!
|
||||
//! HA `automations.yaml` is a YAML sequence of automation objects:
|
||||
//!
|
||||
//! ```yaml
|
||||
//! - id: '1620000000001'
|
||||
//! alias: "Turn on lights at sunset"
|
||||
//! trigger: [...]
|
||||
//! condition: []
|
||||
//! action: [...]
|
||||
//! - id: '1620000000002'
|
||||
//! alias: "Turn off lights at midnight"
|
||||
//! trigger: [...]
|
||||
//! action: [...]
|
||||
//! ```
|
||||
|
||||
use std::path::Path;
|
||||
|
||||
use serde::Deserialize;
|
||||
|
||||
use crate::MigrateError;
|
||||
|
||||
/// Diagnostic summary of `automations.yaml`.
|
||||
#[derive(Clone, Debug)]
|
||||
pub struct AutomationsSummary {
|
||||
pub count: usize,
|
||||
/// `(id, alias)` pairs. `id` defaults to an empty string if absent.
|
||||
pub automations: Vec<AutomationIdent>,
|
||||
}
|
||||
|
||||
/// Minimal identifying info for a single automation.
|
||||
#[derive(Clone, Debug)]
|
||||
pub struct AutomationIdent {
|
||||
pub id: String,
|
||||
pub alias: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Deserialize)]
|
||||
struct HaAutomationRow {
|
||||
#[serde(default)]
|
||||
id: String,
|
||||
#[serde(default)]
|
||||
alias: Option<String>,
|
||||
// All other fields (trigger, condition, action, mode, etc.) ignored in P1.
|
||||
#[allow(dead_code)]
|
||||
#[serde(flatten)]
|
||||
_rest: serde_json::Value,
|
||||
}
|
||||
|
||||
/// Read `automations.yaml` from `path` and return a summary.
|
||||
pub fn read_automations(path: &Path) -> Result<AutomationsSummary, MigrateError> {
|
||||
let raw = std::fs::read_to_string(path).map_err(|e| MigrateError::Io {
|
||||
path: path.display().to_string(),
|
||||
source: e,
|
||||
})?;
|
||||
|
||||
if raw.trim().is_empty() {
|
||||
return Ok(AutomationsSummary { count: 0, automations: vec![] });
|
||||
}
|
||||
|
||||
let rows: Vec<HaAutomationRow> =
|
||||
serde_yaml::from_str(&raw).map_err(|e| MigrateError::YamlParse {
|
||||
path: path.display().to_string(),
|
||||
source: e,
|
||||
})?;
|
||||
|
||||
let automations = rows
|
||||
.iter()
|
||||
.map(|r| AutomationIdent { id: r.id.clone(), alias: r.alias.clone() })
|
||||
.collect::<Vec<_>>();
|
||||
|
||||
Ok(AutomationsSummary { count: rows.len(), automations })
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use std::io::Write;
|
||||
use tempfile::NamedTempFile;
|
||||
|
||||
const FIXTURE: &str = r#"
|
||||
- id: '1620000000001'
|
||||
alias: "Turn on lights at sunset"
|
||||
trigger:
|
||||
- platform: sun
|
||||
event: sunset
|
||||
action:
|
||||
- service: light.turn_on
|
||||
target:
|
||||
entity_id: light.living_room
|
||||
|
||||
- id: '1620000000002'
|
||||
alias: "Turn off lights at midnight"
|
||||
trigger:
|
||||
- platform: time
|
||||
at: "00:00:00"
|
||||
action:
|
||||
- service: light.turn_off
|
||||
target:
|
||||
entity_id: all
|
||||
"#;
|
||||
|
||||
#[test]
|
||||
fn parses_automation_count_and_ids() {
|
||||
let mut f = NamedTempFile::new().unwrap();
|
||||
f.write_all(FIXTURE.as_bytes()).unwrap();
|
||||
let summary = read_automations(f.path()).unwrap();
|
||||
assert_eq!(summary.count, 2);
|
||||
assert_eq!(summary.automations.len(), 2);
|
||||
assert_eq!(summary.automations[0].id, "1620000000001");
|
||||
assert_eq!(
|
||||
summary.automations[0].alias.as_deref(),
|
||||
Some("Turn on lights at sunset")
|
||||
);
|
||||
assert_eq!(summary.automations[1].id, "1620000000002");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn empty_automations_returns_zero_count() {
|
||||
let mut f = NamedTempFile::new().unwrap();
|
||||
f.write_all(b"").unwrap();
|
||||
let summary = read_automations(f.path()).unwrap();
|
||||
assert_eq!(summary.count, 0);
|
||||
}
|
||||
}
|
||||
@@ -1,77 +0,0 @@
|
||||
//! CLI argument types for `homecore-migrate`.
|
||||
//!
|
||||
//! Shared between `src/main.rs` and integration tests. The `clap`-derived
|
||||
//! `Cli` struct is the entry-point; `Command` is the subcommand enum.
|
||||
|
||||
use std::path::PathBuf;
|
||||
|
||||
use clap::{Parser, Subcommand};
|
||||
|
||||
/// homecore-migrate — migrate from Python Home Assistant to HOMECORE.
|
||||
#[derive(Debug, Parser)]
|
||||
#[command(name = "homecore-migrate", version, about)]
|
||||
pub struct Cli {
|
||||
#[command(subcommand)]
|
||||
pub command: Command,
|
||||
}
|
||||
|
||||
#[derive(Debug, Subcommand)]
|
||||
pub enum Command {
|
||||
/// Inspect what is in the HA .storage directory and flag unsupported versions.
|
||||
Inspect(InspectArgs),
|
||||
/// Import entity registry from HA into a HOMECORE storage directory.
|
||||
ImportEntities(ImportEntitiesArgs),
|
||||
/// Import device registry (P1: parses and reports; wiring to HOMECORE P2).
|
||||
ImportDevices(ImportDevicesArgs),
|
||||
/// Inspect config entries (P1: count + domain list; conversion is P2).
|
||||
InspectConfigEntries(InspectConfigEntriesArgs),
|
||||
/// Parse secrets.yaml and report secret names (values redacted).
|
||||
InspectSecrets(InspectSecretsArgs),
|
||||
/// Count and list automations from automations.yaml (conversion is P2).
|
||||
InspectAutomations(InspectAutomationsArgs),
|
||||
}
|
||||
|
||||
#[derive(Debug, clap::Args)]
|
||||
pub struct InspectArgs {
|
||||
/// Path to the HA `.storage/` directory.
|
||||
#[arg(long)]
|
||||
pub storage: PathBuf,
|
||||
}
|
||||
|
||||
#[derive(Debug, clap::Args)]
|
||||
pub struct ImportEntitiesArgs {
|
||||
/// Path to the HA `.storage/` directory.
|
||||
#[arg(long)]
|
||||
pub storage: PathBuf,
|
||||
/// Path to the HOMECORE storage directory (destination).
|
||||
#[arg(long)]
|
||||
pub to: PathBuf,
|
||||
}
|
||||
|
||||
#[derive(Debug, clap::Args)]
|
||||
pub struct ImportDevicesArgs {
|
||||
/// Path to the HA `.storage/` directory.
|
||||
#[arg(long)]
|
||||
pub storage: PathBuf,
|
||||
}
|
||||
|
||||
#[derive(Debug, clap::Args)]
|
||||
pub struct InspectConfigEntriesArgs {
|
||||
/// Path to the HA `.storage/` directory.
|
||||
#[arg(long)]
|
||||
pub storage: PathBuf,
|
||||
}
|
||||
|
||||
#[derive(Debug, clap::Args)]
|
||||
pub struct InspectSecretsArgs {
|
||||
/// Path to the HA config directory (contains `secrets.yaml`).
|
||||
#[arg(long)]
|
||||
pub config_dir: PathBuf,
|
||||
}
|
||||
|
||||
#[derive(Debug, clap::Args)]
|
||||
pub struct InspectAutomationsArgs {
|
||||
/// Path to the HA config directory (contains `automations.yaml`).
|
||||
#[arg(long)]
|
||||
pub config_dir: PathBuf,
|
||||
}
|
||||
@@ -1,128 +0,0 @@
|
||||
//! Parser for `core.config_entries` (HA storage schema v1, minor_version varies).
|
||||
//!
|
||||
//! Per ADR-134 §6 Q5, `.storage/core.config_entries` format is undocumented
|
||||
//! and version-gated. P1 reads the envelope and emits:
|
||||
//! - count of config entries
|
||||
//! - list of integration domains represented
|
||||
//!
|
||||
//! Conversion to HOMECORE plugin manifests is P2.
|
||||
//!
|
||||
//! Note: `config_entries` uses a different `minor_version` track from
|
||||
//! `entity_registry`. As of HA 2025.1 it is typically minor_version=1 or 2.
|
||||
//! We accept any minor_version ≤ MAX_SUPPORTED_MINOR and hard-error above it.
|
||||
|
||||
use std::path::Path;
|
||||
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
use crate::{storage::read_envelope, MigrateError};
|
||||
|
||||
/// Maximum `minor_version` we claim to understand for config_entries.
|
||||
const MAX_SUPPORTED_MINOR: u32 = 4;
|
||||
|
||||
/// Diagnostic summary produced by P1 inspection.
|
||||
#[derive(Clone, Debug, Serialize)]
|
||||
pub struct ConfigEntriesSummary {
|
||||
pub count: usize,
|
||||
pub domains: Vec<String>,
|
||||
}
|
||||
|
||||
/// Minimal fields we read from each config-entry row.
|
||||
#[derive(Debug, Deserialize)]
|
||||
struct HaConfigEntryRow {
|
||||
domain: String,
|
||||
#[allow(dead_code)]
|
||||
entry_id: String,
|
||||
/// Title shown in HA UI (informational only in P1).
|
||||
#[serde(default)]
|
||||
#[allow(dead_code)]
|
||||
title: Option<String>,
|
||||
/// Source of the entry: "user" | "discovery" | "import" etc.
|
||||
#[serde(default)]
|
||||
#[allow(dead_code)]
|
||||
source: Option<String>,
|
||||
/// State: "loaded" | "setup_error" etc.
|
||||
#[serde(default)]
|
||||
#[allow(dead_code)]
|
||||
state: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Deserialize)]
|
||||
struct HaConfigEntriesData {
|
||||
entries: Vec<HaConfigEntryRow>,
|
||||
}
|
||||
|
||||
/// Read `core.config_entries` from `path` and return a diagnostic summary.
|
||||
pub fn inspect_config_entries(path: &Path) -> Result<ConfigEntriesSummary, MigrateError> {
|
||||
let env = read_envelope(path)?;
|
||||
let file_str = path.display().to_string();
|
||||
|
||||
// config_entries has version=1 and minor_version in 1..MAX_SUPPORTED_MINOR.
|
||||
if env.version != 1 || env.minor_version > MAX_SUPPORTED_MINOR {
|
||||
return Err(MigrateError::UnsupportedSchemaVersion {
|
||||
file: file_str.clone(),
|
||||
version: env.version,
|
||||
minor_version: env.minor_version,
|
||||
});
|
||||
}
|
||||
|
||||
let data: HaConfigEntriesData =
|
||||
serde_json::from_value(env.data).map_err(|e| MigrateError::JsonParse {
|
||||
path: file_str,
|
||||
source: e,
|
||||
})?;
|
||||
|
||||
let mut domains: Vec<String> = data.entries.iter().map(|e| e.domain.clone()).collect();
|
||||
domains.sort();
|
||||
domains.dedup();
|
||||
|
||||
Ok(ConfigEntriesSummary {
|
||||
count: data.entries.len(),
|
||||
domains,
|
||||
})
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use std::io::Write;
|
||||
use tempfile::NamedTempFile;
|
||||
|
||||
const FIXTURE: &str = r#"{
|
||||
"version": 1,
|
||||
"minor_version": 1,
|
||||
"key": "core.config_entries",
|
||||
"data": {
|
||||
"entries": [
|
||||
{"domain": "hue", "entry_id": "ce_001", "title": "Philips Hue", "source": "user", "state": "loaded"},
|
||||
{"domain": "zha", "entry_id": "ce_002", "title": "ZHA", "source": "user", "state": "loaded"},
|
||||
{"domain": "hue", "entry_id": "ce_003", "title": "Hue 2", "source": "user", "state": "setup_error"}
|
||||
]
|
||||
}
|
||||
}"#;
|
||||
|
||||
#[test]
|
||||
fn inspect_emits_count_and_domains() {
|
||||
let mut f = NamedTempFile::new().unwrap();
|
||||
f.write_all(FIXTURE.as_bytes()).unwrap();
|
||||
let summary = inspect_config_entries(f.path()).unwrap();
|
||||
assert_eq!(summary.count, 3);
|
||||
assert_eq!(summary.domains, vec!["hue", "zha"]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn unknown_minor_version_hard_errors() {
|
||||
let json = r#"{
|
||||
"version": 1, "minor_version": 99,
|
||||
"key": "core.config_entries",
|
||||
"data": {"entries": []}
|
||||
}"#;
|
||||
let mut f = NamedTempFile::new().unwrap();
|
||||
f.write_all(json.as_bytes()).unwrap();
|
||||
let err = inspect_config_entries(f.path()).unwrap_err();
|
||||
assert!(matches!(
|
||||
err,
|
||||
MigrateError::UnsupportedSchemaVersion { minor_version: 99, .. }
|
||||
));
|
||||
}
|
||||
}
|
||||
@@ -1,99 +0,0 @@
|
||||
//! Parser for `core.device_registry` (HA storage schema v1, minor_version 1–13).
|
||||
//!
|
||||
//! P1: deserializes the envelope and returns `Vec<DeviceImport>`.
|
||||
//! HOMECORE's device registry isn't fully wired yet (ADR-127 §2.5 deferred
|
||||
//! to P2), so `DeviceImport` is a staging type for the future hand-off.
|
||||
|
||||
use std::path::Path;
|
||||
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
use crate::{storage::read_envelope, storage_format::v13, MigrateError};
|
||||
|
||||
/// Staging type for a device imported from HA. Not yet wired to HOMECORE's
|
||||
/// device registry (ADR-127 §2.5 — deferred to P2).
|
||||
#[derive(Clone, Debug, Serialize, Deserialize)]
|
||||
pub struct DeviceImport {
|
||||
pub id: String,
|
||||
pub config_entries: Vec<String>,
|
||||
#[serde(default)]
|
||||
pub manufacturer: Option<String>,
|
||||
#[serde(default)]
|
||||
pub model: Option<String>,
|
||||
#[serde(default)]
|
||||
pub name: Option<String>,
|
||||
/// `identifiers` — list of `[integration, id]` pairs. Preserved as raw
|
||||
/// JSON for P2 consumption; not yet mapped to HOMECORE DeviceEntry.
|
||||
#[serde(default)]
|
||||
pub identifiers: Vec<Vec<String>>,
|
||||
#[serde(default)]
|
||||
pub connections: Vec<Vec<String>>,
|
||||
#[serde(default)]
|
||||
pub via_device_id: Option<String>,
|
||||
#[serde(default)]
|
||||
pub area_id: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Deserialize)]
|
||||
struct HaDeviceRegistryData {
|
||||
devices: Vec<DeviceImport>,
|
||||
/// Deleted device tombstones — ignored in P1.
|
||||
#[serde(default)]
|
||||
#[allow(dead_code)]
|
||||
deleted_devices: Vec<serde_json::Value>,
|
||||
}
|
||||
|
||||
/// Read `core.device_registry` from `path` and return the raw import list.
|
||||
pub fn read_device_registry(path: &Path) -> Result<Vec<DeviceImport>, MigrateError> {
|
||||
let env = read_envelope(path)?;
|
||||
let file_str = path.display().to_string();
|
||||
v13::require_supported(&file_str, env.version, env.minor_version)?;
|
||||
|
||||
let data: HaDeviceRegistryData =
|
||||
serde_json::from_value(env.data).map_err(|e| MigrateError::JsonParse {
|
||||
path: file_str,
|
||||
source: e,
|
||||
})?;
|
||||
Ok(data.devices)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use std::io::Write;
|
||||
use tempfile::NamedTempFile;
|
||||
|
||||
const FIXTURE: &str = r#"{
|
||||
"version": 1,
|
||||
"minor_version": 13,
|
||||
"key": "core.device_registry",
|
||||
"data": {
|
||||
"devices": [
|
||||
{
|
||||
"id": "dev_abc",
|
||||
"config_entries": ["ce_001"],
|
||||
"manufacturer": "Philips",
|
||||
"model": "Hue Bridge",
|
||||
"name": "Philips Hue Bridge",
|
||||
"identifiers": [["hue", "001788FFFE3D4B13"]],
|
||||
"connections": [["mac", "00:17:88:ff:fe:3d:4b:13"]],
|
||||
"via_device_id": null,
|
||||
"area_id": null
|
||||
}
|
||||
],
|
||||
"deleted_devices": []
|
||||
}
|
||||
}"#;
|
||||
|
||||
#[test]
|
||||
fn parses_device_registry() {
|
||||
let mut f = NamedTempFile::new().unwrap();
|
||||
f.write_all(FIXTURE.as_bytes()).unwrap();
|
||||
let devices = read_device_registry(f.path()).unwrap();
|
||||
assert_eq!(devices.len(), 1);
|
||||
let d = &devices[0];
|
||||
assert_eq!(d.id, "dev_abc");
|
||||
assert_eq!(d.manufacturer.as_deref(), Some("Philips"));
|
||||
assert_eq!(d.identifiers, vec![vec!["hue", "001788FFFE3D4B13"]]);
|
||||
}
|
||||
}
|
||||
@@ -1,269 +0,0 @@
|
||||
//! Parser for `core.entity_registry` (HA storage schema v1, minor_version 1–13).
|
||||
//!
|
||||
//! Reads the `.storage/core.entity_registry` file and converts it into a
|
||||
//! `Vec<homecore::EntityEntry>` that can be loaded directly into the HOMECORE
|
||||
//! in-memory entity registry.
|
||||
//!
|
||||
//! Schema as of HA 2025.1 (minor_version=13):
|
||||
//! ```json
|
||||
//! {
|
||||
//! "version": 1, "minor_version": 13, "key": "core.entity_registry",
|
||||
//! "data": {
|
||||
//! "entities": [
|
||||
//! {
|
||||
//! "entity_id": "light.kitchen",
|
||||
//! "unique_id": "hue_lamp_42",
|
||||
//! "platform": "hue",
|
||||
//! "name": "Kitchen lamp",
|
||||
//! "disabled_by": null,
|
||||
//! "area_id": "kitchen",
|
||||
//! "device_id": "abc123",
|
||||
//! "entity_category": null,
|
||||
//! "config_entry_id": "ce_001"
|
||||
//! }
|
||||
//! ]
|
||||
//! }
|
||||
//! }
|
||||
//! ```
|
||||
|
||||
use std::path::Path;
|
||||
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
use homecore::{registry::DisabledBy, EntityCategory, EntityEntry, EntityId};
|
||||
|
||||
use crate::{
|
||||
storage::read_envelope,
|
||||
storage_format::v13,
|
||||
MigrateError,
|
||||
};
|
||||
|
||||
// Key used by `inspect` subcommand when scanning the directory.
|
||||
#[allow(dead_code)]
|
||||
const FILE_KEY: &str = "core.entity_registry";
|
||||
|
||||
/// Raw HA entity registry data block (the `data` field in the envelope).
|
||||
#[derive(Debug, Deserialize)]
|
||||
struct HaEntityRegistryData {
|
||||
entities: Vec<HaEntityRow>,
|
||||
/// Deleted-entity tombstones (ignored in P1 — forwarded as Q5 note).
|
||||
#[serde(default)]
|
||||
#[allow(dead_code)]
|
||||
deleted_entities: Vec<serde_json::Value>,
|
||||
}
|
||||
|
||||
/// A single row from `data.entities`.
|
||||
#[derive(Debug, Serialize, Deserialize)]
|
||||
struct HaEntityRow {
|
||||
entity_id: String,
|
||||
#[serde(default)]
|
||||
unique_id: Option<String>,
|
||||
platform: String,
|
||||
/// User-set display name (separate from HA-integration default name).
|
||||
#[serde(default)]
|
||||
name: Option<String>,
|
||||
#[serde(default)]
|
||||
disabled_by: Option<HaDisabledBy>,
|
||||
#[serde(default)]
|
||||
area_id: Option<String>,
|
||||
#[serde(default)]
|
||||
device_id: Option<String>,
|
||||
#[serde(default)]
|
||||
entity_category: Option<HaEntityCategory>,
|
||||
#[serde(default)]
|
||||
config_entry_id: Option<String>,
|
||||
// Fields present in v13 that we capture but do not yet map to HOMECORE.
|
||||
// Forwarded as Q5 items.
|
||||
#[serde(default)]
|
||||
hidden_by: Option<String>, // v13: "user" | "integration"
|
||||
#[serde(default)]
|
||||
has_entity_name: Option<bool>, // v13: HA naming convention flag
|
||||
#[serde(default)]
|
||||
original_name: Option<String>, // v13: integration-provided default name
|
||||
#[serde(default)]
|
||||
icon: Option<String>, // v13: mdi:xxx icon override
|
||||
#[serde(default)]
|
||||
original_icon: Option<String>, // v13: integration-provided icon
|
||||
#[serde(default)]
|
||||
aliases: Option<Vec<String>>, // v13: user-set aliases for voice assist
|
||||
#[serde(default)]
|
||||
capabilities: Option<serde_json::Value>, // v13: integration-specific caps
|
||||
#[serde(default)]
|
||||
supported_features: Option<u64>, // v13: bitmask
|
||||
}
|
||||
|
||||
#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
|
||||
#[serde(rename_all = "snake_case")]
|
||||
enum HaDisabledBy {
|
||||
User,
|
||||
Integration,
|
||||
ConfigEntry,
|
||||
Device,
|
||||
#[serde(other)]
|
||||
Unknown,
|
||||
}
|
||||
|
||||
#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
|
||||
#[serde(rename_all = "lowercase")]
|
||||
enum HaEntityCategory {
|
||||
Config,
|
||||
Diagnostic,
|
||||
#[serde(other)]
|
||||
Unknown,
|
||||
}
|
||||
|
||||
fn map_disabled_by(v: Option<HaDisabledBy>) -> Option<DisabledBy> {
|
||||
v.and_then(|d| match d {
|
||||
HaDisabledBy::User => Some(DisabledBy::User),
|
||||
HaDisabledBy::Integration => Some(DisabledBy::Integration),
|
||||
HaDisabledBy::ConfigEntry => Some(DisabledBy::ConfigEntry),
|
||||
HaDisabledBy::Device => Some(DisabledBy::Device),
|
||||
HaDisabledBy::Unknown => None,
|
||||
})
|
||||
}
|
||||
|
||||
fn map_entity_category(v: Option<HaEntityCategory>) -> Option<EntityCategory> {
|
||||
v.and_then(|c| match c {
|
||||
HaEntityCategory::Config => Some(EntityCategory::Config),
|
||||
HaEntityCategory::Diagnostic => Some(EntityCategory::Diagnostic),
|
||||
HaEntityCategory::Unknown => None,
|
||||
})
|
||||
}
|
||||
|
||||
/// Read `core.entity_registry` from `path` and return HOMECORE entries.
|
||||
///
|
||||
/// Errors:
|
||||
/// - `MigrateError::Io` if the file cannot be read
|
||||
/// - `MigrateError::JsonParse` if the JSON is malformed
|
||||
/// - `MigrateError::UnsupportedSchemaVersion` if minor_version is not 1–13
|
||||
/// - `MigrateError::EntityId` if any `entity_id` string is invalid
|
||||
pub fn read_entity_registry(path: &Path) -> Result<Vec<EntityEntry>, MigrateError> {
|
||||
let env = read_envelope(path)?;
|
||||
let file_str = path.display().to_string();
|
||||
v13::require_supported(&file_str, env.version, env.minor_version)?;
|
||||
|
||||
let data: HaEntityRegistryData =
|
||||
serde_json::from_value(env.data).map_err(|e| MigrateError::JsonParse {
|
||||
path: file_str.clone(),
|
||||
source: e,
|
||||
})?;
|
||||
|
||||
let mut entries = Vec::with_capacity(data.entities.len());
|
||||
for row in data.entities {
|
||||
let entity_id = EntityId::parse(&row.entity_id)?;
|
||||
entries.push(EntityEntry {
|
||||
entity_id,
|
||||
unique_id: row.unique_id,
|
||||
platform: row.platform,
|
||||
name: row.name,
|
||||
disabled_by: map_disabled_by(row.disabled_by),
|
||||
area_id: row.area_id,
|
||||
device_id: row.device_id,
|
||||
entity_category: map_entity_category(row.entity_category),
|
||||
config_entry_id: row.config_entry_id,
|
||||
});
|
||||
}
|
||||
Ok(entries)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use std::io::Write;
|
||||
use tempfile::NamedTempFile;
|
||||
|
||||
fn write_fixture(json: &str) -> NamedTempFile {
|
||||
let mut f = NamedTempFile::new().unwrap();
|
||||
f.write_all(json.as_bytes()).unwrap();
|
||||
f
|
||||
}
|
||||
|
||||
const FIXTURE_V13: &str = r#"{
|
||||
"version": 1,
|
||||
"minor_version": 13,
|
||||
"key": "core.entity_registry",
|
||||
"data": {
|
||||
"entities": [
|
||||
{
|
||||
"entity_id": "light.kitchen",
|
||||
"unique_id": "hue_lamp_42",
|
||||
"platform": "hue",
|
||||
"name": "Kitchen lamp",
|
||||
"disabled_by": null,
|
||||
"area_id": "kitchen",
|
||||
"device_id": "abc123",
|
||||
"entity_category": null,
|
||||
"config_entry_id": "ce_001"
|
||||
},
|
||||
{
|
||||
"entity_id": "sensor.bedroom_temperature",
|
||||
"unique_id": "zigbee_temp_01",
|
||||
"platform": "zha",
|
||||
"name": null,
|
||||
"disabled_by": "integration",
|
||||
"area_id": null,
|
||||
"device_id": "dev_02",
|
||||
"entity_category": "diagnostic",
|
||||
"config_entry_id": "ce_002",
|
||||
"hidden_by": null,
|
||||
"has_entity_name": true,
|
||||
"original_name": "Temperature",
|
||||
"aliases": ["room temp"],
|
||||
"supported_features": 0
|
||||
}
|
||||
],
|
||||
"deleted_entities": []
|
||||
}
|
||||
}"#;
|
||||
|
||||
#[test]
|
||||
fn parses_v13_entity_registry() {
|
||||
let f = write_fixture(FIXTURE_V13);
|
||||
let entries = read_entity_registry(f.path()).unwrap();
|
||||
assert_eq!(entries.len(), 2);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn entity_fields_round_trip_correctly() {
|
||||
let f = write_fixture(FIXTURE_V13);
|
||||
let entries = read_entity_registry(f.path()).unwrap();
|
||||
let light = entries.iter().find(|e| e.entity_id.as_str() == "light.kitchen").unwrap();
|
||||
assert_eq!(light.unique_id.as_deref(), Some("hue_lamp_42"));
|
||||
assert_eq!(light.platform, "hue");
|
||||
assert_eq!(light.name.as_deref(), Some("Kitchen lamp"));
|
||||
assert!(light.disabled_by.is_none());
|
||||
assert_eq!(light.area_id.as_deref(), Some("kitchen"));
|
||||
assert_eq!(light.device_id.as_deref(), Some("abc123"));
|
||||
assert!(light.entity_category.is_none());
|
||||
assert_eq!(light.config_entry_id.as_deref(), Some("ce_001"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn disabled_by_maps_to_homecore() {
|
||||
let f = write_fixture(FIXTURE_V13);
|
||||
let entries = read_entity_registry(f.path()).unwrap();
|
||||
let sensor = entries
|
||||
.iter()
|
||||
.find(|e| e.entity_id.as_str() == "sensor.bedroom_temperature")
|
||||
.unwrap();
|
||||
assert_eq!(sensor.disabled_by, Some(DisabledBy::Integration));
|
||||
assert_eq!(sensor.entity_category, Some(EntityCategory::Diagnostic));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn unknown_minor_version_raises_error() {
|
||||
let json = r#"{
|
||||
"version": 1, "minor_version": 99,
|
||||
"key": "core.entity_registry",
|
||||
"data": {"entities": [], "deleted_entities": []}
|
||||
}"#;
|
||||
let f = write_fixture(json);
|
||||
let err = read_entity_registry(f.path()).unwrap_err();
|
||||
assert!(
|
||||
matches!(err, MigrateError::UnsupportedSchemaVersion { minor_version: 99, .. }),
|
||||
"got: {err}"
|
||||
);
|
||||
let msg = err.to_string();
|
||||
assert!(msg.contains("minor_version=99"), "{msg}");
|
||||
}
|
||||
}
|
||||
@@ -1,76 +0,0 @@
|
||||
//! homecore-migrate — Migration tooling from Python Home Assistant.
|
||||
//!
|
||||
//! Implements [ADR-134](../../docs/adr/ADR-134-homecore-migration-from-python-ha.md)
|
||||
//! (referenced via ADR-126 §4, series map row ADR-134 HOMECORE-MIGRATE).
|
||||
//!
|
||||
//! ## P1 scope
|
||||
//!
|
||||
//! - [`storage`] — `HaStorageDir`, `HaStorageEnvelope`; `read_envelope(path)`
|
||||
//! - [`storage_format`] — versioned format parsers (`v13`); unknown minor_version → hard error
|
||||
//! - [`entity_registry`] — `core.entity_registry` → `Vec<homecore::EntityEntry>`
|
||||
//! - [`device_registry`] — `core.device_registry` → `Vec<DeviceImport>` (P1 stub)
|
||||
//! - [`config_entries`] — `core.config_entries` diagnostic (count + domain list; P2 converts)
|
||||
//! - [`secrets`] — `secrets.yaml` → `HashMap<String, String>`
|
||||
//! - [`automations`] — `automations.yaml` count + ID list (P2 converts)
|
||||
//! - [`cli`] — `clap`-derived subcommand types shared between `src/main.rs` and tests
|
||||
//!
|
||||
//! ## What is NOT here yet (deferred to P2+)
|
||||
//!
|
||||
//! - Conversion of `config_entries` to HOMECORE plugin manifests
|
||||
//! - Conversion of `automations.yaml` to `homecore-automation` YAML
|
||||
//! - Side-by-side runtime mode (requires `homecore-recorder`, ADR-132)
|
||||
//! - `!secret` reference resolution in non-secrets YAML files
|
||||
|
||||
pub mod automations;
|
||||
pub mod cli;
|
||||
pub mod config_entries;
|
||||
pub mod device_registry;
|
||||
pub mod entity_registry;
|
||||
pub mod secrets;
|
||||
pub mod storage;
|
||||
pub mod storage_format;
|
||||
|
||||
/// Crate-level error type. Each module exposes `MigrateError` variants.
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum MigrateError {
|
||||
#[error("I/O error reading {path}: {source}")]
|
||||
Io {
|
||||
path: String,
|
||||
#[source]
|
||||
source: std::io::Error,
|
||||
},
|
||||
|
||||
#[error("JSON parse error in {path}: {source}")]
|
||||
JsonParse {
|
||||
path: String,
|
||||
#[source]
|
||||
source: serde_json::Error,
|
||||
},
|
||||
|
||||
#[error("YAML parse error in {path}: {source}")]
|
||||
YamlParse {
|
||||
path: String,
|
||||
#[source]
|
||||
source: serde_yaml::Error,
|
||||
},
|
||||
|
||||
/// Fired when the outer `{version, minor_version}` envelope version is
|
||||
/// known but the `minor_version` is not supported by any compiled parser.
|
||||
/// Per ADR-134 §6 Q5: hard error on unknown minor_version.
|
||||
#[error(
|
||||
"unsupported schema version in {file}: \
|
||||
version={version} minor_version={minor_version}. \
|
||||
Upgrade homecore-migrate or downgrade HA to a supported release."
|
||||
)]
|
||||
UnsupportedSchemaVersion {
|
||||
file: String,
|
||||
version: u32,
|
||||
minor_version: u32,
|
||||
},
|
||||
|
||||
#[error("missing required field '{field}' in {context}")]
|
||||
MissingField { field: String, context: String },
|
||||
|
||||
#[error("entity_id parse error: {0}")]
|
||||
EntityId(#[from] homecore::EntityIdError),
|
||||
}
|
||||
@@ -1,103 +0,0 @@
|
||||
//! `homecore-migrate` binary — CLI entry point.
|
||||
|
||||
use clap::Parser;
|
||||
use homecore_migrate::cli::{Cli, Command};
|
||||
|
||||
fn main() -> anyhow::Result<()> {
|
||||
tracing_subscriber::fmt::init();
|
||||
let cli = Cli::parse();
|
||||
|
||||
match cli.command {
|
||||
Command::Inspect(args) => {
|
||||
println!("Inspecting HA .storage directory: {}", args.storage.display());
|
||||
// Probe entity_registry
|
||||
let entity_path = args.storage.join("core.entity_registry");
|
||||
if entity_path.exists() {
|
||||
match homecore_migrate::entity_registry::read_entity_registry(&entity_path) {
|
||||
Ok(entries) => println!(" core.entity_registry: {} entities", entries.len()),
|
||||
Err(e) => println!(" core.entity_registry: ERROR — {e}"),
|
||||
}
|
||||
}
|
||||
// Probe device_registry
|
||||
let device_path = args.storage.join("core.device_registry");
|
||||
if device_path.exists() {
|
||||
match homecore_migrate::device_registry::read_device_registry(&device_path) {
|
||||
Ok(devices) => println!(" core.device_registry: {} devices", devices.len()),
|
||||
Err(e) => println!(" core.device_registry: ERROR — {e}"),
|
||||
}
|
||||
}
|
||||
// Probe config_entries
|
||||
let ce_path = args.storage.join("core.config_entries");
|
||||
if ce_path.exists() {
|
||||
match homecore_migrate::config_entries::inspect_config_entries(&ce_path) {
|
||||
Ok(s) => println!(
|
||||
" core.config_entries: {} entries, domains: {}",
|
||||
s.count,
|
||||
s.domains.join(", ")
|
||||
),
|
||||
Err(e) => println!(" core.config_entries: ERROR — {e}"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Command::ImportEntities(args) => {
|
||||
let entity_path = args.storage.join("core.entity_registry");
|
||||
let entries =
|
||||
homecore_migrate::entity_registry::read_entity_registry(&entity_path)?;
|
||||
println!("Imported {} entity entries (P1: in-memory only)", entries.len());
|
||||
println!(" Destination: {} (P2 persistence)", args.to.display());
|
||||
for e in &entries {
|
||||
println!(
|
||||
" {} ({}{})",
|
||||
e.entity_id.as_str(),
|
||||
e.platform,
|
||||
if e.disabled_by.is_some() { " DISABLED" } else { "" }
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
Command::ImportDevices(args) => {
|
||||
let device_path = args.storage.join("core.device_registry");
|
||||
let devices =
|
||||
homecore_migrate::device_registry::read_device_registry(&device_path)?;
|
||||
println!("Parsed {} device entries (P1: staging only, wiring to HOMECORE is P2)", devices.len());
|
||||
}
|
||||
|
||||
Command::InspectConfigEntries(args) => {
|
||||
let ce_path = args.storage.join("core.config_entries");
|
||||
let summary =
|
||||
homecore_migrate::config_entries::inspect_config_entries(&ce_path)?;
|
||||
println!(
|
||||
"config_entries: {} total, domains: {}",
|
||||
summary.count,
|
||||
summary.domains.join(", ")
|
||||
);
|
||||
}
|
||||
|
||||
Command::InspectSecrets(args) => {
|
||||
let secrets_path = args.config_dir.join("secrets.yaml");
|
||||
let secrets = homecore_migrate::secrets::read_secrets(&secrets_path)?;
|
||||
println!("{} secrets found:", secrets.len());
|
||||
let mut keys: Vec<_> = secrets.keys().collect();
|
||||
keys.sort();
|
||||
for k in keys {
|
||||
println!(" {} = <redacted>", k);
|
||||
}
|
||||
}
|
||||
|
||||
Command::InspectAutomations(args) => {
|
||||
let auto_path = args.config_dir.join("automations.yaml");
|
||||
let summary = homecore_migrate::automations::read_automations(&auto_path)?;
|
||||
println!("{} automations:", summary.count);
|
||||
for a in &summary.automations {
|
||||
println!(
|
||||
" id={} alias={}",
|
||||
a.id,
|
||||
a.alias.as_deref().unwrap_or("<unnamed>")
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
@@ -1,105 +0,0 @@
|
||||
//! Parser for HA `secrets.yaml`.
|
||||
//!
|
||||
//! `secrets.yaml` is a flat YAML key→value map at the root of the HA
|
||||
//! config directory (NOT inside `.storage/`). Example:
|
||||
//!
|
||||
//! ```yaml
|
||||
//! mqtt_password: hunter2
|
||||
//! latitude: 51.5074
|
||||
//! longitude: -0.1278
|
||||
//! ```
|
||||
//!
|
||||
//! Values are always strings in HA (even numeric-looking ones are quoted in
|
||||
//! practice). We parse all values as strings to avoid type-mismatch errors.
|
||||
//!
|
||||
//! `!secret <name>` reference resolution (i.e., checking that every secret
|
||||
//! referenced in other YAML files exists here) is deferred to P2.
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::path::Path;
|
||||
|
||||
use crate::MigrateError;
|
||||
|
||||
/// Read `secrets.yaml` from `path` and return a `name → value` map.
|
||||
///
|
||||
/// Returns an empty map if the file is empty (HA allows that).
|
||||
pub fn read_secrets(path: &Path) -> Result<HashMap<String, String>, MigrateError> {
|
||||
let raw = std::fs::read_to_string(path).map_err(|e| MigrateError::Io {
|
||||
path: path.display().to_string(),
|
||||
source: e,
|
||||
})?;
|
||||
|
||||
if raw.trim().is_empty() {
|
||||
return Ok(HashMap::new());
|
||||
}
|
||||
|
||||
let parsed: serde_yaml::Value =
|
||||
serde_yaml::from_str(&raw).map_err(|e| MigrateError::YamlParse {
|
||||
path: path.display().to_string(),
|
||||
source: e,
|
||||
})?;
|
||||
|
||||
let map = match parsed {
|
||||
serde_yaml::Value::Mapping(m) => m,
|
||||
_ => {
|
||||
return Err(MigrateError::MissingField {
|
||||
field: "<root mapping>".into(),
|
||||
context: path.display().to_string(),
|
||||
})
|
||||
}
|
||||
};
|
||||
|
||||
let mut result = HashMap::with_capacity(map.len());
|
||||
for (k, v) in map {
|
||||
let key = match k {
|
||||
serde_yaml::Value::String(s) => s,
|
||||
other => format!("{other:?}"),
|
||||
};
|
||||
let value = match v {
|
||||
serde_yaml::Value::String(s) => s,
|
||||
serde_yaml::Value::Number(n) => n.to_string(),
|
||||
serde_yaml::Value::Bool(b) => b.to_string(),
|
||||
serde_yaml::Value::Null => String::new(),
|
||||
other => serde_yaml::to_string(&other)
|
||||
.unwrap_or_else(|_| "<unparseable>".into())
|
||||
.trim()
|
||||
.to_string(),
|
||||
};
|
||||
result.insert(key, value);
|
||||
}
|
||||
Ok(result)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use std::io::Write;
|
||||
use tempfile::NamedTempFile;
|
||||
|
||||
#[test]
|
||||
fn parses_simple_key_value_map() {
|
||||
let yaml = "mqtt_password: hunter2\nlatitude: 51.5074\n";
|
||||
let mut f = NamedTempFile::new().unwrap();
|
||||
f.write_all(yaml.as_bytes()).unwrap();
|
||||
let secrets = read_secrets(f.path()).unwrap();
|
||||
assert_eq!(secrets.get("mqtt_password").map(String::as_str), Some("hunter2"));
|
||||
assert_eq!(secrets.get("latitude").map(String::as_str), Some("51.5074"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn empty_secrets_file_returns_empty_map() {
|
||||
let mut f = NamedTempFile::new().unwrap();
|
||||
f.write_all(b"").unwrap();
|
||||
let secrets = read_secrets(f.path()).unwrap();
|
||||
assert!(secrets.is_empty());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn secret_count_is_correct() {
|
||||
let yaml = "a: 1\nb: 2\nc: 3\n";
|
||||
let mut f = NamedTempFile::new().unwrap();
|
||||
f.write_all(yaml.as_bytes()).unwrap();
|
||||
let secrets = read_secrets(f.path()).unwrap();
|
||||
assert_eq!(secrets.len(), 3);
|
||||
}
|
||||
}
|
||||
@@ -1,101 +0,0 @@
|
||||
//! HA `.storage/` directory abstraction and the outer storage envelope.
|
||||
//!
|
||||
//! Every file in `.storage/` shares the same outer JSON shape:
|
||||
//!
|
||||
//! ```json
|
||||
//! {
|
||||
//! "version": 1,
|
||||
//! "minor_version": 3,
|
||||
//! "key": "core.entity_registry",
|
||||
//! "data": { ... }
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! `read_envelope` reads and validates this outer wrapper. The `data` field is
|
||||
//! left as `serde_json::Value` — version-specific parsers in `storage_format`
|
||||
//! are responsible for further deserialization.
|
||||
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
use crate::MigrateError;
|
||||
|
||||
/// Points to a HA `.storage/` directory.
|
||||
#[derive(Clone, Debug)]
|
||||
pub struct HaStorageDir {
|
||||
pub path: PathBuf,
|
||||
}
|
||||
|
||||
impl HaStorageDir {
|
||||
pub fn new(path: impl Into<PathBuf>) -> Self {
|
||||
Self { path: path.into() }
|
||||
}
|
||||
|
||||
/// Returns the full path to a named storage file.
|
||||
pub fn file_path(&self, name: &str) -> PathBuf {
|
||||
self.path.join(name)
|
||||
}
|
||||
}
|
||||
|
||||
/// The outer JSON envelope that wraps every HA `.storage/*.json` file.
|
||||
/// Source: `homeassistant/helpers/storage.py` `Store._write_data`.
|
||||
#[derive(Clone, Debug, Serialize, Deserialize)]
|
||||
pub struct HaStorageEnvelope {
|
||||
pub version: u32,
|
||||
/// Introduced in HA 2022.x for backwards-compatible schema additions.
|
||||
#[serde(default)]
|
||||
pub minor_version: u32,
|
||||
pub key: String,
|
||||
/// Inner payload. Parsed by versioned format-specific code.
|
||||
pub data: serde_json::Value,
|
||||
}
|
||||
|
||||
/// Read and deserialize a `.storage/*.json` envelope from `path`.
|
||||
///
|
||||
/// Returns `MigrateError::Io` if the file cannot be read, or
|
||||
/// `MigrateError::JsonParse` if the JSON is malformed.
|
||||
pub fn read_envelope(path: &Path) -> Result<HaStorageEnvelope, MigrateError> {
|
||||
let raw = std::fs::read_to_string(path).map_err(|e| MigrateError::Io {
|
||||
path: path.display().to_string(),
|
||||
source: e,
|
||||
})?;
|
||||
serde_json::from_str(&raw).map_err(|e| MigrateError::JsonParse {
|
||||
path: path.display().to_string(),
|
||||
source: e,
|
||||
})
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
const WELL_FORMED: &str = r#"{
|
||||
"version": 1,
|
||||
"minor_version": 3,
|
||||
"key": "core.entity_registry",
|
||||
"data": {"entities": []}
|
||||
}"#;
|
||||
|
||||
#[test]
|
||||
fn envelope_parses_well_formed() {
|
||||
let env: HaStorageEnvelope = serde_json::from_str(WELL_FORMED).unwrap();
|
||||
assert_eq!(env.version, 1);
|
||||
assert_eq!(env.minor_version, 3);
|
||||
assert_eq!(env.key, "core.entity_registry");
|
||||
assert!(env.data.get("entities").is_some());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn envelope_missing_minor_version_defaults_to_zero() {
|
||||
let json = r#"{"version": 1, "key": "core.config_entries", "data": {}}"#;
|
||||
let env: HaStorageEnvelope = serde_json::from_str(json).unwrap();
|
||||
assert_eq!(env.minor_version, 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn envelope_rejects_malformed_json() {
|
||||
let result = serde_json::from_str::<HaStorageEnvelope>("not json");
|
||||
assert!(result.is_err());
|
||||
}
|
||||
}
|
||||
@@ -1,13 +0,0 @@
|
||||
//! Versioned format parsers for HA `.storage/` files.
|
||||
//!
|
||||
//! Each sub-module handles one `(version, minor_version)` generation of a
|
||||
//! particular storage key. Adding support for a new HA schema version means
|
||||
//! adding a new `v<N>.rs` module; the dispatch function in each parser module
|
||||
//! routes to the right implementation.
|
||||
//!
|
||||
//! Per ADR-134 §6 Q5: unknown `minor_version` values produce a hard
|
||||
//! `MigrateError::UnsupportedSchemaVersion` — we do NOT silently fall back
|
||||
//! to an older parser, because schema changes can be load-bearing (new fields,
|
||||
//! renamed keys, semantic reinterpretations).
|
||||
|
||||
pub mod v13;
|
||||
@@ -1,80 +0,0 @@
|
||||
//! Versioned format parser for HA storage schema version 13.
|
||||
//!
|
||||
//! Applies to (as of HA 2025.1):
|
||||
//! - `core.entity_registry` — `version=1, minor_version=13`
|
||||
//! - `core.device_registry` — `version=1, minor_version=13`
|
||||
//!
|
||||
//! Source: `homeassistant/helpers/entity_registry.py` `STORAGE_VERSION_MINOR`
|
||||
//! and `homeassistant/helpers/device_registry.py` `STORAGE_VERSION_MINOR`.
|
||||
//!
|
||||
//! `core.config_entries` uses a different versioning scheme; see
|
||||
//! `config_entries.rs` for details.
|
||||
|
||||
/// The major storage `version` this module handles.
|
||||
pub const MAJOR_VERSION: u32 = 1;
|
||||
|
||||
/// The `minor_version` values this module handles.
|
||||
/// Any value outside this set raises `MigrateError::UnsupportedSchemaVersion`.
|
||||
pub const SUPPORTED_MINOR_VERSIONS: &[u32] = &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
|
||||
|
||||
/// Return `true` if the given envelope header is handled by this module.
|
||||
pub fn handles(version: u32, minor_version: u32) -> bool {
|
||||
version == MAJOR_VERSION && SUPPORTED_MINOR_VERSIONS.contains(&minor_version)
|
||||
}
|
||||
|
||||
/// Validate that `(version, minor_version)` is supported; return the error
|
||||
/// with the given `file` path embedded if not.
|
||||
///
|
||||
/// Call this at the top of every parser that routes through v13 before
|
||||
/// attempting any field access.
|
||||
pub fn require_supported(
|
||||
file: &str,
|
||||
version: u32,
|
||||
minor_version: u32,
|
||||
) -> Result<(), crate::MigrateError> {
|
||||
if !handles(version, minor_version) {
|
||||
return Err(crate::MigrateError::UnsupportedSchemaVersion {
|
||||
file: file.to_owned(),
|
||||
version,
|
||||
minor_version,
|
||||
});
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn handles_all_supported_minor_versions() {
|
||||
for &mv in SUPPORTED_MINOR_VERSIONS {
|
||||
assert!(handles(1, mv), "minor_version {mv} should be supported");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn rejects_unknown_minor_version() {
|
||||
assert!(!handles(1, 99));
|
||||
assert!(!handles(2, 13));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn require_supported_ok_for_v13() {
|
||||
assert!(require_supported("core.entity_registry", 1, 13).is_ok());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn require_supported_err_carries_file_name() {
|
||||
let err = require_supported("core.entity_registry", 1, 99).unwrap_err();
|
||||
let msg = err.to_string();
|
||||
assert!(
|
||||
msg.contains("core.entity_registry"),
|
||||
"error should contain file name: {msg}"
|
||||
);
|
||||
assert!(
|
||||
msg.contains("minor_version=99"),
|
||||
"error should contain minor_version: {msg}"
|
||||
);
|
||||
}
|
||||
}
|
||||
-7
@@ -1,7 +0,0 @@
|
||||
# This file is automatically @generated by Cargo.
|
||||
# It is not intended for manual editing.
|
||||
version = 4
|
||||
|
||||
[[package]]
|
||||
name = "homecore-plugin-example"
|
||||
version = "0.1.0-alpha.0"
|
||||
@@ -1,39 +0,0 @@
|
||||
# homecore-plugin-example — example WASM plugin proving the ADR-128 host ABI.
|
||||
#
|
||||
# This crate targets wasm32-unknown-unknown and compiles to a `.wasm` binary
|
||||
# that is loaded by the `homecore-plugins` integration test. It is NOT a
|
||||
# workspace member (excluded below) because wasm32 targets cannot participate
|
||||
# in a mixed host/device workspace `cargo test --workspace`.
|
||||
#
|
||||
# Build with:
|
||||
# rustup target add wasm32-unknown-unknown
|
||||
# cargo build --target wasm32-unknown-unknown --release -p homecore-plugin-example
|
||||
#
|
||||
# The compiled binary lands at:
|
||||
# target/wasm32-unknown-unknown/release/homecore_plugin_example.wasm
|
||||
|
||||
[package]
|
||||
name = "homecore-plugin-example"
|
||||
version = "0.1.0-alpha.0"
|
||||
edition = "2021"
|
||||
license = "MIT"
|
||||
authors = ["rUv <ruv@ruv.net>", "HOMECORE Contributors"]
|
||||
description = "Example WASM plugin for HOMECORE — proves the ADR-128 P2 host ABI (guest side)"
|
||||
repository = "https://github.com/ruvnet/RuView"
|
||||
|
||||
# Compile as a dynamic library so the WASM host can `Module::new` the bytes.
|
||||
[lib]
|
||||
name = "homecore_plugin_example"
|
||||
crate-type = ["cdylib"]
|
||||
path = "src/lib.rs"
|
||||
|
||||
[dependencies]
|
||||
# No external dependencies — the plugin uses only std + manual JSON parsing.
|
||||
# Real plugins would pull in serde/serde_json for complex payloads.
|
||||
|
||||
[profile.release]
|
||||
# Minimise binary size for WASM.
|
||||
opt-level = "s"
|
||||
lto = true
|
||||
codegen-units = 1
|
||||
panic = "abort"
|
||||
@@ -1,31 +0,0 @@
|
||||
# homecore-plugin-example
|
||||
|
||||
Example WASM plugin for the HOMECORE plugin system (ADR-128 P2).
|
||||
|
||||
Demonstrates the complete ADR-128 host ABI round-trip:
|
||||
|
||||
- `plugin_setup` — subscribes to `sensor.test_temp` state changes
|
||||
- `plugin_handle_state_changed` — sets `binary_sensor.test_alert` to `on` when temp > 25, `off` when temp < 20
|
||||
|
||||
## Build
|
||||
|
||||
```sh
|
||||
# Ensure the wasm32 target is installed (once)
|
||||
rustup target add wasm32-unknown-unknown
|
||||
|
||||
# Build the example plugin (from this directory)
|
||||
cargo build --target wasm32-unknown-unknown --release -p homecore-plugin-example
|
||||
```
|
||||
|
||||
Output: `target/wasm32-unknown-unknown/release/homecore_plugin_example.wasm`
|
||||
|
||||
## Run the integration test
|
||||
|
||||
```sh
|
||||
# From v2/
|
||||
cargo test -p homecore-plugins --features wasmtime
|
||||
```
|
||||
|
||||
## ABI
|
||||
|
||||
See `homecore-plugins/src/host_abi.rs` for the authoritative host ABI spec.
|
||||
@@ -1,106 +0,0 @@
|
||||
//! Guest-side ABI helpers — matching `homecore-plugins/src/host_abi.rs`.
|
||||
//!
|
||||
//! # Memory model
|
||||
//!
|
||||
//! The host allocates into the guest's linear memory via the exported
|
||||
//! `alloc` / `dealloc` functions. The guest calls host imports with
|
||||
//! (ptr: i32, len: i32) pairs pointing into its own linear memory.
|
||||
//!
|
||||
//! # Allocator
|
||||
//!
|
||||
//! A simple bump allocator backed by a static mutable pointer. Suitable
|
||||
//! only for the WASM guest context where the host drives all allocations
|
||||
//! and deallocations synchronously (no concurrency inside a WASM module).
|
||||
//!
|
||||
//! # Wire format
|
||||
//!
|
||||
//! All host↔guest transfers use **UTF-8 JSON** (see host_abi.rs §Wire types).
|
||||
//! Maximum buffer: 65,536 bytes.
|
||||
|
||||
/// Maximum ABI buffer size — mirrors `MAX_ABI_BUFFER_BYTES` on the host.
|
||||
pub const MAX_ABI_BUFFER_BYTES: usize = 65_536;
|
||||
|
||||
// ── Bump allocator ─────────────────────────────────────────────────────────
|
||||
|
||||
/// Start of heap area (bump pointer). Placed after the 64 KiB stack.
|
||||
static mut BUMP: usize = 0x1_0000; // 64 KiB
|
||||
|
||||
/// Allocate `size` bytes from the bump heap. Returns the pointer.
|
||||
///
|
||||
/// # Safety
|
||||
/// The caller must not write past `ptr + size`.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn alloc(size: i32) -> i32 {
|
||||
if size <= 0 {
|
||||
return 0;
|
||||
}
|
||||
let size = size as usize;
|
||||
// Align to 8 bytes.
|
||||
let aligned = (BUMP + 7) & !7;
|
||||
BUMP = aligned + size;
|
||||
aligned as i32
|
||||
}
|
||||
|
||||
/// Deallocate a buffer. No-op for the bump allocator — caller is the host,
|
||||
/// which drives the alloc/dealloc lifecycle and calls this after each call.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn dealloc(_ptr: i32, _size: i32) {
|
||||
// Bump allocator: no-op. For a real plugin, replace with a proper allocator.
|
||||
}
|
||||
|
||||
// ── Host import declarations ───────────────────────────────────────────────
|
||||
|
||||
extern "C" {
|
||||
/// Read the current state for an entity. See host_abi.rs §hc_state_get.
|
||||
/// Returns bytes written into `out_ptr`, or -1 (not found), -2 (too small).
|
||||
pub fn hc_state_get(
|
||||
key_ptr: i32,
|
||||
key_len: i32,
|
||||
out_ptr: i32,
|
||||
out_cap: i32,
|
||||
) -> i32;
|
||||
|
||||
/// Write state for an entity. Returns 0 on success, negative on error.
|
||||
pub fn hc_state_set(
|
||||
eid_ptr: i32,
|
||||
eid_len: i32,
|
||||
state_ptr: i32,
|
||||
state_len: i32,
|
||||
attrs_ptr: i32,
|
||||
attrs_len: i32,
|
||||
) -> i32;
|
||||
|
||||
/// Subscribe to state changes for an entity. Returns 0 on success.
|
||||
pub fn hc_state_subscribe(eid_ptr: i32, eid_len: i32) -> i32;
|
||||
|
||||
/// Log a message. level: 0=debug 1=info 2=warn 3=error.
|
||||
pub fn hc_log(level: i32, msg_ptr: i32, msg_len: i32);
|
||||
}
|
||||
|
||||
// ── ABI helpers ────────────────────────────────────────────────────────────
|
||||
|
||||
/// Write entity state via `hc_state_set`.
|
||||
///
|
||||
/// Returns the result of `hc_state_set` (0 = ok).
|
||||
///
|
||||
/// # Safety
|
||||
/// `entity_id`, `state`, and `attrs` must be valid UTF-8 strings.
|
||||
pub fn set_state(entity_id: &str, state: &str, attrs: &str) -> i32 {
|
||||
unsafe {
|
||||
hc_state_set(
|
||||
entity_id.as_ptr() as i32,
|
||||
entity_id.len() as i32,
|
||||
state.as_ptr() as i32,
|
||||
state.len() as i32,
|
||||
attrs.as_ptr() as i32,
|
||||
attrs.len() as i32,
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
/// Emit a log message at INFO level.
|
||||
pub fn log_info(msg: &str) {
|
||||
unsafe {
|
||||
hc_log(1, msg.as_ptr() as i32, msg.len() as i32);
|
||||
}
|
||||
}
|
||||
@@ -1,133 +0,0 @@
|
||||
//! HOMECORE example WASM plugin — proves the ADR-128 P2 host ABI round-trip.
|
||||
//!
|
||||
//! # Behaviour
|
||||
//!
|
||||
//! This plugin monitors `sensor.test_temp` and controls
|
||||
//! `binary_sensor.test_alert` based on the temperature reading:
|
||||
//!
|
||||
//! - `sensor.test_temp` > 25 → set `binary_sensor.test_alert` to `"on"`
|
||||
//! - `sensor.test_temp` < 20 → set `binary_sensor.test_alert` to `"off"`
|
||||
//! - Between 20 and 25 → no change (hysteresis dead-band)
|
||||
//!
|
||||
//! # ABI
|
||||
//!
|
||||
//! The plugin is compiled to `wasm32-unknown-unknown` and exposes the three
|
||||
//! exports required by the HOMECORE host ABI (ADR-128 §5.2):
|
||||
//!
|
||||
//! | Export | Signature | Called when |
|
||||
//! |--------|-----------|-------------|
|
||||
//! | `plugin_setup` | `(ptr:i32, len:i32) → i32` | Config entry set up |
|
||||
//! | `plugin_handle_state_changed` | `(ptr:i32, len:i32) → i32` | State change event |
|
||||
//! | `alloc` | `(size:i32) → i32` | Host needs a guest buffer |
|
||||
//! | `dealloc` | `(ptr:i32, size:i32)` | Host frees a guest buffer |
|
||||
//!
|
||||
//! # Wire format
|
||||
//!
|
||||
//! All payloads are **UTF-8 JSON** delivered via length-prefixed linear
|
||||
//! memory pointers. See `abi.rs` for the guest-side helpers and
|
||||
//! `homecore-plugins/src/host_abi.rs` for the authoritative spec.
|
||||
|
||||
mod abi;
|
||||
|
||||
// Re-export alloc/dealloc so the host can find them.
|
||||
pub use abi::{alloc, dealloc};
|
||||
|
||||
// ── Entity IDs ─────────────────────────────────────────────────────────────
|
||||
|
||||
const TEMP_SENSOR: &str = "sensor.test_temp";
|
||||
const ALERT_SENSOR: &str = "binary_sensor.test_alert";
|
||||
|
||||
// ── Thresholds ─────────────────────────────────────────────────────────────
|
||||
|
||||
const HIGH_THRESH: f64 = 25.0; // above → alert on
|
||||
const LOW_THRESH: f64 = 20.0; // below → alert off
|
||||
|
||||
// ── Plugin exports ──────────────────────────────────────────────────────────
|
||||
|
||||
/// `plugin_setup(config_entry_ptr: i32, config_entry_len: i32) → i32`
|
||||
///
|
||||
/// Called once by the host when the config entry is set up. Subscribes to
|
||||
/// `sensor.test_temp` state changes so the host will deliver them via
|
||||
/// `plugin_handle_state_changed`.
|
||||
///
|
||||
/// Returns 0 on success, negative on error.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn plugin_setup(_ptr: i32, _len: i32) -> i32 {
|
||||
// Subscribe to temperature sensor state changes.
|
||||
let sub_result = abi::hc_state_subscribe(
|
||||
TEMP_SENSOR.as_ptr() as i32,
|
||||
TEMP_SENSOR.len() as i32,
|
||||
);
|
||||
if sub_result != 0 {
|
||||
return -1;
|
||||
}
|
||||
abi::log_info("homecore-plugin-example: setup complete, subscribed to sensor.test_temp");
|
||||
0
|
||||
}
|
||||
|
||||
/// `plugin_handle_state_changed(event_ptr: i32, event_len: i32) → i32`
|
||||
///
|
||||
/// Called by the host whenever a subscribed entity changes state.
|
||||
/// The payload is a JSON object:
|
||||
/// `{"event_type":"state_changed","entity_id":"…","new_state":"…","attributes":{}}`
|
||||
///
|
||||
/// Returns 0 on success, negative on error.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn plugin_handle_state_changed(ptr: i32, len: i32) -> i32 {
|
||||
if len <= 0 || len as usize > abi::MAX_ABI_BUFFER_BYTES {
|
||||
return -1;
|
||||
}
|
||||
|
||||
// Read the event JSON from linear memory.
|
||||
let slice = std::slice::from_raw_parts(ptr as *const u8, len as usize);
|
||||
let json_str = match std::str::from_utf8(slice) {
|
||||
Ok(s) => s,
|
||||
Err(_) => return -2,
|
||||
};
|
||||
|
||||
// Parse the event JSON.
|
||||
let entity_id = extract_json_string(json_str, "entity_id");
|
||||
let new_state_raw = extract_json_string(json_str, "new_state");
|
||||
|
||||
// Only act on sensor.test_temp.
|
||||
match entity_id.as_deref() {
|
||||
Some(e) if e == TEMP_SENSOR => {}
|
||||
_ => return 0,
|
||||
};
|
||||
|
||||
let new_state = match new_state_raw {
|
||||
Some(s) => s,
|
||||
None => return 0,
|
||||
};
|
||||
|
||||
// Parse the temperature value.
|
||||
let temp: f64 = match new_state.parse::<f64>() {
|
||||
Ok(t) => t,
|
||||
Err(_) => return 0, // not a number — ignore
|
||||
};
|
||||
|
||||
// Apply threshold logic with hysteresis dead-band.
|
||||
if temp > HIGH_THRESH {
|
||||
abi::set_state(ALERT_SENSOR, "on", "{}");
|
||||
abi::log_info("homecore-plugin-example: temp > 25, alert ON");
|
||||
} else if temp < LOW_THRESH {
|
||||
abi::set_state(ALERT_SENSOR, "off", "{}");
|
||||
abi::log_info("homecore-plugin-example: temp < 20, alert OFF");
|
||||
}
|
||||
// Dead-band: 20 <= temp <= 25, no change.
|
||||
|
||||
0
|
||||
}
|
||||
|
||||
// ── Minimal JSON field extraction ──────────────────────────────────────────
|
||||
|
||||
/// Extract a string value for `key` from a flat JSON object string.
|
||||
/// Returns `Some(value)` if found, `None` otherwise.
|
||||
/// Only handles simple `"key":"value"` pairs at the top level.
|
||||
fn extract_json_string(json: &str, key: &str) -> Option<String> {
|
||||
let needle = format!("\"{}\":\"", key);
|
||||
let start = json.find(&needle)? + needle.len();
|
||||
let rest = &json[start..];
|
||||
let end = rest.find('"')?;
|
||||
Some(rest[..end].to_owned())
|
||||
}
|
||||
@@ -1,64 +0,0 @@
|
||||
# HOMECORE-PLUGINS — WASM integration plugin system.
|
||||
# Implements ADR-128 (HOMECORE-PLUGINS), P1 scaffold:
|
||||
# - PluginManifest (serde-deserialised, superset of HA manifest.json)
|
||||
# - HomeCorePlugin async trait + PluginId + PluginError
|
||||
# - PluginRuntime trait + InProcessRuntime (native Rust, first-party plugins)
|
||||
# - PluginRegistry (load / unload / list)
|
||||
#
|
||||
# P2 will add the `wasmtime` feature (gated below, default-off) for the real
|
||||
# Wasmtime JIT sandbox. wasm3 interpretation mode lands behind `--features wasm3`
|
||||
# in P3 for constrained-hardware targets.
|
||||
|
||||
[package]
|
||||
name = "homecore-plugins"
|
||||
version = "0.1.0-alpha.0"
|
||||
edition = "2021"
|
||||
license = "MIT"
|
||||
authors = ["rUv <ruv@ruv.net>", "HOMECORE Contributors"]
|
||||
description = "WASM integration plugin runtime for HOMECORE (ADR-128 P1 scaffold)"
|
||||
repository = "https://github.com/ruvnet/RuView"
|
||||
|
||||
[lib]
|
||||
name = "homecore_plugins"
|
||||
path = "src/lib.rs"
|
||||
|
||||
[features]
|
||||
default = []
|
||||
# P2: real Wasmtime JIT sandbox (Cranelift; ~15 MB binary delta on Pi 5).
|
||||
# Do not enable in production until the host ABI is frozen (ADR-128 §8 risk).
|
||||
wasmtime = ["dep:wasmtime"]
|
||||
# P3: wasm3 interpretation mode for constrained hardware (~50 kB).
|
||||
wasm3 = ["dep:wasm3"]
|
||||
|
||||
[dependencies]
|
||||
# HOMECORE state machine — local path (ADR-127).
|
||||
homecore = { path = "../homecore", version = "0.1.0-alpha.0" }
|
||||
|
||||
# Async runtime — same version as workspace.
|
||||
tokio = { version = "1", features = ["sync", "rt", "rt-multi-thread", "time", "macros"] }
|
||||
|
||||
# Async trait support for HomeCorePlugin.
|
||||
async-trait = "0.1"
|
||||
|
||||
# Error handling.
|
||||
thiserror = "1"
|
||||
|
||||
# Serialisation (manifest JSON + ABI call payloads).
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = "1"
|
||||
|
||||
# UUIDs for config entry IDs in host_abi.rs.
|
||||
uuid = { version = "1", features = ["v4"] }
|
||||
|
||||
# Optional Wasmtime runtime (P2, default-off — 30 MB dep).
|
||||
# Bumped from 25.0.3 → 42 to remediate RUSTSEC-2026-0095 and RUSTSEC-2026-0096
|
||||
# (Cranelift/Winch sandbox-escape CVEs, CVSS 9.0 — iter-11 security sprint HC-03/04).
|
||||
wasmtime = { version = "42", optional = true }
|
||||
|
||||
# Optional wasm3 interpretation runtime (P3, default-off).
|
||||
wasm3 = { version = "0.3", optional = true }
|
||||
|
||||
[dev-dependencies]
|
||||
tokio = { version = "1", features = ["sync", "rt", "rt-multi-thread", "time", "macros", "test-util"] }
|
||||
# WAT text-format compiler for inline WASM unit tests (wasmtime feature only).
|
||||
wat = { version = "1", optional = false }
|
||||
@@ -1,144 +0,0 @@
|
||||
# homecore-plugins
|
||||
|
||||
WASM integration plugin runtime for HOMECORE with native Rust runtime (P1) and Wasmtime JIT sandbox support (P2).
|
||||
|
||||
[](https://crates.io/crates/homecore-plugins)
|
||||
|
||||
|
||||
[](https://github.com/ruvnet/RuView)
|
||||
[](../../docs/adr/ADR-128-homecore-integration-plugin-system.md)
|
||||
|
||||
**P1 scaffold**: manifest parsing, plugin traits, and in-memory native Rust plugin registry. Wasmtime sandbox (P2) and hot-reload (P3) are deferred.
|
||||
|
||||
## What this crate does
|
||||
|
||||
`homecore-plugins` provides a trait-based plugin system that can host both native Rust plugins (in-process) and WASM plugins (Wasmtime sandbox, P2). It defines:
|
||||
|
||||
- **PluginManifest** — JSON schema for plugin metadata (superset of Home Assistant's `manifest.json`), validated at load time
|
||||
- **HomeCorePlugin trait** — async lifecycle hooks (`setup`, `teardown`, state changed handlers)
|
||||
- **PluginRuntime trait** — abstraction over execution environments (native vs WASM)
|
||||
- **InProcessRuntime** — built-in runtime for first-party Rust plugins (P1)
|
||||
- **PluginRegistry** — manages loading, unloading, and querying plugins
|
||||
- **Host ABI (stubs)** — C-compatible function signatures for WASM ↔ homecore calls (wiring in P2)
|
||||
|
||||
The system is designed to be feature-gated: compile with `--features wasmtime` to unlock JIT sandbox support for untrusted third-party plugins.
|
||||
|
||||
## Features
|
||||
|
||||
- **Native Rust plugins** — first-party integrations compiled into the binary, zero sandbox overhead (P1)
|
||||
- **WASM plugin framework** — trait-based abstraction ready for Wasmtime JIT (P2) or wasm3 interpreter (P3)
|
||||
- **PluginManifest validation** — required fields enforced at load time; superset of HA manifest fields
|
||||
- **Async plugin lifecycle** — `setup()` and `teardown()` for resource management
|
||||
- **State change subscriptions** — plugins can subscribe to entity state changes with handler callbac
|
||||
- **Config entry lifecycle** — plugin receives config when registered; P3 adds hot-reload
|
||||
- **Feature-gated runtimes** — Wasmtime (30 MB, P2) and wasm3 (50 kB, P3) are optional dependencies
|
||||
- **Manifest inheritance from Home Assistant** — `codeowners`, `requirements`, `documentation`, `issue_tracker`, IoT classification
|
||||
|
||||
## Capabilities
|
||||
|
||||
| Capability | Type | Method | Notes |
|
||||
|------------|------|--------|-------|
|
||||
| Load native plugin | Runtime | `InProcessRuntime::load(manifest, handler)` | Sync; handler is a Rust type implementing `HomeCorePlugin` |
|
||||
| Load WASM plugin | Runtime | `WasmtimeRuntime::load(wasm_bytes, manifest)` (P2) | Async; JIT compiles via Cranelift; requires `--features wasmtime` |
|
||||
| List loaded plugins | Registry | `PluginRegistry::list()` | Returns `Vec<(PluginId, PluginManifest)>` |
|
||||
| Query plugin config | Registry | `PluginRegistry::get_config(plugin_id)` | Returns `Arc<ConfigEntryJson>` |
|
||||
| Call plugin handler | Host ABI | `hc_state_changed(event)` (P2) | WASM plugin receives state change events via exported function |
|
||||
| Unload plugin | Registry | `PluginRegistry::unload(plugin_id)` | Calls `teardown()`, frees memory (P3 = hot-reload) |
|
||||
|
||||
## Comparison to Home Assistant
|
||||
|
||||
| Aspect | Home Assistant | homecore-plugins |
|
||||
|--------|----------------|------------------|
|
||||
| Plugin language | Python (`.py` integrations) | Rust (P1) + WASM (P2+) |
|
||||
| Sandbox | None (all Python in same process) | None (P1); Wasmtime sandbox (P2) |
|
||||
| Plugin discovery | `homeassistant/components/` directory | `PluginManifest` JSON + registry |
|
||||
| Config lifecycle | YAML + dynamic reload | Config entry + manifest (hot-reload P3) |
|
||||
| Host ABI | CPython C API | C types + Wasmtime exported functions (P2) |
|
||||
| Manifest format | Home Assistant's `manifest.json` subset | Superset with `ioc_class`, `cog_publisher` |
|
||||
| Feature gating | Integration-specific | Feature flags: `wasmtime`, `wasm3` |
|
||||
|
||||
## Performance
|
||||
|
||||
- **Native plugin overhead** — same as regular Rust function calls; no sandbox cost
|
||||
- **WASM plugin sandbox** — Wasmtime JIT ~5 ms per call (after warmup); memory overhead ~10 MB per instance
|
||||
- **Manifest parsing** — < 1 ms (serde_json)
|
||||
- **Registry operations** — O(1) plugin lookup (DashMap); O(n) for `list()`
|
||||
- **No per-crate benchmarks yet** — a follow-up issue tracks baseline measurements
|
||||
|
||||
## Usage
|
||||
|
||||
Native plugin (P1):
|
||||
|
||||
```rust
|
||||
use homecore_plugins::{HomeCorePlugin, PluginManifest, InProcessRuntime};
|
||||
use async_trait::async_trait;
|
||||
|
||||
struct MyPlugin;
|
||||
|
||||
#[async_trait]
|
||||
impl HomeCorePlugin for MyPlugin {
|
||||
async fn setup(&mut self) -> Result<(), homecore_plugins::PluginError> {
|
||||
println!("Plugin setup");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn teardown(&mut self) -> Result<(), homecore_plugins::PluginError> {
|
||||
println!("Plugin teardown");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn on_state_changed(&mut self, _event: &homecore_plugins::StateChangedEventJson) -> Result<(), homecore_plugins::PluginError> {
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() {
|
||||
let manifest = PluginManifest {
|
||||
domain: "my_plugin".to_string(),
|
||||
name: "My Plugin".to_string(),
|
||||
..Default::default()
|
||||
};
|
||||
|
||||
let mut runtime = InProcessRuntime::new();
|
||||
let plugin_id = runtime.load(manifest.clone(), MyPlugin).await.expect("load plugin");
|
||||
println!("Loaded plugin: {:?}", plugin_id);
|
||||
runtime.unload(&plugin_id).await.ok();
|
||||
}
|
||||
```
|
||||
|
||||
WASM plugin (P2 example):
|
||||
|
||||
```bash
|
||||
# Build a WASM plugin (requires --features wasmtime)
|
||||
cargo build -p homecore-plugin-example --target wasm32-unknown-unknown --release
|
||||
|
||||
# The WasmtimeRuntime will be available at P2:
|
||||
# let mut runtime = WasmtimeRuntime::new();
|
||||
# let plugin_id = runtime.load(wasm_bytes, manifest).await?;
|
||||
```
|
||||
|
||||
## Relation to other HOMECORE crates
|
||||
|
||||
```
|
||||
homecore-plugins (plugin registry + runtime abstraction)
|
||||
├─ homecore (state machine; plugins receive state changes)
|
||||
├─ homecore-plugin-example (reference WASM plugin)
|
||||
├─ homecore-server (loads plugins at startup)
|
||||
└─ homecore-automation (can invoke handlers via service calls)
|
||||
```
|
||||
|
||||
## Security Notes
|
||||
|
||||
**P1 (this release)**: No sandbox. Native Rust plugins have full process access.
|
||||
|
||||
**P2 (planned)**: Wasmtime JIT sandbox is opt-in via `--features wasmtime`. WASM plugins run in isolated memory with explicit host ABI calls to access homecore state. The host ABI is frozen before P2 begins (ADR-128 §8 risk mitigation).
|
||||
|
||||
**P4+**: Ed25519 signature verification and permission enforcement for third-party Cog registry distribution.
|
||||
|
||||
## References
|
||||
|
||||
- [ADR-128: HOMECORE Integration Plugin System](../../docs/adr/ADR-128-homecore-integration-plugin-system.md)
|
||||
- [homecore-plugin-example: reference WASM plugin](../homecore-plugin-example)
|
||||
- [Host ABI spec](src/host_abi.rs)
|
||||
- [README — wifi-densepose](../../../README.md)
|
||||
@@ -1,35 +0,0 @@
|
||||
//! `PluginError` — typed error enum for the homecore-plugins crate.
|
||||
|
||||
use thiserror::Error;
|
||||
|
||||
/// Errors produced by the HOMECORE plugin system.
|
||||
#[derive(Debug, Error)]
|
||||
pub enum PluginError {
|
||||
/// The plugin manifest JSON is missing required fields or is malformed.
|
||||
#[error("invalid manifest: {0}")]
|
||||
InvalidManifest(String),
|
||||
|
||||
/// A plugin with this ID is already loaded in the registry.
|
||||
#[error("plugin already loaded: {0}")]
|
||||
AlreadyLoaded(String),
|
||||
|
||||
/// No plugin with this ID is loaded in the registry.
|
||||
#[error("plugin not found: {0}")]
|
||||
NotFound(String),
|
||||
|
||||
/// The plugin runtime failed to spawn or execute the plugin.
|
||||
#[error("runtime error: {0}")]
|
||||
RuntimeError(String),
|
||||
|
||||
/// The plugin's `setup` hook returned an error.
|
||||
#[error("plugin setup failed: {0}")]
|
||||
SetupFailed(String),
|
||||
|
||||
/// The plugin's `unload` hook returned an error.
|
||||
#[error("plugin unload failed: {0}")]
|
||||
UnloadFailed(String),
|
||||
|
||||
/// IO error (manifest file not found, WASM binary missing, etc.).
|
||||
#[error("io error: {0}")]
|
||||
Io(#[from] std::io::Error),
|
||||
}
|
||||
@@ -1,128 +0,0 @@
|
||||
//! Host ABI — the public on-the-wire memory format between the HOMECORE host
|
||||
//! and every WASM plugin.
|
||||
//!
|
||||
//! # Overview
|
||||
//!
|
||||
//! HOMECORE uses **JSON over UTF-8 linear memory** for all host↔guest data.
|
||||
//! This matches HA's JSON-everywhere convention and makes call payloads
|
||||
//! inspectable in debuggers without a schema file. Each `hc_*` host function
|
||||
//! and each guest export uses the same pointer + length convention:
|
||||
//!
|
||||
//! ```text
|
||||
//! host calls alloc(size) → ptr (exported by guest)
|
||||
//! host writes UTF-8 bytes into guest linear memory at [ptr, ptr+size)
|
||||
//! host calls the guest export with (ptr: i32, len: i32)
|
||||
//! guest reads and JSON-decodes the slice
|
||||
//! guest writes its reply via hc_state_set / hc_log / etc. (host imports)
|
||||
//! host calls dealloc(ptr, size) when finished (exported by guest)
|
||||
//! ```
|
||||
//!
|
||||
//! # Wire types
|
||||
//!
|
||||
//! | Call | Direction | JSON schema |
|
||||
//! |------|-----------|-------------|
|
||||
//! | `hc_state_get` reply | host → caller | `{"entity_id":"…","state":"…","attributes":{…}}` or null bytes (not found) |
|
||||
//! | `hc_state_set` args | guest → host | `(entity_id, state, attrs)` as 3 separate ptr/len pairs; each is a UTF-8 string or JSON object |
|
||||
//! | `hc_log` args | guest → host | `(level: i32, msg)` where level 0=debug 1=info 2=warn 3=error |
|
||||
//! | `hc_state_subscribe` | guest → host | entity_id UTF-8 string |
|
||||
//! | `setup_entry` | host → guest | `{"entry_id":"…","domain":"…","data":{}}` (ConfigEntry JSON) |
|
||||
//! | `receive_event` | host → guest | `{"event_type":"state_changed","entity_id":"…","new_state":"…"}` |
|
||||
//!
|
||||
//! # Memory layout guarantees
|
||||
//!
|
||||
//! - Buffers are **always** valid UTF-8 (JSON subset).
|
||||
//! - Maximum buffer size is **64 KiB** (65,536 bytes). Larger payloads must
|
||||
//! be split by the caller; the host rejects oversized writes with a WASM
|
||||
//! trap. This bound is enforced in [`write_guest_buf`].
|
||||
//! - The host **never** holds a guest memory pointer across a WASM call
|
||||
//! boundary. Pointers are only valid for the duration of a single call.
|
||||
//!
|
||||
//! # `hc_state_subscribe` semantics
|
||||
//!
|
||||
//! A plugin calls `hc_state_subscribe(eid_ptr, eid_len)` once per entity it
|
||||
//! wants to track. Subsequent state changes for that entity arrive via a
|
||||
//! `receive_event` call with event_type `"state_changed"`.
|
||||
//!
|
||||
//! Subscriptions are held for the lifetime of the plugin instance.
|
||||
|
||||
/// Maximum number of bytes the host will write into a single guest buffer.
|
||||
/// Plugins may safely size their `alloc` buffers at this ceiling.
|
||||
pub const MAX_ABI_BUFFER_BYTES: usize = 65_536;
|
||||
|
||||
/// JSON payload passed to `setup_entry` when a config entry is set up.
|
||||
///
|
||||
/// Serialises to HA-compat `ConfigEntry` JSON.
|
||||
#[derive(Debug, serde::Serialize, serde::Deserialize)]
|
||||
pub struct ConfigEntryJson {
|
||||
pub entry_id: String,
|
||||
pub domain: String,
|
||||
pub title: String,
|
||||
pub data: serde_json::Value,
|
||||
}
|
||||
|
||||
impl ConfigEntryJson {
|
||||
/// Construct a minimal config entry for test / bootstrap use.
|
||||
pub fn bootstrap(domain: &str) -> Self {
|
||||
Self {
|
||||
entry_id: uuid::Uuid::new_v4().to_string(),
|
||||
domain: domain.to_owned(),
|
||||
title: domain.to_owned(),
|
||||
data: serde_json::json!({}),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// JSON payload for `receive_event` — `state_changed` variant.
|
||||
#[derive(Debug, serde::Serialize, serde::Deserialize)]
|
||||
pub struct StateChangedEventJson {
|
||||
pub event_type: String,
|
||||
pub entity_id: String,
|
||||
pub new_state: Option<String>,
|
||||
pub attributes: serde_json::Value,
|
||||
}
|
||||
|
||||
impl StateChangedEventJson {
|
||||
/// Construct a `state_changed` event payload.
|
||||
pub fn state_changed(
|
||||
entity_id: &str,
|
||||
new_state: Option<&str>,
|
||||
attributes: serde_json::Value,
|
||||
) -> Self {
|
||||
Self {
|
||||
event_type: "state_changed".to_owned(),
|
||||
entity_id: entity_id.to_owned(),
|
||||
new_state: new_state.map(str::to_owned),
|
||||
attributes,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Log levels for `hc_log`.
|
||||
#[repr(i32)]
|
||||
pub enum LogLevel {
|
||||
Debug = 0,
|
||||
Info = 1,
|
||||
Warn = 2,
|
||||
Error = 3,
|
||||
}
|
||||
|
||||
impl LogLevel {
|
||||
/// Convert from the i32 wire value. Unknown values map to `Warn`.
|
||||
pub fn from_i32(n: i32) -> Self {
|
||||
match n {
|
||||
0 => LogLevel::Debug,
|
||||
1 => LogLevel::Info,
|
||||
3 => LogLevel::Error,
|
||||
_ => LogLevel::Warn,
|
||||
}
|
||||
}
|
||||
|
||||
pub fn as_str(&self) -> &'static str {
|
||||
match self {
|
||||
LogLevel::Debug => "DEBUG",
|
||||
LogLevel::Info => "INFO",
|
||||
LogLevel::Warn => "WARN",
|
||||
LogLevel::Error => "ERROR",
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,56 +0,0 @@
|
||||
//! HOMECORE-PLUGINS — WASM integration plugin system.
|
||||
//!
|
||||
//! Implements [ADR-128](../../docs/adr/ADR-128-homecore-integration-plugin-system.md)
|
||||
//! P1 scaffold: manifest parsing, the `HomeCorePlugin` async trait, the
|
||||
//! `PluginRuntime` abstraction, and the `PluginRegistry`.
|
||||
//!
|
||||
//! ## What's here (P1)
|
||||
//!
|
||||
//! - [`manifest`] — `PluginManifest`: superset of HA `manifest.json`; serde
|
||||
//! round-trip + required-field validation.
|
||||
//! - [`plugin`] — `HomeCorePlugin` async trait, `PluginId` newtype.
|
||||
//! - [`runtime`] — `PluginRuntime` trait + `InProcessRuntime` (native Rust,
|
||||
//! first-party plugins compiled into the binary).
|
||||
//! - [`registry`] — `PluginRegistry<R>`: load / unload / list plugins.
|
||||
//! - [`error`] — `PluginError` typed error enum.
|
||||
//!
|
||||
//! ## What's NOT here yet (deferred)
|
||||
//!
|
||||
//! - `WasmtimeRuntime` (P2, `--features wasmtime`): Cranelift JIT sandbox on
|
||||
//! Pi 5 / x86_64. The runtime-selection question (Wasmtime vs wasm3) is still
|
||||
//! open (ADR-128 §8) and will be resolved in Q2 before P2 begins.
|
||||
//! - Host ABI wiring: `hc_state_get`, `hc_state_set`, `hc_event_fire`, etc.
|
||||
//! (P2 — requires ADR-127 state machine API freeze first).
|
||||
//! - Config entry lifecycle + hot-load (P3).
|
||||
//! - Cog registry distribution + Ed25519 signature verification (P4).
|
||||
//! - Permission enforcement (P5).
|
||||
//!
|
||||
//! ## Feature flags
|
||||
//!
|
||||
//! | Feature | Default | Description |
|
||||
//! |---------|---------|-------------|
|
||||
//! | `wasmtime` | off | Wasmtime Cranelift JIT runtime (P2) |
|
||||
//! | `wasm3` | off | wasm3 interpreter runtime for constrained hardware (P3) |
|
||||
|
||||
pub mod error;
|
||||
pub mod host_abi;
|
||||
pub mod manifest;
|
||||
pub mod plugin;
|
||||
pub mod registry;
|
||||
pub mod runtime;
|
||||
|
||||
#[cfg(feature = "wasmtime")]
|
||||
pub mod wasmtime_runtime;
|
||||
|
||||
pub use error::PluginError;
|
||||
pub use host_abi::{ConfigEntryJson, StateChangedEventJson};
|
||||
pub use manifest::{IotClass, IntegrationType, PluginManifest};
|
||||
pub use plugin::{HomeCorePlugin, PluginId};
|
||||
pub use registry::PluginRegistry;
|
||||
pub use runtime::{InProcessRuntime, LoadedPlugin, PluginRuntime};
|
||||
|
||||
#[cfg(feature = "wasmtime")]
|
||||
pub use wasmtime_runtime::{WasmPlugin, WasmtimeRuntime};
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests;
|
||||
@@ -1,144 +0,0 @@
|
||||
//! Plugin manifest — superset of HA's `manifest.json`.
|
||||
//!
|
||||
//! See ADR-128 §3 for the full field list. Fields present in HA's schema
|
||||
//! are preserved verbatim. HOMECORE-specific fields are marked `[HOMECORE]`.
|
||||
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
use crate::error::PluginError;
|
||||
|
||||
/// Coarse-grained permission claim string (glob pattern).
|
||||
/// Example: `"state:write:sensor.*"`.
|
||||
pub type PermissionClaim = String;
|
||||
|
||||
/// HA `iot_class` values (non-exhaustive — HA adds new classes over time).
|
||||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "snake_case")]
|
||||
pub enum IotClass {
|
||||
LocalPush,
|
||||
LocalPolling,
|
||||
CloudPush,
|
||||
CloudPolling,
|
||||
AssumedState,
|
||||
Calculated,
|
||||
#[serde(other)]
|
||||
Other,
|
||||
}
|
||||
|
||||
/// HOMECORE integration type.
|
||||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "snake_case")]
|
||||
pub enum IntegrationType {
|
||||
Integration,
|
||||
Helper,
|
||||
Entity,
|
||||
#[serde(other)]
|
||||
Other,
|
||||
}
|
||||
|
||||
/// Parsed and validated plugin manifest.
|
||||
///
|
||||
/// Serialises to/from HA-compatible `manifest.json`. HOMECORE-only fields
|
||||
/// are `Option<…>` so that a plain HA manifest is a valid (native-only)
|
||||
/// HOMECORE manifest.
|
||||
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
|
||||
pub struct PluginManifest {
|
||||
/// Unique integration domain identifier (e.g. `"mqtt"`).
|
||||
pub domain: String,
|
||||
|
||||
/// Human-readable integration name.
|
||||
pub name: String,
|
||||
|
||||
/// SemVer-ish version string (HA uses calendar-versioning, e.g. `"2025.1.0"`).
|
||||
pub version: String,
|
||||
|
||||
/// Optional documentation URL.
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub documentation: Option<String>,
|
||||
|
||||
/// HA `iot_class` — how the integration communicates with the device.
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub iot_class: Option<IotClass>,
|
||||
|
||||
/// Whether this integration ships a UI config flow.
|
||||
#[serde(default)]
|
||||
pub config_flow: bool,
|
||||
|
||||
/// HOMECORE integration type (optional, defaults to Integration).
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub integration_type: Option<IntegrationType>,
|
||||
|
||||
/// Intra-HOMECORE dependencies (other plugin domains this one requires).
|
||||
#[serde(default)]
|
||||
pub dependencies: Vec<String>,
|
||||
|
||||
/// External package requirements — kept for schema compat, ignored in HOMECORE
|
||||
/// (WASM modules carry their own static deps, no pip).
|
||||
#[serde(default)]
|
||||
pub requirements: Vec<String>,
|
||||
|
||||
// ── [HOMECORE] fields ──────────────────────────────────────────────────
|
||||
|
||||
/// [HOMECORE] Relative path to the `.wasm` binary (absent for native plugins).
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub wasm_module: Option<String>,
|
||||
|
||||
/// [HOMECORE] `sha256:<hex>` hash of the wasm binary; verified before execution.
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub wasm_module_hash: Option<String>,
|
||||
|
||||
/// [HOMECORE] Ed25519 signature of the wasm binary hash (`ed25519:<base64>`).
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub wasm_module_sig: Option<String>,
|
||||
|
||||
/// [HOMECORE] Ed25519 public key of the plugin publisher.
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub publisher_key: Option<String>,
|
||||
|
||||
/// [HOMECORE] Minimum HOMECORE version required by this plugin.
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub min_homecore_version: Option<String>,
|
||||
|
||||
/// [HOMECORE] Subset of host functions the WASM module imports.
|
||||
#[serde(default)]
|
||||
pub host_imports_required: Vec<String>,
|
||||
|
||||
/// [HOMECORE] Coarse-grained permission claims (glob patterns).
|
||||
#[serde(default)]
|
||||
pub homecore_permissions: Vec<PermissionClaim>,
|
||||
|
||||
/// [HOMECORE] Seed app registry cog ID for distribution.
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub cog_id: Option<String>,
|
||||
}
|
||||
|
||||
impl PluginManifest {
|
||||
/// Parse a `manifest.json` JSON string and validate required fields.
|
||||
///
|
||||
/// Required fields: `domain`, `name`, `version`.
|
||||
pub fn parse_json(s: &str) -> Result<Self, PluginError> {
|
||||
let m: Self = serde_json::from_str(s)
|
||||
.map_err(|e| PluginError::InvalidManifest(e.to_string()))?;
|
||||
m.validate()?;
|
||||
Ok(m)
|
||||
}
|
||||
|
||||
fn validate(&self) -> Result<(), PluginError> {
|
||||
if self.domain.trim().is_empty() {
|
||||
return Err(PluginError::InvalidManifest(
|
||||
"manifest `domain` must not be empty".into(),
|
||||
));
|
||||
}
|
||||
if self.name.trim().is_empty() {
|
||||
return Err(PluginError::InvalidManifest(
|
||||
"manifest `name` must not be empty".into(),
|
||||
));
|
||||
}
|
||||
if self.version.trim().is_empty() {
|
||||
return Err(PluginError::InvalidManifest(
|
||||
"manifest `version` must not be empty".into(),
|
||||
));
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
@@ -1,59 +0,0 @@
|
||||
//! `HomeCorePlugin` trait + `PluginId` newtype.
|
||||
//!
|
||||
//! Every first-party and third-party HOMECORE integration must implement
|
||||
//! `HomeCorePlugin`. P1 provides an in-process native Rust implementation;
|
||||
//! the WASM ABI wrapper (which maps the WASM exports `setup_entry`,
|
||||
//! `call_service_handler`, `receive_event` to this trait) lands in P2.
|
||||
|
||||
use std::fmt;
|
||||
|
||||
use async_trait::async_trait;
|
||||
use homecore::HomeCore;
|
||||
|
||||
use crate::error::PluginError;
|
||||
|
||||
/// Unique identifier for a loaded plugin — mirrors the `domain` field of
|
||||
/// the plugin's `PluginManifest` (e.g. `"mqtt"`, `"homecore_lights"`).
|
||||
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
|
||||
pub struct PluginId(pub String);
|
||||
|
||||
impl PluginId {
|
||||
/// Create a new `PluginId` from any string-like value.
|
||||
pub fn new(s: impl Into<String>) -> Self {
|
||||
Self(s.into())
|
||||
}
|
||||
|
||||
/// Return the inner domain string.
|
||||
pub fn as_str(&self) -> &str {
|
||||
&self.0
|
||||
}
|
||||
}
|
||||
|
||||
impl fmt::Display for PluginId {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
f.write_str(&self.0)
|
||||
}
|
||||
}
|
||||
|
||||
/// Lifecycle trait that every HOMECORE integration must implement.
|
||||
///
|
||||
/// Implementing types are passed to [`PluginRuntime::load`]; the runtime
|
||||
/// calls these methods at the appropriate lifecycle points.
|
||||
///
|
||||
/// # Async
|
||||
/// Both methods are `async` to allow network / IO initialisation without
|
||||
/// blocking the Tokio runtime. The `async_trait` macro erases the `impl`
|
||||
/// return type so it works in trait objects.
|
||||
#[async_trait]
|
||||
pub trait HomeCorePlugin: Send + Sync + 'static {
|
||||
/// Called once when the plugin's config entry is being set up.
|
||||
///
|
||||
/// The plugin receives a reference to the `HomeCore` runtime and should
|
||||
/// register its entities, services, and event subscriptions here.
|
||||
async fn setup(&self, hc: HomeCore) -> Result<(), PluginError>;
|
||||
|
||||
/// Called when the plugin is being removed from the registry.
|
||||
///
|
||||
/// The plugin should clean up subscriptions and deregister its entities.
|
||||
async fn unload(&self) -> Result<(), PluginError>;
|
||||
}
|
||||
@@ -1,102 +0,0 @@
|
||||
//! `PluginRegistry` — load, unload, and list HOMECORE plugins.
|
||||
//!
|
||||
//! The registry is runtime-agnostic: it accepts any type that implements
|
||||
//! [`PluginRuntime`] and delegates load/unload to it. This allows swapping
|
||||
//! the `InProcessRuntime` (P1) for a `WasmtimeRuntime` (P2) without
|
||||
//! changing registry code.
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::sync::Arc;
|
||||
|
||||
use homecore::HomeCore;
|
||||
use tokio::sync::RwLock;
|
||||
|
||||
use crate::error::PluginError;
|
||||
use crate::manifest::PluginManifest;
|
||||
use crate::plugin::{HomeCorePlugin, PluginId};
|
||||
use crate::runtime::{LoadedPlugin, PluginRuntime};
|
||||
|
||||
/// Holds all loaded plugins keyed by `PluginId`.
|
||||
///
|
||||
/// Thread-safe via `RwLock` — concurrent reads are cheap; writes (load /
|
||||
/// unload) take an exclusive lock only while mutating the map.
|
||||
pub struct PluginRegistry<R: PluginRuntime> {
|
||||
runtime: R,
|
||||
plugins: RwLock<HashMap<PluginId, LoadedPlugin>>,
|
||||
}
|
||||
|
||||
impl<R: PluginRuntime> PluginRegistry<R> {
|
||||
/// Create an empty registry backed by `runtime`.
|
||||
pub fn new(runtime: R) -> Self {
|
||||
Self {
|
||||
runtime,
|
||||
plugins: RwLock::new(HashMap::new()),
|
||||
}
|
||||
}
|
||||
|
||||
/// Load a plugin, call its `setup` hook, and insert it into the registry.
|
||||
///
|
||||
/// Returns `PluginError::AlreadyLoaded` if a plugin with the same ID is
|
||||
/// already registered.
|
||||
pub async fn load(
|
||||
&self,
|
||||
manifest: PluginManifest,
|
||||
plugin: Arc<dyn HomeCorePlugin>,
|
||||
hc: HomeCore,
|
||||
) -> Result<PluginId, PluginError> {
|
||||
let id = PluginId::new(&manifest.domain);
|
||||
|
||||
{
|
||||
let guard = self.plugins.read().await;
|
||||
if guard.contains_key(&id) {
|
||||
return Err(PluginError::AlreadyLoaded(id.to_string()));
|
||||
}
|
||||
}
|
||||
|
||||
let loaded = self
|
||||
.runtime
|
||||
.load(id.clone(), manifest, plugin)
|
||||
.await?;
|
||||
|
||||
loaded
|
||||
.setup(hc)
|
||||
.await
|
||||
.map_err(|e| PluginError::SetupFailed(e.to_string()))?;
|
||||
|
||||
self.plugins.write().await.insert(id.clone(), loaded);
|
||||
Ok(id)
|
||||
}
|
||||
|
||||
/// Unload a plugin by ID, calling its `unload` hook first.
|
||||
///
|
||||
/// Returns `PluginError::NotFound` if the plugin was not loaded.
|
||||
pub async fn unload(&self, id: &PluginId) -> Result<(), PluginError> {
|
||||
let loaded = {
|
||||
let mut guard = self.plugins.write().await;
|
||||
guard
|
||||
.remove(id)
|
||||
.ok_or_else(|| PluginError::NotFound(id.to_string()))?
|
||||
};
|
||||
|
||||
loaded
|
||||
.unload()
|
||||
.await
|
||||
.map_err(|e| PluginError::UnloadFailed(e.to_string()))?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Return a snapshot of currently loaded plugin IDs and their manifest domains.
|
||||
pub async fn list(&self) -> Vec<(PluginId, String)> {
|
||||
let guard = self.plugins.read().await;
|
||||
guard
|
||||
.iter()
|
||||
.map(|(id, lp)| (id.clone(), lp.manifest.domain.clone()))
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// Return `true` if a plugin with this ID is loaded.
|
||||
pub async fn contains(&self, id: &PluginId) -> bool {
|
||||
self.plugins.read().await.contains_key(id)
|
||||
}
|
||||
}
|
||||
@@ -1,95 +0,0 @@
|
||||
//! `PluginRuntime` trait + `InProcessRuntime` (P1).
|
||||
//!
|
||||
//! Abstracts over Wasmtime (P2, `--features wasmtime`) and native in-process
|
||||
//! Rust plugins (P1, always-on). A third backend, wasm3 (P3), will provide
|
||||
//! interpretation mode for constrained hardware.
|
||||
//!
|
||||
//! # Architecture
|
||||
//!
|
||||
//! ```text
|
||||
//! PluginRegistry
|
||||
//! │
|
||||
//! ▼
|
||||
//! PluginRuntime ◄─── InProcessRuntime (P1, native Rust, <1 µs call)
|
||||
//! ◄─── WasmtimeRuntime (P2, Cranelift JIT, ~5 ms cold start)
|
||||
//! ◄─── Wasm3Runtime (P3, interpreter, ~50 kB, Pi Zero)
|
||||
//! ```
|
||||
|
||||
use std::sync::Arc;
|
||||
|
||||
use async_trait::async_trait;
|
||||
use homecore::HomeCore;
|
||||
|
||||
use crate::error::PluginError;
|
||||
use crate::manifest::PluginManifest;
|
||||
use crate::plugin::{HomeCorePlugin, PluginId};
|
||||
|
||||
/// A loaded plugin handle — returned by [`PluginRuntime::load`].
|
||||
pub struct LoadedPlugin {
|
||||
pub id: PluginId,
|
||||
pub manifest: PluginManifest,
|
||||
/// Underlying plugin instance (boxed trait object).
|
||||
pub(crate) instance: Arc<dyn HomeCorePlugin>,
|
||||
}
|
||||
|
||||
impl LoadedPlugin {
|
||||
/// Delegate to the inner plugin's `setup` method.
|
||||
pub async fn setup(&self, hc: HomeCore) -> Result<(), PluginError> {
|
||||
self.instance.setup(hc).await
|
||||
}
|
||||
|
||||
/// Delegate to the inner plugin's `unload` method.
|
||||
pub async fn unload(&self) -> Result<(), PluginError> {
|
||||
self.instance.unload().await
|
||||
}
|
||||
}
|
||||
|
||||
/// Abstraction over the WASM (and native) plugin execution environment.
|
||||
///
|
||||
/// P2 will supply a `WasmtimeRuntime` that compiles `.wasm` bytes with
|
||||
/// Cranelift; P3 adds a `Wasm3Runtime` for constrained targets. Both will
|
||||
/// implement this trait so the registry is runtime-agnostic.
|
||||
#[async_trait]
|
||||
pub trait PluginRuntime: Send + Sync + 'static {
|
||||
/// Load a plugin from a boxed [`HomeCorePlugin`] implementation and a
|
||||
/// parsed `PluginManifest`. Returns a `LoadedPlugin` handle.
|
||||
async fn load(
|
||||
&self,
|
||||
id: PluginId,
|
||||
manifest: PluginManifest,
|
||||
plugin: Arc<dyn HomeCorePlugin>,
|
||||
) -> Result<LoadedPlugin, PluginError>;
|
||||
}
|
||||
|
||||
/// Native in-process runtime — loads first-party Rust plugins directly.
|
||||
///
|
||||
/// No WASM compilation; no sandbox. Intended for first-party plugins
|
||||
/// (RuView MQTT bridge, presence sensor, etc.) that are compiled into the
|
||||
/// HOMECORE binary and therefore trusted. Third-party / community plugins
|
||||
/// must use the `WasmtimeRuntime` (P2) for isolation.
|
||||
pub struct InProcessRuntime;
|
||||
|
||||
#[async_trait]
|
||||
impl PluginRuntime for InProcessRuntime {
|
||||
async fn load(
|
||||
&self,
|
||||
id: PluginId,
|
||||
manifest: PluginManifest,
|
||||
plugin: Arc<dyn HomeCorePlugin>,
|
||||
) -> Result<LoadedPlugin, PluginError> {
|
||||
Ok(LoadedPlugin {
|
||||
id,
|
||||
manifest,
|
||||
instance: plugin,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// ── Feature-gated Wasmtime implementation (P2) ───────────────────────────
|
||||
//
|
||||
// The full `WasmtimeRuntime` lives in `crate::wasmtime_runtime` (P2).
|
||||
// It is re-exported from `crate::lib` as `WasmtimeRuntime` when the
|
||||
// `wasmtime` feature is enabled. The `PluginRuntime` trait below is
|
||||
// kept intentionally narrow (in-process plugin contract) so the WASM
|
||||
// path can use its own `WasmPlugin` wrapper without forcing the trait
|
||||
// to carry WASM-specific concerns.
|
||||
@@ -1,233 +0,0 @@
|
||||
//! Unit tests for homecore-plugins P1 scaffold.
|
||||
//!
|
||||
//! Covers: manifest parse + round-trip, manifest field validation,
|
||||
//! PluginRegistry load/unload/list/duplicate, InProcessRuntime,
|
||||
//! and PluginError variants.
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use std::sync::Arc;
|
||||
|
||||
use async_trait::async_trait;
|
||||
use homecore::HomeCore;
|
||||
use tokio::sync::Mutex;
|
||||
|
||||
use crate::error::PluginError;
|
||||
use crate::manifest::PluginManifest;
|
||||
use crate::plugin::{HomeCorePlugin, PluginId};
|
||||
use crate::registry::PluginRegistry;
|
||||
use crate::runtime::InProcessRuntime;
|
||||
|
||||
// ── Test double ────────────────────────────────────────────────────────
|
||||
|
||||
/// Minimal plugin that records setup/unload calls.
|
||||
struct TestPlugin {
|
||||
pub setup_called: Mutex<bool>,
|
||||
pub unload_called: Mutex<bool>,
|
||||
}
|
||||
|
||||
impl TestPlugin {
|
||||
fn new() -> Arc<Self> {
|
||||
Arc::new(Self {
|
||||
setup_called: Mutex::new(false),
|
||||
unload_called: Mutex::new(false),
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait]
|
||||
impl HomeCorePlugin for TestPlugin {
|
||||
async fn setup(&self, _hc: HomeCore) -> Result<(), PluginError> {
|
||||
*self.setup_called.lock().await = true;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn unload(&self) -> Result<(), PluginError> {
|
||||
*self.unload_called.lock().await = true;
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
fn minimal_manifest(domain: &str) -> PluginManifest {
|
||||
PluginManifest {
|
||||
domain: domain.into(),
|
||||
name: "Test Plugin".into(),
|
||||
version: "1.0.0".into(),
|
||||
documentation: None,
|
||||
iot_class: None,
|
||||
config_flow: false,
|
||||
integration_type: None,
|
||||
dependencies: vec![],
|
||||
requirements: vec![],
|
||||
wasm_module: None,
|
||||
wasm_module_hash: None,
|
||||
wasm_module_sig: None,
|
||||
publisher_key: None,
|
||||
min_homecore_version: None,
|
||||
host_imports_required: vec![],
|
||||
homecore_permissions: vec![],
|
||||
cog_id: None,
|
||||
}
|
||||
}
|
||||
|
||||
// ── Manifest tests ─────────────────────────────────────────────────────
|
||||
|
||||
#[test]
|
||||
fn manifest_parse_round_trip() {
|
||||
let json = r#"{
|
||||
"domain": "mqtt",
|
||||
"name": "MQTT",
|
||||
"version": "2025.1.0",
|
||||
"iot_class": "local_push",
|
||||
"config_flow": true,
|
||||
"dependencies": [],
|
||||
"requirements": [],
|
||||
"wasm_module": "mqtt.wasm",
|
||||
"homecore_permissions": ["state:write:sensor.*"]
|
||||
}"#;
|
||||
|
||||
let m = PluginManifest::parse_json(json).expect("should parse");
|
||||
assert_eq!(m.domain, "mqtt");
|
||||
assert_eq!(m.version, "2025.1.0");
|
||||
assert!(m.config_flow);
|
||||
assert_eq!(m.homecore_permissions, vec!["state:write:sensor.*"]);
|
||||
|
||||
// round-trip: serialize back to JSON and re-parse
|
||||
let serialised = serde_json::to_string(&m).expect("should serialise");
|
||||
let m2 = PluginManifest::parse_json(&serialised).expect("round-trip should parse");
|
||||
assert_eq!(m.domain, m2.domain);
|
||||
assert_eq!(m.version, m2.version);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn manifest_rejects_empty_domain() {
|
||||
let json = r#"{"domain":"","name":"X","version":"1.0.0"}"#;
|
||||
let err = PluginManifest::parse_json(json).unwrap_err();
|
||||
assert!(
|
||||
err.to_string().contains("domain"),
|
||||
"error should mention domain: {err}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn manifest_rejects_missing_domain() {
|
||||
let json = r#"{"name":"X","version":"1.0.0"}"#;
|
||||
// serde will fill domain as "" due to missing field → validation rejects
|
||||
let err = PluginManifest::parse_json(json).unwrap_err();
|
||||
// Either a serde error (missing field) or a validation error is acceptable
|
||||
let s = err.to_string();
|
||||
assert!(!s.is_empty(), "should produce a non-empty error");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn manifest_rejects_empty_version() {
|
||||
let json = r#"{"domain":"lights","name":"Lights","version":""}"#;
|
||||
let err = PluginManifest::parse_json(json).unwrap_err();
|
||||
assert!(
|
||||
err.to_string().contains("version"),
|
||||
"error should mention version: {err}"
|
||||
);
|
||||
}
|
||||
|
||||
// ── Registry + InProcessRuntime tests ─────────────────────────────────
|
||||
|
||||
#[tokio::test]
|
||||
async fn registry_load_and_list() {
|
||||
let hc = HomeCore::new();
|
||||
let registry = PluginRegistry::new(InProcessRuntime);
|
||||
let plugin = TestPlugin::new();
|
||||
let manifest = minimal_manifest("lights");
|
||||
|
||||
let id = registry
|
||||
.load(manifest, plugin.clone(), hc)
|
||||
.await
|
||||
.expect("load should succeed");
|
||||
|
||||
assert_eq!(id.as_str(), "lights");
|
||||
assert!(*plugin.setup_called.lock().await, "setup should have been called");
|
||||
|
||||
let listing = registry.list().await;
|
||||
assert_eq!(listing.len(), 1);
|
||||
assert_eq!(listing[0].0.as_str(), "lights");
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn registry_unload_removes_plugin() {
|
||||
let hc = HomeCore::new();
|
||||
let registry = PluginRegistry::new(InProcessRuntime);
|
||||
let plugin = TestPlugin::new();
|
||||
|
||||
let id = registry
|
||||
.load(minimal_manifest("switch"), plugin.clone(), hc)
|
||||
.await
|
||||
.expect("load should succeed");
|
||||
|
||||
registry.unload(&id).await.expect("unload should succeed");
|
||||
assert!(*plugin.unload_called.lock().await, "unload should have been called");
|
||||
assert_eq!(registry.list().await.len(), 0);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn registry_rejects_duplicate_load() {
|
||||
let hc1 = HomeCore::new();
|
||||
let hc2 = HomeCore::new();
|
||||
let registry = PluginRegistry::new(InProcessRuntime);
|
||||
|
||||
registry
|
||||
.load(minimal_manifest("sensor"), TestPlugin::new(), hc1)
|
||||
.await
|
||||
.expect("first load should succeed");
|
||||
|
||||
let err = registry
|
||||
.load(minimal_manifest("sensor"), TestPlugin::new(), hc2)
|
||||
.await
|
||||
.unwrap_err();
|
||||
|
||||
assert!(
|
||||
matches!(err, PluginError::AlreadyLoaded(_)),
|
||||
"expected AlreadyLoaded, got: {err:?}"
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn registry_unload_unknown_plugin_returns_not_found() {
|
||||
let registry = PluginRegistry::new(InProcessRuntime);
|
||||
let id = PluginId::new("nonexistent");
|
||||
let err = registry.unload(&id).await.unwrap_err();
|
||||
assert!(
|
||||
matches!(err, PluginError::NotFound(_)),
|
||||
"expected NotFound, got: {err:?}"
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn in_process_runtime_setup_called() {
|
||||
let hc = HomeCore::new();
|
||||
let registry = PluginRegistry::new(InProcessRuntime);
|
||||
let plugin = TestPlugin::new();
|
||||
|
||||
registry
|
||||
.load(minimal_manifest("climate"), plugin.clone(), hc)
|
||||
.await
|
||||
.expect("load should succeed");
|
||||
|
||||
assert!(
|
||||
*plugin.setup_called.lock().await,
|
||||
"InProcessRuntime must call setup"
|
||||
);
|
||||
}
|
||||
|
||||
// ── Error display ──────────────────────────────────────────────────────
|
||||
|
||||
#[test]
|
||||
fn error_display_variants() {
|
||||
let e1 = PluginError::AlreadyLoaded("mqtt".into());
|
||||
assert!(e1.to_string().contains("mqtt"));
|
||||
|
||||
let e2 = PluginError::NotFound("climate".into());
|
||||
assert!(e2.to_string().contains("climate"));
|
||||
|
||||
let e3 = PluginError::RuntimeError("boom".into());
|
||||
assert!(e3.to_string().contains("boom"));
|
||||
}
|
||||
}
|
||||
@@ -1,553 +0,0 @@
|
||||
//! `WasmtimeRuntime` — Cranelift JIT WASM plugin runtime (ADR-128 P2).
|
||||
//!
|
||||
//! # Design
|
||||
//!
|
||||
//! Each `.wasm` binary is compiled once per process by a shared [`Engine`].
|
||||
//! Every call to [`WasmtimeRuntime::load_wasm`] creates a new [`Store`] so
|
||||
//! plugins are fully isolated — one plugin cannot read another's linear memory.
|
||||
//!
|
||||
//! The 4 host imports the WASM module receives are registered via a [`Linker`]:
|
||||
//!
|
||||
//! | Import | Signature | Description |
|
||||
//! |--------|-----------|-------------|
|
||||
//! | `hc_state_get` | `(i32,i32,i32,i32)→i32` | Read entity state into guest buffer |
|
||||
//! | `hc_state_set` | `(i32,i32,i32,i32,i32,i32)→i32` | Write entity state from guest buffer |
|
||||
//! | `hc_state_subscribe` | `(i32,i32)→i32` | Subscribe to state-changed events |
|
||||
//! | `hc_log` | `(i32,i32,i32)→()` | Structured log output from plugin |
|
||||
//!
|
||||
//! WASI is **not** imported — plugins have no filesystem or network access.
|
||||
//!
|
||||
//! # Memory convention
|
||||
//!
|
||||
//! The guest exports `alloc(size: i32) → i32` and `dealloc(ptr: i32, size: i32)`.
|
||||
//! The host calls `alloc` before writing a buffer into guest memory, then calls
|
||||
//! `dealloc` when done. See [`host_abi`] for the full ABI spec.
|
||||
|
||||
use std::sync::{Arc, Mutex};
|
||||
|
||||
use homecore::HomeCore;
|
||||
use wasmtime::{Engine, Linker, Module, Store};
|
||||
|
||||
use crate::error::PluginError;
|
||||
use crate::host_abi::{LogLevel, StateChangedEventJson, MAX_ABI_BUFFER_BYTES};
|
||||
|
||||
// ── Store data ─────────────────────────────────────────────────────────────
|
||||
|
||||
/// Per-plugin state stored inside the Wasmtime [`Store`].
|
||||
///
|
||||
/// Wasmtime's `Store<T>` exposes `T` to host functions via `caller.data()`.
|
||||
/// We store the `HomeCore` handle and a list of subscribed entity IDs here.
|
||||
pub struct PluginStoreData {
|
||||
pub hc: HomeCore,
|
||||
pub subscriptions: Vec<String>,
|
||||
}
|
||||
|
||||
// ── WasmtimeRuntime ────────────────────────────────────────────────────────
|
||||
|
||||
/// Wasmtime-backed WASM plugin runtime (Cranelift JIT on Pi 5 and x86_64).
|
||||
///
|
||||
/// One `Engine` is shared across all plugins for module caching. Each plugin
|
||||
/// gets its own isolated `Store`.
|
||||
pub struct WasmtimeRuntime {
|
||||
engine: Engine,
|
||||
}
|
||||
|
||||
impl WasmtimeRuntime {
|
||||
/// Create a new runtime with default Cranelift config.
|
||||
pub fn new() -> Result<Self, PluginError> {
|
||||
let engine = Engine::default();
|
||||
Ok(Self { engine })
|
||||
}
|
||||
|
||||
/// Compile and instantiate a WASM plugin from raw bytes.
|
||||
///
|
||||
/// Returns a [`WasmPlugin`] handle that owns the `Store` and the
|
||||
/// `Instance`. The handle can be used to call into the WASM module.
|
||||
pub fn load_wasm(
|
||||
&self,
|
||||
wasm_bytes: &[u8],
|
||||
hc: HomeCore,
|
||||
) -> Result<WasmPlugin, PluginError> {
|
||||
let module = Module::new(&self.engine, wasm_bytes)
|
||||
.map_err(|e| PluginError::RuntimeError(format!("WASM compile: {e}")))?;
|
||||
|
||||
let mut linker: Linker<PluginStoreData> = Linker::new(&self.engine);
|
||||
register_host_imports(&mut linker)?;
|
||||
|
||||
let store_data = PluginStoreData {
|
||||
hc,
|
||||
subscriptions: Vec::new(),
|
||||
};
|
||||
let mut store = Store::new(&self.engine, store_data);
|
||||
|
||||
let instance = linker
|
||||
.instantiate(&mut store, &module)
|
||||
.map_err(|e| PluginError::RuntimeError(format!("WASM instantiate: {e}")))?;
|
||||
|
||||
Ok(WasmPlugin {
|
||||
inner: Arc::new(Mutex::new((store, instance))),
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
impl Default for WasmtimeRuntime {
|
||||
fn default() -> Self {
|
||||
Self::new().expect("default Wasmtime engine should not fail")
|
||||
}
|
||||
}
|
||||
|
||||
// ── Host import registration ───────────────────────────────────────────────
|
||||
|
||||
/// Register the 4 host imports every HOMECORE plugin can call.
|
||||
fn register_host_imports(
|
||||
linker: &mut Linker<PluginStoreData>,
|
||||
) -> Result<(), PluginError> {
|
||||
register_hc_state_get(linker)?;
|
||||
register_hc_state_set(linker)?;
|
||||
register_hc_state_subscribe(linker)?;
|
||||
register_hc_log(linker)?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// `hc_state_get(key_ptr: i32, key_len: i32, out_ptr: i32, out_cap: i32) → i32`
|
||||
///
|
||||
/// Reads the current state for the entity whose UTF-8 ID is in the guest
|
||||
/// buffer at `[key_ptr, key_ptr+key_len)`. Writes the JSON-encoded state
|
||||
/// into `[out_ptr, out_ptr+out_cap)`. Returns the number of bytes written,
|
||||
/// or -1 if the entity is not found, or -2 if `out_cap` is too small.
|
||||
fn register_hc_state_get(
|
||||
linker: &mut Linker<PluginStoreData>,
|
||||
) -> Result<(), PluginError> {
|
||||
linker
|
||||
.func_wrap(
|
||||
"env",
|
||||
"hc_state_get",
|
||||
|mut caller: wasmtime::Caller<'_, PluginStoreData>,
|
||||
key_ptr: i32,
|
||||
key_len: i32,
|
||||
out_ptr: i32,
|
||||
out_cap: i32|
|
||||
-> i32 {
|
||||
// Phase 1: read the entity key from guest memory.
|
||||
let key: String = {
|
||||
let mem = match caller.get_export("memory") {
|
||||
Some(wasmtime::Extern::Memory(m)) => m,
|
||||
_ => return -1,
|
||||
};
|
||||
match read_str(mem.data(&caller), key_ptr, key_len) {
|
||||
Some(k) => k.to_owned(),
|
||||
None => return -1,
|
||||
}
|
||||
};
|
||||
|
||||
// Phase 2: look up state and build JSON (no borrow on caller).
|
||||
let entity_id = match homecore::EntityId::parse(&key) {
|
||||
Ok(id) => id,
|
||||
Err(_) => return -1,
|
||||
};
|
||||
let json_bytes: Vec<u8> = {
|
||||
let state_arc = match caller.data().hc.states().get(&entity_id) {
|
||||
Some(s) => s,
|
||||
None => return -1,
|
||||
};
|
||||
match serde_json::to_vec(&*state_arc) {
|
||||
Ok(v) => v,
|
||||
Err(_) => return -1,
|
||||
}
|
||||
};
|
||||
|
||||
if json_bytes.len() > out_cap as usize {
|
||||
return -2;
|
||||
}
|
||||
|
||||
// Phase 3: write JSON back into guest memory.
|
||||
let mem = match caller.get_export("memory") {
|
||||
Some(wasmtime::Extern::Memory(m)) => m,
|
||||
_ => return -1,
|
||||
};
|
||||
let end = out_ptr as usize + json_bytes.len();
|
||||
let out = match mem.data_mut(&mut caller).get_mut(out_ptr as usize..end) {
|
||||
Some(s) => s,
|
||||
None => return -1,
|
||||
};
|
||||
out.copy_from_slice(&json_bytes);
|
||||
json_bytes.len() as i32
|
||||
},
|
||||
)
|
||||
.map_err(|e| PluginError::RuntimeError(format!("register hc_state_get: {e}")))?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// `hc_state_set(eid_ptr,eid_len,state_ptr,state_len,attrs_ptr,attrs_len) → i32`
|
||||
///
|
||||
/// Sets the state for the entity whose UTF-8 ID is at `[eid_ptr,eid_ptr+eid_len)`.
|
||||
/// The new state string is at `[state_ptr,state_ptr+state_len)`.
|
||||
/// The attributes JSON is at `[attrs_ptr,attrs_ptr+attrs_len)`.
|
||||
/// Returns 0 on success, negative on error.
|
||||
fn register_hc_state_set(
|
||||
linker: &mut Linker<PluginStoreData>,
|
||||
) -> Result<(), PluginError> {
|
||||
linker
|
||||
.func_wrap(
|
||||
"env",
|
||||
"hc_state_set",
|
||||
|mut caller: wasmtime::Caller<'_, PluginStoreData>,
|
||||
eid_ptr: i32,
|
||||
eid_len: i32,
|
||||
state_ptr: i32,
|
||||
state_len: i32,
|
||||
attrs_ptr: i32,
|
||||
attrs_len: i32|
|
||||
-> i32 {
|
||||
// Read all strings from guest memory in one borrow.
|
||||
let (eid, new_state, attrs_str) = {
|
||||
let mem = match caller.get_export("memory") {
|
||||
Some(wasmtime::Extern::Memory(m)) => m,
|
||||
_ => return -1,
|
||||
};
|
||||
let data = mem.data(&caller);
|
||||
let eid = match read_str(data, eid_ptr, eid_len) {
|
||||
Some(s) => s.to_owned(),
|
||||
None => return -1,
|
||||
};
|
||||
let new_state = match read_str(data, state_ptr, state_len) {
|
||||
Some(s) => s.to_owned(),
|
||||
None => return -1,
|
||||
};
|
||||
let attrs_str = read_str(data, attrs_ptr, attrs_len)
|
||||
.unwrap_or("{}")
|
||||
.to_owned();
|
||||
(eid, new_state, attrs_str)
|
||||
};
|
||||
|
||||
let entity_id = match homecore::EntityId::parse(&eid) {
|
||||
Ok(id) => id,
|
||||
Err(_) => return -2,
|
||||
};
|
||||
let attrs: serde_json::Value =
|
||||
serde_json::from_str(&attrs_str).unwrap_or(serde_json::json!({}));
|
||||
|
||||
caller
|
||||
.data()
|
||||
.hc
|
||||
.states()
|
||||
.set(entity_id, new_state, attrs, homecore::Context::new());
|
||||
0
|
||||
},
|
||||
)
|
||||
.map_err(|e| PluginError::RuntimeError(format!("register hc_state_set: {e}")))?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// `hc_state_subscribe(eid_ptr: i32, eid_len: i32) → i32`
|
||||
///
|
||||
/// Records a subscription so the host will call `receive_event` on future
|
||||
/// state changes for this entity. Returns 0 on success, -1 on invalid entity.
|
||||
fn register_hc_state_subscribe(
|
||||
linker: &mut Linker<PluginStoreData>,
|
||||
) -> Result<(), PluginError> {
|
||||
linker
|
||||
.func_wrap(
|
||||
"env",
|
||||
"hc_state_subscribe",
|
||||
|mut caller: wasmtime::Caller<'_, PluginStoreData>,
|
||||
eid_ptr: i32,
|
||||
eid_len: i32|
|
||||
-> i32 {
|
||||
let eid: String = {
|
||||
let mem = match caller.get_export("memory") {
|
||||
Some(wasmtime::Extern::Memory(m)) => m,
|
||||
_ => return -1,
|
||||
};
|
||||
match read_str(mem.data(&caller), eid_ptr, eid_len) {
|
||||
Some(s) => s.to_owned(),
|
||||
None => return -1,
|
||||
}
|
||||
};
|
||||
caller.data_mut().subscriptions.push(eid);
|
||||
0
|
||||
},
|
||||
)
|
||||
.map_err(|e| PluginError::RuntimeError(format!("register hc_state_subscribe: {e}")))?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// `hc_log(level: i32, msg_ptr: i32, msg_len: i32) → ()`
|
||||
///
|
||||
/// Structured log output from the plugin. `level`: 0=debug 1=info 2=warn 3=error.
|
||||
fn register_hc_log(
|
||||
linker: &mut Linker<PluginStoreData>,
|
||||
) -> Result<(), PluginError> {
|
||||
linker
|
||||
.func_wrap(
|
||||
"env",
|
||||
"hc_log",
|
||||
|mut caller: wasmtime::Caller<'_, PluginStoreData>,
|
||||
level: i32,
|
||||
msg_ptr: i32,
|
||||
msg_len: i32| {
|
||||
let mem = match caller.get_export("memory") {
|
||||
Some(wasmtime::Extern::Memory(m)) => m,
|
||||
_ => return,
|
||||
};
|
||||
let msg = read_str(mem.data(&caller), msg_ptr, msg_len)
|
||||
.unwrap_or("(invalid utf8)")
|
||||
.to_owned();
|
||||
let lvl = LogLevel::from_i32(level);
|
||||
eprintln!("[PLUGIN {}] {}", lvl.as_str(), msg);
|
||||
},
|
||||
)
|
||||
.map_err(|e| PluginError::RuntimeError(format!("register hc_log: {e}")))?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
// ── WasmPlugin ─────────────────────────────────────────────────────────────
|
||||
|
||||
/// A loaded WASM plugin instance. Wraps a Wasmtime `Store` + `Instance`.
|
||||
///
|
||||
/// The `Arc<Mutex<_>>` allows the handle to be `Clone` + `Send` while
|
||||
/// maintaining exclusive access for calls into the WASM module.
|
||||
pub struct WasmPlugin {
|
||||
pub inner: Arc<Mutex<(Store<PluginStoreData>, wasmtime::Instance)>>,
|
||||
}
|
||||
|
||||
impl WasmPlugin {
|
||||
/// Return a snapshot of the entity IDs this plugin has subscribed to.
|
||||
pub fn subscriptions(&self) -> Vec<String> {
|
||||
self.inner
|
||||
.lock()
|
||||
.map(|g| g.0.data().subscriptions.clone())
|
||||
.unwrap_or_default()
|
||||
}
|
||||
|
||||
/// Call the `plugin_setup` export with the given config-entry JSON.
|
||||
pub fn call_setup(&self, config_entry_json: &str) -> Result<i32, PluginError> {
|
||||
let mut guard = self
|
||||
.inner
|
||||
.lock()
|
||||
.map_err(|e| PluginError::RuntimeError(format!("lock: {e}")))?;
|
||||
let (store, instance) = &mut *guard;
|
||||
call_export_str(store, instance, "plugin_setup", config_entry_json)
|
||||
}
|
||||
|
||||
/// Call `plugin_handle_state_changed` with a [`StateChangedEventJson`].
|
||||
pub fn call_state_changed(
|
||||
&self,
|
||||
event: &StateChangedEventJson,
|
||||
) -> Result<i32, PluginError> {
|
||||
let json = serde_json::to_string(event)
|
||||
.map_err(|e| PluginError::RuntimeError(format!("serialize event: {e}")))?;
|
||||
let mut guard = self
|
||||
.inner
|
||||
.lock()
|
||||
.map_err(|e| PluginError::RuntimeError(format!("lock: {e}")))?;
|
||||
let (store, instance) = &mut *guard;
|
||||
call_export_str(store, instance, "plugin_handle_state_changed", &json)
|
||||
}
|
||||
}
|
||||
|
||||
// ── Memory helpers ─────────────────────────────────────────────────────────
|
||||
|
||||
/// Read a UTF-8 string from guest linear memory.
|
||||
fn read_str(mem: &[u8], ptr: i32, len: i32) -> Option<&str> {
|
||||
if len < 0 || len as usize > MAX_ABI_BUFFER_BYTES {
|
||||
return None;
|
||||
}
|
||||
let ptr = ptr as usize;
|
||||
let len = len as usize;
|
||||
let slice = mem.get(ptr..ptr + len)?;
|
||||
std::str::from_utf8(slice).ok()
|
||||
}
|
||||
|
||||
/// Allocate a guest buffer via `alloc`, write `payload`, call `export_fn(ptr, len)`,
|
||||
/// then free via `dealloc`. Returns the i32 result of the guest export.
|
||||
fn call_export_str(
|
||||
store: &mut Store<PluginStoreData>,
|
||||
instance: &wasmtime::Instance,
|
||||
export_fn: &str,
|
||||
payload: &str,
|
||||
) -> Result<i32, PluginError> {
|
||||
let payload_bytes = payload.as_bytes().to_vec(); // owned copy avoids reborrow issues
|
||||
let payload_len = payload_bytes.len() as i32;
|
||||
|
||||
// 1. Allocate guest buffer.
|
||||
let alloc = instance
|
||||
.get_typed_func::<i32, i32>(&mut *store, "alloc")
|
||||
.map_err(|e| PluginError::RuntimeError(format!("get alloc: {e}")))?;
|
||||
let ptr = alloc
|
||||
.call(&mut *store, payload_len)
|
||||
.map_err(|e| PluginError::RuntimeError(format!("call alloc: {e}")))?;
|
||||
|
||||
// 2. Write payload into guest memory.
|
||||
{
|
||||
let mem = instance
|
||||
.get_memory(&mut *store, "memory")
|
||||
.ok_or_else(|| PluginError::RuntimeError("no memory export".into()))?;
|
||||
let guest_slice = mem
|
||||
.data_mut(&mut *store)
|
||||
.get_mut(ptr as usize..ptr as usize + payload_bytes.len())
|
||||
.ok_or_else(|| PluginError::RuntimeError("guest memory OOB".into()))?;
|
||||
guest_slice.copy_from_slice(&payload_bytes);
|
||||
}
|
||||
|
||||
// 3. Call the guest export.
|
||||
let func = instance
|
||||
.get_typed_func::<(i32, i32), i32>(&mut *store, export_fn)
|
||||
.map_err(|e| PluginError::RuntimeError(format!("get {export_fn}: {e}")))?;
|
||||
let result = func
|
||||
.call(&mut *store, (ptr, payload_len))
|
||||
.map_err(|e| PluginError::RuntimeError(format!("call {export_fn}: {e}")))?;
|
||||
|
||||
// 4. Free the guest buffer.
|
||||
let dealloc = instance
|
||||
.get_typed_func::<(i32, i32), ()>(&mut *store, "dealloc")
|
||||
.map_err(|e| PluginError::RuntimeError(format!("get dealloc: {e}")))?;
|
||||
dealloc
|
||||
.call(&mut *store, (ptr, payload_len))
|
||||
.map_err(|e| PluginError::RuntimeError(format!("call dealloc: {e}")))?;
|
||||
|
||||
Ok(result)
|
||||
}
|
||||
|
||||
// ── Unit tests (using inline WAT) ──────────────────────────────────────────
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
/// A minimal WAT module that implements all host imports as no-ops and
|
||||
/// exports `alloc` / `dealloc` / `plugin_setup` /
|
||||
/// `plugin_handle_state_changed`. Compiled at test time via `wat::parse_str`.
|
||||
///
|
||||
/// The `hc_state_set` call in the test plugin writes back a hard-coded
|
||||
/// entity via the host import (the host import will actually call back into
|
||||
/// the HomeCore state machine via `caller.data()`).
|
||||
const TEST_WAT: &str = r#"
|
||||
(module
|
||||
;; Host imports
|
||||
(import "env" "hc_state_get"
|
||||
(func $hc_state_get (param i32 i32 i32 i32) (result i32)))
|
||||
(import "env" "hc_state_set"
|
||||
(func $hc_state_set (param i32 i32 i32 i32 i32 i32) (result i32)))
|
||||
(import "env" "hc_state_subscribe"
|
||||
(func $hc_state_subscribe (param i32 i32) (result i32)))
|
||||
(import "env" "hc_log"
|
||||
(func $hc_log (param i32 i32 i32)))
|
||||
|
||||
;; Linear memory: 1 page = 64 KiB
|
||||
(memory (export "memory") 1)
|
||||
|
||||
;; Simple bump allocator state
|
||||
(global $bump (mut i32) (i32.const 1024))
|
||||
|
||||
;; alloc(size) → ptr
|
||||
(func (export "alloc") (param $size i32) (result i32)
|
||||
(local $ptr i32)
|
||||
(local.set $ptr (global.get $bump))
|
||||
(global.set $bump (i32.add (global.get $bump) (local.get $size)))
|
||||
(local.get $ptr)
|
||||
)
|
||||
|
||||
;; dealloc(ptr, size) — no-op in bump allocator
|
||||
(func (export "dealloc") (param i32 i32))
|
||||
|
||||
;; plugin_setup(ptr, len) → 0
|
||||
(func (export "plugin_setup") (param i32 i32) (result i32)
|
||||
(i32.const 0)
|
||||
)
|
||||
|
||||
;; plugin_handle_state_changed(ptr, len) → 0
|
||||
;; Calls hc_log with a fixed message so we can observe the import works.
|
||||
(func (export "plugin_handle_state_changed") (param i32 i32) (result i32)
|
||||
;; log "ok" at INFO level — offset 0 in memory, write "ok" there first
|
||||
(i32.store8 (i32.const 0) (i32.const 111)) ;; 'o'
|
||||
(i32.store8 (i32.const 1) (i32.const 107)) ;; 'k'
|
||||
(call $hc_log (i32.const 1) (i32.const 0) (i32.const 2))
|
||||
(i32.const 0)
|
||||
)
|
||||
)
|
||||
"#;
|
||||
|
||||
#[test]
|
||||
fn wasmtime_runtime_compiles_and_instantiates_wat() {
|
||||
let wasm_bytes = wat::parse_str(TEST_WAT).expect("WAT should parse");
|
||||
let rt = WasmtimeRuntime::new().expect("engine should init");
|
||||
let hc = HomeCore::new();
|
||||
let plugin = rt.load_wasm(&wasm_bytes, hc).expect("should instantiate");
|
||||
|
||||
// call plugin_setup — expect 0
|
||||
let r = plugin
|
||||
.call_setup(r#"{"entry_id":"test","domain":"test","title":"test","data":{}}"#)
|
||||
.expect("setup should not error");
|
||||
assert_eq!(r, 0, "plugin_setup should return 0");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn hc_state_set_round_trip_via_wat() {
|
||||
/// WAT plugin that calls hc_state_set to write "on" for binary_sensor.test_alert
|
||||
const SET_WAT: &str = r#"
|
||||
(module
|
||||
(import "env" "hc_state_get"
|
||||
(func $hc_state_get (param i32 i32 i32 i32) (result i32)))
|
||||
(import "env" "hc_state_set"
|
||||
(func $hc_state_set (param i32 i32 i32 i32 i32 i32) (result i32)))
|
||||
(import "env" "hc_state_subscribe"
|
||||
(func $hc_state_subscribe (param i32 i32) (result i32)))
|
||||
(import "env" "hc_log"
|
||||
(func $hc_log (param i32 i32 i32)))
|
||||
|
||||
(memory (export "memory") 1)
|
||||
(global $bump (mut i32) (i32.const 2048))
|
||||
|
||||
(func (export "alloc") (param $size i32) (result i32)
|
||||
(local $ptr i32)
|
||||
(local.set $ptr (global.get $bump))
|
||||
(global.set $bump (i32.add (global.get $bump) (local.get $size)))
|
||||
(local.get $ptr)
|
||||
)
|
||||
(func (export "dealloc") (param i32 i32))
|
||||
|
||||
;; Strings stored at known offsets in memory:
|
||||
;; offset 0: "binary_sensor.test_alert" (24 bytes)
|
||||
;; offset 64: "on" (2 bytes)
|
||||
;; offset 128: "{}" (2 bytes)
|
||||
(data (i32.const 0) "binary_sensor.test_alert")
|
||||
(data (i32.const 64) "on")
|
||||
(data (i32.const 128) "{}")
|
||||
|
||||
;; plugin_setup: call hc_state_set to write "on"
|
||||
(func (export "plugin_setup") (param i32 i32) (result i32)
|
||||
(call $hc_state_set
|
||||
(i32.const 0) ;; eid_ptr
|
||||
(i32.const 24) ;; eid_len = len("binary_sensor.test_alert")
|
||||
(i32.const 64) ;; state_ptr
|
||||
(i32.const 2) ;; state_len = len("on")
|
||||
(i32.const 128) ;; attrs_ptr
|
||||
(i32.const 2) ;; attrs_len = len("{}")
|
||||
)
|
||||
drop
|
||||
(i32.const 0)
|
||||
)
|
||||
|
||||
(func (export "plugin_handle_state_changed") (param i32 i32) (result i32)
|
||||
(i32.const 0)
|
||||
)
|
||||
)
|
||||
"#;
|
||||
let wasm_bytes = wat::parse_str(SET_WAT).expect("WAT should parse");
|
||||
let rt = WasmtimeRuntime::new().expect("engine");
|
||||
let hc = HomeCore::new();
|
||||
let plugin = rt.load_wasm(&wasm_bytes, hc.clone()).expect("instantiate");
|
||||
|
||||
// Call plugin_setup — the WAT calls hc_state_set inside.
|
||||
plugin.call_setup("{}").expect("setup");
|
||||
|
||||
// Verify the host state machine saw the write.
|
||||
let eid = homecore::EntityId::parse("binary_sensor.test_alert").unwrap();
|
||||
let state = hc.states().get(&eid).expect("state should exist");
|
||||
assert_eq!(
|
||||
state.state, "on",
|
||||
"hc_state_set via host import should write 'on'"
|
||||
);
|
||||
}
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user