Skip to main content

sonos_cli/cli/
resolve.rs

1use sonos_sdk::{Group, SonosSystem, Speaker};
2
3use crate::cli::GlobalFlags;
4use crate::config::Config;
5use crate::errors::CliError;
6
7/// Resolve --speaker / --group flags to a Speaker handle.
8///
9/// Priority: `--group` wins over `--speaker`. With neither flag, falls back to the
10/// configured default group, then the coordinator of the **largest** group, then any
11/// speaker.
12pub fn resolve_speaker(
13    system: &SonosSystem,
14    config: &Config,
15    global: &GlobalFlags,
16) -> Result<Speaker, CliError> {
17    // --group wins over --speaker
18    if let Some(group_name) = &global.group {
19        let resolved = config.resolve_alias(group_name);
20        let g = system
21            .group(resolved)
22            .ok_or_else(|| CliError::GroupNotFound(resolved.to_string()))?;
23        return g
24            .coordinator()
25            .ok_or_else(|| CliError::GroupNotFound(resolved.to_string()));
26    }
27
28    if let Some(speaker_name) = &global.speaker {
29        let resolved = config.resolve_alias(speaker_name);
30        return system
31            .speaker(resolved)
32            .ok_or_else(|| CliError::SpeakerNotFound(resolved.to_string()));
33    }
34
35    // Default: config group → first group coordinator → first speaker
36    if let Some(default_group) = &config.default_group {
37        if let Some(g) = system.group(default_group) {
38            if let Some(coordinator) = g.coordinator() {
39                return Ok(coordinator);
40            }
41        }
42    }
43
44    // Prefer a group coordinator so we get track/position data
45    // (non-coordinator speakers return NOT_IMPLEMENTED for these).
46    //
47    // Pick the *largest* group rather than whichever one happens to come first.
48    // `groups()` has no meaningful order, so `.next()` chose arbitrarily: on a
49    // household with a 4-speaker group playing and one idle standalone speaker,
50    // bare `sonos status` reported the idle speaker as often as not.
51    //
52    // Member count is the right tiebreak because it comes from topology and is
53    // free to read. Preferring a *playing* group would be more precise but costs
54    // a SOAP fetch per group — in a fresh process the cache is cold, so it would
55    // turn picking a default into N round-trips. Speakers are grouped in order to
56    // play together, so the biggest group is the one the user means.
57    //
58    // Ties break on group id so repeated invocations agree.
59    if let Some(coordinator) = largest_group_first(system)
60        .into_iter()
61        .find_map(|g| g.coordinator())
62    {
63        return Ok(coordinator);
64    }
65
66    // Last resort: first speaker (standalone, no groups)
67    system
68        .speakers()
69        .into_iter()
70        .next()
71        .ok_or_else(|| CliError::SpeakerNotFound("no speakers available".to_string()))
72}
73
74/// Resolve --group / --speaker flags to a Group handle.
75///
76/// Priority: `--group` wins. With no flag, falls back to the configured default
77/// group, then the **largest** group.
78pub fn resolve_group(
79    system: &SonosSystem,
80    config: &Config,
81    global: &GlobalFlags,
82) -> Result<Group, CliError> {
83    if let Some(group_name) = &global.group {
84        let resolved = config.resolve_alias(group_name);
85        return system
86            .group(resolved)
87            .ok_or_else(|| CliError::GroupNotFound(resolved.to_string()));
88    }
89
90    // Default: config group → largest group
91    if let Some(default_group) = &config.default_group {
92        if let Some(g) = system.group(default_group) {
93            return Ok(g);
94        }
95    }
96
97    // Same reasoning as `resolve_speaker`: `groups()` is backed by a HashMap, so
98    // `.next()` picked arbitrarily. This one matters more — `resolve_group` backs
99    // the `volume` and `mute` *write* commands, so a bare `sonos volume 30` could
100    // change the volume of whichever group happened to come out first.
101    largest_group_first(system)
102        .into_iter()
103        .next()
104        .ok_or_else(|| CliError::GroupNotFound("no groups available".to_string()))
105}
106
107/// Groups ordered by member count descending, ties broken on group id.
108///
109/// Shared by `resolve_speaker` and `resolve_group` so a bare command and its
110/// group-scoped equivalent cannot disagree about which group they mean.
111fn largest_group_first(system: &SonosSystem) -> Vec<Group> {
112    let mut groups = system.groups();
113    groups.sort_by(|a, b| {
114        b.member_ids
115            .len()
116            .cmp(&a.member_ids.len())
117            .then_with(|| a.id.as_str().cmp(b.id.as_str()))
118    });
119    groups
120}
121
122/// Resolve --speaker flag for speaker-only commands (bass, treble, loudness).
123/// Rejects --group with a validation error.
124pub fn require_speaker_only(
125    system: &SonosSystem,
126    config: &Config,
127    global: &GlobalFlags,
128    command_name: &str,
129) -> Result<Speaker, CliError> {
130    if global.group.is_some() {
131        return Err(CliError::Validation(format!(
132            "--speaker is required for {command_name}"
133        )));
134    }
135    let name = global
136        .speaker
137        .as_deref()
138        .ok_or_else(|| CliError::Validation(format!("--speaker is required for {command_name}")))?;
139    let resolved = config.resolve_alias(name);
140    system
141        .speaker(resolved)
142        .ok_or_else(|| CliError::SpeakerNotFound(resolved.to_string()))
143}
144
145#[cfg(all(test, feature = "test-helpers"))]
146mod tests {
147    use super::*;
148
149    #[test]
150    fn resolve_speaker_by_name() {
151        let system = SonosSystem::with_speakers(&["Kitchen"]);
152        let config = Config::default();
153        let global = GlobalFlags {
154            speaker: Some("Kitchen".into()),
155            group: None,
156            ..Default::default()
157        };
158        let spk = resolve_speaker(&system, &config, &global).unwrap();
159        assert_eq!(spk.name, "Kitchen");
160    }
161
162    #[test]
163    fn resolve_speaker_not_found() {
164        let system = SonosSystem::with_speakers(&["Kitchen"]);
165        let config = Config::default();
166        let global = GlobalFlags {
167            speaker: Some("Nonexistent".into()),
168            group: None,
169            ..Default::default()
170        };
171        let result = resolve_speaker(&system, &config, &global);
172        assert!(matches!(result, Err(CliError::SpeakerNotFound(_))));
173    }
174
175    #[test]
176    fn resolve_speaker_falls_back_to_first() {
177        let system = SonosSystem::with_speakers(&["Kitchen"]);
178        let config = Config::default();
179        let global = GlobalFlags::default();
180        let spk = resolve_speaker(&system, &config, &global).unwrap();
181        assert_eq!(spk.name, "Kitchen");
182    }
183
184    #[test]
185    fn resolve_speaker_prefers_group_coordinator() {
186        let system = SonosSystem::with_groups(&["Kitchen", "Bedroom"]);
187        let config = Config::default();
188        let global = GlobalFlags::default();
189        let spk = resolve_speaker(&system, &config, &global).unwrap();
190
191        // Must be *some* group's coordinator, not an arbitrary member. This
192        // deliberately does not assert which one: the previous version compared
193        // against `groups().into_iter().next()`, which baked the unordered
194        // iteration order into the expectation — the very behaviour that made
195        // bare `sonos status` pick a random speaker on real hardware.
196        let is_a_coordinator = system
197            .groups()
198            .into_iter()
199            .filter_map(|g| g.coordinator())
200            .any(|c| c.name == spk.name);
201        assert!(
202            is_a_coordinator,
203            "{} is not any group's coordinator",
204            spk.name
205        );
206    }
207
208    #[test]
209    fn resolve_speaker_empty_system_fails() {
210        let system = SonosSystem::with_speakers(&[]);
211        let config = Config::default();
212        let global = GlobalFlags::default();
213        let result = resolve_speaker(&system, &config, &global);
214        assert!(result.is_err());
215    }
216
217    #[test]
218    fn require_speaker_only_rejects_group() {
219        let system = SonosSystem::with_speakers(&["Kitchen"]);
220        let global = GlobalFlags {
221            speaker: None,
222            group: Some("Living Room".into()),
223            ..Default::default()
224        };
225        let result = require_speaker_only(&system, &Config::default(), &global, "bass");
226        assert!(matches!(result, Err(CliError::Validation(_))));
227    }
228
229    #[test]
230    fn require_speaker_only_requires_speaker_flag() {
231        let system = SonosSystem::with_speakers(&["Kitchen"]);
232        let global = GlobalFlags::default();
233        let result = require_speaker_only(&system, &Config::default(), &global, "bass");
234        assert!(matches!(result, Err(CliError::Validation(_))));
235    }
236
237    #[test]
238    fn require_speaker_only_finds_speaker() {
239        let system = SonosSystem::with_speakers(&["Kitchen"]);
240        let global = GlobalFlags {
241            speaker: Some("Kitchen".into()),
242            group: None,
243            ..Default::default()
244        };
245        let spk = require_speaker_only(&system, &Config::default(), &global, "bass").unwrap();
246        assert_eq!(spk.name, "Kitchen");
247    }
248
249    #[test]
250    fn resolve_group_by_name() {
251        let system = SonosSystem::with_groups(&["Kitchen", "Bedroom"]);
252        let config = Config::default();
253        let global = GlobalFlags {
254            speaker: None,
255            group: Some("Kitchen".into()),
256            ..Default::default()
257        };
258        let grp = resolve_group(&system, &config, &global).unwrap();
259        let coord = grp.coordinator().unwrap();
260        assert_eq!(coord.name, "Kitchen");
261    }
262
263    #[test]
264    fn resolve_group_not_found() {
265        let system = SonosSystem::with_groups(&["Kitchen"]);
266        let config = Config::default();
267        let global = GlobalFlags {
268            speaker: None,
269            group: Some("Nonexistent".into()),
270            ..Default::default()
271        };
272        let result = resolve_group(&system, &config, &global);
273        assert!(matches!(result, Err(CliError::GroupNotFound(_))));
274    }
275
276    #[test]
277    fn resolve_group_falls_back_to_first() {
278        let system = SonosSystem::with_groups(&["Kitchen"]);
279        let config = Config::default();
280        let global = GlobalFlags::default();
281        let grp = resolve_group(&system, &config, &global).unwrap();
282        let coord = grp.coordinator().unwrap();
283        assert_eq!(coord.name, "Kitchen");
284    }
285
286    #[test]
287    fn resolve_group_uses_config_default() {
288        let system = SonosSystem::with_groups(&["Kitchen", "Bedroom"]);
289        let config = Config {
290            default_group: Some("Bedroom".into()),
291            ..Config::default()
292        };
293        let global = GlobalFlags::default();
294        let grp = resolve_group(&system, &config, &global).unwrap();
295        let coord = grp.coordinator().unwrap();
296        assert_eq!(coord.name, "Bedroom");
297    }
298
299    #[test]
300    fn resolve_group_empty_system_fails() {
301        let system = SonosSystem::with_groups(&[]);
302        let config = Config::default();
303        let global = GlobalFlags::default();
304        let result = resolve_group(&system, &config, &global);
305        assert!(matches!(result, Err(CliError::GroupNotFound(_))));
306    }
307
308    #[test]
309    fn resolve_group_flag_wins_over_speaker() {
310        let system = SonosSystem::with_groups(&["Kitchen", "Bedroom"]);
311        let config = Config::default();
312        let global = GlobalFlags {
313            speaker: Some("Bedroom".into()),
314            group: Some("Kitchen".into()),
315            ..Default::default()
316        };
317        let grp = resolve_group(&system, &config, &global).unwrap();
318        let coord = grp.coordinator().unwrap();
319        assert_eq!(coord.name, "Kitchen");
320    }
321
322    #[test]
323    fn resolve_speaker_with_alias() {
324        let system = SonosSystem::with_speakers(&["Master Bedroom"]);
325        let mut config = Config::default();
326        config.set_alias("Master Bedroom", "bed");
327        let global = GlobalFlags {
328            speaker: Some("bed".into()),
329            group: None,
330            ..Default::default()
331        };
332        let spk = resolve_speaker(&system, &config, &global).unwrap();
333        assert_eq!(spk.name, "Master Bedroom");
334    }
335
336    #[test]
337    fn resolve_speaker_alias_not_found_shows_resolved_name() {
338        let system = SonosSystem::with_speakers(&["Kitchen"]);
339        let mut config = Config::default();
340        config.set_alias("Master Bedroom", "bed");
341        let global = GlobalFlags {
342            speaker: Some("bed".into()),
343            group: None,
344            ..Default::default()
345        };
346        let result = resolve_speaker(&system, &config, &global);
347        assert!(
348            matches!(result, Err(CliError::SpeakerNotFound(ref name)) if name == "Master Bedroom")
349        );
350    }
351
352    #[test]
353    fn resolve_group_with_alias() {
354        let system = SonosSystem::with_groups(&["Living Room"]);
355        let mut config = Config::default();
356        config.set_alias("Living Room", "lr");
357        let global = GlobalFlags {
358            speaker: None,
359            group: Some("lr".into()),
360            ..Default::default()
361        };
362        let grp = resolve_group(&system, &config, &global).unwrap();
363        let coord = grp.coordinator().unwrap();
364        assert_eq!(coord.name, "Living Room");
365    }
366
367    #[test]
368    fn require_speaker_only_resolves_alias() {
369        let system = SonosSystem::with_speakers(&["Master Bedroom"]);
370        let mut config = Config::default();
371        config.set_alias("Master Bedroom", "bed");
372        let global = GlobalFlags {
373            speaker: Some("bed".into()),
374            group: None,
375            ..Default::default()
376        };
377        let spk = require_speaker_only(&system, &config, &global, "bass").unwrap();
378        assert_eq!(spk.name, "Master Bedroom");
379    }
380
381    /// Build a system with one multi-member group beside a standalone speaker.
382    ///
383    /// The standalone group is listed *first* so an implementation that takes
384    /// whatever `groups()` yields first can pick the wrong one.
385    fn system_with_one_big_group() -> SonosSystem {
386        use sonos_sdk::sonos_discovery::Device;
387        use sonos_sdk::{GroupId, SpeakerId};
388
389        let devices: Vec<Device> = ["Bedroom", "Living Room", "Bathroom", "Kitchen"]
390            .iter()
391            .enumerate()
392            .map(|(i, name)| Device {
393                id: format!("RINCON_{i:03}"),
394                name: (*name).to_string(),
395                room_name: (*name).to_string(),
396                ip_address: format!("192.0.2.{}", 10 + i),
397                port: 1400,
398                model_name: "Sonos One".to_string(),
399            })
400            .collect();
401
402        SonosSystem::from_devices_offline_with_groups(
403            devices,
404            vec![
405                // Kitchen, standalone — deliberately first.
406                (
407                    GroupId::new("RINCON_003:1"),
408                    SpeakerId::new("RINCON_003"),
409                    vec![SpeakerId::new("RINCON_003")],
410                ),
411                // Bedroom coordinating a three-speaker group.
412                (
413                    GroupId::new("RINCON_000:1"),
414                    SpeakerId::new("RINCON_000"),
415                    vec![
416                        SpeakerId::new("RINCON_000"),
417                        SpeakerId::new("RINCON_001"),
418                        SpeakerId::new("RINCON_002"),
419                    ],
420                ),
421            ],
422        )
423        .expect("offline construction cannot fail")
424    }
425
426    fn no_flags() -> GlobalFlags {
427        GlobalFlags::default()
428    }
429
430    /// Bare `sonos status` must report the group the user is listening to.
431    ///
432    /// Hardware regression: with a four-speaker group playing and one idle
433    /// standalone speaker, `sonos status` reported the idle speaker, because the
434    /// old code took `groups().into_iter().next()` and `groups` is a `HashMap`.
435    #[test]
436    fn resolve_speaker_defaults_to_largest_group() {
437        let spk = resolve_speaker(
438            &system_with_one_big_group(),
439            &Config::default(),
440            &no_flags(),
441        )
442        .expect("a speaker must resolve");
443        assert_eq!(
444            spk.name, "Bedroom",
445            "expected the three-member group's coordinator, got {}",
446            spk.name
447        );
448    }
449
450    /// Same for `resolve_group`, which backs the `volume` and `mute` *writes* —
451    /// so picking arbitrarily here changes the wrong speakers' volume.
452    #[test]
453    fn resolve_group_defaults_to_largest_group() {
454        let grp = resolve_group(
455            &system_with_one_big_group(),
456            &Config::default(),
457            &no_flags(),
458        )
459        .expect("a group must resolve");
460        assert_eq!(grp.member_ids.len(), 3, "expected the three-member group");
461        assert_eq!(
462            grp.coordinator().map(|c| c.name),
463            Some("Bedroom".to_string())
464        );
465    }
466}