feat: merge upstream dev branch

- Add Gluetun dynamic VPN-to-HTTP proxy provider
   - Add remote services and authentication system
   - Add country code utilities
   - Add Docker binary detection
   - Update proxy providers

unshackle/core/proxies/surfsharkvpn.py

@@ -44,8 +44,21 @@ class SurfsharkVPN(Proxy):
     def get_proxy(self, query: str) -> Optional[str]:
         """
         Get an HTTP(SSL) proxy URI for a SurfsharkVPN server.
+
+        Supports:
+        - Country code: "us", "ca", "gb"
+        - Country ID: "228"
+        - Specific server: "us-bos" (Boston)
+        - City selection: "us:seattle", "ca:toronto"
         """
         query = query.lower()
+        city = None
+
+        # Check if query includes city specification (e.g., "us:seattle")
+        if ":" in query:
+            query, city = query.split(":", maxsplit=1)
+            city = city.strip()
+
         if re.match(r"^[a-z]{2}\d+$", query):
             # country and surfsharkvpn server id, e.g., au-per, be-anr, us-bos
             hostname = f"{query}.prod.surfshark.com"
@@ -62,13 +75,18 @@ class SurfsharkVPN(Proxy):
                 # SurfsharkVPN doesnt have servers in this region
                 return
 
-            server_mapping = self.server_map.get(country["countryCode"].lower())
+            # Check server_map for pinned servers (can include city)
+            server_map_key = f"{country['countryCode'].lower()}:{city}" if city else country["countryCode"].lower()
+            server_mapping = self.server_map.get(server_map_key) or (
+                self.server_map.get(country["countryCode"].lower()) if not city else None
+            )
+
             if server_mapping:
                 # country was set to a specific server ID in config
                 hostname = f"{country['code'].lower()}{server_mapping}.prod.surfshark.com"
             else:
                 # get the random server ID
-                random_server = self.get_random_server(country["countryCode"])
+                random_server = self.get_random_server(country["countryCode"], city)
                 if not random_server:
                     raise ValueError(
                         f"The SurfsharkVPN Country {query} currently has no random servers. "
@@ -92,18 +110,44 @@ class SurfsharkVPN(Proxy):
             ):
                 return country
 
-    def get_random_server(self, country_id: str):
+    def get_random_server(self, country_id: str, city: Optional[str] = None):
         """
-        Get the list of random Server for a Country.
+        Get a random server for a Country, optionally filtered by city.
 
-        Note: There may not always be more than one recommended server.
+        Args:
+            country_id: The country code (e.g., "US", "CA")
+            city: Optional city name to filter by (case-insensitive)
+
+        Note: The API may include a 'location' field with city information.
+        If not available, this will return any server from the country.
         """
-        country = [x["connectionName"] for x in self.countries if x["countryCode"].lower() == country_id.lower()]
+        servers = [x for x in self.countries if x["countryCode"].lower() == country_id.lower()]
+
+        # Filter by city if specified
+        if city:
+            city_lower = city.lower()
+            # Check if servers have a 'location' field for city filtering
+            city_servers = [
+                x
+                for x in servers
+                if x.get("location", "").lower() == city_lower or x.get("city", "").lower() == city_lower
+            ]
+
+            if city_servers:
+                servers = city_servers
+            else:
+                raise ValueError(
+                    f"No servers found in city '{city}' for country '{country_id}'. "
+                    "Try a different city or check the city name spelling."
+                )
+
+        # Get connection names from filtered servers
+        connection_names = [x["connectionName"] for x in servers]
+
         try:
-            country = random.choice(country)
-            return country
-        except Exception:
-            raise ValueError("Could not get random countrycode from the countries list.")
+            return random.choice(connection_names)
+        except (IndexError, KeyError):
+            raise ValueError(f"Could not get random server for country '{country_id}'.")
 
     @staticmethod
     def get_countries() -> list[dict]: