apache · traeak · Oct 21, 2025 · Nov 17, 2025
diff --git a/...s/TSHttpTxnNextHopNamedStrategyGet.en.rst → ...tions/TSHttpTxnNextHopStrategyFind.en.rst b/...s/TSHttpTxnNextHopNamedStrategyGet.en.rst → ...tions/TSHttpTxnNextHopStrategyFind.en.rst
@@ -18,8 +18,8 @@
 
 .. default-domain:: cpp
 
-TSHttpTxnNextHopNamedStrategyGet
-********************************
+TSHttpTxnNextHopStrategyFind
+****************************
 
 Synopsis
 ========
@@ -28,7 +28,7 @@ Synopsis
 
     #include <ts/ts.h>
 
-.. function:: void const* TSHttpTxnNextHopNamedStrategyGet(TSHttpTxn txnp, const char *name)
+.. function:: TSStrategy TSHttpTxnNextHopStrategyFind(TSHttpTxn txnp, const char *name)
 
 Description
 ===========

diff --git a/doc/developer-guide/api/functions/TSHttpTxnNextHopStrategyGet.en.rst b/doc/developer-guide/api/functions/TSHttpTxnNextHopStrategyGet.en.rst
@@ -28,7 +28,7 @@ Synopsis
 
     #include <ts/ts.h>
 
-.. function:: void const* TSHttpTxnNextHopStrategyGet(TSHttpTxn txnp)
+.. function:: TSStrategy TSHttpTxnNextHopStrategyGet(TSHttpTxn txnp)
 
 Description
 ===========

diff --git a/doc/developer-guide/api/functions/TSHttpTxnNextHopStrategySet.en.rst b/doc/developer-guide/api/functions/TSHttpTxnNextHopStrategySet.en.rst
@@ -28,7 +28,7 @@ Synopsis
 
     #include <ts/ts.h>
 
-.. function:: void TSHttpTxnNextHopStrategySet(TSHttpTxn txnp, void const* strategy)
+.. function:: void TSHttpTxnNextHopStrategySet(TSHttpTxn txnp, TSStrategy strategy)
 
 Description
 ===========
@@ -39,7 +39,7 @@ nullptr to indicate that parent.config will be used instead.
 
 Plugins can get a strategy by name by calling
 :func:`TSHttpTxnNextHopStrategyGet` to get the current transaction's
-active strategy or :func:`TSHttpTxnNextHopNamedStrategyGet` to
+active strategy or :func:`TSHttpTxnNextHopStrategyFind` to
 look up a strategy by name using the transaction's pointer to the
 NextHopStrategyFactory strategy database.
 
@@ -53,4 +53,4 @@ NextHopStrategyFactory strategy database.
 See Also
 ========
 
-:func:`TSHttpTxnNextHopStrategyGet`, :func:`TSHttpTxnNextHopNamedStrategyGet`.
+:func:`TSHttpTxnNextHopStrategyGet`, :func:`TSHttpTxnNextHopStrategyFind`.
diff --git a/...tions/TSHttpNextHopStrategyNameGet.en.rst → ...functions/TSNextHopStrategyNameGet.en.rst b/...tions/TSHttpNextHopStrategyNameGet.en.rst → ...functions/TSNextHopStrategyNameGet.en.rst
@@ -18,8 +18,8 @@
 
 .. default-domain:: cpp
 
-TSHttpNextHopStrategyNameGet
-****************************
+TSNextHopStrategyNameGet
+************************
 
 Synopsis
 ========
@@ -28,13 +28,13 @@ Synopsis
 
     #include <ts/ts.h>
 
-.. function:: char const* TSHttpNextHopStrategyNameGet(void const* strategy)
+.. function:: char const* TSNextHopStrategyNameGet(TSStrategy strategy)
 
 Description
 ===========
 
-Gets the name associated with the provided strategy.
-This may be nullptr indicating that parent.config is in use.
+Gets the name associated with the provided strategy pointer.
+This may be nullptr which indicates that parent.config is in use.
 
 .. note::
 

