feat: Add headless RPC daemon mode with gRPC streaming for remote clients

[ja7ad]

Preflight checklist

• I searched existing issues and this has not been proposed already.
• I checked the README and this is not already supported.

Component

Core Engine / CLI / GUI / TUI

Problem

Hydra currently operates as a standalone foreground application tied directly to the active session lifecycle. This presents several limitations:

1. Remote & Background Use Cases: Running Hydra continuously on a VPS, NAS, or headless home server requires terminal multiplexers (tmux/screen) without a native client-server separation.
2. Multi-Interface Disconnect: The Desktop GUI, TUI, CLI, and browser extensions cannot share a single, central engine instance. Closing the UI interrupts active downloads rather than leaving a background daemon running.
3. Telemetry Polling Bottlenecks: Traditional JSON-RPC implementations (such as aria2c --enable-rpc) suffer from polling latency and JSON serialization overhead when streaming high-frequency download chunks and speed metrics.

Proposed solution

Implement a dedicated Headless RPC Daemon mode (hydra daemon) powered by gRPC (HTTP/2 + Protocol Buffers) with bidirectional streaming support, allowing CLI, TUI, GUI, and browser extensions to act as thin clients.

Core Capabilities

1. Daemon Subcommand & Flags:

• hydra daemon --port 6800 --host 0.0.0.0
• --rpc-secret <TOKEN>: Specify a custom authentication token.
• --no-auth: Explicitly disable authentication (useful for local IPC/isolated environments).
• Automatically generate a secure API key/token on startup if none is provided and display it in the logs/save to ~/.hydra/daemon.token.

2. High-Performance gRPC Streaming:

• Utilize tonic (gRPC over HTTP/2) for low-overhead client-daemon communication.
• Expose server-streaming RPCs (e.g., StreamTaskUpdates, StreamActiveChunks) to broadcast real-time metrics, transfer rates, and segment allocation to connected frontends at 60 FPS without polling.

3. Remote Management API:

• Task Control: Add single/batch URLs, pause, resume, restart, and cancel.
• Queue & Scheduler: Queue priorities, scheduled start/stop timestamps, and bandwidth throttling rules.
• File Management: Purge tasks, delete downloaded files from disk, or change destination paths.

4. Client Connect Modes:

• Add a connection flag/config across CLI, TUI, and GUI to route actions to a daemon instance:

hydra --rpc-addr "192.168.1.50:6800" --rpc-secret "your-token" add "https://example.com/file.iso"
hydra-tui --connect "127.0.0.1:6800"

Alternatives considered

• JSON-RPC over WebSockets/HTTP (aria2 model): High serialization and polling overhead for rapid multi-chunk state visualizations. Note: A lightweight grpc-web or JSON-RPC compatibility proxy can be added alongside gRPC for browser extensions if needed.
• UNIX Domain Sockets only: Restricts connections to local IPC and does not support remote management across LAN/VPS/NAS setups.

Platforms this should cover

• Linux
• macOS
• Windows
• Android / iOS (via libhydra)

Additional context

Proposed Protobuf Definition Draft

syntax = "proto3";
package hydra.v1;

service HydraDaemon {
  rpc AddDownload (AddDownloadRequest) returns (TaskResponse);
  rpc ControlTask (ControlTaskRequest) returns (TaskResponse);
  rpc ListTasks (ListTasksRequest) returns (TaskListResponse);
  rpc StreamTaskUpdates (StreamRequest) returns (stream TaskUpdateEvent);
}

message TaskUpdateEvent {
  string task_id = 1;
  uint64 downloaded_bytes = 2;
  uint64 total_bytes = 3;
  uint64 current_speed = 4;
  repeated ChunkState chunks = 5;
}

message ChunkState {
  uint32 chunk_index = 1;
  uint64 offset = 2;
  uint64 length = 3;
  float progress = 4;
}

Compatibility

• This changes existing behavior (flags, defaults, output format, or the C ABI).

Contribution

• I'm willing to open a pull request implementing this.