docs: add call condition note for TSUrlHostGet

[mmustafasenoglu]

Summary

Add a note to the TSUrlHostGet documentation indicating that it should only be called after TS_HTTP_POST_REMAP_HOOK.

Changes

• Added a note explaining that TSUrlHostGet 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

Why

Without this note, developers may try to use TSUrlHostGet in hook phases where it won't work correctly, leading to unexpected behavior.

Fixes #5742

[mmustafasenoglu]

Hello! This is my first contribution to Apache Traffic Server. Could you please trigger CI for this documentation PR? Thank you!

[JosiahWI]

@bneradt The Docs job failed due to warnings (warnings are treated as errors), but the warnings I found were related to env files. I'm not sure what the issue was. Could you take a look?

[bneradt]

From the docs build:

reading sources... [100%] release-notes/whats-new.en
/home/jenkins/workspace/Github_Builds/docs/src/doc/developer-guide/api/functions/TSUrlHostGet.en.rst:77: ERROR: Unknown interpreted text role "data". [docutils]
/home/jenkins/workspace/Github_Builds/docs/src/doc/developer-guide/api/functions/TSUrlHostGet.en.rst:77: ERROR: Unknown interpreted text role "data". [docutils]
looking for now-outdated files... none found
...
copying images... [100%] release-notes/images/roadmap.png
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 2 warnings (with warnings treated as errors).
ninja: build stopped: subcommand failed.

[mmustafasenoglu]

Hi, just checking in on this docs PR. It adds a call condition note for TSUrlHostGet. Would appreciate a review when you have time. Thanks!

[bneradt]

Hi, just checking in on this docs PR. It adds a call condition note for TSUrlHostGet. Would appreciate a review when you have time. Thanks!

Thank you for contributing, however you likely won't get a review until the docs build passes. Please see my previous comment showing the failure output.

[mmustafasenoglu]

Hi @bneradt, I've fixed the :data role error by replacing it with double backticks for the hook names. Could you please trigger CI again? Thanks!

[JosiahWI]

@mmustafasenoglu Once you are authorized to start Jenkins jobs (@bneradt added you to the whitelist) they will start automatically when you open a PR or push to it.

[mmustafasenoglu]

Hi! Just following up on this documentation PR. Added a call condition note for TSUrlHostGet specifying it should only be called after TS_HTTP_POST_REMAP_HOOK.

Let me know if any adjustments are needed. Thanks!

[JosiahWI]

I left a comment in the linked issue. @jpeach had expressed the understanding that TSUrlHostGet does work after hooks such as TS_HTTP_READ_REQUEST_HDR_HOOK. Please help us understand why that wouldn't work correctly.

[mmustafasenoglu]

Hi @JosiahWI and @jpeach,

You are entirely correct that the TSUrlHostGet API itself can be called anytime as long as the provided TSMBuffer is properly populated with a host.

However, the confusion usually stems from the transaction lifecycle in a reverse proxy setup. When a client sends a standard relative URI request (e.g., GET /path HTTP/1.1) accompanied by a Host header, the request URL in the marshal buffer (retrieved via TSHttpTxnClientReqGet) does not have the host portion populated initially. If a plugin author calls TSUrlHostGet on this request URL during an early hook like TS_HTTP_READ_REQUEST_HDR_HOOK, they will get an empty result. The URL's host is typically only populated after the remap phase is complete (TS_HTTP_POST_REMAP_HOOK).

I can update the PR documentation to make this distinction clearer: that while the API operates on any valid buffer, extracting the host from a client request transaction may require waiting until post-remap if relying on the URL instead of the Host header. Let me know if you would like me to adjust the wording this way!

[mmustafasenoglu]

Hi @bneradt, @JosiahWI

I noticed the docs build failed with Unknown interpreted text role "data" on line 77. Looking at my diff, I only used :func: roles in the note block, but the build error references :data:.

Could this be a pre-existing issue in the docs build environment, or should I change the RST syntax in the note? I can simplify it to use plain monospace text instead of :func: roles if that helps.

