Add supervisor for local-stt servers

[yujonglee]

No description provided.

[coderabbitai]

📝 Walkthrough

Walkthrough

The changes introduce a supervisor-based architecture for managing STT server lifecycles using the ractor library. A new supervisor module orchestrates internal and external STT actors, replacing direct server lifecycle management. Shared state now holds a supervisor reference, error handling is updated with supervisor-specific variants, and server initialization flows through supervisor calls instead of direct actor invocations.

Changes

Cohort / File(s)	Summary
Dependency Management plugins/local-stt/Cargo.toml	Added ractor-supervisor dependency; retained existing ractor dependency.
Error Type Updates plugins/local-stt/src/error.rs	Removed TauriError, IoError, and ServerAlreadyRunning variants; added ServerStopFailed(String) and SupervisorNotFound variants.
Supervisor Implementation plugins/local-stt/src/server/supervisor.rs	New module with supervisor initialization, actor spawn/stop functions, and constants for internal/external STT actors and supervisor naming.
Core State & Integration plugins/local-stt/src/lib.rs, plugins/local-stt/src/ext.rs	Added stt_supervisor: Option<ActorRef<...>> field to shared State; removed Default derive; refactored server orchestration to route through supervisor and replaced direct actor calls with supervisor-driven lifecycle management.
External Server Refactoring plugins/local-stt/src/server/external.rs	Introduced CommandBuilder type with factory pattern; replaced cmd: Command field with cmd_builder: CommandBuilder and port: u16 in ExternalSTTArgs; added cleanup_state helper for graceful resource termination.
Internal Server Updates plugins/local-stt/src/server/internal.rs	Derived Clone for InternalSTTArgs; added ServerError message handling in actor's handle method.
Module Exports plugins/local-stt/src/server/mod.rs	Added pub mod supervisor; export.

Sequence Diagram(s)

sequenceDiagram
    participant Plugin as Local STT Plugin
    participant Supervisor as STT Supervisor
    participant Internal as Internal STT Actor
    participant External as External STT Actor

    Plugin->>Supervisor: spawn_stt_supervisor()
    Supervisor-->>Plugin: ActorRef<DynamicSupervisorMsg>
    
    Plugin->>Supervisor: start_internal_stt(args)
    Supervisor->>Internal: spawn child with InternalSTTArgs
    Internal-->>Supervisor: spawned
    
    Plugin->>Supervisor: start_external_stt(args)
    Supervisor->>External: spawn child with ExternalSTTArgs
    External-->>Supervisor: spawned
    
    Note over Supervisor: Both actors under supervision<br/>with transient restart policy
    
    Plugin->>Supervisor: stop_stt_server(server_type)
    Supervisor->>Supervisor: terminate_child(actor_name)
    Supervisor-->>Plugin: Result
    
    Plugin->>Supervisor: stop_all_stt_servers()
    Supervisor->>Internal: terminate
    Supervisor->>External: terminate
    Supervisor-->>Plugin: Result

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

• Multiple interdependent changes: Refactoring spans core orchestration (ext.rs), shared state (lib.rs), and external server initialization (server/external.rs) with dependencies on new supervisor module.
• New actor/supervisor patterns: supervisor.rs introduces ractor-based dynamic supervision with child spawning, termination, and registry polling logic requiring verification of correctness.
• Public API modifications: State struct loses Default derive and gains supervisor field; ExternalSTTArgs changes from direct Command to CommandBuilder factory pattern with new port field—impacts caller code.
• Error surface changes: Removal of TauriError/IoError and addition of supervisor-specific variants requires review of error handling paths.
• Resource lifecycle: New cleanup_state helper and Arc usage in external server warrant careful review for resource cleanup and memory safety.

Possibly related PRs

