feat: add home assistant capability with pi-relay

pi/README.md

@@ -111,25 +111,32 @@ scripts/deploy-pios-pi.sh pi@10.21.x.x
 That script:
 
 1. builds `.#packages.aarch64-linux.noisebell-static` locally
-2. decrypts the Pi-facing secrets locally with `agenix`
-3. uploads the binary and secrets to the Pi
-4. installs Tailscale and Avahi if needed
-5. writes `/etc/noisebell/noisebell.env`
-6. installs `noisebell.service`
-7. enables and starts the service
-8. runs `tailscale up` with the decrypted auth key
+2. builds `.#packages.aarch64-linux.noisebell-relay-static` locally
+3. decrypts the Pi-facing secrets locally with `agenix`
+4. uploads the binaries and secrets to the Pi
+5. installs Tailscale and Avahi if needed
+6. writes `/etc/noisebell/noisebell.env`
+7. writes `/etc/noisebell/noisebell-relay.env`
+8. installs `noisebell.service` and `noisebell-relay.service`
+9. enables and starts both services
+10. runs `tailscale up` with the decrypted auth key
 
 ## Files written on the Pi
 
 The deploy script creates:
 
 - `/opt/noisebell/releases/<timestamp>/noisebell`
+- `/opt/noisebell/releases/<timestamp>/noisebell-relay`
 - `/opt/noisebell/current` -> current release symlink
 - `/etc/noisebell/pi-to-cache-key`
 - `/etc/noisebell/cache-to-pi-key`
+- `/etc/noisebell/relay-webhook-secret`
+- `/etc/noisebell/homeassistant-webhook-id`
 - `/etc/noisebell/tailscale-auth-key`
 - `/etc/noisebell/noisebell.env`
+- `/etc/noisebell/noisebell-relay.env`
 - `/etc/systemd/system/noisebell.service`
+- `/etc/systemd/system/noisebell-relay.service`
 
 All secret files are root-only.
 
@@ -171,6 +178,34 @@ The deployed service uses these environment variables:
 | `NOISEBELL_BIND_ADDRESS` | `0.0.0.0` | HTTP bind address |
 | `NOISEBELL_ACTIVE_LOW` | `true` | Low GPIO = door open |
 
+## Relay service configuration
+
+The optional relay service accepts authenticated webhooks from cache-service and forwards them to Home Assistant on the local network.
+
+| Variable | Default | Description |
+|---|---|---|
+| `NOISEBELL_RELAY_PORT` | `8090` | HTTP port for the relay webhook endpoint |
+| `NOISEBELL_RELAY_BIND_ADDRESS` | `0.0.0.0` | HTTP bind address |
+| `NOISEBELL_RELAY_TARGET_BASE_URL` | `http://homeassistant.local:8123` | Base URL for Home Assistant |
+| `NOISEBELL_RELAY_TARGET_WEBHOOK_ID` | required | Home Assistant webhook ID |
+| `NOISEBELL_RELAY_INBOUND_API_KEY` | required | Bearer token expected from cache-service |
+| `NOISEBELL_RELAY_RETRY_ATTEMPTS` | `3` | Forward retry count |
+| `NOISEBELL_RELAY_RETRY_BASE_DELAY_SECS` | `1` | Exponential backoff base delay |
+| `NOISEBELL_RELAY_HTTP_TIMEOUT_SECS` | `10` | Outbound request timeout |
+
+Example cache target for the relay:
+
+```nix
+{
+  services.noisebell-cache.outboundWebhooks = [
+    {
+      url = "http://noisebell-pi.local:8090/webhook";
+      secretFile = /run/agenix/noisebell-relay-webhook-secret;
+    }
+  ];
+}
+```
+
 ## API
 
 All endpoints require `Authorization: Bearer <token>`.

pi/pi-relay/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "noisebell-relay"
+version = "0.1.0"
+edition = "2021"
+
+[lints]
+workspace = true
+
+[dependencies]
+anyhow = "1.0"
+axum = "0.8"
+noisebell-common = { path = "../../remote/noisebell-common" }
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
+tokio = { version = "1", features = ["rt-multi-thread", "macros", "net", "signal", "time"] }
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }

pi/pi-relay/src/main.rs

