Implement notification stream rpc

proto/torrent.proto

@@ -15,6 +15,10 @@ service Torrents {
   rpc Pause(PauseRequest) returns (PauseResponse);
   // Resume a paused torrent.
   rpc Resume(ResumeRequest) returns (ResumeResponse);
+  // Subscribe to a live stream of torrent notifications. Events are delivered
+  // from the subscribe point onward — no history is replayed. New subscribers
+  // only see events that fire after they connect.
+  rpc Notifications(NotificationsRequest) returns (stream Notification);
 }
 
 message AddRequest {
@@ -56,6 +60,69 @@ message ResumeRequest {
 
 message ResumeResponse {}
 
+message NotificationsRequest {
+  // If non-empty, only events for these torrent ids (or id prefixes, as
+  // accepted by `Status`/`Remove`) are delivered.
+  repeated string ids = 1;
+  // If non-empty, only these event kinds are delivered. An empty list means
+  // all kinds.
+  repeated NotificationKind kinds = 2;
+}
+
+message Notification {
+  // Wall-clock time the daemon observed the change, in milliseconds since the
+  // Unix epoch.
+  uint64 observed_at_unix_millis = 1;
+  // What changed. Use this to dispatch; use the `oneof detail` for
+  // kind-specific payload.
+  NotificationKind kind = 2;
+  // Full snapshot of the torrent *after* the change. Always populated so
+  // consumers don't need to fan out to `Status` for context.
+  TorrentStatus torrent = 3;
+  oneof detail {
+    StateChanged state_changed = 10;
+    ProgressMark progress = 11;
+    AddedInfo added = 12;
+    RemovedInfo removed = 13;
+  }
+}
+
+enum NotificationKind {
+  NOTIFICATION_KIND_UNSPECIFIED = 0;
+  // Emitted once when a torrent is added via `Add`.
+  TORRENT_ADDED = 1;
+  // Emitted once when a torrent is removed via `Remove`.
+  TORRENT_REMOVED = 2;
+  // Emitted on any `State` transition, including PAUSED <-> DOWNLOADING,
+  // DOWNLOADING <-> STALE, * -> FINISHED, * -> ERROR.
+  STATE_CHANGED = 3;
+  // Emitted when the integer download percentage changes (rate-limited).
+  // No event is sent if the percentage did not advance since the last tick.
+  PROGRESS = 4;
+}
+
+message StateChanged {
+  State previous = 1;
+  State current = 2;
+}
+
+message ProgressMark {
+  // Current integer percentage 0..=100.
+  uint32 percent = 1;
+  // Bytes downloaded since the previous PROGRESS event for this torrent.
+  uint64 bytes_delta = 2;
+}
+
+message AddedInfo {
+  // Source string as provided to `Add` (magnet, URL, or file path).
+  string source = 1;
+}
+
+message RemovedInfo {
+  // True if `Remove` was called with `delete_files = true`.
+  bool files_deleted = 1;
+}
+
 enum State {
   STATE_UNSPECIFIED = 0;
   PENDING = 1;
@@ -63,6 +130,12 @@ enum State {
   PAUSED = 3;
   FINISHED = 4;
   ERROR = 5;
+  // Live per librqbit, but the daemon has detected a stall: no byte progress
+  // for several ticks AND zero connected peers. The torrent is still
+  // considered live by the underlying engine; this state is an application-
+  // level overlay. Recovers to DOWNLOADING automatically when bytes advance
+  // or a peer connects.
+  STALE = 6;
 }
 
 message TorrentStatus {