6.9 KiB
Pipelines web client
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.
- 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
WebSocketto/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
- Authenticated browser proxy. Pages, assets, artifacts, and
/connectrequire a signed session cookie. The proxy refuses to start without its configured password/secret file. Never disable authentication on a real service. - Private control APIs. Pipelines and harness APIs have no authentication. Keep them on loopback; expose only the authenticated proxy on a trusted LAN/VPN. Use TLS/VPN for remote access, not an Internet-facing raw API.
- 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 for development
For normal installation, use ./install. The following
commands are for a separate development process with an existing web-auth file
(PIPELINES_WEB_AUTH_FILE, default ~/.config/pipelines/web-auth.json). They do
not create an account or configure autostart.
cd web
node serve.mjs # http://127.0.0.1:8090/ (proxies /connect and /artifacts/ -> 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
The page's Server URL field (in Settings → Connection) prefills with
ws://<this page's host><port>/connect — the proxy. Press Connect there the
first time; the endpoint is then remembered and re-opened on later loads. Nothing
is baked in.
On a deployment where ntfy already uses 8090, pick another port for the page
(e.g. --port 8095). These commands are foreground processes; managed startup is
described in the installation guide.
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 # 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 and /artifacts/ 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
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
protocol smoke can pass while a browser cannot. serve.mjs therefore proxies /connect (dropping Origin) so the page and
the socket are one origin. It proxies /artifacts/ for the same reason: artifact
URLs resolve against the configured server, which in a proxied deployment is the
page's own origin, so the gallery's images, the viewer, session.html and
downloads would otherwise 404 while the WebSocket worked.
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 LAN or Tailscale address for the page (e.g.
http://100.85.25.33:8095/), then press Connect in Settings. Both hops are plaintext, so
there is no mixed-content block; only do this on a trusted tailnet/VPN.
Verification notes
- 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.