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            quiet: false,
157            verbose: 0,
158            no_input: false,
159        };
160        let spk = resolve_speaker(&system, &config, &global).unwrap();
161        assert_eq!(spk.name, "Kitchen");
162    }
163
164    #[test]
165    fn resolve_speaker_not_found() {
166        let system = SonosSystem::with_speakers(&["Kitchen"]);
167        let config = Config::default();
168        let global = GlobalFlags {
169            speaker: Some("Nonexistent".into()),
170            group: None,
171            quiet: false,
172            verbose: 0,
173            no_input: false,
174        };
175        let result = resolve_speaker(&system, &config, &global);
176        assert!(matches!(result, Err(CliError::SpeakerNotFound(_))));
177    }
178
179    #[test]
180    fn resolve_speaker_falls_back_to_first() {
181        let system = SonosSystem::with_speakers(&["Kitchen"]);
182        let config = Config::default();
183        let global = GlobalFlags {
184            speaker: None,
185            group: None,
186            quiet: false,
187            verbose: 0,
188            no_input: false,
189        };
190        let spk = resolve_speaker(&system, &config, &global).unwrap();
191        assert_eq!(spk.name, "Kitchen");
192    }
193
194    #[test]
195    fn resolve_speaker_prefers_group_coordinator() {
196        let system = SonosSystem::with_groups(&["Kitchen", "Bedroom"]);
197        let config = Config::default();
198        let global = GlobalFlags {
199            speaker: None,
200            group: None,
201            quiet: false,
202            verbose: 0,
203            no_input: false,
204        };
205        let spk = resolve_speaker(&system, &config, &global).unwrap();
206
207        // Must be *some* group's coordinator, not an arbitrary member. This
208        // deliberately does not assert which one: the previous version compared
209        // against `groups().into_iter().next()`, which baked the unordered
210        // iteration order into the expectation — the very behaviour that made
211        // bare `sonos status` pick a random speaker on real hardware.
212        let is_a_coordinator = system
213            .groups()
214            .into_iter()
215            .filter_map(|g| g.coordinator())
216            .any(|c| c.name == spk.name);
217        assert!(
218            is_a_coordinator,
219            "{} is not any group's coordinator",
220            spk.name
221        );
222    }
223
224    #[test]
225    fn resolve_speaker_empty_system_fails() {
226        let system = SonosSystem::with_speakers(&[]);
227        let config = Config::default();
228        let global = GlobalFlags {
229            speaker: None,
230            group: None,
231            quiet: false,
232            verbose: 0,
233            no_input: false,
234        };
235        let result = resolve_speaker(&system, &config, &global);
236        assert!(result.is_err());
237    }
238
239    #[test]
240    fn require_speaker_only_rejects_group() {
241        let system = SonosSystem::with_speakers(&["Kitchen"]);
242        let global = GlobalFlags {
243            speaker: None,
244            group: Some("Living Room".into()),
245            quiet: false,
246            verbose: 0,
247            no_input: false,
248        };
249        let result = require_speaker_only(&system, &Config::default(), &global, "bass");
250        assert!(matches!(result, Err(CliError::Validation(_))));
251    }
252
253    #[test]
254    fn require_speaker_only_requires_speaker_flag() {
255        let system = SonosSystem::with_speakers(&["Kitchen"]);
256        let global = GlobalFlags {
257            speaker: None,
258            group: None,
259            quiet: false,
260            verbose: 0,
261            no_input: false,
262        };
263        let result = require_speaker_only(&system, &Config::default(), &global, "bass");
264        assert!(matches!(result, Err(CliError::Validation(_))));
265    }
266
267    #[test]
268    fn require_speaker_only_finds_speaker() {
269        let system = SonosSystem::with_speakers(&["Kitchen"]);
270        let global = GlobalFlags {
271            speaker: Some("Kitchen".into()),
272            group: None,
273            quiet: false,
274            verbose: 0,
275            no_input: false,
276        };
277        let spk = require_speaker_only(&system, &Config::default(), &global, "bass").unwrap();
278        assert_eq!(spk.name, "Kitchen");
279    }
280
281    #[test]
282    fn resolve_group_by_name() {
283        let system = SonosSystem::with_groups(&["Kitchen", "Bedroom"]);
284        let config = Config::default();
285        let global = GlobalFlags {
286            speaker: None,
287            group: Some("Kitchen".into()),
288            quiet: false,
289            verbose: 0,
290            no_input: false,
291        };
292        let grp = resolve_group(&system, &config, &global).unwrap();
293        let coord = grp.coordinator().unwrap();
294        assert_eq!(coord.name, "Kitchen");
295    }
296
297    #[test]
298    fn resolve_group_not_found() {
299        let system = SonosSystem::with_groups(&["Kitchen"]);
300        let config = Config::default();
301        let global = GlobalFlags {
302            speaker: None,
303            group: Some("Nonexistent".into()),
304            quiet: false,
305            verbose: 0,
306            no_input: false,
307        };
308        let result = resolve_group(&system, &config, &global);
309        assert!(matches!(result, Err(CliError::GroupNotFound(_))));
310    }
311
312    #[test]
313    fn resolve_group_falls_back_to_first() {
314        let system = SonosSystem::with_groups(&["Kitchen"]);
315        let config = Config::default();
316        let global = GlobalFlags {
317            speaker: None,
318            group: None,
319            quiet: false,
320            verbose: 0,
321            no_input: false,
322        };
323        let grp = resolve_group(&system, &config, &global).unwrap();
324        let coord = grp.coordinator().unwrap();
325        assert_eq!(coord.name, "Kitchen");
326    }
327
328    #[test]
329    fn resolve_group_uses_config_default() {
330        let system = SonosSystem::with_groups(&["Kitchen", "Bedroom"]);
331        let config = Config {
332            default_group: Some("Bedroom".into()),
333            ..Config::default()
334        };
335        let global = GlobalFlags {
336            speaker: None,
337            group: None,
338            quiet: false,
339            verbose: 0,
340            no_input: false,
341        };
342        let grp = resolve_group(&system, &config, &global).unwrap();
343        let coord = grp.coordinator().unwrap();
344        assert_eq!(coord.name, "Bedroom");
345    }
346
347    #[test]
348    fn resolve_group_empty_system_fails() {
349        let system = SonosSystem::with_groups(&[]);
350        let config = Config::default();
351        let global = GlobalFlags {
352            speaker: None,
353            group: None,
354            quiet: false,
355            verbose: 0,
356            no_input: false,
357        };
358        let result = resolve_group(&system, &config, &global);
359        assert!(matches!(result, Err(CliError::GroupNotFound(_))));
360    }
361
362    #[test]
363    fn resolve_group_flag_wins_over_speaker() {
364        let system = SonosSystem::with_groups(&["Kitchen", "Bedroom"]);
365        let config = Config::default();
366        let global = GlobalFlags {
367            speaker: Some("Bedroom".into()),
368            group: Some("Kitchen".into()),
369            quiet: false,
370            verbose: 0,
371            no_input: false,
372        };
373        let grp = resolve_group(&system, &config, &global).unwrap();
374        let coord = grp.coordinator().unwrap();
375        assert_eq!(coord.name, "Kitchen");
376    }
377
378    #[test]
379    fn resolve_speaker_with_alias() {
380        let system = SonosSystem::with_speakers(&["Master Bedroom"]);
381        let mut config = Config::default();
382        config.set_alias("Master Bedroom", "bed");
383        let global = GlobalFlags {
384            speaker: Some("bed".into()),
385            group: None,
386            quiet: false,
387            verbose: 0,
388            no_input: false,
389        };
390        let spk = resolve_speaker(&system, &config, &global).unwrap();
391        assert_eq!(spk.name, "Master Bedroom");
392    }
393
394    #[test]
395    fn resolve_speaker_alias_not_found_shows_resolved_name() {
396        let system = SonosSystem::with_speakers(&["Kitchen"]);
397        let mut config = Config::default();
398        config.set_alias("Master Bedroom", "bed");
399        let global = GlobalFlags {
400            speaker: Some("bed".into()),
401            group: None,
402            quiet: false,
403            verbose: 0,
404            no_input: false,
405        };
406        let result = resolve_speaker(&system, &config, &global);
407        assert!(
408            matches!(result, Err(CliError::SpeakerNotFound(ref name)) if name == "Master Bedroom")
409        );
410    }
411
412    #[test]
413    fn resolve_group_with_alias() {
414        let system = SonosSystem::with_groups(&["Living Room"]);
415        let mut config = Config::default();
416        config.set_alias("Living Room", "lr");
417        let global = GlobalFlags {
418            speaker: None,
419            group: Some("lr".into()),
420            quiet: false,
421            verbose: 0,
422            no_input: false,
423        };
424        let grp = resolve_group(&system, &config, &global).unwrap();
425        let coord = grp.coordinator().unwrap();
426        assert_eq!(coord.name, "Living Room");
427    }
428
429    #[test]
430    fn require_speaker_only_resolves_alias() {
431        let system = SonosSystem::with_speakers(&["Master Bedroom"]);
432        let mut config = Config::default();
433        config.set_alias("Master Bedroom", "bed");
434        let global = GlobalFlags {
435            speaker: Some("bed".into()),
436            group: None,
437            quiet: false,
438            verbose: 0,
439            no_input: false,
440        };
441        let spk = require_speaker_only(&system, &config, &global, "bass").unwrap();
442        assert_eq!(spk.name, "Master Bedroom");
443    }
444
445    /// Build a system with one multi-member group beside a standalone speaker.
446    ///
447    /// The standalone group is listed *first* so an implementation that takes
448    /// whatever `groups()` yields first can pick the wrong one.
449    fn system_with_one_big_group() -> SonosSystem {
450        use sonos_sdk::sonos_discovery::Device;
451        use sonos_sdk::{GroupId, SpeakerId};
452
453        let devices: Vec<Device> = ["Bedroom", "Living Room", "Bathroom", "Kitchen"]
454            .iter()
455            .enumerate()
456            .map(|(i, name)| Device {
457                id: format!("RINCON_{i:03}"),
458                name: (*name).to_string(),
459                room_name: (*name).to_string(),
460                ip_address: format!("192.0.2.{}", 10 + i),
461                port: 1400,
462                model_name: "Sonos One".to_string(),
463            })
464            .collect();
465
466        SonosSystem::from_devices_offline_with_groups(
467            devices,
468            vec![
469                // Kitchen, standalone — deliberately first.
470                (
471                    GroupId::new("RINCON_003:1"),
472                    SpeakerId::new("RINCON_003"),
473                    vec![SpeakerId::new("RINCON_003")],
474                ),
475                // Bedroom coordinating a three-speaker group.
476                (
477                    GroupId::new("RINCON_000:1"),
478                    SpeakerId::new("RINCON_000"),
479                    vec![
480                        SpeakerId::new("RINCON_000"),
481                        SpeakerId::new("RINCON_001"),
482                        SpeakerId::new("RINCON_002"),
483                    ],
484                ),
485            ],
486        )
487        .expect("offline construction cannot fail")
488    }
489
490    fn no_flags() -> GlobalFlags {
491        GlobalFlags {
492            speaker: None,
493            group: None,
494            quiet: false,
495            verbose: 0,
496            no_input: false,
497        }
498    }
499
500    /// Bare `sonos status` must report the group the user is listening to.
501    ///
502    /// Hardware regression: with a four-speaker group playing and one idle
503    /// standalone speaker, `sonos status` reported the idle speaker, because the
504    /// old code took `groups().into_iter().next()` and `groups` is a `HashMap`.
505    #[test]
506    fn resolve_speaker_defaults_to_largest_group() {
507        let spk = resolve_speaker(
508            &system_with_one_big_group(),
509            &Config::default(),
510            &no_flags(),
511        )
512        .expect("a speaker must resolve");
513        assert_eq!(
514            spk.name, "Bedroom",
515            "expected the three-member group's coordinator, got {}",
516            spk.name
517        );
518    }
519
520    /// Same for `resolve_group`, which backs the `volume` and `mute` *writes* —
521    /// so picking arbitrarily here changes the wrong speakers' volume.
522    #[test]
523    fn resolve_group_defaults_to_largest_group() {
524        let grp = resolve_group(
525            &system_with_one_big_group(),
526            &Config::default(),
527            &no_flags(),
528        )
529        .expect("a group must resolve");
530        assert_eq!(grp.member_ids.len(), 3, "expected the three-member group");
531        assert_eq!(
532            grp.coordinator().map(|c| c.name),
533            Some("Bedroom".to_string())
534        );
535    }
536}