Crate aranet_service

Source

Expand description

Background collector and HTTP REST API for Aranet sensors.

This crate provides a service that:

Polls configured Aranet devices on a schedule
Stores readings in the local database
Exposes a REST API for querying data
Provides WebSocket connections for real-time updates
Optional API key authentication and rate limiting

§REST API Endpoints

GET /api/health - Lightweight service health check (no auth required)
GET /api/health/detailed - Database, collector, and platform diagnostics
GET /api/status - Collector status plus per-device polling statistics
GET /api/devices - List all known devices
GET /api/devices/current - Latest reading for every known device
GET /api/devices/:id - Get device info
GET /api/devices/:id/current - Latest reading wrapped in CurrentReadingResponse
GET /api/devices/:id/readings - Query readings with filters
GET /api/devices/:id/history - Query cached history
GET /api/readings - All readings across devices
GET /api/config, PUT /api/config - Read or update runtime configuration
POST /api/config/devices, PUT/DELETE /api/config/devices/:id - Manage monitored devices
POST /api/collector/start, POST /api/collector/stop - Control the background collector
GET /metrics - Prometheus metrics export
WS /api/ws - Real-time readings stream
GET /, GET /dashboard - Embedded dashboard shell

§Configuration

The service reads configuration from ~/.config/aranet/server.toml:

[server]
bind = "127.0.0.1:8080"

[storage]
path = "~/.local/share/aranet/data.db"

[[devices]]
address = "Aranet4 17C3C"
alias = "office"
poll_interval = 60

§Security

Optional security features can be enabled:

[security]
# Require X-API-Key header for protected API, WebSocket, and metrics requests
api_key_enabled = true
api_key = "your-secure-random-key-at-least-32-chars"

# Rate limit requests per IP address
rate_limit_enabled = true
rate_limit_requests = 100   # max requests per window
rate_limit_window_secs = 60 # window duration

The dashboard shell routes (/ and /dashboard) remain public so browsers can load the UI. Protected API, metrics, and WebSocket requests still honor the configured security settings.

For WebSocket connections, browsers cannot set custom headers. Use the token query parameter only on /api/ws instead: ws://localhost:8080/api/ws?token=your-api-key

Note: Query parameters may be logged by proxies or appear in browser history. For sensitive deployments, consider using a short-lived token exchange endpoint rather than passing the API key directly in the query string.

§Platform Setup

§macOS

§Bluetooth Permissions

The Aranet devices use Bluetooth Low Energy. On macOS, you need to grant Bluetooth permissions:

Terminal App: When running from Terminal, the Terminal app must have Bluetooth permission in System Preferences > Privacy & Security > Bluetooth.
VS Code Terminal: Add VS Code to the Bluetooth permissions list.
LaunchAgent: For background services, add aranet-service to the Bluetooth permission list. You may need to use a signed binary or run with appropriate entitlements.

§User-Level Service (Recommended)

Install as a user LaunchAgent (no root required):

# Install the service
aranet-service service install --user

# Start the service
aranet-service service start --user

# Check status
aranet-service service status --user

# Stop and uninstall
aranet-service service stop --user
aranet-service service uninstall --user

The LaunchAgent plist is created at ~/Library/LaunchAgents/dev.rye.aranet.plist.

§Linux

§BlueZ D-Bus Access

The service needs access to the BlueZ D-Bus interface. For user-level services:

Ensure your user is in the bluetooth group:

sudo usermod -a -G bluetooth $USER
# Log out and back in for group changes to take effect

D-Bus session access: User-level systemd services need the D-Bus session. Create a drop-in config if needed:

mkdir -p ~/.config/systemd/user/aranet.service.d
cat > ~/.config/systemd/user/aranet.service.d/dbus.conf << EOF
[Service]
Environment="DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/%U/bus"
EOF
systemctl --user daemon-reload

§User-Level Service

# Install the user service
aranet-service service install --user

# Enable and start
systemctl --user enable --now dev.rye.aranet

# Check status
systemctl --user status dev.rye.aranet

# View logs
journalctl --user -u dev.rye.aranet -f

# Stop and uninstall
systemctl --user stop dev.rye.aranet
aranet-service service uninstall --user

§System-Level Service

For system services, you need to create a dedicated user:

# Create aranet user (with bluetooth group membership)
sudo useradd -r -s /sbin/nologin -G bluetooth aranet

# Install as system service
sudo aranet-service service install

# Start the service
sudo systemctl enable --now dev.rye.aranet

§Windows

§Bluetooth Permissions

Windows requires the app to be granted Bluetooth access through Settings:

Settings > Privacy & Security > Bluetooth > Allow apps to access your Bluetooth

§Running as a Service

On Windows, the service runs as a Windows Service. Install and manage via:

# Run as Administrator
aranet-service service install
aranet-service service start

# Check status (in Services panel or via)
aranet-service service status

# Stop and uninstall
aranet-service service stop
aranet-service service uninstall

Note: Windows Services run in session 0 without a desktop, which may affect Bluetooth access. Consider using Task Scheduler to run the service at logon if you encounter Bluetooth issues:

# Create a scheduled task to run at logon
schtasks /create /tn "AranetService" /tr "aranet-service run" /sc onlogon /rl highest

Re-exports§

pub use collector::Collector;
pub use config::Config;
pub use config::ConfigError;
pub use config::DeviceConfig;
pub use config::InfluxDbConfig;
pub use config::MqttConfig;
pub use config::NotificationConfig;
pub use config::PrometheusConfig;
pub use config::SecurityConfig;
pub use config::ServerConfig;
pub use config::StorageConfig;
pub use config::WebhookConfig;
pub use config::WebhookEndpoint;
pub use state::AppState;
pub use state::ReadingEvent;

Modules§

api: REST API endpoints for the aranet-service.
collector: Background data collector for polling Aranet devices.
config: Server configuration.
dashboard: Embedded web dashboard for monitoring Aranet sensors.
influxdb: InfluxDB line protocol exporter for Aranet sensor readings.
mdns: mDNS/DNS-SD service discovery for the Aranet service.
middleware: Security middleware for the aranet-service API.
state: Application state shared across handlers.
webhook: Webhook notification system for threshold alerts.
ws: WebSocket handler for real-time updates.

Structs§

RunOptions: Runtime options for starting the HTTP service.

Functions§

app: Build the fully layered HTTP application used in production and end-to-end tests.
init_tracing: Initialize the default tracing subscriber used by the service binaries.
run: Run the HTTP service until shutdown.