docs: add call condition note for TSUrlHostGet

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)`

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,11 +41,23 @@ 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
 ========
 
 :manpage:`TSAPI(3ts)`,
 :manpage:`TSHttpTxnClientReqGet(3ts)`,
 :manpage:`TSHttpTxnServerReqGet(3ts)`,
 :manpage:`TSHttpTxnServerRespGet(3ts)`,
-:manpage:`TSHttpTxnClientRespGet(3ts)`
+:manpage:`TSHttpTxnClientRespGet(3ts)`,
+:manpage:`TSHttpHdrHostGet(3ts)`,
+:manpage:`TSUrlHostGet(3ts)`

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
+   :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
 =============
 
@@ -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)`
+:manpage:`TSUrlPercentEncode(3ts)`

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");
   }
-}
+}