@@ -0,0 +1,148 @@
+use std::sync::Arc;
+use std::time::Duration;
+
+use anyhow::{Context, Result};
+use axum::extract::State;
+use axum::http::{HeaderMap, StatusCode};
+use axum::routing::{get, post};
+use axum::{Json, Router};
+use noisebell_common::{validate_bearer, WebhookPayload};
+use tracing::{error, info, warn};
+
+#[derive(Clone)]
+struct AppState {
+    client: reqwest::Client,
+    inbound_api_key: String,
+    target_url: String,
+    target_secret: Option<String>,
+    retry_attempts: u32,
+    retry_base_delay_secs: u64,
+}
+
+async fn post_webhook(
+    State(state): State<Arc<AppState>>,
+    headers: HeaderMap,
+    Json(payload): Json<WebhookPayload>,
+) -> StatusCode {
+    if !validate_bearer(&headers, &state.inbound_api_key) {
+        return StatusCode::UNAUTHORIZED;
+    }
+
+    info!(status = %payload.status, timestamp = payload.timestamp, "relay received webhook");
+
+    for attempt in 0..=state.retry_attempts {
+        let mut req = state.client.post(&state.target_url).json(&payload);
+        if let Some(secret) = &state.target_secret {
+            req = req.bearer_auth(secret);
+        }
+
+        match req.send().await {
+            Ok(resp) if resp.status().is_success() => {
+                info!(status = %payload.status, "relay forwarded webhook");
+                return StatusCode::OK;
+            }
+            result => {
+                let err_msg = match &result {
+                    Ok(resp) => format!("HTTP {}", resp.status()),
+                    Err(err) => err.to_string(),
+                };
+                if attempt == state.retry_attempts {
+                    error!(error = %err_msg, "relay failed to forward webhook after {} attempts", state.retry_attempts + 1);
+                    return StatusCode::BAD_GATEWAY;
+                }
+
+                let delay = Duration::from_secs(state.retry_base_delay_secs * 2u64.pow(attempt));
+                warn!(error = %err_msg, attempt = attempt + 1, "relay forward failed, retrying in {:?}", delay);
+                tokio::time::sleep(delay).await;
+            }
+        }
+    }
+
+    StatusCode::BAD_GATEWAY
+}
+
+async fn health() -> StatusCode {
+    StatusCode::OK
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    tracing_subscriber::fmt()
+        .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
+        .init();
+
+    let port: u16 = std::env::var("NOISEBELL_RELAY_PORT")
+        .unwrap_or_else(|_| "8090".into())
+        .parse()
+        .context("NOISEBELL_RELAY_PORT must be a valid u16")?;
+
+    let bind_address =
+        std::env::var("NOISEBELL_RELAY_BIND_ADDRESS").unwrap_or_else(|_| "0.0.0.0".into());
+
+    let inbound_api_key = std::env::var("NOISEBELL_RELAY_INBOUND_API_KEY")
+        .context("NOISEBELL_RELAY_INBOUND_API_KEY is required")?;
+
+    let target_base_url = std::env::var("NOISEBELL_RELAY_TARGET_BASE_URL")
+        .unwrap_or_else(|_| "http://homeassistant.local:8123".into())
+        .trim_end_matches('/')
+        .to_string();
+
+    let target_webhook_id = std::env::var("NOISEBELL_RELAY_TARGET_WEBHOOK_ID")
+        .context("NOISEBELL_RELAY_TARGET_WEBHOOK_ID is required")?;
+
+    let target_secret =
+        std::env::var("NOISEBELL_RELAY_TARGET_SECRET").ok().filter(|value| !value.is_empty());
+
+    let retry_attempts: u32 = std::env::var("NOISEBELL_RELAY_RETRY_ATTEMPTS")
+        .unwrap_or_else(|_| "3".into())
+        .parse()
+        .context("NOISEBELL_RELAY_RETRY_ATTEMPTS must be a valid u32")?;
+
+    let retry_base_delay_secs: u64 = std::env::var("NOISEBELL_RELAY_RETRY_BASE_DELAY_SECS")
+        .unwrap_or_else(|_| "1".into())
+        .parse()
+        .context("NOISEBELL_RELAY_RETRY_BASE_DELAY_SECS must be a valid u64")?;
+
+    let http_timeout_secs: u64 = std::env::var("NOISEBELL_RELAY_HTTP_TIMEOUT_SECS")
+        .unwrap_or_else(|_| "10".into())
+        .parse()
+        .context("NOISEBELL_RELAY_HTTP_TIMEOUT_SECS must be a valid u64")?;
+
+    let target_url = format!("{target_base_url}/api/webhook/{target_webhook_id}");
+
+    let client = reqwest::Client::builder()
+        .timeout(Duration::from_secs(http_timeout_secs))
+        .build()
+        .context("failed to build HTTP client")?;
+
+    let state = Arc::new(AppState {
+        client,
+        inbound_api_key,
+        target_url,
+        target_secret,
+        retry_attempts,
+        retry_base_delay_secs,
+    });
+
+    let app = Router::new()
+        .route("/health", get(health))
+        .route("/webhook", post(post_webhook))
+        .with_state(state);
+
+    let listener = tokio::net::TcpListener::bind((&*bind_address, port))
+        .await
+        .context(format!("failed to bind to {bind_address}:{port}"))?;
+
+    info!(port, "relay listening");
+
+    let mut sigterm = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
+        .context("failed to register SIGTERM handler")?;
+    axum::serve(listener, app)
+        .with_graceful_shutdown(async move {
+            sigterm.recv().await;
+        })
+        .await
+        .context("relay server error")?;
+
+    Ok(())
+}