docs: what a live codespace showed - #529
Conversation
Port visibility reverts to private on every codespace restart, and sam-one says so again; gh is not in the image, so the gh command in the hint runs on your own machine; a sam-node that finds no router for about three minutes exits on purpose, so nodes are started again after a longer stop, with the identity they already hold. GitHub's proxy names the public host in X-Forwarded-Host, which the zero-config inference already reads, so the reference says so. The lock file loses its final newline: that is how Codespaces writes it, and the checkout stays clean.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation for GitHub Codespaces and the sam-one reference guide, detailing how sam-one infers the advertised WebSocket address behind HTTPS proxies and explaining node behavior during codespace idle stops. The review feedback suggests minor phrasing improvements to make the documentation clearer and more precise, such as clarifying the header combination for --external-url and refining colloquial language regarding mesh recovery and node restarts.
| | `--bind-address` | `0.0.0.0` | Host to bind. | | ||
| | `--port` | `0` | TCP port. `0` picks a free one and prints it in the banner. | | ||
| | `--external-url` | | Public URL on which nodes reach this instance, for a reverse proxy or a hosted platform. Can also be set with `SAM_EXTERNAL_URL`. When omitted behind an HTTPS proxy (Cloud Run, Fly.io), `/info` infers the advertised `wss` address from the incoming `Host` / `X-Forwarded-Proto` headers automatically. | | ||
| | `--external-url` | | Public URL on which nodes reach this instance, for a reverse proxy or a hosted platform. Can also be set with `SAM_EXTERNAL_URL`. When omitted behind an HTTPS proxy (Cloud Run, Fly.io, a forwarded Codespaces port), `/info` infers the advertised `wss` address from the incoming `Host` or `X-Forwarded-Host` and `X-Forwarded-Proto` headers automatically. | |
There was a problem hiding this comment.
The phrase 'incoming Host or X-Forwarded-Host and X-Forwarded-Proto headers' is slightly ambiguous. Clarifying this with parentheses makes it clear that X-Forwarded-Proto is always used alongside either host header.
Suggested change:
| `--external-url` | | Public URL on which nodes reach this instance, for a reverse proxy or a hosted platform. Can also be set with `SAM_EXTERNAL_URL`. When omitted behind an HTTPS proxy (Cloud Run, Fly.io, a forwarded Codespaces port), `/info` infers the advertised `wss` address from the incoming `Host` (or `X-Forwarded-Host`) and `X-Forwarded-Proto` headers automatically. || tokens, and enrolled devices reconnect on their own as long as the mesh is | ||
| back within about three minutes. |
There was a problem hiding this comment.
The phrase 'is back' is a bit colloquial. Using 'comes back' or 'is restarted' is more precise and natural in this context.
| tokens, and enrolled devices reconnect on their own as long as the mesh is | |
| back within about three minutes. | |
| tokens, and enrolled devices reconnect on their own as long as the mesh comes | |
| back within about three minutes. |
| for about three minutes exits on purpose, so after a longer stop you start | ||
| your nodes again (`sam-node run --daemonize`; they need no new | ||
| enrollment) or run them under a service manager that restarts them. |
There was a problem hiding this comment.
The phrase 'you start your nodes again' is a bit passive/colloquial. It would be clearer and more direct to say 'you will need to restart your nodes' or 'you must restart your nodes'.
Suggested change:
for about three minutes exits on purpose, so after a longer stop you will need to restart
your nodes (`sam-node run --daemonize`; they need no new
enrollment) or run them under a service manager that restarts them.1 participant
Follow-up to #522, which was merged before this commit landed on the branch.
What a real codespace showed, folded into the guide and the reference:
sam-onewarns again and you set it to public once more.ghis not in the image, so thegh codespace ports visibilitycommand in the hint runs on your own machine.sam-nodethat finds no router for about three minutes exits on purpose, so after a longer idle stop nodes are started again; they keep their identity and do not enroll twice.Host: localhost:<port>and names the public host inX-Forwarded-Host, which the zero-config inference already reads; the reference says so..devcontainer/devcontainer-lock.jsonis committed without a final newline, which is how Codespaces rewrites it, so the checkout stays clean inside a codespace.