add support for timeout on plugins (#4)

Author: xscriptor

.gitattributes

@@ -0,0 +1,27 @@
+# Auto-detect text files and always use LF everywhere (Linux, macOS and
+# Windows). CRLF is never checked out, so no autocrlf warnings on Windows.
+* text=auto eol=lf
+
+# Rust source code
+*.rs linguist-language=Rust text
+
+# Configuration files
+*.toml linguist-language=TOML text
+*.jsonc linguist-language=JSON text
+*.json linguist-language=JSON text
+Cargo.lock linguist-language=TOML text
+
+# Scripts and CI
+*.sh linguist-language=Shell text eol=lf
+*.ps1 linguist-language=PowerShell text
+*.yml linguist-language=YAML text
+*.yaml linguist-language=YAML text
+
+# Documentation
+*.md linguist-language=Markdown text
+LICENSE linguist-language=Text text
+*.txt linguist-language=Text text
+
+# Git configuration
+.gitignore linguist-language=Ignore-List text
+.gitattributes linguist-language=Git-Attributes text

.github/workflows/rust-tests.yml

@@ -1,4 +1,4 @@
-name: Rust Tests
+name: CI
 
 on:
   push:
@@ -7,9 +7,18 @@ on:
   pull_request:
 
 jobs:
-  test:
-    runs-on: ubuntu-latest
+  ci:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
     steps:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
-      - run: cargo test --workspace
+      - name: CI (Linux/macOS)
+        if: runner.os != 'Windows'
+        run: bash ci/unix.sh
+      - name: CI (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: ./ci/windows.ps1

CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 2026-08-19
+
+### Timeout Standard
+
+- All plugins now wrap their work in `with_timeout` with an own runtime budget (2–25 s); on timeout they respond with fallback lines or exit gracefully, so a hung plugin can never hang xfetch.
+- A plugin without a runtime limit is rejected — enforced by CI (`ci/unix.sh`, `ci/windows.ps1`, running on Linux, macOS and Windows). PRs must pass CI.
+- Requires `xfetch-plugin-api` with `with_timeout` (see the `api` repo).
+
+### Plugins (as of 2026-08-19)
+
+- `animate-logo` — logo animation for the daemon
+- `display-resolution` — screen resolution
+- `docker` — container stats
+- `github-stats` — GitHub profile statistics
+- `music-player` — MPD/Spotify status
+- `temperature` — CPU/thermal zone temperatures
+- `theme-detection` — GTK theme detection
+- `theme-manager` — theme registry management
+- `timezone` — local time and UTC offset
+- `user-info` — user, host and groups
+- `weather` — weather via wttr.in
+
+Each plugin has its own CHANGELOG with its specific budget and changes.

CONTRIBUTING.md

@@ -12,8 +12,16 @@
   <li>Fork the repository and create a feature branch.</li>
   <li>Create or update a plugin directory at the repository root.</li>
   <li>Run <code>cargo test --workspace</code>.</li>
+  <li>
+    Run the full CI locally before opening the PR:
+    <code>bash ci/unix.sh</code> (Linux/macOS) or <code>./ci/windows.ps1</code>
+    (Windows). The CI checks tests <strong>and</strong> the plugin standard.
+  </li>
   <li>Document the plugin in its own <code>README.md</code> and in <a href="./README.md">README.md</a>.</li>
-  <li>Open a pull request with usage details and any required external dependencies.</li>
+  <li>
+    Open a pull request with usage details and any required external
+    dependencies. PRs that fail CI are rejected.
+  </li>
 </ol>
 
 <h2>Plugin Rules</h2>
@@ -23,6 +31,14 @@
   <li>Keep plugins focused on a single responsibility.</li>
   <li>Write errors to stderr and exit with a non-zero status on failure.</li>
   <li>Prefer stable, actively maintained dependencies and keep them minimal.</li>
+  <li>
+    <strong>Every plugin MUST have a runtime limit.</strong> Wrap all work in
+    <code>with_timeout</code> (from <code>xfetch_plugin_api</code>) with a
+    <code>const BUDGET</code> that fits the plugin (local probes: ~2 s,
+    network calls: 15–25 s) and respond with fallback lines when the budget
+    elapses. A plugin without a timeout is rejected: it could hang xfetch
+    forever. This is enforced by CI.
+  </li>
 </ul>
 
 <h2>Protocol Guide</h2>

Cargo.lock

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# CI for Linux/macOS: build, test and enforce the plugin standard.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+cargo test --workspace
+
+# Standard: every plugin must wrap its work in with_timeout (CONTRIBUTING.md).
+for f in plugins/*/src/main.rs; do
+  grep -q "with_timeout" "$f" || {
+    echo "::error::$f must use xfetch_plugin_api::with_timeout" >&2
+    exit 1
+  }
+done
+echo "All plugins use with_timeout."

ci/unix.sh

@@ -0,0 +1,14 @@
+# CI for Windows: build, test and enforce the plugin standard.
+$ErrorActionPreference = "Stop"
+Set-Location (Join-Path $PSScriptRoot "..")
+
+cargo test --workspace
+
+# Standard: every plugin must wrap its work in with_timeout (CONTRIBUTING.md).
+foreach ($f in Get-ChildItem "plugins\*\src\main.rs") {
+    if (-not (Select-String -Path $f.FullName -Pattern "with_timeout" -Quiet)) {
+        Write-Error "$($f.FullName) must use xfetch_plugin_api::with_timeout"
+        exit 1
+    }
+}
+Write-Host "All plugins use with_timeout."

ci/windows.ps1

@@ -1,9 +1,4 @@
 # Changelog
 
-## 2026-08-15 — v0.1.0
-
-### Full Frame Cycle for Frame-Style Animations
-
-- Fixed frame truncation in `frame` style: when `duration_ms` is not set in the logo animation config, the plugin no longer caps the output to the 1200 ms default (e.g. 14 frames at 12 fps), which caused the animation to be cut short and restart from the beginning.
-- When `duration_ms` is absent and `style` is `frame` with source frames available, the plugin now emits every source frame exactly once (e.g. all 36 frames of a kitty animation), letting the host loop the complete animation.
-- Behavior for generated styles (`sweep`, `wave`, `rainbow`, `sparkle`, `breathing`, `none`) and for explicit `duration_ms` values is unchanged.
+## 2026-08-19
+- Wrapped work in `with_timeout` with a 10 s budget; on timeout it exits with an error instead of hanging.

plugins/animate-logo/CHANGELOG.md

@@ -1,43 +1,56 @@
+use std::time::Duration;
 use xfetch_plugin_api::{
-    AnimationFrame, read_logo_animation_request, write_logo_animation_frames,
+    AnimationFrame, read_logo_animation_request, with_timeout, write_logo_animation_frames,
 };
 
+/// Frame generation is CPU-bound; the user-controlled duration can demand
+/// thousands of frames, so the budget is generous.
+const BUDGET: Duration = Duration::from_secs(10);
+
 fn main() {
-    let request = match read_logo_animation_request() {
-        Ok(value) => value,
-        Err(err) => {
-            eprintln!("{}", err);
-            std::process::exit(1);
-        }
-    };
+    let frames: Vec<AnimationFrame> = match with_timeout(BUDGET, || {
+        let request = match read_logo_animation_request() {
+            Ok(value) => value,
+            Err(err) => {
+                eprintln!("{}", err);
+                std::process::exit(1);
+            }
+        };
 
-    let args = request.args;
-    let fps = clamp(args.fps.unwrap_or(12), 1, 60);
-    let frame_delay = 1000 / fps;
-    let style = args.style.as_deref().unwrap_or("sweep");
+        let args = request.args;
+        let fps = clamp(args.fps.unwrap_or(12), 1, 60);
+        let frame_delay = 1000 / fps;
+        let style = args.style.as_deref().unwrap_or("sweep");
 
-    let frame_count = if args.duration_ms.is_none()
-        && style == "frame"
-        && request.frames.as_ref().is_some_and(|sets| !sets.is_empty())
-    {
-        request.frames.as_ref().unwrap().len() as u64
-    } else {
-        let duration_ms = std::cmp::max(frame_delay, args.duration_ms.unwrap_or(1200));
-        std::cmp::max(1, duration_ms / frame_delay)
-    };
+        let frame_count = if args.duration_ms.is_none()
+            && style == "frame"
+            && request.frames.as_ref().is_some_and(|sets| !sets.is_empty())
+        {
+            request.frames.as_ref().unwrap().len() as u64
+        } else {
+            let duration_ms = std::cmp::max(frame_delay, args.duration_ms.unwrap_or(1200));
+            std::cmp::max(1, duration_ms / frame_delay)
+        };
 
-    let frame_sets = request.frames.unwrap_or_default();
+        let frame_sets = request.frames.unwrap_or_default();
 
-    let frames: Vec<AnimationFrame> = match style {
-        "frame" if !frame_sets.is_empty() => {
-            generate_ascii_frame_animation(&frame_sets, frame_count, frame_delay)
+        match style {
+            "frame" if !frame_sets.is_empty() => {
+                generate_ascii_frame_animation(&frame_sets, frame_count, frame_delay)
+            }
+            "wave" => generate_wave_animation(&request.lines, frame_count, frame_delay),
+            "rainbow" => generate_rainbow_animation(&request.lines, frame_count, frame_delay),
+            "sparkle" => generate_sparkle_animation(&request.lines, frame_count, frame_delay),
+            "breathing" => generate_breathing_animation(&request.lines, frame_count, frame_delay),
+            "none" => generate_static_animation(&request.lines, frame_count, frame_delay),
+            _ => generate_sweep_animation(&request.lines, frame_count, frame_delay),
+        }
+    }) {
+        Ok(frames) => frames,
+        Err(_) => {
+            eprintln!("animate-logo: timed out");
+            std::process::exit(1);
         }
-        "wave" => generate_wave_animation(&request.lines, frame_count, frame_delay),
-        "rainbow" => generate_rainbow_animation(&request.lines, frame_count, frame_delay),
-        "sparkle" => generate_sparkle_animation(&request.lines, frame_count, frame_delay),
-        "breathing" => generate_breathing_animation(&request.lines, frame_count, frame_delay),
-        "none" => generate_static_animation(&request.lines, frame_count, frame_delay),
-        _ => generate_sweep_animation(&request.lines, frame_count, frame_delay),
     };
 
     if let Err(err) = write_logo_animation_frames(frames) {

plugins/animate-logo/src/main.rs

@@ -0,0 +1,4 @@
+# Changelog
+
+## 2026-08-19
+- Wrapped work in `with_timeout` with a 2 s budget; on timeout it responds with a fallback line.