abd696b0d9
Add the Settings destination under lib/features/settings with an editable websocket endpoint, truthful connection states, one ping per connect/mount, workspace validation and persistence under new feature-owned keys. Material and Cupertino controls, wrapping copy at large text, pending ping state, and isolated probe tools plus widget/unit coverage.
131 lines
6.9 KiB
Markdown
131 lines
6.9 KiB
Markdown
# N1 Settings
|
||
|
||
The Settings destination for the Flutter client: server connection and the
|
||
server-side workspace, in native Material controls and Cupertino controls on iOS.
|
||
|
||
## Files
|
||
|
||
- `lib/features/settings/settings_screen.dart` — `SettingsScreen`.
|
||
- `lib/features/settings/settings_controller.dart` — draft/validation, shared
|
||
client actions, ping-on-connected, workspace persistence, dispose ownership.
|
||
- `lib/features/settings/settings_store.dart` — `SettingsStore`,
|
||
`SharedPreferencesSettingsStore`, `MemorySettingsStore`.
|
||
- `lib/features/settings/settings_copy.dart` — the web/Android words, workspace
|
||
validation, connection-card lines.
|
||
- `lib/features/settings/default_endpoint.dart` — same-origin web default.
|
||
- `lib/features/settings/settings_controls.dart`, `settings_sections.dart`,
|
||
`settings_trust_warning.dart`, `settings_layout.dart`, `settings_keys.dart`.
|
||
- `lib/features/settings/settings.dart` — public barrel for manager registration.
|
||
- `test/features/settings/*` — copy, persistence, controller and widget tests.
|
||
- `tool/settings_probe.dart`, `tool/settings_probe_server.dart`,
|
||
`tool/settings_probe_capture.dart` — isolated browser fixture/capture entry.
|
||
|
||
## Manager registration
|
||
|
||
```dart
|
||
import 'package:pipelines_app/features/settings/settings.dart';
|
||
|
||
SettingsScreen(client: sharedPipelinesClient)
|
||
// optional: initialEndpoint: Uri?, store: SettingsStore?, ping: PingCallback?
|
||
```
|
||
|
||
`SettingsScreen` takes the shell's single `PipelinesClient`. It subscribes to
|
||
`client.states`, sends `ping` once per connected transition (plus once when the
|
||
screen opens against an already-connected client), and offers Connect /
|
||
Disconnect / Reconnect. It never calls `client.dispose()` and never opens a
|
||
connection on construction, so registering/rebuilding the screen cannot start a
|
||
second socket or tear down another feature's connection.
|
||
|
||
While connected it shows `Server build {version} ({commit})` and
|
||
`Server time {time}` from the ping reply. Until that reply arrives the card says
|
||
`Loading server details…`, so a request in flight is never reported as an
|
||
unavailable value. Only a completed reply that omits a field renders `Server
|
||
build unavailable` / `Server time unavailable`; a failed ping renders one
|
||
explicit `Server details unavailable: …` line instead of repeating both
|
||
"unavailable" lines. No zero or stale value is substituted. Disconnect and
|
||
reconnect clear the previous server's details.
|
||
|
||
Connection card copy and state lines follow `web/src/settings.js` and
|
||
`SettingsScreen.kt`: `Not connected`, `Connecting (attempt N)…`, `Connected`,
|
||
`Disconnected` + reason + `Retrying with backoff…`, plus the trusted-LAN/VPN
|
||
warning. A dropped socket's attempt/backoff state comes from the transport.
|
||
|
||
Workspace validation is the web rule: blank is untouched (no error), a relative
|
||
path is rejected, Save is enabled only for a trimmed absolute path. The saved
|
||
line is `Saved workspace: /path` or `Saved workspace: (none)`, and the helper
|
||
states that the path is an absolute directory on the execution server, not the
|
||
phone's storage. Save failures keep the previous saved value and say so.
|
||
|
||
## Persistence
|
||
|
||
`shared_preferences` keys are owned by this feature:
|
||
|
||
- `pipelines.next.serverUrl.v1`
|
||
- `pipelines.next.workspace.v1`
|
||
|
||
No legacy Android/web key (`server_url`, `workspace`,
|
||
`pipelines.web.serverUrl.v2`, `pipelines.web.workspace.v1`, notification keys)
|
||
is read, migrated or written. The endpoint is validated and persisted before
|
||
`client.connect` is attempted, matching the web's write-before-connect
|
||
behaviour; a value that fails to connect stays stored. When the store write
|
||
itself fails, the screen still connects and says the value applies to this
|
||
session only. Credentials in a URL are rejected before any write or socket.
|
||
Only those two strings are stored; nothing else.
|
||
|
||
The web `shared_preferences` implementation may namespace its keys internally;
|
||
the logical keys above are the independent feature keys and tests assert the
|
||
legacy keys stay untouched.
|
||
|
||
## Web default endpoint
|
||
|
||
`defaultServerUrl()` returns `''` on native builds. On web it derives
|
||
`ws(s)://<page host[:port]>/connect` from `Uri.base` (`kIsWeb`, no `dart:html`),
|
||
so the screen starts from the configurable same-origin proxy and no server host
|
||
or production endpoint is baked into the app. The field remains editable and
|
||
only the validated value is persisted.
|
||
|
||
## Verification
|
||
|
||
- `flutter test test/features/settings` — 39 tests pass (copy/default endpoint,
|
||
persistence keys/legacy isolation, controller connect/validation/ping/
|
||
disconnect/reconnect/backoff/dispose ownership/workspace errors, Material and
|
||
Cupertino widgets, invalid URL, pending vs completed-empty ping, failed-ping
|
||
single line, field labels in semantics, narrow + 2× text with full labels and
|
||
helper copy, unmount ownership).
|
||
- `flutter test` (full app) — 52 tests pass.
|
||
- `flutter analyze` — no issues; `dart format --set-exit-if-changed` clean on the
|
||
19 Dart settings/test/tool files.
|
||
- `flutter build web` (main) and `flutter build web -t tool/settings_probe.dart`
|
||
— both built.
|
||
- Real browser evidence from an isolated loopback probe server (`/connect`
|
||
answers `ping` with `probe-1.2.3`/`abc1234`/time), headless Chrome over CDP:
|
||
`settings-idle`, `settings-connected`, `settings-validation` (clicked Connect
|
||
after an `http://` draft), `settings-workspace` (typed `/srv/pipelines`,
|
||
clicked Save), `settings-dark`, `settings-ios`, `settings-narrow` (390×844,
|
||
1.6× text). See `public/settings-captures/manifest.md`.
|
||
- Fix verification with a 6 s delayed pong: at 1.5 s the card shows
|
||
`Connected` + `Loading server details…` (no "unavailable"), and after the pong
|
||
it shows the real build/time. At 320×700/2× and 390×844/2× the full
|
||
`Server URL`/`Workspace path (on the server)` labels and the complete helper
|
||
and error sentences render (no ellipsis or line cap). See
|
||
`public/settings-fix-captures/manifest.md`.
|
||
- The 20 candidate paths are new and currently **untracked** (`??`, none
|
||
ignored); landing must `git add` them. The candidate is left uncommitted per
|
||
the stage instruction.
|
||
|
||
## Gaps / not done
|
||
|
||
- Notifications are not part of this screen yet. The queue item names them, but
|
||
the task scope here was connection/workspace and the project has no
|
||
notification plugin; adding one needs a dependency decision.
|
||
- No Templates card: navigation into the templates feature is shell/feature
|
||
registration work owned elsewhere.
|
||
- No protocol-mismatch warning (the web page shows one); it needs a shared
|
||
protocol-version constant not present in the app yet.
|
||
- Mobile builds/devices and the real production server were not used. The
|
||
Cupertino rendering is shown through the web probe with an iOS platform theme,
|
||
not on an actual iOS device.
|
||
- The probe's `connected` capture is an automatic fixture connect; validation
|
||
and workspace-save captures use actual browser clicks/typing. The main web
|
||
entry (`lib/main.dart`) is still the scaffold and was not modified.
|