[MERGE] Stage changes from mulitiple PRs

  - [x] Closes #205
  - [x] Closes #213
  - [x] Closes #317

 * Superceeds #372
 * Superceeds #373

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

- **New Features**
  - Added user-facing warnings to guide correct usage when joining multicast groups, including suggestions and examples for better usage patterns.
- **Improvements**
  - Enhanced validation of input parameters when joining multicast groups, with clearer feedback for invalid or suboptimal configurations.
  - Improved consistency in default binding behavior for multicast group operations.
- **Documentation**
  - Corrected typographical errors and improved phrasing in the FAQ documentation for clarity and accuracy.
  - Introduced enhanced URL validation and sanitization for documentation links.
  - Improved handling of external links and intersphinx mappings to ensure only secure and allowed URLs are used in documentation.
- **Tests**
  - Added new test suite to verify URL sanitization functionality.
  - Extended spelling checks with additional typo corrections.
  - Included optional extra tests to enhance security and coverage.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: reactive-firewall

docs/FAQ.md

@@ -199,9 +199,9 @@ From the
 [documentation](https://github.com/reactive-firewall/multicast/blob/v1.4/multicast/__init__.py#L155):
 > Arbitrary port to use by default, though any dynamic and free port would work.
 
-While developers and network admistrators must consider other factors in the real world deployment,
+While developers and network administrators must consider other factors in real-world deployments,
 it is fair to say any free port in the dynamic or "ephemeral" port range of `49152`-`65535` should
-work so far as this Multicast module is concerned.
+work as far as this Multicast module is concerned.
 
 * For `SAY` the port refers to the destination port.
 * for `RECV` and `HEAR` the port refers to the port to listen on.
@@ -231,7 +231,8 @@ work so far as this Multicast module is concerned.
 * Typically, the documentation will be automatically built by CI/CD and posted to the official
   documentation site.
 
-* However if one still wishes to manually build the documentation, there is a make target for this:
+* However, if one still wishes to build the documentation manually, there is a `make` target
+  specifically for this:
 
   ```bash
   make build-docs

docs/conf.py

@@ -46,6 +46,8 @@
 sys.path.insert(0, os.path.abspath(".."))
 from docs.utils import _validate_git_ref  # noqa
 from docs.utils import slugify_header  # noqa
+from docs.utils import sanitize_url  # noqa
+from docs.utils import sanitize_intersphinx_mapping  # noqa
 
 # Define the branch reference for linkcode_resolve
 DOCS_BUILD_REF: str = _validate_git_ref(os.environ.get("DOCS_BUILD_REF", "stable"))
@@ -309,7 +311,7 @@
 myst_gfm_only = False
 
 myst_html_meta = {
-	"github_url": f"https://github.com/reactive-firewall/{project}"
+	"github_url": sanitize_url(f"https://github.com/reactive-firewall/{project}"),
 }
 
 # For GH-style admonitions to MyST conversion
@@ -419,7 +421,7 @@
 
 # -- Link resolver -------------------------------------------------------------
 
-linkcode_url_prefix: str = f"https://github.com/reactive-firewall/{project}"
+linkcode_url_prefix: str = sanitize_url(f"https://github.com/reactive-firewall/{project}")
 
 suffix = "/issues/%s"
 
@@ -432,9 +434,11 @@
 
 # try to link with official python3 documentation.
 # see https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html for more
-intersphinx_mapping = {
-	"python": ("https://docs.python.org/3", (None, "python-inv.txt"))
-}
+intersphinx_mapping = sanitize_intersphinx_mapping(
+	{
+		"python": ("https://docs.python.org/3", (None, "python-inv.txt")),
+	},
+)
 
 
 def linkcode_resolve(domain, info):
@@ -450,4 +454,4 @@ def linkcode_resolve(domain, info):
 		theResult = theResult.replace("/multicast.py", "/multicast/__init__.py")
 	if "/tests.py" in theResult:
 		theResult = theResult.replace("/tests.py", "/tests/__init__.py")
-	return quote(theResult, safe=":/-._")
+	return sanitize_url(quote(theResult, safe=":/-._"))

docs/utils.py

@@ -17,6 +17,7 @@
 # limitations under the License.
 
 import re
+from urllib.parse import urlparse, urlunparse, quote
 
 
 # Git reference validation pattern
@@ -26,6 +27,110 @@
 GIT_REF_PATTERN = r'^[a-zA-Z0-9][a-zA-Z0-9_\-./]*$'
 
 
+# URL allowed scheme list
+# Enforces:
+# - URLs Must start with https
+URL_ALLOWED_SCHEMES = frozenset({"https"})
+
+
+# URL allowed domain list
+# Enforces:
+# - URLs Must belong to one of these domains
+URL_ALLOWED_NETLOCS = frozenset({"github.com", "readthedocs.com", "docs.python.org"})
+
+
+# Maximum allowed URL length
+MAX_URL_LENGTH = 2048  # Common browser limit
+"""Maximum allowed length for URL validation.
+
+Should be large enough for most URLs but no larger than common browser limits.
+
+Unit-Testing:
+
+	First set up test fixtures by importing utils.
+
+		>>> import docs.utils as _utils
+		>>>
+
+		>>> _utils.MAX_URL_LENGTH is not None
+		True
+		>>> type(_utils.MAX_URL_LENGTH) is type(int())
+		True
+		>>> _utils.MAX_URL_LENGTH > 0
+		True
+		>>> _utils.MAX_URL_LENGTH >= 256
+		True
+		>>> _utils.MAX_URL_LENGTH <= 2048
+		True
+		>>>
+
+"""
+
+
+# Error messages for URL validation
+INVALID_LENGTH_ERROR = f"URL exceeds maximum length of {MAX_URL_LENGTH} characters."
+"""Length error message for URL validation.
+
+Unit-Testing:
+
+	First set up test fixtures by importing utils.
+
+		>>> import docs.utils as _utils
+		>>>
+
+		>>> _utils.INVALID_LENGTH_ERROR is not None
+		True
+		>>> type(_utils.INVALID_LENGTH_ERROR) is type(str())
+		True
+		>>> len(_utils.INVALID_LENGTH_ERROR) > 0
+		True
+		>>>
+
+"""
+
+
+INVALID_SCHEME_ERROR = "Invalid URL scheme. Only 'https' is allowed."
+"""Scheme error message for URL validation.
+
+Unit-Testing:
+
+	First set up test fixtures by importing utils.
+
+		>>> import docs.utils as _utils
+		>>>
+
+		>>> _utils.INVALID_SCHEME_ERROR is not None
+		True
+		>>> type(_utils.INVALID_SCHEME_ERROR) is type(str())
+		True
+		>>> len(_utils.INVALID_SCHEME_ERROR) > 0
+		True
+		>>>
+
+"""
+
+
+INVALID_DOMAIN_ERROR = f"Invalid or untrusted domain. Only {URL_ALLOWED_NETLOCS} are allowed."
+"""Domain error message for URL validation.
+
+Unit-Testing:
+
+	First set up test fixtures by importing utils.
+
+		>>> import docs.utils as _utils
+		>>>
+
+		>>> _utils.INVALID_DOMAIN_ERROR is not None
+		True
+		>>> type(_utils.INVALID_DOMAIN_ERROR) is type(str())
+		True
+		>>> len(_utils.INVALID_DOMAIN_ERROR) > 0
+		True
+		>>>
+
+"""
+
+
 def _validate_git_ref(ref: str) -> str:
 	"""
 	Validate if the provided string is a valid Git reference.
@@ -126,3 +231,92 @@ def slugify_header(s: str) -> str:
 	text = re.sub(r'[^\w\- ]', "", s).strip().lower()
 	# Then replace consecutive spaces or dashes with a single dash
 	return re.sub(r'[-\s]+', "-", text)
+
+
+def sanitize_url(url: str) -> str:
+	"""
+	Sanitize and validate a URL according to allowed schemes and domains.
+
+	This function validates that the URL uses an allowed scheme (https) and points
+	to a trusted domain, then safely encodes its path and query components.
+
+	Args:
+		url (str) -- The URL to sanitize.
+
+	Returns:
+		str -- The sanitized URL.
+
+	Raises:
+		ValueError -- If the URL has an invalid scheme or points to an untrusted domain.
+
+
+	Unit-Testing:
+
+		Testcase 0: First set up test fixtures by importing utils.
+
+		>>> import docs.utils as _utils
+		>>>
+
+		Testcase 1: Basic URL with spaces and special characters.
+
+		>>> url_fxtr = "https://github.com/user/Hello World!"
+		>>> _utils.sanitize_url(url_fxtr)
+		'https://github.com/user/Hello%20World%21'
+		>>>
+
+	"""
+	# Validate length
+	if len(url) > MAX_URL_LENGTH:
+		raise ValueError(INVALID_LENGTH_ERROR)
+	parsed_url = urlparse(url)
+	# Validate scheme
+	if parsed_url.scheme not in URL_ALLOWED_SCHEMES:
+		raise ValueError(INVALID_SCHEME_ERROR)
+	# Validate netloc
+	if parsed_url.netloc not in URL_ALLOWED_NETLOCS:
+		raise ValueError(INVALID_DOMAIN_ERROR)
+	# Sanitize path and query - using the safe parameter to preserve URL structure
+	sanitized_path = quote(parsed_url.path, safe="/=")
+	sanitized_query = quote(parsed_url.query, safe="&=")
+	# Reconstruct the sanitized URL
+	return urlunparse((
+		parsed_url.scheme,
+		parsed_url.netloc,
+		sanitized_path,
+		parsed_url.params,
+		sanitized_query,
+		parsed_url.fragment,
+	))
+
+
+def sanitize_intersphinx_mapping(mapping: dict) -> dict:
+	"""
+	Sanitize URLs in an intersphinx mapping dictionary.
+
+	This function applies URL sanitization to each URL in the mapping while
+	preserving the associated extra values.
+
+	Args:
+		mapping (dict) -- A dictionary mapping names to tuples of (url, extra_value).
+
+	Returns:
+		dict -- A dictionary with the same structure but with sanitized URLs.
+
+	Unit-Testing:
+
+		Testcase 1: Basic intersphinx mapping.
+
+		>>> mapping = {'python': ('https://docs.python.org/3', None)}
+		>>> sanitize_intersphinx_mapping(mapping)
+		{'python': ('https://docs.python.org/3', None)}
+
+		Testcase 2: Mapping with URL containing special characters.
+
+		>>> mapping = {'project': ('https://github.com/user/project with spaces', None)}
+		>>> result = sanitize_intersphinx_mapping(mapping)
+		>>> result['project'][0]
+		'https://github.com/user/project%20with%20spaces'
+		>>>
+
+	"""
+	return {key: (sanitize_url(url), extra_value) for key, (url, extra_value) in mapping.items()}