140 lines
7.2 KiB
Markdown
140 lines
7.2 KiB
Markdown
# 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 `WebSocket` to `/connect`,
|
|
matched by request id, with the same server-URL rules as the Android client.
|
|
- **Reported chat metrics.** The top-right **Chat information** button opens
|
|
output tokens/sec, total tokens, context usage/window and reported USD cost
|
|
without taking space from the conversation. Unreported metrics are
|
|
unavailable, not zero or a subscription-price estimate.
|
|
- **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 `/connect`
|
|
require 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`](../docs/install.md). 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.
|
|
|
|
```sh
|
|
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](../docs/install.md).
|
|
|
|
## 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` 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.
|