docs: describe both paths that reach the HTTP listener #918

Merged

coilysiren merged 1 commit from issue-905-http-reachability into main

2026-08-17 18:26:15 +00:00

coilyco-ops commented

2026-08-17 18:24:35 +00:00

Member

Rewrites the reachability paragraph as two paths rather than one, and names the sidecar-less lane.

The two false claims, both corrected

"no ... NodePort" - the ports are now listed: sirens-echo 30120, sirens-deep 30121, sirens-deep-owl-glass 30122, with the ClusterIP retained so the in-namespace path is unchanged.
"routes callers through Echo's Tailscale sidecar" - sirens-deep-owl-glass runs tailnet.enabled: false. It has no sidecar and no MagicDNS name, and the NodePort is its only path. The doc now says that outright, including that it had no tailnet reach before that port existed.

The boundary claim stays

Unchanged, as the issue says it should: the NodePort is LAN and tailnet only, the home router forwards nothing to it, and no public resource is rendered, so reaching /v1/turn still requires being an authorized node on the tailnet. The sentence about the process carrying no credential of its own was the right frame and is kept verbatim.

One thing the issue did not list

The "A trusted caller" section opened with "Echo is exposed through ingress-tailscale", which is the same stale single-path claim one section down. Now "reached over the tailnet or the LAN behind it".

I did not restate that SIRENS_ECHO_HTTP_TOKEN refuses nobody. That section already ends with "Trust does nothing today beyond a span attribute recording whether the caller authenticated", and callerTrusted is called at http.go:227 for a span attribute and a turn field with no refusal path, so the page is already correct on that point and repeating it would only add words.

Not answered here

The director's second ask - confirming the real reachability of 30120, 30121, and 30122, especially 30122 - is a live-system question and DevOps owns it. If the effective boundary did change, that is a separate issue and not a docs one.

closes #905

Rewrites the reachability paragraph as two paths rather than one, and names the sidecar-less lane. ## The two false claims, both corrected * **"no ... NodePort"** - the ports are now listed: `sirens-echo` 30120, `sirens-deep` 30121, `sirens-deep-owl-glass` 30122, with the ClusterIP retained so the in-namespace path is unchanged. * **"routes callers through Echo's Tailscale sidecar"** - `sirens-deep-owl-glass` runs `tailnet.enabled: false`. It has no sidecar and no MagicDNS name, and the NodePort is its only path. The doc now says that outright, including that it had no tailnet reach before that port existed. ## The boundary claim stays Unchanged, as the issue says it should: the NodePort is LAN and tailnet only, the home router forwards nothing to it, and no public resource is rendered, so reaching `/v1/turn` still requires being an authorized node on the tailnet. The sentence about the process carrying no credential of its own was the right frame and is kept verbatim. ## One thing the issue did not list The "A trusted caller" section opened with "Echo is exposed through `ingress-tailscale`", which is the same stale single-path claim one section down. Now "reached over the tailnet or the LAN behind it". I did **not** restate that `SIRENS_ECHO_HTTP_TOKEN` refuses nobody. That section already ends with "Trust does nothing today beyond a span attribute recording whether the caller authenticated", and `callerTrusted` is called at `http.go:227` for a span attribute and a turn field with no refusal path, so the page is already correct on that point and repeating it would only add words. ## Not answered here The director's second ask - confirming the real reachability of 30120, 30121, and 30122, especially 30122 - is a live-system question and DevOps owns it. If the effective boundary did change, that is a separate issue and not a docs one. closes #905

coilyco-ops added 1 commit

2026-08-17 18:24:36 +00:00

docs: describe both paths that reach the HTTP listener

ci / image-build (pull_request) Successful in 42s

Details

ci / test (pull_request) Successful in 1m5s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / publish-observed (pull_request) Has been skipped

Details

59691b2e7e

The reachability paragraph said the deployment publishes no NodePort and
routes callers through Echo's Tailscale sidecar. Both halves are now false.
deploy PR 634 gave each Sirens lane a NodePort on kai-server, and the
owl.glass lane runs tailnet.enabled: false, so it has no sidecar and no
MagicDNS name at all.

Rewritten as two paths rather than one, with the sidecar-less lane named as
the case that has only the second, and the ports listed. One port per lane
covers both surfaces because HTTPHandler hangs /mcp and the /v1 paths off one
mux on one listener.

The security claim is unchanged and stays: the NodePort is LAN and tailnet
only, the home router forwards nothing to it, and no public resource is
rendered, so reaching /v1/turn still requires being an authorized node on the
tailnet. What was stale is the mechanism, not the boundary.

The trusted-caller section said Echo is exposed through ingress-tailscale,
which is no longer true of every lane, so it now names the tailnet and the LAN
behind it.

closes #905

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-17 18:24:36 +00:00

coilyco-ops referenced this pull request

2026-08-17 18:24:53 +00:00

docs/sirens-echo-http.md describes a reachability model the deployment no longer has #905