diff --git a/doc/developer-guide/api/functions/TSRemapNextHopStrategyFind.en.rst b/doc/developer-guide/api/functions/TSRemapNextHopStrategyFind.en.rst
@@ -0,0 +1,52 @@
+.. Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed
+   with this work for additional information regarding copyright
+   ownership.  The ASF licenses this file to you under the Apache
+   License, Version 2.0 (the "License"); you may not use this file
+   except in compliance with the License.  You may obtain a copy of
+   the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied.  See the License for the specific language governing
+   permissions and limitations under the License.
+
+.. include:: ../../../common.defs
+
+.. default-domain:: cpp
+
+TSRemapNextHopStrategyFind
+**************************
+
+Synopsis
+========
+
+.. code-block:: cpp
+
+    #include <ts/ts.h>
+
+.. function:: TSStrategy TSRemapNextHopStrategyFind(const char *name)
+
+Description
+===========
+
+Gets a pointer to the specified :arg:`name` NextHopSelectionStrategy.
+This may be nullptr indicating that no strategy exists with the given name.
+
+This function may ONLY be called during TSRemapNewInstance.
+The resulting strategy pointer is valid for all subsequent transactions.
+
+.. note::
+
+   This returned pointer must not be freed and the contents must not
+   be changed.
+   Strategy pointers held by plugins will become invalid when ATS
+   configs are reloaded and should be reset with :func:`TSRemapNewInstance`
+
+See Also
+========
+
+:func:`TSRemapNextHopStrategySet`
diff --git a/doc/developer-guide/api/functions/TSRemapNextHopStrategyGet.en.rst b/doc/developer-guide/api/functions/TSRemapNextHopStrategyGet.en.rst
@@ -0,0 +1,52 @@
+.. Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed
+   with this work for additional information regarding copyright
+   ownership.  The ASF licenses this file to you under the Apache
+   License, Version 2.0 (the "License"); you may not use this file
+   except in compliance with the License.  You may obtain a copy of
+   the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied.  See the License for the specific language governing
+   permissions and limitations under the License.
+
+.. include:: ../../../common.defs
+
+.. default-domain:: cpp
+
+TSRemapNextHopStrategyGet
+*************************
+
+Synopsis
+========
+
+.. code-block:: cpp
+
+    #include <ts/ts.h>
+
+.. function:: TSStrategy TSRemapNextHopStrategyGet()
+
+Description
+===========
+
+Gets a pointer to the current remap rule being loaded.
+This may be nullptr indicating that parent.config is in use.
+
+This function may ONLY be called during TSRemapNewInstance.
+The resulting strategy pointer is valid for all subsequent transactions.
+
+.. note::
+
+   This strategy pointer must not be freed and the contents must not
+   be changed.
+   Strategy pointers held by plugins will become invalid when ATS
+   configs are reloaded and should be reset with :func:`TSRemapNewInstance`
+
+See Also
+========
+
+:func:`TSRemapNextHopStrategySet`
diff --git a/doc/developer-guide/api/functions/TSRemapNextHopStrategySet.en.rst b/doc/developer-guide/api/functions/TSRemapNextHopStrategySet.en.rst
@@ -0,0 +1,56 @@
+.. Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed
+   with this work for additional information regarding copyright
+   ownership.  The ASF licenses this file to you under the Apache
+   License, Version 2.0 (the "License"); you may not use this file
+   except in compliance with the License.  You may obtain a copy of
+   the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied.  See the License for the specific language governing
+   permissions and limitations under the License.
+
+.. include:: ../../../common.defs
+
+.. default-domain:: cpp
+
+TSRemapNextHopNameGet
+***********************
+
+Synopsis
+========
+
+.. code-block:: cpp
+
+    #include <ts/ts.h>
+
+.. function:: void TSRemapNextHopStrategySet(TSStrategy strategy)
+
+Description
+===========
+
+Sets the next hop strategy for the currently loading remap rule.
+This :arg:`strategy` pointer must be a valid strategy and can be
+nullptr to indicate that parent.config will be used instead.
+
+Plugins can get a strategy by name by calling
+:func:`TSRemapNextHopStrategyGet` to get the current transaction's active
+strategy or :func:`TSRemapNextHopStrategyFind` to look up a strategy by
+name using the loading remap rule's pointer to the NextHopStrategyFactory
+strategy database.
+
+.. note::
+
+   This strategy pointer must not be freed and the contents must not
+   be changed.
+   Strategy pointers held by plugins will become invalid when ATS
+   configs are reloaded and should be reset with :func:`TSRemapNewInstance`
+
+See Also
+========
+
+:func:`TSRemapNextHopStrategyGet`, :func:`TSRemapNextHopStrategyFind`.
diff --git a/doc/developer-guide/api/functions/TSTypes.en.rst b/doc/developer-guide/api/functions/TSTypes.en.rst
@@ -335,6 +335,8 @@ more widely. Those are described on this page.
 .. type:: TSFetchSM
 .. type:: TSFetchEvent
 
+.. type:: TSStrategy
+
 .. type:: TSHttpPriority
 
    The abstract type of the various HTTP priority implementations.

diff --git a/include/proxy/http/remap/UrlMapping.h b/include/proxy/http/remap/UrlMapping.h
@@ -36,6 +36,7 @@
 #include "tscore/List.h"
 
 class NextHopSelectionStrategy;
