# Pipelines web spike (Route B) A throwaway, dependency-free browser client that proves the Pipelines **WebSocket protocol works from a web page** end to end. It is a spike, not a product: it renders a pipeline list and a run detail and nothing else. This directory is deliberately **separate from `android/`** and does not touch it. The Android app remains the Kotlin/Compose client. ## Why this route Two ways to expose the app as a web app were considered: - **Route A — Compose Multiplatform Web (WASM):** reuse the Kotlin protocol layer and Compose UI. Most code reuse, but needs the Kotlin/WASM toolchain. - **Route B — browser-native client (this spike):** a small JS app using the browser's native `WebSocket`. No toolchain, browser-native behaviour, and it can be verified against a live server immediately. This spike is Route B. The `android/` protocol models were the spec: the wire format, server-URL rules and reply matching here mirror `android/app/src/main/java/net/awan/pipelines/data/`. ## Safety (unchanged from the Android client) - **Trusted LAN/VPN only.** The Pipelines API has **no authentication** and is **not internet-safe**. Do not expose the server to untrusted networks. A web page widens that surface: any tab can open the socket. - **No secrets.** Nothing is stored except the server URL, in `localStorage`. - **No hardcoded server.** The URL is entered by the user; there is no default address baked in. ## Layout | File | Android counterpart | Notes | | --- | --- | --- | | `src/protocol.js` | `data/protocol/Message.kt` (constants) | types + `#success`/`#failure` | | `src/serverUrl.js` | `data/transport/ServerUrl.kt` | `validateServerUrl`, `resolveArtifactUrl` | | `src/client.js` | `data/transport/PipelinesClient.kt` | one reused socket, id matching, backoff. DOM-free | | `src/repository.js` | `data/PipelinesRepository.kt` | typed request builders | | `src/app.js` | `ui/**` | DOM UI: pipeline list + run detail | | `serve.mjs` | — | zero-dep static server | | `test/*.test.mjs` | `app/src/test/**` | `node --test` | | `test/smoke.mjs` | — | live end-to-end against a running server | `client.js` is DOM-free on purpose, so the smoke test drives the **same** transport module the page uses. ## Run it ```sh cd web node serve.mjs # http://127.0.0.1:8090/ node serve.mjs --host 0.0.0.0 # reachable from other devices (trusted LAN/VPN) ``` `serve.mjs` both serves the page and **proxies `/connect`** to the Pipelines server (`--pipelines 127.0.0.1:8080` by default), so the page and the WebSocket are one origin. The page defaults its URL field to `ws:///connect` (the proxy) — just press **Connect**. Nothing is hardcoded: the default is derived from wherever the page was loaded and can be overridden. ### Why the page cannot connect directly (`403`) `internal/server/websocket.go` calls `websocket.Accept(w, r, nil)` — `github.com/coder/websocket` — which **rejects an upgrade whose `Origin` host does not match the request `Host`**. A browser page served from `:8090` opening `ws://HOST:8080/connect` sends `Origin: http://HOST:8090` and is refused: ``` HTTP/1.1 403 Forbidden request Origin "HOST:8090" is not authorized for Host "HOST:8080" ``` A Node or `curl` client sends no `Origin` and is accepted — which is why the smoke test passes while a browser does not. The proxy sidesteps this by making the page same-origin and dropping the `Origin` header on the way through (the server has no authentication, so nothing is lost). Any web client that is served from a different origin than the Pipelines server hits this same 403. To open the page from another device, bind `--host 0.0.0.0` and use this machine's Tailscale/LAN address for the page only, e.g. `http://100.85.25.33:8090/`, then press Connect (the field already holds `ws://100.85.25.33:8090/connect`). Both hops are plaintext, so there is no mixed-content block; only do this on a trusted tailnet/VPN. ## Test it ```sh cd web node --test test/ # unit tests, no server PIPELINES_WS_URL=ws://127.0.0.1:8080/connect node test/smoke.mjs # live ``` `node --test` covers the ported URL validation/artifact resolution and the transport (id matching, serialization order, error replies, timeouts, not-connected guard, reconnect). `smoke.mjs` connects to a real server and runs `ping`, `list_pipelines`, `list_runs`, `get_pipeline`, `get_run`, and (when the newest run has artifacts) an artifact `HEAD`. ## Verification status Run on macOS with Node v26.9.0 against a live `pipelines` server on `ws://127.0.0.1:8080/connect`: - `node --test test/` → **20 tests, 0 failures.** - `node test/smoke.mjs` → **SMOKE PASS (6 checks)**: websocket connected, `ping -> pong`, `list_pipelines -> 14 pipelines`, `list_runs -> 189 runs`, `get_pipeline #1`, `get_run #189`. No artifact fetch (that run had none). - `node --check` parses every source and test file. - `serve.mjs` serves `/`, `index.html`, `styles.css` and each `src/*.js` with the right content type (200); `/favicon.ico` is 204; `/nope.js` is 404; with `curl --path-as-is` no raw `..` path escapes `web/` (traversal attempts either serve a file inside `web/` or 404). The cross-origin `403` and the proxy fix were verified on macOS against the live server (`ws://100.85.25.33:8080/connect`): - Direct handshake with `Origin: http://100.85.25.33:8090` → `HTTP/1.1 403 Forbidden` (`request Origin "100.85.25.33:8090" is not authorized for Host "100.85.25.33:8080"`); the same handshake without `Origin` → `101 Switching Protocols`. - Through the proxy (`:8090`) with the same browser `Origin` → `101 Switching Protocols`. - `PIPELINES_WS_URL=ws://100.85.25.33:8090/connect node test/smoke.mjs` → **SMOKE PASS (6 checks)** — a full request/reply session over the tunnel. **Not verified:** the rendered page itself. No desktop browser was connected to this session, so the DOM UI was not opened, clicked or screenshotted. `app.js` parses and its data path is exercised through the shared `client`/`repository`/ `serverUrl` modules, but its rendering and event wiring are unproven. Also unverified: `wss://`/TLS (no TLS server was available) and multiple concurrent browser tabs. ## Next step Before committing to a route, open `http://127.0.0.1:8090/` in a browser, connect to the running server, and confirm the list/detail flow. If Route A is chosen instead, the `data/`-layer mapping in the table above is the port checklist; the Android-API friction lives in the artifact viewer, navigation, lifecycle and `SharedPreferences` touchpoints (`android/README.md` documents them).