Clarify the search for a proxy

1 files changed, 18 insertions, 0 deletions

diff --git a/awx/main/utils/proxy.py b/awx/main/utils/proxy.py
index e60155bf42..744c73fed5 100644
--- a/awx/main/utils/proxy.py
+++ b/awx/main/utils/proxy.py
@@ -13,6 +13,24 @@ It is the source data from which request.headers (read-only) is constructed.
 
 
 def is_proxy_in_headers(request: Request, proxy_list: list[str], headers: list[str]) -> bool:
+    """
+    Determine if the request went through at least one proxy in the list.
+    Example:
+    request.environ = {
+        "HTTP_X_FOO": "8.8.8.8, 192.168.2.1",
+        "REMOTE_ADDR": "192.168.2.1",
+        "REMOTE_HOST": "foobar"
+    }
+    proxy_list = ["192.168.2.1"]
+    headers = ["HTTP_X_FOO", "REMOTE_ADDR", "REMOTE_HOST"]
+
+    The above would return True since 192.168.2.1 is a value for the header HTTP_X_FOO
+
+    request: The DRF/Django request. request.environ dict will be used for searching for proxies
+    proxy_list: A list of known and trusted proxies may be ip or hostnames
+    headers: A list of keys for which to consider values that may contain a proxy
+    """
+
     remote_hosts = set()
 
     for header in headers: