improve doc for global proxy

Author: michaeloffner

docs/recipes/global-proxy.md

@@ -32,34 +32,74 @@ this.proxy = {
 };
 ```
 
-### Include
+### Target-Specific Proxy Configuration
 
-You can limit the proxy to specific hosts by defining a list (or array) of hosts it should be used for:
+Lucee provides two mutually exclusive methods to control which hosts use the proxy: **includes** and **excludes**. These options allow you to fine-tune proxy usage based on your application's requirements.
+
+> **Important**: The `includes` and `excludes` options only support exact hostname matches. Wildcards and partial matches are not supported. All hostnames are converted to lowercase for comparison.
+
+#### Using `includes`
+
+The `includes` option specifies a whitelist of hosts that should use the proxy. Any request to a host not in this list will bypass the proxy and connect directly. This is useful when you only need to access specific external services through a proxy.
+
+```lucee
+this.proxy = {
+    server: "myproxy.com",
+    port: 1234,
+    username: "susi",
+    password: "sorglos",
+    includes: "api.example.com,cdn.example.com"
+};
+```
+
+You can also use an array instead of a comma-delimited list:
 
 ```lucee
 this.proxy = {
     server: "myproxy.com",
     port: 1234,
     username: "susi",
     password: "sorglos",
-    includes: "whatever.com,lucee.org"
+    includes: ["api.example.com", "cdn.example.com"]
 };
 ```
 
-### Exclude
+#### Using `excludes`
 
-Or you can do the opposite, defining for which hosts it should not apply:
+The `excludes` option specifies hosts that should bypass the proxy. All other hosts will use the proxy. This is useful when most of your traffic should go through the proxy, but certain hosts should connect directly.
 
 ```lucee
 this.proxy = {
     server: "myproxy.com",
     port: 1234,
     username: "susi",
     password: "sorglos",
-    excludes: ["lucee.org", "whatever.com"]
+    excludes: "internal.example.com,localhost"
 };
 ```
 
+You can also use an array instead of a comma-delimited list:
+
+```lucee
+this.proxy = {
+    server: "myproxy.com",
+    port: 1234,
+    username: "susi",
+    password: "sorglos",
+    excludes: ["internal.example.com", "localhost"]
+};
+```
+
+#### Special Handling for Local Addresses
+
+By default, local addresses (`localhost`, `127.0.0.1`, and `0:0:0:0:0:0:0:1`) are automatically excluded from proxy usage unless explicitly included in the `includes` list. This is a built-in behavior to prevent proxy loops and ensure local connections remain direct.
+
+#### Restrictions
+
+- You cannot use both `includes` and `excludes` in the same proxy configuration. You must choose one approach.
+- If you specify an empty list for either `includes` or `excludes`, it will be treated as if the option was not provided.
+- All hostname comparisons are case-insensitive.
+
 ## Configuring Proxy in .CFConfig.json
 
 In addition to Application.cfc, you can also configure the global proxy in a .CFConfig.json file:
@@ -72,8 +112,8 @@ In addition to Application.cfc, you can also configure the global proxy in a .CF
     "port": 1234,
     "username": "susi",
     "password": "sorglos",
-    "includes": "good.org",
-    "excludes": "bad.com,whatever.com"
+    "includes": "api.example.com,cdn.example.com",
+    "excludes": null
   }
 }
 ```
@@ -87,7 +127,7 @@ Both methods support the following configuration options:
 - **port** - The port number of the proxy server
 - **username** - Optional username for proxy authentication
 - **password** - Optional password for proxy authentication
-- **includes** - Comma-delimited list or array of hosts that should use the proxy
-- **excludes** - Comma-delimited list or array of hosts that should not use the proxy
+- **includes** - Comma-delimited list or array of hosts that should use the proxy (exact match only)
+- **excludes** - Comma-delimited list or array of hosts that should not use the proxy (exact match only)
 
-Note that you cannot use both `includes` and `excludes` at the same time - you must choose one approach.
+Remember that you cannot use both `includes` and `excludes` at the same time - you must choose one approach. If both are provided, the behavior is undefined and may change in future versions.