Files
pipelines/web

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
test/browser.mjs — zero-dependency Chrome DevTools driver
test/ui-smoke.mjs UI review captures live browser check; writes screenshots
PARITY.md android/ feature set the acceptance checklist
AGENTS.md android/AGENTS.md the area map for this workstream

client.js is DOM-free on purpose, so the smoke test drives the same transport module the page uses.

Run it

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://<this page's host>/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

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: wss:///TLS (no TLS server was available) and multiple concurrent browser tabs.

Rendered-page verification (2026-10-19)

The gap above is closed: node test/ui-smoke.mjs launches the installed Chrome headless through the zero-dependency DevTools driver (test/browser.mjs), serves the page, connects it through the proxy, and captures what actually rendered. Against the live server it rendered 29 pipelines, opened a pipeline detail and a run detail, and wrote three PNGs. Flow: web → connect → pipeline list → pipeline detail → Runs tab → run detail, all with real clicks.

cd web
node test/ui-smoke.mjs --out /tmp/web-ui     # needs a running Pipelines server

Next step

Feature parity with the Android app is tracked in PARITY.md; that table is the acceptance gate (a row is only done with a captured browser E2E). Work is planned as small items, one per row or tight group of rows.