docs: a proxy is not the answer to an unreachable endpoint - #189
Merged
Conversation
Both AI-features documents put the outbound-proxy section ahead of the stage-by-stage diagnosis, so a reader arriving with "the endpoint in our corporate network is unreachable" meets the proxy first and configures one. That is not a hypothetical: it happened. An endpoint sitting in another network segment without a firewall rule was read as a proxy problem and cost several rounds before the missing rule was found. A proxy answers "outbound traffic MAY only leave this network through the proxy"; it does nothing for a route that is blocked. Both sections now say so up front and point at the stage diagnosis, which answers the question in seconds - the cheaper first step.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Both AI-features documents put the outbound-proxy section ahead of the stage-by-stage connection diagnosis. A reader arriving with "the endpoint in our corporate network is unreachable" meets the proxy first — and configures one.
That is not hypothetical. It is what happened in the case that produced #185, #186 and #187: an LLM endpoint sitting in a different network segment without a firewall rule was read as a proxy problem. Several rounds and two releases later, the actual cause turned out to be the missing rule. A proxy answers "outbound traffic may only leave this network through the proxy"; it does nothing for a route that is blocked.
What
A short note at the top of both proxy sections stating what a proxy is and is not for, pointing at the stage diagnosis (
LLM endpoint DNS:/TCP:/TLS:) that answers the question in seconds — the cheaper first step. The repo document names the real incident in one sentence, so the next reader does not have to rediscover it.Docs only, no code. Anchors verified against the actual headings; the docs site generates ids via
rehype-slug/github-slugger andDocs UI buildpasses.Note on the three PRs this closes out
Asked to judge whether to keep or revert them, my recommendation was to keep all three:
UseProxy = falsewas hard-coded, so a mandatory proxy could not be used at all), becauseMode: Offequivalence is covered by unit tests and an end-to-end test in the production handler shape, and because the failing calls on 1.2.2/1.2.3 reached a TCP timeout — field evidence that theOffpath connects directly.This PR is the one change that came out of that review.