Files
pipelines/web/README.md
T
alan bd09c55c47 Merge lane-go: titles, verdicts, human stage, line result format, stale-client guard
Integrates nine commits of reviewed work from the lane-go branch after the
automated resolver failed on this merge five times (each attempt dying on the
malformed-result defect whose fix is contained in this same merge).

Integration decisions:
- Search: kept main's shipped design (Store.Search + SearchResponse.Results) and
  dropped lane-go's parallel, older attempt (an unused Message.Matches field, an
  absent runs.search, and two partial TUI plumbing blocks). lane-go itself did not
  compile: protocol.SearchMatch was undefined and model.go referenced searchNav,
  requestSearch and applyRunNav, which exist nowhere. Those partial TUI blocks are
  removed; the queued TUI omni-search item will implement the surface properly on
  main's design.
- Both sides' additions are kept where they are independent: run titles and
  provenance, the human decision stage and its CLI/TUI surface, the derived stage
  verdict, the stale-client guard, the line-oriented result format, and main's
  search command.
- The search key's help label is now "/ omni search"; the two tests asserting the
  old label are updated rather than the label reverted.
- docs/cli.md and the packaged operations reference carry both sides' text.

Verified: go build ./... , go vet ./... and the full go test ./... suite pass.
2026-10-16 22:21:43 +01:00

142 lines
6.5 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 |
`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:** 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).