Configurable Hash Algorithm and Parameters for Consistent Hash Parent Selection

configs/records.yaml.default.in

@@ -130,6 +130,7 @@ records:
 ##############################################################################
     parent_proxy:
       retry_time: 300
+      consistent_hash_algorithm: siphash24
 
 ##############################################################################
 # Security. Docs:

configs/strategies.schema.json

@@ -157,6 +157,29 @@
                     "url"
                   ]
                 },
+                "hash_algorithm": {
+                  "type": "string",
+                  "description": "when using consistent_hash, this specifies the hash algorithm to use",
+                  "enum": [
+                    "siphash24",
+                    "siphash13"
+                  ]
+                },
+                "hash_seed0": {
+                  "type": "integer",
+                  "description": "when using consistent_hash, this specifies the first 64 bits of the hash seed (decimal integer)",
+                  "minimum": 0
+                },
+                "hash_seed1": {
+                  "type": "integer",
+                  "description": "when using consistent_hash, this specifies the second 64 bits of the hash seed (decimal integer)",
+                  "minimum": 0
+                },
+                "hash_replicas": {
+                  "type": "integer",
+                  "description": "when using consistent_hash, this specifies the number of virtual nodes (replicas) per host",
+                  "minimum": 1
+                },
                 "go_direct": {
                     "type": "boolean",
                     "description": "wether, true/false, users of the strategy may bypass parents and go directly to the origin"

doc/admin-guide/files/parent.config.en.rst

@@ -278,6 +278,12 @@ The following list shows the possible actions and their allowed values.
        The other traffic is unaffected. Once the downed parent becomes
        available, the traffic distribution returns to the pre-down
        state.
+
+       The hash algorithm used for consistent hashing can be configured via
+       :ts:cv:`proxy.config.http.parent_proxy.consistent_hash_algorithm`. Available
+       algorithms are ``siphash24`` (default) and ``siphash13`` (faster).
+       See the records.yaml documentation for details.
+
     - ``latched`` - The first parent in the list is marked as primary and is
       always chosen until connection errors cause it to be marked down.  When
       this occurs the next parent in the list then becomes primary.  The primary
@@ -318,6 +324,62 @@ The following list shows the possible actions and their allowed values.
 
   -  ``false`` - The default.  Do not ignore the host status.
 
+.. _parent-config-format-hash-algorithm:
+
+``hash_algorithm``
+    When using ``round_robin=consistent_hash``, this specifies the hash algorithm to use
+    for this specific rule, overriding the global default set in :ts:cv:`proxy.config.http.parent_proxy.consistent_hash_algorithm`.
+
+    Allowed values:
+
+    - ``siphash24`` - SipHash-2-4 (default). Cryptographically strong, DoS-resistant.
+    - ``siphash13`` - SipHash-1-3. ~50% faster than SipHash-2-4, still DoS-resistant.
+
+    Example::
+
+        dest_domain=. parent="p1.x.com:80,p2.x.com:80" round_robin=consistent_hash hash_algorithm=siphash13
+
+.. _parent-config-format-hash-seed0:
+
+``hash_seed0``
+    When using ``round_robin=consistent_hash``, this specifies the first 64 bits of the hash seed (key).
+
+    - For SipHash algorithms, this is the first half of the 128-bit cryptographic key (k0)
+    - For future 64-bit algorithms, this will be the full seed value
+
+    Value must be specified as a decimal integer (e.g. ``12345678901234567``). Default is ``0``.
+
+    Example::
+
+        dest_domain=. parent="p1.x.com:80,p2.x.com:80" round_robin=consistent_hash hash_seed0=1234567890
+
+.. _parent-config-format-hash-seed1:
+
+``hash_seed1``
+    When using ``round_robin=consistent_hash``, this specifies the second 64 bits of the hash seed (key).
+
+    - For SipHash algorithms, this is the second half of the 128-bit cryptographic key (k1)
+    - For future 64-bit algorithms, this value is ignored
+
+    Value must be specified as a decimal integer (e.g. ``9876543210987654321``). Default is ``0``.
+
+    Example::
+
+        dest_domain=. parent="p1.x.com:80,p2.x.com:80" round_robin=consistent_hash hash_seed0=1234567890 hash_seed1=9876543210
+
+.. _parent-config-format-hash-replicas:
+
+``hash_replicas``
+    When using ``round_robin=consistent_hash``, this specifies the number of virtual nodes (replicas)
+    per parent host on the consistent hash ring.
+
+    Increasing the replica count improves the distribution of requests across parent proxies but uses
+    more memory. Must be greater than 0. Default is ``1024``.
+
+    Example::
+
+        dest_domain=. parent="p1.x.com:80,p2.x.com:80" round_robin=consistent_hash hash_replicas=2048
+
 Examples
 ========
 

doc/admin-guide/files/records.yaml.en.rst

@@ -1471,6 +1471,63 @@ Parent Proxy Configuration
    ``2`` Mark the host down. This is the default.
    ===== ======================================================================
 
+.. ts:cv:: CONFIG proxy.config.http.parent_proxy.consistent_hash_algorithm STRING siphash24
+
+   Selects the hash algorithm used for consistent hash parent selection. This setting
+   only affects parent selection when ``round_robin=consistent_hash`` is configured in
+   :file:`parent.config`. The hash algorithm determines how requests are distributed
+   across parent proxies.
+
+   ============== ================================================================================
+   Value          Description
+   ============== ================================================================================
+   ``siphash24``  SipHash-2-4 (default). Cryptographically strong, DoS-resistant hash function.
+   ``siphash13``  SipHash-1-3. ~50% faster than SipHash-2-4, still DoS-resistant.
+   ============== ================================================================================
+
+   .. warning::
+
+      Changing this setting will cause requests to be redistributed differently across
+      parent proxies. This can lead to cache churn and increased origin load during the
+      transition period. Plan the migration carefully and consider doing it during
+      low-traffic periods.
+
+.. ts:cv:: CONFIG proxy.config.http.parent_proxy.consistent_hash_seed0 INT 0
+
+   The first 64 bits of the hash seed (key) for consistent hash parent selection.
+   This setting only affects parent selection when ``round_robin=consistent_hash`` is configured.
+
+   - For SipHash algorithms, this forms the first half of the 128-bit cryptographic key (k0)
+   - For future 64-bit hash algorithms (like XXH3), this is the full seed value
+
+   The value must be specified as a decimal integer (e.g. ``12345678901234567``). Default is ``0``.
+   Per-rule configuration is available in :file:`parent.config` using ``hash_seed0=<value>``.
+   Per-strategy configuration is available in :file:`strategies.yaml` using ``hash_seed0: <value>``.
+
+.. ts:cv:: CONFIG proxy.config.http.parent_proxy.consistent_hash_seed1 INT 0
+
+   The second 64 bits of the hash seed (key) for consistent hash parent selection.
+   This setting only affects parent selection when ``round_robin=consistent_hash`` is configured.
+
+   - For SipHash algorithms, this forms the second half of the 128-bit cryptographic key (k1)
+   - For future 64-bit hash algorithms, this value is ignored
+
+   The value must be specified as a decimal integer (e.g. ``9876543210987654321``). Default is ``0``.
+   Per-rule configuration is available in :file:`parent.config` using ``hash_seed1=<value>``.
+   Per-strategy configuration is available in :file:`strategies.yaml` using ``hash_seed1: <value>``.
+
+.. ts:cv:: CONFIG proxy.config.http.parent_proxy.consistent_hash_replicas INT 1024
+
+   The number of virtual nodes (replicas) per parent host on the consistent hash ring.
+   This setting only affects parent selection when ``round_robin=consistent_hash`` is configured.
+
+   Increasing the replica count improves the distribution of requests across parent proxies
+   but uses more memory. The default value of 1024 provides good distribution in most scenarios.
+
+   Must be greater than 0. Default is ``1024``.
+   Per-rule configuration is available in :file:`parent.config` using ``hash_replicas=<value>``.
+   Per-strategy configuration is available in :file:`strategies.yaml` using ``hash_replicas: <value>``.
+
 .. ts:cv:: CONFIG proxy.config.http.parent_proxy.enable_parent_timeout_markdowns INT 0
    :reloadable:
    :overridable:

doc/admin-guide/files/strategies.yaml.en.rst

@@ -201,6 +201,62 @@ Each **strategy** in the list may using the following parameters:
    #. **parent**: Use the parent URL as set via the API :cpp:func:`TSHttpTxnParentSelectionUrlSet`.
       This again is likely set via an existing plugin such as the **cachekey** plugin.
 
+- **hash_algorithm**: The hash algorithm used by the **consistent_hash** policy. This parameter allows
+  per-strategy selection of the hash algorithm. If not specified, defaults to **siphash24** (or the value
+  set in :ts:cv:`proxy.config.http.parent_proxy.consistent_hash_algorithm`). Use one of:
+
+   #. **siphash24**: (**default**) SipHash-2-4. Cryptographically strong, DoS-resistant hash function.
+   #. **siphash13**: SipHash-1-3. ~50% faster than SipHash-2-4, still DoS-resistant.
+
+  Example:
+
+  .. code-block:: yaml
+
+     policy: consistent_hash
+     hash_algorithm: siphash13
+
+- **hash_seed0**: The first 64 bits of the hash seed (key) for the **consistent_hash** policy.
+
+  - For SipHash algorithms, this forms the first half of the 128-bit cryptographic key (k0)
+  - For future 64-bit hash algorithms, this is the full seed value
+
+  Value must be specified as a decimal integer. Default is **0**.
+
+  Example:
+
+  .. code-block:: yaml
+
+     policy: consistent_hash
+     hash_seed0: 12345678901234567
+
+- **hash_seed1**: The second 64 bits of the hash seed (key) for the **consistent_hash** policy.
+
+  - For SipHash algorithms, this forms the second half of the 128-bit cryptographic key (k1)
+  - For future 64-bit hash algorithms, this value is ignored
+
+  Value must be specified as a decimal integer. Default is **0**.
+
+  Example:
+
+  .. code-block:: yaml
+
+     policy: consistent_hash
+     hash_seed0: 12345678901234567
+     hash_seed1: 9876543210987654321
+
+- **hash_replicas**: The number of virtual nodes (replicas) per host on the consistent hash ring for
+  the **consistent_hash** policy.
+
+  Increasing the replica count improves the distribution of requests across hosts but uses more memory.
+  Must be greater than 0. Default is **1024**.
+
+  Example:
+
+  .. code-block:: yaml
+
+     policy: consistent_hash
+     hash_replicas: 2048
+
 - **go_direct**: A boolean value indicating whether a transaction may bypass proxies and go direct to the origin. Defaults to **true**
 - **parent_is_proxy**: A boolean value which indicates if the groups of hosts are proxy caches or origins.  **true** (default) means all the hosts used in the remap are |TS| caches.  **false** means the hosts are origins that the next hop strategies may use for load balancing and/or failover.
 - **cache_peer_result**: A boolean value that is only used when the **policy** is 'consistent_hash' and a **peering_ring** mode is used for the strategy. When set to true, the default, all responses from upstream and peer endpoints are allowed to be cached.  Setting this to false will disable caching responses received from a peer host. Only responses from upstream origins or parents will be cached for this strategy.

include/proxy/ParentConsistentHash.h

@@ -38,14 +38,17 @@
 //
 class ParentConsistentHash : public ParentSelectionStrategy
 {
-  // there are two hashes PRIMARY parents
-  // and SECONDARY parents.
-  ATSHash64Sip24                     hash[2];
+  std::unique_ptr<ATSHash64>         hash[2];
   std::unique_ptr<ATSConsistentHash> chash[2];
   pRecord                           *parents[2];
   bool                               foundParents[2][MAX_PARENTS];
   bool                               ignore_query;
   int                                secondary_mode;
+  ParentHashAlgorithm                selected_algorithm;
+  uint64_t                           hash_seed0;
+  uint64_t                           hash_seed1;
+
+  std::unique_ptr<ATSHash64> createHashInstance(ParentHashAlgorithm algo, uint64_t seed0, uint64_t seed1);
 
 public:
   static const int PRIMARY   = 0;

include/proxy/ParentSelection.h

@@ -73,6 +73,8 @@ enum class ParentRetry_t {
   BOTH = 3
 };
 
+enum class ParentHashAlgorithm { SIPHASH24 = 0, SIPHASH13 };
+
 struct UnavailableServerResponseCodes {
   UnavailableServerResponseCodes(char *val);
   ~UnavailableServerResponseCodes(){};
@@ -163,6 +165,10 @@ class ParentRecord : public ControlBase
   int                             max_unavailable_server_retries     = 1;
   int                             secondary_mode                     = 1;
   bool                            ignore_self_detect                 = false;
+  ParentHashAlgorithm             consistent_hash_algorithm          = ParentHashAlgorithm::SIPHASH24;
+  uint64_t                        consistent_hash_seed0              = 0;
+  uint64_t                        consistent_hash_seed1              = 0;
+  int consistent_hash_replicas = 1024; // Number of virtual nodes per host (int to match ATSConsistentHash constructor)
 };
 
 // If the parent was set by the external customer api,

include/proxy/http/remap/NextHopConsistentHash.h

@@ -46,8 +46,12 @@ class NextHopConsistentHash : public NextHopSelectionStrategy
   uint64_t getHashKey(uint64_t sm_id, const HttpRequestData &hrdata, ATSHash64 *h);
 
 public:
-  NHHashKeyType hash_key = NHHashKeyType::PATH_HASH_KEY;
-  NHHashUrlType hash_url = NHHashUrlType::REQUEST;
+  NHHashKeyType hash_key       = NHHashKeyType::PATH_HASH_KEY;
+  NHHashUrlType hash_url       = NHHashUrlType::REQUEST;
+  std::string   hash_algorithm = "siphash24"; // Default hash algorithm name
+  uint64_t      hash_seed0     = 0;           // First 64 bits of hash seed
+  uint64_t      hash_seed1     = 0;           // Second 64 bits of hash seed
+  int           hash_replicas  = 1024;        // Number of virtual nodes per host (int to match ATSConsistentHash constructor)
 
   NextHopConsistentHash() = delete;
   NextHopConsistentHash(const std::string_view name, const NHPolicyType &policy, ts::Yaml::Map &n);