feat(protocols): Add more control over gathering additional information (#180)

* protocols: Add more control over gathering additional information

Adds GatherToggle which allows choosing the behaviour for how the query
handles fetching additional information. The choices are:
- DontGather - Don't attempt to fetch information
- AttemptGather - Try to fetch the information but ignore errors
- Required - Try to fetch information and fail if it errors

A handy macro was also added to utils to dispatch additional queries
based on a GatherToggle value.

* Add/Update badge

* protocols: Improve GatherToggle enum names

Co-Authored-By: Cain <75994858+cainthebest@users.noreply.github.com>
Co-Authored-By: CosminPerRam <cosmin.p@live.com>

* Add/Update badge

---------

Co-authored-by: GitHub Action <action@github.com>
Co-authored-by: Cain <75994858+cainthebest@users.noreply.github.com>
Co-authored-by: CosminPerRam <cosmin.p@live.com>

crates/lib/src/protocols/valve/mod.rs

@@ -28,7 +28,11 @@ macro_rules! game_query_mod {
     ($mod_name: ident, $pretty_name: expr, $engine: expr, $default_port: literal, $gathering_settings: expr) => {
         #[doc = $pretty_name]
         pub mod $mod_name {
-            use crate::protocols::valve::{Engine, GatheringSettings};
+            #[allow(unused_imports)]
+            use crate::protocols::{
+                types::GatherToggle,
+                valve::{Engine, GatheringSettings},
+            };
 
             crate::protocols::valve::game_query_fn!($pretty_name, $engine, $default_port, $gathering_settings);
         }

crates/lib/src/protocols/valve/protocol.rs

@@ -19,7 +19,7 @@ use crate::{
         },
     },
     socket::{Socket, UdpSocket},
-    utils::{retry_on_timeout, u8_lower_upper},
+    utils::{maybe_gather, retry_on_timeout, u8_lower_upper},
     GDErrorKind::{BadGame, Decompress, UnknownEnumCast},
     GDResult,
 };
@@ -470,13 +470,13 @@ fn get_response(
 
     Ok(Response {
         info,
-        players: match gather_settings.players {
-            false => None,
-            true => Some(client.get_server_players(&engine, protocol)?),
-        },
-        rules: match gather_settings.rules {
-            false => None,
-            true => Some(client.get_server_rules(&engine, protocol)?),
-        },
+        players: maybe_gather!(
+            gather_settings.players,
+            client.get_server_players(&engine, protocol)
+        ),
+        rules: maybe_gather!(
+            gather_settings.rules,
+            client.get_server_rules(&engine, protocol)
+        ),
     })
 }

crates/lib/src/protocols/valve/types.rs

@@ -1,6 +1,6 @@
 use std::collections::HashMap;
 
-use crate::protocols::types::{CommonPlayer, CommonResponse, ExtraRequestSettings, GenericPlayer};
+use crate::protocols::types::{CommonPlayer, CommonResponse, ExtraRequestSettings, GatherToggle, GenericPlayer};
 use crate::GDErrorKind::UnknownEnumCast;
 use crate::GDResult;
 use crate::{buffer::Buffer, protocols::GenericResponse};
@@ -283,17 +283,18 @@ impl Engine {
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct GatheringSettings {
-    pub players: bool,
-    pub rules: bool,
+    pub players: GatherToggle,
+    pub rules: GatherToggle,
     pub check_app_id: bool,
 }
 
 impl GatheringSettings {
-    /// Default values are true for both the players and the rules.
+    /// Default values are try to gather but don't fail on timeout for both
+    /// players and rules.
     pub const fn default() -> Self {
         Self {
-            players: true,
-            rules: true,
+            players: GatherToggle::Try,
+            rules: GatherToggle::Try,
             check_app_id: true,
         }
     }