+class NextHopStrategyFactory;
 
 /**
  * Used to store http referrer strings (and/or regexp)
@@ -112,9 +113,15 @@ class url_mapping
   bool              ip_allow_check_enabled_p = false;
   acl_filter_rule  *filter                   = nullptr; // acl filtering (linked list of rules)
   LINK(url_mapping, link);                              // For use with the main Queue linked list holding all the mapping
-  NextHopSelectionStrategy *strategy = nullptr;
-  std::string               remapKey;
-  std::atomic<uint64_t>     _hitCount = 0; // counter can overflow
+
+  NextHopSelectionStrategy *strategy        = nullptr;
+  NextHopStrategyFactory   *strategyFactory = nullptr;
+
+  std::string           remapKey;
+  std::atomic<uint64_t> _hitCount = 0; // counter can overflow
+
+  // For use with the strategies API to be called during TSRemapNewInstance.
+  static inline url_mapping *instance = nullptr;
 
   int
   getRank() const

diff --git a/include/ts/apidefs.h.in b/include/ts/apidefs.h.in
@@ -1080,6 +1080,7 @@ using TSHostLookupResult = struct tsapi_hostlookupresult *;
 using TSAIOCallback      = struct tsapi_aiocallback *;
 using TSAcceptor         = struct tsapi_net_accept *;
 using TSRemapPluginInfo  = struct tsapi_remap_plugin_info *;
+using TSStrategy         = struct tsapi_strategy *;
 
 using TSFetchSM = struct tsapi_fetchsm *;
 

diff --git a/include/ts/ts.h b/include/ts/ts.h
@@ -1579,18 +1579,30 @@ void TSHttpTxnErrorBodySet(TSHttpTxn txnp, char *buf, size_t buflength, char *mi
 */
 char *TSHttpTxnErrorBodyGet(TSHttpTxn txnp, size_t *buflength, char **mimetype);
 
+/**
+    Retrieves a handle to the named strategy in the strategy table.
+    Returns nullptr if no strategy is found.
+    This uses the current transaction's state machine to get
+    access to UrlRewrite's NextHopStrategyFactory.
+    It's preferable to retrieve strategies during TSRemapNewInstance.
+
+    @param txnp HTTP transaction which holds the strategy table.
+    @param name of the strategy to look up.
+
+ */
+TSStrategy TSHttpTxnNextHopStrategyFind(TSHttpTxn txnp, const char *name);
+
 /**
     Sets the Transaction's Next Hop Parent Strategy.
-    Calling this after TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK will
-    result in bad behavior.
+    Must be called before parent selection logic is required.
 
     You can get this strategy pointer by calling TSHttpTxnParentStrategyGet().
 
     @param txnp HTTP transaction whose parent strategy to set.
     @param pointer to the given strategy.
 
  */
-void TSHttpTxnNextHopStrategySet(TSHttpTxn txnp, void const *strategy);
+void TSHttpTxnNextHopStrategySet(TSHttpTxn txnp, TSStrategy strategy);
 
 /**
     Retrieves a pointer to the current next hop selection strategy.
@@ -1601,32 +1613,55 @@ void TSHttpTxnNextHopStrategySet(TSHttpTxn txnp, void const *strategy);
     @param txnp HTTP transaction whose next hop strategy to get.
 
  */
-void const *TSHttpTxnNextHopStrategyGet(TSHttpTxn txnp);
+TSStrategy TSHttpTxnNextHopStrategyGet(TSHttpTxn txnp);
 
 /**
     Returns either null pointer or null terminated pointer to name.
-                DO NOT FREE.
+    DO NOT FREE.
 
     This value may be a nullptr due to:
       - parent proxying not enabled
       - no parent selection strategy (using parent.config)
 
-    @param txnp HTTP transaction whose next hop strategy to get.
+    @param pointer to the NextHopStrategy.
 
  */
-char const *TSHttpNextHopStrategyNameGet(void const *strategy);
+char const *TSNextHopStrategyNameGet(TSStrategy strategy);
 
 /**
     Retrieves a pointer to the named strategy in the strategy table.
-    Returns nullptr if no strategy is set.
-    This uses the current transaction's state machine to get
-    access to UrlRewrite's NextHopStrategyFactory.
+    This can only be called during TSRemapNewInstance.
+    DO NOT FREE.
+
+    Returns nullptr if no strategy found.
+    This uses the currently being loaded RemapConfig NextHopStrategyFactory.
 
-    @param txnp HTTP transaction which holds the strategy table.
     @param name of the strategy to look up.
 
  */
-void const *TSHttpTxnNextHopNamedStrategyGet(TSHttpTxn txnp, const char *name);
+TSStrategy TSRemapNextHopStrategyFind(const char *name);
+
+/**
+    Retrieves a pointer to remap rule strategy pointer.
+    This can only be called during TSRemapNewInstance.
+    DO NOT FREE.
+
+    Returns nullptr if no strategy assigned.
+
+ */
+TSStrategy TSRemapNextHopStrategyGet();
+
+/**
+    Sets the remap rule's next hop strategy.
+    This can only be called during TSRemapNewInstance.
+    DO NOT FREE.
+
+    This strategy must be present in the loading NextHopStrategyFactory.
+
+    @param handle to the strategy to set.
+
+ */
+void TSRemapNextHopStrategySet(TSStrategy strategy);
 
 /**
     Sets the parent proxy name and port. The string hostname is copied