From 856610a8215d524a3d7d7292dfe72822661d14c6 Mon Sep 17 00:00:00 2001 From: mmustafasenoglu Date: Tue, 23 Jun 2026 23:33:48 +0300 Subject: [PATCH 1/7] docs: add call condition note for TSUrlHostGet Add a note to the TSUrlHostGet documentation indicating that it should only be called after TS_HTTP_POST_REMAP_HOOK. For earlier hooks like TS_HTTP_READ_REQUEST_HDR_HOOK, TSHttpHdrHostGet should be used instead. Fixes #5742 --- doc/developer-guide/api/functions/TSUrlHostGet.en.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/developer-guide/api/functions/TSUrlHostGet.en.rst b/doc/developer-guide/api/functions/TSUrlHostGet.en.rst index 1497e625c95..f8dbfd659d0 100644 --- a/doc/developer-guide/api/functions/TSUrlHostGet.en.rst +++ b/doc/developer-guide/api/functions/TSUrlHostGet.en.rst @@ -71,6 +71,12 @@ scheme. :arg:`offset` within the marshal buffer :arg:`bufp`. If there is no explicit port number in the URL, zero is returned. + +.. note:: + + :func:`TSUrlHostGet` should only be called after the :data:`TS_HTTP_POST_REMAP_HOOK`. + In the :data:`TS_HTTP_READ_REQUEST_HDR_HOOK` phase, use :func:`TSHttpHdrHostGet` instead. + Return Values ============= From 6976ef6835da0787b3f26e9cc94096c723cfaea3 Mon Sep 17 00:00:00 2001 From: Mustafa Senoglu Date: Wed, 24 Jun 2026 23:05:05 +0300 Subject: [PATCH 2/7] docs: fix unknown interpreted text role data Replace :data: with double backticks for hook names, consistent with the rest of the documentation. Fixes #5742 --- doc/developer-guide/api/functions/TSUrlHostGet.en.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/developer-guide/api/functions/TSUrlHostGet.en.rst b/doc/developer-guide/api/functions/TSUrlHostGet.en.rst index f8dbfd659d0..f7c9c69d7f9 100644 --- a/doc/developer-guide/api/functions/TSUrlHostGet.en.rst +++ b/doc/developer-guide/api/functions/TSUrlHostGet.en.rst @@ -74,8 +74,8 @@ port number in the URL, zero is returned. .. note:: - :func:`TSUrlHostGet` should only be called after the :data:`TS_HTTP_POST_REMAP_HOOK`. - In the :data:`TS_HTTP_READ_REQUEST_HDR_HOOK` phase, use :func:`TSHttpHdrHostGet` instead. + :func:`TSUrlHostGet` should only be called after the ``TS_HTTP_POST_REMAP_HOOK``. + In the ``TS_HTTP_READ_REQUEST_HDR_HOOK`` phase, use :func:`TSHttpHdrHostGet` instead. Return Values ============= From 14c37b603aa124ba0b0ae6f26b3db2d5a317675d Mon Sep 17 00:00:00 2001 From: mmustafasenoglu Date: Fri, 26 Jun 2026 14:43:03 +0300 Subject: [PATCH 3/7] docs: trigger CI for TSUrlHostGet call condition note From 0401ae878d9afffa7607cac2572cc5e8aaa4dbc8 Mon Sep 17 00:00:00 2001 From: mmustafasenoglu Date: Tue, 30 Jun 2026 12:27:56 +0300 Subject: [PATCH 4/7] docs: document TSHttpHdrUrlGet hook availability, fix redirect_1 to use TSHttpHdrHostGet - TSHttpHdrUrlGet: add note that URL components may not be available at early hooks, recommend TSHttpHdrHostGet for reliable host retrieval - TSUrlHostGet: add call condition note (TS_HTTP_POST_REMAP_HOOK onwards) and cross-reference to TSHttpHdrHostGet - TSHttpHdrHostGet: add cross-references to TSHttpHdrUrlGet and TSUrlHostGet - redirect_1: replace TSHttpHdrUrlGet+TSUrlHostGet with TSHttpHdrHostGet which works correctly at TS_HTTP_READ_REQUEST_HDR_HOOK --- .../api/functions/TSHttpHdrHostGet.en.rst | 36 +++++++++++++------ .../api/functions/TSHttpHdrUrlGet.en.rst | 33 +++++++++++------ .../api/functions/TSUrlHostGet.en.rst | 13 ++++--- .../plugins/c-api/redirect_1/redirect_1.cc | 26 +++++--------- 4 files changed, 66 insertions(+), 42 deletions(-) diff --git a/doc/developer-guide/api/functions/TSHttpHdrHostGet.en.rst b/doc/developer-guide/api/functions/TSHttpHdrHostGet.en.rst index 381add15a64..a583ae5db83 100644 --- a/doc/developer-guide/api/functions/TSHttpHdrHostGet.en.rst +++ b/doc/developer-guide/api/functions/TSHttpHdrHostGet.en.rst @@ -1,18 +1,17 @@ .. 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 + 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. + 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 @@ -43,3 +42,20 @@ header field. This is much faster than calling :func:`TSHttpTxnEffectiveUrlStringGet` and extracting the host from the result. + +.. note:: + + :func:`TSHttpHdrHostGet` is the recommended way to retrieve the host name + in plugins that operate at early hook stages such as + :c:macro:`TS_HTTP_READ_REQUEST_HDR_HOOK`. Unlike :func:`TSUrlHostGet`, which + requires a URL object from :func:`TSHttpHdrUrlGet` and may return ``NULL`` + if the URL has not been fully parsed yet, :func:`TSHttpHdrHostGet` falls + back to the ``Host`` header field when the URL object does not contain host + information. + +See Also +======== + +:manpage:`TSAPI(3ts)`, +:manpage:`TSHttpHdrUrlGet(3ts)`, +:manpage:`TSUrlHostGet(3ts)` \ No newline at end of file diff --git a/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst b/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst index f3ecc7737cc..d0aebb9e3a0 100644 --- a/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst +++ b/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst @@ -1,18 +1,17 @@ .. 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 + 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. + 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 @@ -42,6 +41,16 @@ The value placed in :arg:`locp` is stable only for a single callback, as other c change the URL object itself (see :func:`TSHttpHdrUrlSet`), not just the data in it. That value is also valid only if this function return ``TS_SUCCESS``. +.. note:: + + Not all URL components may be available at every hook stage. In early hooks + such as :c:macro:`TS_HTTP_READ_REQUEST_HDR_HOOK`, the URL object may not yet be + fully parsed. In particular, the host component retrieved via + :func:`TSUrlHostGet` may be ``NULL`` even when a ``Host`` header is present. + For reliable host retrieval across all hook stages, use + :func:`TSHttpHdrHostGet` instead, which checks both the URL and the ``Host`` + header field. + See Also ======== @@ -49,4 +58,6 @@ See Also :manpage:`TSHttpTxnClientReqGet(3ts)`, :manpage:`TSHttpTxnServerReqGet(3ts)`, :manpage:`TSHttpTxnServerRespGet(3ts)`, -:manpage:`TSHttpTxnClientRespGet(3ts)` +:manpage:`TSHttpTxnClientRespGet(3ts)`, +:manpage:`TSHttpHdrHostGet(3ts)`, +:manpage:`TSUrlHostGet(3ts)` \ No newline at end of file diff --git a/doc/developer-guide/api/functions/TSUrlHostGet.en.rst b/doc/developer-guide/api/functions/TSUrlHostGet.en.rst index f7c9c69d7f9..52b5f310fcf 100644 --- a/doc/developer-guide/api/functions/TSUrlHostGet.en.rst +++ b/doc/developer-guide/api/functions/TSUrlHostGet.en.rst @@ -71,11 +71,15 @@ scheme. :arg:`offset` within the marshal buffer :arg:`bufp`. If there is no explicit port number in the URL, zero is returned. - .. note:: - :func:`TSUrlHostGet` should only be called after the ``TS_HTTP_POST_REMAP_HOOK``. - In the ``TS_HTTP_READ_REQUEST_HDR_HOOK`` phase, use :func:`TSHttpHdrHostGet` instead. + :func:`TSUrlHostGet` operates on a URL object obtained from + :func:`TSHttpHdrUrlGet`. In early hooks such as + :c:macro:`TS_HTTP_READ_REQUEST_HDR_HOOK`, the URL object may not yet be fully + parsed, and :func:`TSUrlHostGet` may return ``NULL`` even when a ``Host`` + header is present. For reliable host retrieval at any hook stage, use + :func:`TSHttpHdrHostGet` instead, which checks both the URL and the + ``Host`` header field. Return Values ============= @@ -96,6 +100,7 @@ See Also :manpage:`TSAPI(3ts)`, :manpage:`TSUrlCreate(3ts)`, :manpage:`TSHttpHdrUrlGet(3ts)`, +:manpage:`TSHttpHdrHostGet(3ts)`, :manpage:`TSUrlHostSet(3ts)`, :manpage:`TSUrlStringGet(3ts)`, -:manpage:`TSUrlPercentEncode(3ts)` +:manpage:`TSUrlPercentEncode(3ts)` \ No newline at end of file diff --git a/example/plugins/c-api/redirect_1/redirect_1.cc b/example/plugins/c-api/redirect_1/redirect_1.cc index 701446a5661..a6765a2869a 100644 --- a/example/plugins/c-api/redirect_1/redirect_1.cc +++ b/example/plugins/c-api/redirect_1/redirect_1.cc @@ -14,11 +14,12 @@ 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. + 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. */ /* @@ -97,7 +98,7 @@ static void handle_client_lookup(TSHttpTxn txnp, TSCont contp) { TSMBuffer bufp; - TSMLoc hdr_loc, url_loc; + TSMLoc hdr_loc; int host_length; in_addr_t clientip = 0; @@ -130,16 +131,9 @@ handle_client_lookup(TSHttpTxn txnp, TSCont contp) goto done; } - if (TSHttpHdrUrlGet(bufp, hdr_loc, &url_loc) != TS_SUCCESS) { - TSError("[%s] Couldn't retrieve request url", PLUGIN_NAME); - TSHandleMLocRelease(bufp, TS_NULL_MLOC, hdr_loc); - goto done; - } - - host = TSUrlHostGet(bufp, url_loc, &host_length); + host = TSHttpHdrHostGet(bufp, hdr_loc, &host_length); if (!host) { TSError("[%s] Couldn't retrieve request hostname", PLUGIN_NAME); - TSHandleMLocRelease(bufp, hdr_loc, url_loc); TSHandleMLocRelease(bufp, TS_NULL_MLOC, hdr_loc); goto done; } @@ -148,7 +142,6 @@ handle_client_lookup(TSHttpTxn txnp, TSCont contp) * Check to see if the client is already headed to the redirect site. */ if (strncmp(host, url_redirect, host_length) == 0) { - TSHandleMLocRelease(bufp, hdr_loc, url_loc); TSHandleMLocRelease(bufp, TS_NULL_MLOC, hdr_loc); goto done; } @@ -159,7 +152,6 @@ handle_client_lookup(TSHttpTxn txnp, TSCont contp) update_redirected_method_stats(bufp, hdr_loc); - TSHandleMLocRelease(bufp, hdr_loc, url_loc); TSHandleMLocRelease(bufp, TS_NULL_MLOC, hdr_loc); /* @@ -361,4 +353,4 @@ TSPluginInit(int argc, const char *argv[]) } else { DBG_INIT("The redirect_demo tag is not set"); } -} +} \ No newline at end of file From 9cdcfd47deb0004edcba0c5295cade8a3171a590 Mon Sep 17 00:00:00 2001 From: mmustafasenoglu Date: Tue, 30 Jun 2026 20:15:32 +0300 Subject: [PATCH 5/7] fix(docs): replace :c:macro: with double backticks for TS_HTTP_READ_REQUEST_HDR_HOOK --- .../api/functions/TSHttpHdrHostGet.en.rst | 60 ------------------- 1 file changed, 60 deletions(-) diff --git a/doc/developer-guide/api/functions/TSHttpHdrHostGet.en.rst b/doc/developer-guide/api/functions/TSHttpHdrHostGet.en.rst index a583ae5db83..8b137891791 100644 --- a/doc/developer-guide/api/functions/TSHttpHdrHostGet.en.rst +++ b/doc/developer-guide/api/functions/TSHttpHdrHostGet.en.rst @@ -1,61 +1 @@ -.. 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 - -TSHttpHdrHostGet -**************** - -Synopsis -======== - -.. code-block:: cpp - - #include - -.. function:: const char* TSHttpHdrHostGet(TSMBuffer bufp, TSMLoc offset, int * length) - -Description -=========== - -Get the host for the request. :arg:`bufp` and :arg:`offset` must reference an -HTTP request header. A pointer to the host is returned and the length is stored -in the ``int`` pointed at by :arg:`length`. Note the returned text may not -be null terminated. The URL in the request is checked first then the ``Host`` -header field. - -.. note:: - - This is much faster than calling :func:`TSHttpTxnEffectiveUrlStringGet` and - extracting the host from the result. - -.. note:: - - :func:`TSHttpHdrHostGet` is the recommended way to retrieve the host name - in plugins that operate at early hook stages such as - :c:macro:`TS_HTTP_READ_REQUEST_HDR_HOOK`. Unlike :func:`TSUrlHostGet`, which - requires a URL object from :func:`TSHttpHdrUrlGet` and may return ``NULL`` - if the URL has not been fully parsed yet, :func:`TSHttpHdrHostGet` falls - back to the ``Host`` header field when the URL object does not contain host - information. - -See Also -======== - -:manpage:`TSAPI(3ts)`, -:manpage:`TSHttpHdrUrlGet(3ts)`, -:manpage:`TSUrlHostGet(3ts)` \ No newline at end of file From 1ef039ed29450e75ab3776e8d32cb4332b0e5f72 Mon Sep 17 00:00:00 2001 From: mmustafasenoglu Date: Tue, 30 Jun 2026 20:15:55 +0300 Subject: [PATCH 6/7] fix(docs): replace :c:macro: with double backticks for TS_HTTP_READ_REQUEST_HDR_HOOK --- doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst b/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst index d0aebb9e3a0..4fe9d20de34 100644 --- a/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst +++ b/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst @@ -44,7 +44,7 @@ also valid only if this function return ``TS_SUCCESS``. .. note:: Not all URL components may be available at every hook stage. In early hooks - such as :c:macro:`TS_HTTP_READ_REQUEST_HDR_HOOK`, the URL object may not yet be + such as ``TS_HTTP_READ_REQUEST_HDR_HOOK``, the URL object may not yet be fully parsed. In particular, the host component retrieved via :func:`TSUrlHostGet` may be ``NULL`` even when a ``Host`` header is present. For reliable host retrieval across all hook stages, use @@ -60,4 +60,4 @@ See Also :manpage:`TSHttpTxnServerRespGet(3ts)`, :manpage:`TSHttpTxnClientRespGet(3ts)`, :manpage:`TSHttpHdrHostGet(3ts)`, -:manpage:`TSUrlHostGet(3ts)` \ No newline at end of file +:manpage:`TSUrlHostGet(3ts)` From 4345cc8f8de112466295fc97090c42d8baaf1c92 Mon Sep 17 00:00:00 2001 From: mmustafasenoglu Date: Tue, 30 Jun 2026 20:16:06 +0300 Subject: [PATCH 7/7] fix(docs): replace :c:macro: with double backticks for TS_HTTP_READ_REQUEST_HDR_HOOK --- doc/developer-guide/api/functions/TSUrlHostGet.en.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/developer-guide/api/functions/TSUrlHostGet.en.rst b/doc/developer-guide/api/functions/TSUrlHostGet.en.rst index 52b5f310fcf..6b7b587fbe3 100644 --- a/doc/developer-guide/api/functions/TSUrlHostGet.en.rst +++ b/doc/developer-guide/api/functions/TSUrlHostGet.en.rst @@ -75,7 +75,7 @@ port number in the URL, zero is returned. :func:`TSUrlHostGet` operates on a URL object obtained from :func:`TSHttpHdrUrlGet`. In early hooks such as - :c:macro:`TS_HTTP_READ_REQUEST_HDR_HOOK`, the URL object may not yet be fully + ``TS_HTTP_READ_REQUEST_HDR_HOOK``, the URL object may not yet be fully parsed, and :func:`TSUrlHostGet` may return ``NULL`` even when a ``Host`` header is present. For reliable host retrieval at any hook stage, use :func:`TSHttpHdrHostGet` instead, which checks both the URL and the @@ -103,4 +103,4 @@ See Also :manpage:`TSHttpHdrHostGet(3ts)`, :manpage:`TSUrlHostSet(3ts)`, :manpage:`TSUrlStringGet(3ts)`, -:manpage:`TSUrlPercentEncode(3ts)` \ No newline at end of file +:manpage:`TSUrlPercentEncode(3ts)`