bd09c55c47
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.
142 lines
6.5 KiB
Markdown
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).
|