The previous docs round (906b1da57) described the integration the way
we wanted it to work — `http_listens` plural with a docker bridge
bind, dedicated `audit.log` for per-request JSON records. Live
testing against the real v0.39.0 binary in [905ce58a1] surfaced that
neither field exists in v0.39's config schema, and the docs were
making promises the daemon couldn't keep.
This commit walks every claim in the docs back to what the binary
actually does today, while keeping the upgrade path explicit so the
docs stay coherent when the pinned `_IRON_PROXY_VERSION` bumps:
website/docs/user-guide/egress/iron-proxy.md
- Bind policy section: rewritten. Was "loopback + docker bridge IP
on Linux"; now "loopback only" with an explicit explanation that
v0.39 only supports one bind per daemon and that
host.docker.internal -> host-gateway mapping is what sandboxes
use to reach the loopback bind.
- Bind policy section adds a note on the metrics-port pin that the
previous round of docs didn't even mention.
- State directory layout table: `audit.log` description rewritten
to acknowledge it's a pre-created sentinel for future binary
versions, NOT something the v0.39 daemon writes to.
- New section "Logging on iron-proxy v0.39" replaces the old
"Audit log vs daemon log" section. Explicitly tells operators
the daemon log is the single source of truth for both audiences
on v0.39, with the upgrade path called out.
- Data-flow diagram step 7: rewritten to send per-request records
to `iron-proxy.log` on v0.39 with cross-link to the new logging
section.
- Diagram caption updated.
- Security-model "allowlisted-host exfiltration" line: "audit log
captures" -> "daemon log captures".
- Security-model "LAN peer leak" line: removed the docker-bridge
claim.
- Troubleshooting section's per-request-inspection recipes:
rewritten to use `iron-proxy.log` and explain when the split
stream will land.
- Limitations list gets a new bullet calling out the
single-bind + combined-log v0.39 constraints + the auto-upgrade
posture.
website/docs/developer-guide/egress-internals.md
- Bind policy invariant: documents the singular `http_listen` v0.39
schema constraint + dead-code-until-upgrade status of the
bridge-bind path.
- New "Metrics port collision" invariant documenting why
`metrics.listen: 127.0.0.1:0` is non-negotiable.
- Audit log fail-loud invariant adds the v0.39 schema constraint
note + the new
`test_audit_log_kwarg_does_not_inject_audit_path_v039` regression
test.
- "Subscribing to per-request audit events" section updated to
send watchers at `iron-proxy.log` for v0.39 with the upgrade
pivot called out.
website/docs/reference/cli-commands.md
- Diagnostic shortcut for tailing the audit log: `tail audit.log |
jq` -> `tail iron-proxy.log | jq` with the v0.39 note inline.
Build verification:
- `npx docusaurus build` succeeds across all three locales
(en + zh-Hans + ko).
- New `#logging-on-iron-proxy-v039` anchor lands in the rendered
HTML and the in-page cross-references resolve.
- No new broken anchors introduced (pre-existing warnings on
unrelated zh-Hans pages are unchanged).
- No leftover stale `#audit-log-vs-daemon-log` or `#http_listens`
references anywhere on the egress pages.
bde66ef37a