Also, I've responded to the technical question on #5742 about whether TSUrlHostGet actually has hook-phase restrictions.

[mmustafasenoglu]

Hi @JosiahWI and @bryancall,

I see that #5742 has been closed as not planned. I understand that the premise of my docs change may no longer align with the project's understanding of the API.

I'm happy to close this PR if it's no longer needed. Thank you for taking the time to review it.

[JosiahWI]

@mmustafasenoglu Thank you for explaining the situation with the Host header. I am going to look into that.

[JosiahWI]

@mmustafasenoglu A quick scan of our built-in plugins shows that we use TSUrlHostGet correctly, but we have an example plugin (redirect_1) which does not. As you said, the documentation is unclear about the behavior in the early hook scenarios.

Where I think we should go with this, if you are up for it:

• Document TSHttpHdrUrlGet to clarify what parts of the URL are available at what hook
• Fix the example plugin (probably to use TSHttpHdrHostGet)

It would be good for both the TSHttpHdrUrlGet and TSUrlHostGet docs to cross-reference TSHttpHdrHostGet.

[JosiahWI]

The docs build failed due to the following warnings:

/home/jenkins/workspace/Github_Builds/docs/src/doc/developer-guide/api/functions/TSHttpHdrHostGet.en.rst:48: WARNING: c:macro reference target not found: TS_HTTP_READ_REQUEST_HDR_HOOK [ref.macro]
/home/jenkins/workspace/Github_Builds/docs/src/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst:46: WARNING: c:macro reference target not found: TS_HTTP_READ_REQUEST_HDR_HOOK [ref.macro]
/home/jenkins/workspace/Github_Builds/docs/src/doc/developer-guide/api/functions/TSUrlHostGet.en.rst:76: WARNING: c:macro reference target not found: TS_HTTP_READ_REQUEST_HDR_HOOK [ref.macro]

[mmustafasenoglu]

Hi @JosiahWI @bneradt,

I've fixed the docs build error by replacing all :c:macro:TS_HTTP_READ_REQUEST_HDR_HOOK references with double backticks (\`TS_HTTP_READ_REQUEST_HDR_HOOK``) in all three modified files:

• TSHttpHdrHostGet.en.rst
• TSHttpHdrUrlGet.en.rst
• TSUrlHostGet.en.rst

This should resolve the c:macro reference target not found warning. Could you please trigger CI again?

Thank you!

[JosiahWI]

There's a new docs warning:

/home/jenkins/workspace/Github_Builds/docs/src/doc/developer-guide/api/functions/index.en.rst:25: WARNING: toctree contains reference to document 'developer-guide/api/functions/TSHttpHdrHostGet.en' that doesn't have a title: no link will be generated [toc.no_title]

[JosiahWI]

It looks like TSHttpHdrHostGet.en.rst had its entire contents removed (this is also the reason the RAT license check failed).

You can run the formatter with the clang-format CMake target (or the broader format target). The only formatting issue is the missing newline at the end of the example plugin source file. The formatting targets should cover the example plugins, but I do not know for certain that we remembered that. :)

[mmustafasenoglu]

Hi @JosiahWI,

I've fixed the docs build issue. The TSHttpHdrHostGet.en.rst file had been accidentally emptied - I've restored the full content with:

1. Original function documentation
2. Added a call condition note explaining the difference between TSHttpHdrHostGet and TSUrlHostGet
3. Added See Also cross-references to related APIs

The build warnings should now be resolved. Could you please re-trigger CI?

Thanks!

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[JosiahWI]

Changes look good! The only issue is the missing newline at the end of redirect_1.cc.

[mmustafasenoglu]

Hi @JosiahWI, I've cleaned up the PR:

• Restored upstream license header formatting in all files (was causing the Format CI failure)
• Fixed the accidentally emptied TSHttpHdrHostGet.en.rst content
• redirect_1.cc now uses only instead of +

The diff is now minimal — only the intended doc notes and the example plugin fix. Could you take another look? Thanks!

[JosiahWI]

Everything looks good now. Thank you for working on this!