scion-web-serving

# Serving web content from your agent through the port proxy Services inside your agent are not reachable from outside it. `scion expose` registers a local port with the Hub, which then serves it at a URL that people with access to your agent can open. The link serves web protocols only (HTTP, and WebSockets where supported; see below). For a non-HTTP port (a database, a debugger, SSH or another TCP service), the person uses `scion tunnel` instead, and the port must stay exposed (see Full apps: scion tunnel). ## Steps 1. Run the service on `127.0.0.1` on a free port (1024 or above; 9810 and 18380 cannot be exposed). Only loopback services can be exposed. 2. Run: `scion expose <port> --label "<what it is>"` 3. Check it works the way the person will use it (see What the proxy carries; for pages, references/web-apps.md). 4. Give the person the URL **exactly as printed**, including the trailing `/`. Do not hand out tokens, and do not build the URL by hand. ## Commands - `scion expose <port> --label "<what it is>"` exposes a port and prints its URL. Exposing a port that is already exposed succeeds and prints the same URL; it does not change the label (unexpose and expose again to relabel). - `scion expose --list` lists your exposed ports with their labels and URLs, and whether auto-expose is on. - `scion unexpose <port>` stops exposing a port. It succeeds if the port was not exposed. If auto-expose is on, a port that is still listening may be exposed again on its next scan. - An agent can have at most 10 ports exposed at once. Unexpose ports you no longer need. - These commands work only inside an agent with a Hub connection. ## What the proxy carries - HTTP requests of any method, with the path below the URL and the query string passed through to your service. Programs such as scripts and `curl` can call the URL too, with the Hub credentials of someone who has access to the agent. - Your service does not learn who is calling. Do not build a login on top of the link. - WebSockets and streamed responses (for example server-sent events) work only when the Hub runs its conduit transport, the same setting `scion tunnel` needs. Without it, a WebSocket request is refused with an error, each response is delivered whole once your service has finished it, and request bodies are limited to 32 MiB. - Your service must start answering within 60 seconds (the Hub's default), or the caller gets a timeout error. Without the conduit transport, the whole response must arrive within that time. - What a page opened in a browser through the link can load depends on the Hub: with its page view on, the page's relative URLs load; with it off, the page can only use what is inside it. See references/web-apps.md before serving a web page or app. ## Full apps: scion tunnel For a full multi-file web app, a dev server, or anything the proxy does not carry, the person can run `scion tunnel` on their own machine with the scion CLI, if their Hub has `scion tunnel` turned on and they have port access to the agent. Keep the port exposed with `scion expose <port>` (the tunnel only reaches exposed ports), then suggest: scion tunnel <agent> --port <port> The service then opens on a local port on their machine and works as it does inside the agent, for any protocol. See https://googlecloudplatform.github.io/scion/hosted/user/port-forwarding/ ## Web pages and apps For anything a person opens in a browser through the link, read references/web-apps.md: what loads with and without the Hub's page view, build settings, what does not work in a page, routing, and how to verify it honestly.