• Wrap STT server with actor #1495: Refactors local-stt plugin to use ractor actors for internal/external STT servers with actor types and messages; this PR builds a dynamic supervisor on top of that architecture.
• Proper STT connection fetching with new ai setting #1582: Modifies same local-stt plugin core files (ext.rs, lib.rs, error.rs, server/mod.rs) altering server lifecycle representation and supervisor-driven changes.
• Fix external stt server startups #1402: Adjusts local-stt server startup code (ext.rs, server/external.rs); this PR replaces direct start/stop logic with dynamic supervisor orchestration.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.11% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.
Description check	❓ Inconclusive	No pull request description was provided by the author, making it impossible to assess whether a description exists or relates to the changeset.	Add a pull request description explaining the purpose of the supervisor integration, how it improves the existing architecture, and any migration notes for reviewers.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title accurately reflects the main change: introducing a supervisor for local-stt servers as evidenced by new supervisor.rs module, supervisor integration in lib.rs, and updated error/extension handling.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch supervisor-local-stt

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

plugins/local-stt/src/server/internal.rs (1)

1-135: Fix compile-time error when propagating server failures

String does not implement std::error::Error, so Err(e.into()) fails to compile against ActorProcessingErr. We need to wrap the message in an actual error type before bubbling it up; otherwise the actor never builds.

Apply this diff to store a real error and keep the actor stoppage semantics intact:

@@
-use std::{
-    net::{Ipv4Addr, SocketAddr},
-    path::PathBuf,
-};
+use std::{
+    io,
+    net::{Ipv4Addr, SocketAddr},
+    path::PathBuf,
+};
@@
-pub enum InternalSTTMessage {
-    GetHealth(RpcReplyPort<ServerInfo>),
-    ServerError(String),
-}
+pub enum InternalSTTMessage {
+    GetHealth(RpcReplyPort<ServerInfo>),
+    ServerError(ActorProcessingErr),
+}
@@
-        let whisper_service = HandleError::new(
+        let whisper_service = HandleError::new(
             hypr_transcribe_whisper_local::TranscribeService::builder()
                 .model_path(model_path)
                 .build(),
-            move |err: String| async move {
-                let _ = myself.send_message(InternalSTTMessage::ServerError(err.clone()));
+            move |err: String| async move {
+                let actor_err: ActorProcessingErr =
+                    io::Error::new(io::ErrorKind::Other, err.clone()).into();
+                let _ = myself.send_message(InternalSTTMessage::ServerError(actor_err));
                 (StatusCode::INTERNAL_SERVER_ERROR, err)
             },
         );
@@
-            InternalSTTMessage::ServerError(e) => Err(e.into()),
+            InternalSTTMessage::ServerError(e) => Err(e),

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0df8e3d and 5a54896.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (8)

• plugins/local-stt/Cargo.toml (1 hunks)
• plugins/local-stt/src/error.rs (1 hunks)
• plugins/local-stt/src/ext.rs (6 hunks)
• plugins/local-stt/src/lib.rs (3 hunks)
• plugins/local-stt/src/server/external.rs (5 hunks)
• plugins/local-stt/src/server/internal.rs (2 hunks)
• plugins/local-stt/src/server/mod.rs (1 hunks)
• plugins/local-stt/src/server/supervisor.rs (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (5)

plugins/local-stt/src/server/internal.rs (1)

plugins/local-stt/src/server/supervisor.rs (1)

• e (101-101)

plugins/local-stt/src/lib.rs (2)

plugins/local-stt/src/ext.rs (5)

• state (60-60)
• state (196-196)
• state (255-255)
• state (296-296)
• state (309-309)

plugins/local-stt/src/server/supervisor.rs (2)

• spawn_stt_supervisor (19-31)
• e (101-101)

plugins/local-stt/src/ext.rs (2)

plugins/local-stt/src/server/supervisor.rs (5)

• stop_all_stt_servers (117-123)
• e (101-101)
• stop_stt_server (89-115)
• start_internal_stt (33-39)
• start_external_stt (41-47)

plugins/local-stt/src/server/external.rs (2)

• new (21-25)
• new (42-56)

plugins/local-stt/src/server/supervisor.rs (2)

plugins/local-stt/src/server/external.rs (1)

• name (72-74)

plugins/local-stt/src/server/internal.rs (1)

• name (35-37)

plugins/local-stt/src/server/external.rs (3)

crates/am/src/client.rs (2)

• new (11-16)
• new (99-107)

crates/host/src/lib.rs (1)

• kill_processes_by_matcher (25-47)

plugins/local-stt/src/server/internal.rs (1)

• handle (112-134)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: ci (macos, macos-14)