Networking
Read this when the app needs the internet, a database or your own machine. A guest has no network unless the site asks for one. In a page, its only way out is then the visitor's own browser.
| The guest wants | What it takes |
|---|---|
| HTTP, HTTPS, WebSockets | --network fetch, and a server that allows CORS |
| Other TCP (a database) | a tunnel, over a WebSocket in a page |
| A password or token | a token endpoint, never a secret in the image |
| Your own machine (loopback, private addresses) | --allow-private, for builds and snowglobe run; never in a page |
| Another machine of the daemon | a link |
| UDP | not possible in a page |
HTTP, HTTPS and WebSockets
Build with --network fetch (or snowglobe.network="fetch"). The guest gets a
network card and DHCP. Every request it makes leaves as the page's own browser request. Its
connections to ports 80 and 443 end inside the machine:
- HTTP requests become a
fetch(). - HTTPS is terminated in the machine and replayed with
fetch("https://…"). The certificate is signed by a CA made fresh for each build, which the guest trusts. Nothing else should trust that CA: its key ships with the site. - WebSockets open a browser
WebSocketto the same URL.
The browser's rules still apply:
- HTTP(S) only reaches servers that allow CORS. Others answer with a 502 that says so.
- Loopback, private and link-local addresses (
localhost, 10/8, 192.168/16, 169.254/16, fc00::/7 and the like) are refused, so a guest can't reach the visitor's own machine or network. The page's own origin stays reachable. - Requests carry none of the visitor's cookies, HTTP authentication or referrer: they are the guest's, not the visitor's.
- A request body or WebSocket message is at most 64 MiB.
- UDP goes nowhere.
- Other TCP goes only through a tunnel.
Other TCP: tunnels
A page can't open raw TCP. So a connection to a database, or to any port but 80 and 443, is refused unless the site names it as a tunnel.
--tunnel HOST:PORT=URL carries every connection to HOST:PORT over a WebSocket
to URL, as binary messages. That is what websockify, websocat and Neon's wsproxy speak.
websocat --binary ws-l:0.0.0.0:6543 tcp:127.0.0.1:5432 # next to Postgres
snowglobe build ./my-app --network fetch --tunnel db.internal:5432=wss://db-proxy.example.com/
Credentials
Whatever the guest knows ships with the site. A password in its environment is in the snapshot, for every visitor.
Use a token instead:
- Put
{token}in the tunnel URL. - Name a token endpoint with
--tunnel-token URL. The page asks it for a fresh token on every connection (natively, once per boot). - Put a gateway behind the tunnel. It checks the token and holds the real credentials.
A token only replaces the password. What it opens is whatever the gateway lets any visitor do.
Builds and snowglobe run refuse loopback and private addresses, so a guest can't reach the
host's own services. That holds through HTTPS_PROXY or HTTP_PROXY too: a private IP
or localhost handed to the proxy is refused. --allow-private lets them, for a tunnel endpoint on your own machine
while developing.
Outside a browser
Run natively, the network card goes out through the host instead of a page. So a tunnel's URL may also
be tcp://HOST:PORT: each connection the guest opens to the tunnel's name becomes one to that
address, with no WebSocket proxy in between. The same rules apply, so a tunnel to your own machine needs
--allow-private.
snowglobe run dist/app --tunnel db.internal:5432=tcp://127.0.0.1:5432 --allow-private
snowglobe-vm, and an executable made by snowglobe bundle, also take
--egress:
nonerefuses every connection the guest opens itself. Links and forwarded ports still work.internetallows public addresses.privateadds loopback and private networks, as--allow-privatedoes.
Between machines: links
Machines in the daemon reach each other only through links. A link gives a machine a name to reach
another by: its guest connects to db.internal:5432 and gets the target's guest port. A link
works even when the machine's egress is none, and opens no TCP port on the host.
Links, network modes and each template's egress are covered on Orchestration and fleets.