This is an automated email from the ASF dual-hosted git repository.
cmcfarlen pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new 16c434c282 docs: add call condition note for TSUrlHostGet (#13313)
16c434c282 is described below
commit 16c434c28251804ac8022950cbbe913a6a866b4a
Author: mmustafasenoglu <[email protected]>
AuthorDate: Mon Jul 6 19:13:19 2026 +0300
docs: add call condition note for TSUrlHostGet (#13313)
* 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
* docs: fix unknown interpreted text role data
Replace :data: with double backticks for hook names, consistent
with the rest of the documentation.
Fixes #5742
* docs: trigger CI for TSUrlHostGet call condition note
* 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
* fix(docs): replace :c:macro: with double backticks for
TS_HTTP_READ_REQUEST_HDR_HOOK
* fix(docs): replace :c:macro: with double backticks for
TS_HTTP_READ_REQUEST_HDR_HOOK
* fix(docs): replace :c:macro: with double backticks for
TS_HTTP_READ_REQUEST_HDR_HOOK
* fix: restore TSHttpHdrHostGet docs content and add cross-references
- Restored accidentally emptied TSHttpHdrHostGet.en.rst
- Added call condition note explaining TSHttpHdrHostGet vs TSUrlHostGet
- Added See Also cross-references to related APIs
Fixes docs build warning reported by JosiahWI
* fix: add trailing newline to redirect_1.cc
* fix: restore upstream license header formatting
* fix: restore upstream license header formatting
* fix: restore upstream license header formatting
* fix: restore upstream license header in redirect_1.cc
* fix: restore license header and fix broken string literal
* fix: restore blank line after title underline
* fix: add blank line between title and Synopsis
* fix: apply code changes on top of upstream cleanly
* fix: restore redirect_1.cc with correct API changes
* fix: restore redirect_1.cc with correct TSHttpHdrHostGet usage
* fix: apply TSHttpHdrHostGet changes cleanly on upstream
* fix: restore blank line between title and Synopsis
---------
Co-authored-by: Mustafa Senoglu <[email protected]>
---
.../api/functions/TSHttpHdrHostGet.en.rst | 16 ++++++++++++++++
doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst | 14 +++++++++++++-
doc/developer-guide/api/functions/TSUrlHostGet.en.rst | 11 +++++++++++
example/plugins/c-api/redirect_1/redirect_1.cc | 13 ++-----------
4 files changed, 42 insertions(+), 12 deletions(-)
diff --git a/doc/developer-guide/api/functions/TSHttpHdrHostGet.en.rst
b/doc/developer-guide/api/functions/TSHttpHdrHostGet.en.rst
index 381add15a6..57f1e1b982 100644
--- a/doc/developer-guide/api/functions/TSHttpHdrHostGet.en.rst
+++ b/doc/developer-guide/api/functions/TSHttpHdrHostGet.en.rst
@@ -43,3 +43,19 @@ header field.
This is much faster than calling :func:`TSHttpTxnEffectiveUrlStringGet` and
extracting the host from the result.
+
+.. note::
+
+ :func:`TSHttpHdrHostGet` checks both the URL and the ``Host`` header field,
+ making it reliable at any hook stage. In contrast, :func:`TSUrlHostGet`
+ operates only on the URL object obtained from :func:`TSHttpHdrUrlGet`. In
+ early hooks such as ``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.
+
+See Also
+========
+
+:func:`TSUrlHostGet`,
+:func:`TSHttpHdrUrlGet`,
+:func:`TSHttpTxnEffectiveUrlStringGet`
diff --git a/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst
b/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst
index f3ecc7737c..ddeca6ed08 100644
--- a/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst
+++ b/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst
@@ -42,6 +42,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 ``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 +59,6 @@ See Also
:manpage:`TSHttpTxnClientReqGet(3ts)`,
:manpage:`TSHttpTxnServerReqGet(3ts)`,
:manpage:`TSHttpTxnServerRespGet(3ts)`,
-:manpage:`TSHttpTxnClientRespGet(3ts)`
+:manpage:`TSHttpTxnClientRespGet(3ts)`,
+:manpage:`TSHttpHdrHostGet(3ts)`,
+:manpage:`TSUrlHostGet(3ts)`
diff --git a/doc/developer-guide/api/functions/TSUrlHostGet.en.rst
b/doc/developer-guide/api/functions/TSUrlHostGet.en.rst
index 1497e625c9..6b7b587fbe 100644
--- a/doc/developer-guide/api/functions/TSUrlHostGet.en.rst
+++ b/doc/developer-guide/api/functions/TSUrlHostGet.en.rst
@@ -71,6 +71,16 @@ 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` operates on a URL object obtained from
+ :func:`TSHttpHdrUrlGet`. In early hooks such as
+ ``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
=============
@@ -90,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)`
diff --git a/example/plugins/c-api/redirect_1/redirect_1.cc
b/example/plugins/c-api/redirect_1/redirect_1.cc
index 701446a566..6a9a9a71fa 100644
--- a/example/plugins/c-api/redirect_1/redirect_1.cc
+++ b/example/plugins/c-api/redirect_1/redirect_1.cc
@@ -97,7 +97,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 +130,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 +141,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 +151,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);
/*
