Alexander
ad03caa3f4
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/claude-agent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
111 lines
3.0 KiB
Plaintext
111 lines
3.0 KiB
Plaintext
@startuml MonitorAlbumStream Protocol
|
|
skinparam sequenceMessageAlign center
|
|
title MonitorAlbumStream: Message Protocol
|
|
|
|
participant "Client" as C
|
|
participant "Server" as S
|
|
|
|
== Stream Initialization ==
|
|
|
|
C -> S: gRPC MonitorAlbumStream()
|
|
note right: Opens bidirectional stream
|
|
|
|
== Request Messages (Client -> Server) ==
|
|
|
|
C -> S: MonitorAlbumStreamRequest
|
|
note right #lightblue
|
|
**oneof message:**
|
|
- **start**: StartMonitorRequest
|
|
- album_id (required)
|
|
- quality: LOSSLESS | LOSSY | UNSPECIFIED
|
|
- mode: AUTOMATIC (0) | MANUAL (1)
|
|
- indexer_options: {tracker}
|
|
- **decision**: UserDecision
|
|
- prompt_id (must match pending prompt)
|
|
- confirm | selected_id | selected_ids
|
|
- **cancel**: CancelRequest
|
|
- Gracefully terminates workflow
|
|
end note
|
|
|
|
== Response Messages (Server -> Client) ==
|
|
|
|
S -> C: MonitorAlbumStreamResponse
|
|
note left #lightgreen
|
|
**oneof message:**
|
|
- **status**: StatusUpdate
|
|
- step: MonitorStep enum
|
|
- message: human-readable text
|
|
- data: StreamAlbumInfo | TorrentList | ReleaseInfo
|
|
- **prompt**: PromptForDecision
|
|
- prompt_id: unique identifier
|
|
- type: CONFIRM | SELECT_ONE | SELECT_MANY
|
|
- message: prompt text
|
|
- timeout_seconds: response deadline
|
|
- options: confirm | select_one | select_many config
|
|
- **result**: MonitorAlbumResponse
|
|
- Final response (stream ends after this)
|
|
- **error**: ErrorUpdate
|
|
- failed_step: where error occurred
|
|
- message: error description
|
|
- recoverable: bool
|
|
end note
|
|
|
|
== Monitor Steps (Status Updates) ==
|
|
|
|
note over C, S #lightyellow
|
|
**MonitorStep Enum:**
|
|
1. FETCHING_METADATA - Getting album info from metadata service
|
|
2. CHECKING_OWNED - Checking if already downloaded
|
|
3. SEARCHING_INDEXER - Querying Jackett/indexers
|
|
4. PARSING_RESULTS - Resolving magnets, parsing torrents
|
|
5. FILTERING_QUALITY - Applying quality filter
|
|
6. SELECTING_RELEASE - Choosing best/user-selected release
|
|
7. ADDING_TORRENT - Adding to qBittorrent
|
|
8. SAVING - Persisting to database
|
|
9. COMPLETE - Workflow finished
|
|
end note
|
|
|
|
== Prompt Types (Manual Mode) ==
|
|
|
|
note over C, S #orange
|
|
**CONFIRM** (yes/no decision)
|
|
- confirm_label, cancel_label
|
|
- default_value: bool
|
|
|
|
**SELECT_ONE** (pick one option)
|
|
- options: [{id, label, description}]
|
|
- default_id: pre-selected option
|
|
|
|
**SELECT_MANY** (pick multiple options)
|
|
- options: [{id, label, description}]
|
|
- default_ids: pre-selected options
|
|
- min_selections, max_selections
|
|
end note
|
|
|
|
== Data Payloads ==
|
|
|
|
note over C, S #lightblue
|
|
**StreamAlbumInfo** (at FETCHING_METADATA)
|
|
- artist, title, release_date, already_owned, owned_quality
|
|
|
|
**TorrentList** (at PARSING_RESULTS)
|
|
- torrents: [{id, title, tracker, seeders, format, lossless}]
|
|
|
|
**ReleaseInfo** (at SELECTING_RELEASE)
|
|
- info_hash, format, bit_depth, sample_rate, seeders, tracker
|
|
end note
|
|
|
|
== Timeout Behavior ==
|
|
|
|
note over C, S #pink
|
|
When prompt times out (max: 300s):
|
|
- Server uses **default decision** value
|
|
- Workflow continues automatically
|
|
- No error is raised
|
|
|
|
Timeout is capped server-side at 300s.
|
|
If timeout_seconds on prompt is 0 or exceeds max, 300s is used.
|
|
end note
|
|
|
|
@enduml
|