Files
alan abd696b0d9 feat(app): add native Settings connection and workspace screen
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.
2026-10-21 17:39:18 +01:00

6.9 KiB
Raw Permalink Blame History

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

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.