Cross-cutting concerns

Cross-cutting concerns

Logging

Approach

Use the tracing crate (Rust) and console / debug (Svelte/TypeScript). All backend logging goes through tracing with structured fields.

Log levels

Log output

• File: ~/.rymflux/logs/app.log — rolling file, 10MB per file, 5 rotations. Contains info and above.
• Stdout (dev mode): Full debug+ level when RUST_LOG=rymflux=debug is set.
• Plugin logs: Captured from plugin stderr (per ADR-001), stored per-plugin in ~/.rymflux/logs/plugins/<plugin_id>.log. Surfaced through the diagnostics system (M16).

Structured fields

Every log entry includes:

• timestamp — ISO 8601
• level — error/warn/info/debug/trace
• target — Rust module path
• message — human-readable description
• request_id — UUID, propagated from Tauri invoke call (see Request tracing)

Contextual fields added per event type:

• plugin_id — for plugin-related events
• content_id — for library/playback events
• source — URL or file path for playback events
• query — search query string (truncated at 200 chars)

Observability

Approach

v1 is a desktop app with no production infrastructure. Observability means:

1. Structured logs (see Logging above) — the primary diagnostic tool.
2. Diagnostics command — rymflux diagnostics CLI command (could be a hidden Tauri command or shell alias) that dumps:
   • Registered plugins + their capabilities + process status (running / idle / crashed)
   • Library size (total items, playlists, history entries)
   • Audio device info (name, sample rate, channels)
   • Recent log tail (last 50 lines)
3. Panic handler — std::panic::set_hook captures Rust panics to:
   • Write a crash report to ~/.rymflux/crash-reports/ (panicked thread, stack trace, last 50 log lines)
   • Show a non-blocking error dialog to the user (“Something went wrong. A crash report was saved.”)
   • Do NOT terminate on plugin-related panics (plugins are separate processes)
4. Frontend error boundary — Each room has a Svelte error boundary. A room crash does not take down the shell.

Metrics (v1 minimal)

No metrics infrastructure in v1. Key tracking numbers computed from logs:

• Plugin crash rate (crashes / total requests)
• Search latency per plugin
• Library mutation rate

These become structured metrics (Prometheus / OpenTelemetry) in a future version. For v1, log-based analysis is sufficient.

Error handling

Approach

Errors use a three-tier severity model:

Error types

JSON-RPC error codes

Standard error codes used across all plugin communication (aligned with JSON-RPC 2.0):

Resilience

Plugin crash recovery

• Plugin process exit (expected or unexpected) is handled by the Plugin Runtime.
• If a plugin crashes during a request: return PLUGIN_CRASHED, mark plugin for restart.
• The plugin is restarted on the next request (lazy restart). No automatic restart loop.
• If a plugin crashes 5 times in 5 minutes: disable the plugin and notify the user.
• Plugin crash does not affect any other plugin or the core.

Audio engine resilience

• Audio decode failure for one track: skip to next track in queue. Do not crash the engine.
• Audio device lost (headphones unplugged, sink changed): pause playback, resume on device available.
• Audio thread panic: caught by the panic handler, engine restarts the audio thread.

Database resilience

• SQLite WAL mode enabled for crash recovery.
• Schema version stored in a _schema_version pragma. Migration runs at startup.
• All writes are transactional. Partial writes are rolled back on crash.
• Database file corruption: detected by PRAGMA integrity_check. On failure:
  1. Rename corrupted file to library.db.corrupted.<timestamp>
  2. Create new database
  3. Log warning
  4. App continues with empty library

Async timeout safety

All plugin IPC operations use tokio::time::timeout. Every operation has a configured timeout:

• Plugin launch: 5 seconds (FR-PLUGIN-3)
• Plugin request/response: 30 seconds (configurable, FR-PLUGIN-3)
• Plugin idle: 5 minutes (configurable)
• Search per-plugin: inherits the per-request timeout (30s default)

Caching

What is cached

What is not cached

• Search results across sessions (library is persistent, search is realtime)
• Audio files (no local copy — stream URLs are ephemeral)
• Plugin binaries (launched fresh each time per idle timeout)

Future caching considerations (v2+)

• LRU cache for album artwork (most recently viewed rooms have instant artwork)
• Audio pre-decode for gapless playback (v2, W8)
• Search result cache with invalidation on library mutation
• Offline audio cache (core-managed downloads, W9)

Directory layout

~/.rymflux/
├── config.toml          # User-editable configuration (TOML)
├── data/
│   └── library.db       # SQLite database (machine-generated)
├── logs/
│   ├── app.log          # Rolling log, info+, 10MB per file, 5 rotations
│   └── plugins/
│       └── <plugin-id>.log  # Per-plugin stderr capture
├── plugins/
│   └── <plugin-id>/     # Plugin directories (user-installed)
│       ├── plugin.toml  # Plugin manifest
│       └── ...          # Plugin executable and state
└── crash-reports/       # Rust panic crash reports

The split between user-editable files at the root (config) and machine-generated data in subdirectories is deliberate. Config is hand-edited; data, logs, and crash reports are managed by the platform.

XDG consideration: On Linux, the XDG Base Directory Specification suggests $XDG_CONFIG_HOME/rymflux/ for config and $XDG_DATA_HOME/rymflux/ for data. Rymflux uses ~/.rymflux/ (a single top-level directory) for simplicity in v1, prioritizing macOS-first ergonomics. XDG compliance is a future consideration.

Configuration

Approach

Configuration is stored in a TOML file at ~/.rymflux/config.toml. Written by the app on first launch, editable by the user.

Config categories

Config validation

• All config values are validated on read. Invalid values fall back to defaults with a warning logged.
• File format is TOML (standard Rust ecosystem, toml crate). The plugin.toml format extends this convention to plugins.

Secrets

• No secrets in v1. No API keys, no tokens, no user credentials managed by the core.
• Plugins that require API keys (e.g., a Jamendo API token) manage their own secrets. The plugin stores them in its state directory (~/.rymflux/plugins/<id>/state/) or environment variables.
• The core does not read, store, or transmit plugin secrets.

Security

Threat model

v1 is local-first, single-user (constraint C6, scope non-goals). The threat model is limited:

Capability-based security

• Plugin capabilities are declared in the manifest (capabilities field).
• The core only sends requests for declared capabilities. If a plugin declares search but not stream, the core will never send a stream request.
• Unknown capabilities in the manifest are ignored with a warning (FR-PLUGIN-2).

Request tracing

Approach

Every Tauri invoke call generates a request_id (UUIDv4). This ID is:

1. Attached to all log entries produced during that request
2. Included as the id field in JSON-RPC requests to plugins
3. Emitted in Tauri events so the frontend can correlate events to requests

This enables end-to-end tracing of a single user action across the Svelte frontend, Rust backend, and plugin processes — all from log files.