snowglobe

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 wantsWhat 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 tokena 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 daemona link
UDPnot 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 WebSocket to 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:

  1. Put {token} in the tunnel URL.
  2. Name a token endpoint with --tunnel-token URL. The page asks it for a fresh token on every connection (natively, once per boot).
  3. 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:

  • none refuses every connection the guest opens itself. Links and forwarded ports still work.
  • internet allows public addresses.
  • private adds loopback and private networks, as --allow-private does.

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.