web: README for the finished client, not the spike
Describes what the client is, how to run and test it (OS-assigned smoke port, gitignored captures), the module areas, and keeps the 403/proxy explanation that justifies serving the page from serve.mjs.
This commit is contained in:
+96
-127
@@ -1,75 +1,95 @@
|
||||
# Pipelines web spike (Route B)
|
||||
# Pipelines web client
|
||||
|
||||
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.
|
||||
The browser client for the Pipelines server: the Android app's feature set,
|
||||
rendered for the web, against the same WebSocket protocol and the same words.
|
||||
`web/PARITY.md` is the acceptance checklist and the single source of truth for
|
||||
what is done; this file covers how to run, test and verify it.
|
||||
|
||||
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/`.
|
||||
- **Dependency-free.** Plain ES modules in the browser, hand-written CSS. No
|
||||
framework, no bundler, no build step, no npm install.
|
||||
- **Browser-native transport.** The page opens one `WebSocket` to `/connect`,
|
||||
matched by request id, with the same server-URL rules as the Android client.
|
||||
- **Verified in a real browser.** UI claims are backed by PNGs captured from
|
||||
headless Chrome against a live server (`test/ui-smoke.mjs`); a unit test alone
|
||||
never marks a parity row done.
|
||||
|
||||
## 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.
|
||||
**not internet-safe**. Do not expose the server or this page to untrusted
|
||||
networks.
|
||||
- **No secrets.** The page stores only the server URL and its own small UI
|
||||
preferences (sort/filter choices, attention dismissals, device-local chat
|
||||
overrides) in `localStorage`; nothing is sent anywhere but the configured
|
||||
server.
|
||||
- **No hardcoded server.** The URL is entered by the user, prefilled from the page
|
||||
origin, and can be overridden.
|
||||
|
||||
## 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)
|
||||
node serve.mjs # http://127.0.0.1:8090/ (proxies /connect -> 127.0.0.1:8080)
|
||||
node serve.mjs --host 0.0.0.0 # reachable from other devices (trusted LAN/VPN)
|
||||
node serve.mjs --port 8095 --pipelines 127.0.0.1:8080
|
||||
```
|
||||
|
||||
`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.
|
||||
The page prefills its URL field with `ws://<this page's host><port>/connect` — the
|
||||
proxy — so the usual flow is: open the page, press **Connect**. Nothing is baked
|
||||
in.
|
||||
|
||||
### Why the page cannot connect directly (`403`)
|
||||
On a deployment where ntfy already uses 8090, pick another port for the page
|
||||
(e.g. `--port 8095`). The page is a foreground Node process, not a service.
|
||||
|
||||
`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:
|
||||
## 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 # protocol, live
|
||||
node test/ui-smoke.mjs --out /path/to/captures # browser, live, screenshots
|
||||
```
|
||||
|
||||
`node --test` covers the ported URL rules, the transport, and the pure feature
|
||||
logic (filters, sorting, diffs, graph layout, markdown, chat folding, routing,
|
||||
attention, alerts). It needs no server.
|
||||
|
||||
`smoke.mjs` drives the real client against a running server: `ping`,
|
||||
`list_pipelines`, `list_runs`, `get_pipeline`, `get_run`, artifact `HEAD`.
|
||||
|
||||
`ui-smoke.mjs` starts `serve.mjs` on an **OS-assigned free port** (so concurrent
|
||||
checks never collide), launches the installed Chrome headless, drives the real
|
||||
page and writes PNGs. **That is the UI evidence**: a review reports capture paths,
|
||||
not what it thinks would render. Set `CHROME_PATH` if Chrome is not at the
|
||||
default macOS location, and use `--port`/`WEB_UI_PORT` to pin a port.
|
||||
|
||||
Captures are deliberately gitignored: they are review evidence, not source, and
|
||||
keeping them out of the tree keeps a delivery checkout clean.
|
||||
|
||||
## Layout
|
||||
|
||||
| Area | Where |
|
||||
| --- | --- |
|
||||
| Wire protocol, URL rules | `src/protocol.js`, `src/serverUrl.js` |
|
||||
| Transport (DOM-free, reused by the smoke test) | `src/client.js` |
|
||||
| Typed requests | `src/repository.js` |
|
||||
| Feature logic and models | `src/runs.js`, `src/runDetail.js`, `src/changes.js`, `src/artifacts.js`, `src/pipelines.js`, `src/templates.js`, `src/graph.js`, `src/chat.js`, `src/markdown.js`, `src/search.js`, `src/attention.js`, `src/actions.js`, `src/connection.js`, `src/settings.js`, `src/notify.js`, `src/runEvents.js`, `src/routes.js` |
|
||||
| Shell and views | `src/app.js` (boot, state, navigation, render dispatch), view modules under `src/views/` |
|
||||
| Styling | per-area stylesheets linked from `index.html` |
|
||||
| Server + `/connect` proxy | `serve.mjs` |
|
||||
| Tests | `test/*.test.mjs`, `test/smoke.mjs`, `test/browser.mjs`, `test/ui-smoke.mjs` |
|
||||
| Acceptance gate | `PARITY.md` |
|
||||
| Working map | `AGENTS.md` |
|
||||
|
||||
Keep `client.js` DOM-free: the smoke test and the page must drive the same
|
||||
transport module. Every server-derived string is set with `textContent`, never
|
||||
`innerHTML` — the transcript and diffs are untrusted model output.
|
||||
|
||||
## Why the page connects through `serve.mjs`, not the server directly
|
||||
|
||||
`internal/server/websocket.go` calls `websocket.Accept(w, r, nil)`, which rejects
|
||||
an upgrade whose `Origin` host does not match the request `Host`. A page served
|
||||
from port 8090 opening `ws://HOST:8080/connect` is refused with **403**:
|
||||
|
||||
```
|
||||
HTTP/1.1 403 Forbidden
|
||||
@@ -77,77 +97,26 @@ 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.
|
||||
protocol smoke can pass while a browser cannot. `serve.mjs` therefore also proxies
|
||||
`/connect`, dropping `Origin`, so the page and the socket are one origin.
|
||||
|
||||
**Do not "fix" this by relaxing the server's Origin check** — that check is the
|
||||
only thing between a random web page and an unauthenticated control API. Keep the
|
||||
proxy.
|
||||
|
||||
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.
|
||||
machine's LAN or Tailscale address for the page (e.g.
|
||||
`http://100.85.25.33:8095/`), then press Connect. Both hops are plaintext, so
|
||||
there is no mixed-content block; only do this on a trusted tailnet/VPN.
|
||||
|
||||
## Test it
|
||||
## Verification notes
|
||||
|
||||
```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.
|
||||
- The browser is the gate, never a phone or emulator. No ADB, no device.
|
||||
- Artifact URLs resolve against the configured server (`resolveArtifactUrl`); the
|
||||
page opens them in a tab rather than embedding an Android WebView.
|
||||
- Where the browser genuinely cannot match Android (system-tray notifications need
|
||||
a secure context; `pipelines://` links become URL routes), the parity row says
|
||||
so instead of pretending otherwise.
|
||||
- Feature checks that create server state (a chat, a pipeline) either use a
|
||||
scratch server or the server's explicit ephemeral flag, so verification never
|
||||
leaves clutter in the operator's lists.
|
||||
|
||||
Reference in New Issue
Block a user