Files
pipelines/web/README.md
T
alan 4721b8af10 web: prepare the client workstream for feature parity
Adds the area map (web/AGENTS.md), the parity acceptance checklist
(web/PARITY.md, one row per Android feature), and a zero-dependency browser
verification harness: test/browser.mjs drives the installed Chrome over the
DevTools protocol, and test/ui-smoke.mjs serves the page, connects it through
its own /connect proxy, and captures the rendered pipeline list, a pipeline
detail and a run detail as PNGs.

This closes the spike's 'rendered page not verified' gap (29 pipelines rendered,
three captures) and gives review stages real UI evidence without a phone or an
npm install. Hosting is unchanged: serve.mjs stays alongside the Pipelines
server and proxies /connect.
2026-10-19 02:13:39 +01:00

154 lines
7.0 KiB
Markdown

# 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
```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://<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
```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:** `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.
```sh
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.