c7cc92382b
Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com> Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
259 lines
12 KiB
Markdown
259 lines
12 KiB
Markdown
---
|
|
id: "06-settings-surface"
|
|
title: "Reachability data layer and settings surface"
|
|
status: done
|
|
wave: 4
|
|
depends_on: ["04-reachability-api-and-events"]
|
|
plan: "plan.md"
|
|
requirements:
|
|
- REQ-EXECUTORS-SSH-REACHABILITY-001
|
|
- REQ-EXECUTORS-SSH-REACHABILITY-002
|
|
acceptance_criteria:
|
|
- AC-EXECUTORS-SSH-REACHABILITY-001.25
|
|
- AC-EXECUTORS-SSH-REACHABILITY-002.1
|
|
- AC-EXECUTORS-SSH-REACHABILITY-002.2
|
|
- AC-EXECUTORS-SSH-REACHABILITY-002.3
|
|
- AC-EXECUTORS-SSH-REACHABILITY-002.4
|
|
- AC-EXECUTORS-SSH-REACHABILITY-002.5
|
|
- AC-EXECUTORS-SSH-REACHABILITY-002.10
|
|
- AC-EXECUTORS-SSH-REACHABILITY-002.11
|
|
- AC-EXECUTORS-SSH-REACHABILITY-002.12
|
|
system_design:
|
|
- ../../specs/executors/system-design/ssh-reachability.md
|
|
- ../../specs/executors/system-design/ssh-reachability-surfaces.md
|
|
---
|
|
|
|
# Task 06: Reachability Data Layer and Settings Surface
|
|
|
|
## Summary
|
|
|
|
Add the client types, API calls, and store slice for reachability records, and
|
|
render one on the SSH executor settings page: state, probed host, failure
|
|
reason and message, consecutive-failure count, and the age of the last probe,
|
|
with a probe-now action. Localized in all five supported locales.
|
|
|
|
## In scope
|
|
|
|
- `SSHReachabilityRecord` in `lib/types/http-ssh.ts` mirroring the backend
|
|
shape, including `probing_enabled`, `probe_interval_seconds` (the
|
|
**effective**, clamped interval), and `updated_at` alongside `checked_at`
|
|
and `last_success_at`.
|
|
- `getSSHReachability`, `getSSHExecutorReachability`, and
|
|
`probeSSHExecutorReachability` in `lib/api/domains/ssh-api.ts`, following the
|
|
existing options-spread-then-required-fields ordering in that file.
|
|
- Settings slice state keyed by executor id, plus the
|
|
`executor.reachability.changed` WS handler that applies a pushed record. A
|
|
refetch racing a pushed event is reconciled by keeping whichever payload
|
|
carries the **later `updated_at`**, never `checked_at` — a
|
|
connection-configuration reset clears `checked_at` (it is `null`) while
|
|
still advancing `updated_at`, so reconciling on `checked_at` would make a
|
|
reset compare as older than the record it just invalidated and get
|
|
discarded, leaving a stale `reachable`/`unreachable` state showing for a
|
|
host the user just re-pointed. A `null` `updated_at` (the synthesized
|
|
never-probed shape) always loses to a real record.
|
|
- A `SSHReachabilityCard` rendering state, the host that was actually probed,
|
|
reason and message when `unreachable`, the consecutive-failure count, and
|
|
the age of the last completed probe; marking the result stale past three
|
|
intervals; stating plainly that periodic probing is off when
|
|
`probing_enabled` is `false`, rather than presenting a retained state as
|
|
current; and offering the probe-now action.
|
|
- Refetch on mount and on the configured interval (`probe_interval_seconds`,
|
|
not a constant) while the card is open, because a steady host publishes
|
|
nothing and `checked_at` would otherwise age in place. **No timer runs at
|
|
all when `probing_enabled` is `false`** — the card fetches once on open and
|
|
again after an immediate probe; reading a `0` effective interval literally
|
|
as a cadence would be a zero-delay refetch loop against a record known not
|
|
to be changing.
|
|
- A failed load reports that reachability is not known. It must never render
|
|
as `unreachable`.
|
|
- Mobile-viewport layout, and state exposed to assistive technology as text
|
|
rather than by color alone.
|
|
- Copy through `t()` in `executors.json` across `en`, `pt-pt`, `zh-cn`,
|
|
`zh-hk`, `zh-tw`, with the failure reason rendered as translated copy rather
|
|
than the raw token. Use `pnpm run i18n:zh-hant` for the Traditional Chinese
|
|
pair.
|
|
|
|
## Out of scope
|
|
|
|
- The pre-launch warning. Task 07 owns it. The task-card indicator is
|
|
deferred; see the requirement document's `## Out of scope`.
|
|
- Any backend file.
|
|
- Changing the existing connection, sessions, agent-readiness, or
|
|
task-dir-reclamation cards beyond mounting the new one.
|
|
- Any history, trend, or sparkline. One record per executor is all that exists.
|
|
|
|
## Acceptance
|
|
|
|
- The card renders every field the settings surface owes for each of the three
|
|
states, and a record older than three intervals renders as stale rather than
|
|
current.
|
|
- A pushed `executor.reachability.changed` updates the card without a reload
|
|
and without the card polling for it.
|
|
- A pushed record with a `null` `checked_at` but a newer `updated_at` (a
|
|
reset) replaces a stored `reachable`/`unreachable` record rather than being
|
|
discarded as stale.
|
|
- With `probing_enabled` false the card says periodic probing is off, runs no
|
|
refresh timer, and a load failure says reachability is not known — neither
|
|
renders as `unreachable`.
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
# From apps/ (once per fresh worktree):
|
|
pnpm install --frozen-lockfile
|
|
|
|
# From apps/web:
|
|
pnpm vitest run components/settings/ssh-reachability-card.test.tsx lib/state/slices/settings/settings-slice.test.ts lib/api/domains/ssh-api.test.ts
|
|
pnpm run typecheck
|
|
pnpm run lint
|
|
pnpm run i18n:check
|
|
pnpm run i18n:ratchet
|
|
```
|
|
|
|
## Files likely touched
|
|
|
|
- `apps/web/lib/types/http-ssh.ts`
|
|
- `apps/web/lib/api/domains/ssh-api.ts`
|
|
- `apps/web/lib/state/slices/settings/types.ts`
|
|
- `apps/web/lib/state/slices/settings/settings-slice.ts`
|
|
- `apps/web/lib/state/slices/settings/settings-slice.test.ts`
|
|
- `apps/web/components/settings/ssh-reachability-card.tsx`
|
|
- `apps/web/components/settings/ssh-reachability-card.test.tsx`
|
|
- `apps/web/components/settings/ssh-settings.tsx`
|
|
- `apps/web/src/locales/{en,pt-pt,zh-cn,zh-hk,zh-tw}/executors.json`
|
|
|
|
## Dependencies
|
|
|
|
Task 04. The record shape, the `probing_enabled` flag, and the change action
|
|
are that task's contract.
|
|
|
|
## Risks
|
|
|
|
- Translations gate the build: `check-i18n-keys.mjs` fails on a missing key, an
|
|
extra key, a dropped placeholder, or a value left identical to English. The
|
|
six reason tokens plus the state labels are twelve-plus keys across five
|
|
locales, so this is the largest single source of build failure in the task.
|
|
- The staleness threshold and the refresh cadence both depend on the effective
|
|
interval. The record carries it as `probe_interval_seconds`; use that value
|
|
rather than a constant, or both rules silently drift from the operator's
|
|
configuration.
|
|
- Reconciling on `checked_at` instead of `updated_at` is the one regression
|
|
that passes every test written against a normal probe sequence and only
|
|
fails on a reset, because a reset is the single write that advances
|
|
`updated_at` without advancing `checked_at`. Write the reconciliation test
|
|
around a reset payload specifically, not just a newer/older probe pair.
|
|
- `i18next/no-literal-string` is a lint error repo-wide and
|
|
`check-nonjsx-copy.mjs` scans non-JSX positions by exclusion. A reason-to-copy
|
|
lookup table written as a plain `.ts` map is exactly the shape that rule
|
|
catches.
|
|
|
|
## Parallelism
|
|
|
|
`sequential`
|
|
|
|
## Inputs
|
|
|
|
- System design, sections *API and event contracts* and *Frontend components*.
|
|
- `apps/web/AGENTS.md` for the store-slice and WS-hook conventions and the
|
|
"never fetch data directly in components" rule.
|
|
- `components/settings/ssh-agent-readiness-card.tsx` as the nearest existing
|
|
card shape.
|
|
- `docs/i18n.md` for the five-locale workflow.
|
|
|
|
## Results
|
|
|
|
Implemented under strict `/tdd` (RED confirmed before every GREEN
|
|
implementation):
|
|
|
|
- `SSHReachabilityRecord` (+ `SSHReachabilityState`/`SSHReachabilityReason`)
|
|
added to `apps/web/lib/types/http-ssh.ts`, mirroring the backend
|
|
`reachability.RecordDTO` wire shape used by both the GET responses and the
|
|
`executor.reachability.changed` WS payload.
|
|
- `getSSHReachability`, `getSSHExecutorReachability`, and
|
|
`probeSSHExecutorReachability` added to `lib/api/domains/ssh-api.ts`,
|
|
covered by `lib/api/domains/ssh-api.test.ts` (GET list, GET single with
|
|
executor-id URL-encoding, POST probe-now).
|
|
- A `sshReachability: { byExecutorId }` slice in the settings store
|
|
(`lib/state/slices/settings/{types,settings-slice}.ts`), reconciled on
|
|
`updated_at` — never `checked_at` — via `setSSHReachability`. A `null`
|
|
`updated_at` (the synthesized never-probed placeholder) always loses to a
|
|
record that carries a real timestamp; a first write for an executor is
|
|
always applied. Covered by 6 tests in `settings-slice.test.ts`, including
|
|
the reset case (`checked_at: null`, newer `updated_at`) that a
|
|
`checked_at`-based reconciliation would silently discard.
|
|
- `executor.reachability.changed` registered in `BackendMessageMap`
|
|
(`lib/types/backend.ts`) and wired in
|
|
`lib/ws/handlers/executors.ts` to call `setSSHReachability` directly, so a
|
|
pushed event and a card's own fetch share one reconciliation path.
|
|
- Adding `sshReachability`/`setSSHReachability` required updating both the
|
|
settings slice's own type file *and* the hand-written `AppState` type in
|
|
`lib/state/app-state-types.ts` (which does not derive from the slice types
|
|
by intersection) — missed on the first pass, caught by `pnpm run
|
|
typecheck`.
|
|
- `SSHReachabilityCard` (`components/settings/ssh-reachability-card.tsx`),
|
|
mounted in `SSHExecutorView`
|
|
(`app/settings/executors/ssh/[executorId]/page.tsx`) between
|
|
`SSHConnectionCard` and `SSHSessionsCard`, and exported from
|
|
`ssh-settings.tsx`. Fetches on mount through the store (never into
|
|
component-local-only state), so a live WS push and its own fetch/probe-now
|
|
results converge on the same rendered state. Renders state, probed host,
|
|
reason + message when `unreachable` (reason via a translated lookup, never
|
|
the raw token), consecutive-failure count, and the age of the last
|
|
completed and last successful probe. Marks a record stale past three
|
|
probe intervals (`isReachabilityStale`, a pure exported helper, covered by
|
|
2 direct unit tests plus integration coverage through the card). Refetches
|
|
on the record's own `probe_interval_seconds` (never a constant) while
|
|
probing is enabled, and arms no timer at all when `probing_enabled` is
|
|
false. A load failure with no prior record renders "not known" copy, never
|
|
`unreachable`. 12 tests in `ssh-reachability-card.test.tsx`, split across
|
|
4 `describe` blocks (rendering, live updates, refresh cadence,
|
|
errors/probe-now) to stay under the per-function line lint budget, cover:
|
|
per-state field rendering, staleness on/off, the live pushed-event update
|
|
(via a `PushReachability` test helper calling the same store action the WS
|
|
handler uses — the same pattern as the existing
|
|
`archive-confirmation-settings.test.tsx` "remote update" helper), the
|
|
reset-over-stored-record case, the probing-off no-timer guarantee (a
|
|
`setInterval` spy, filtering out React Testing Library's own internal
|
|
50ms polling interval), the enabled-cadence timer args, the load-failure
|
|
"not known" fallback, and the probe-now round trip.
|
|
- Twelve reachability keys (state labels, six reason tokens, staleness,
|
|
probing-off, probe-now, host/age/failure-count copy, load-failure copy)
|
|
added to `src/locales/en/executors.json`, hand-translated into `pt-pt` and
|
|
`zh-cn`, and propagated to `zh-hk`/`zh-tw` via `pnpm run i18n:zh-hant`
|
|
(which also incidentally re-derives unrelated already-translated `zh-hk`/
|
|
`zh-tw`/`pseudo` catalog entries outside the `executors` namespace from
|
|
current `zh-cn`/`en` source; those out-of-scope regenerated files were
|
|
reverted with `git checkout --` before committing, keeping this commit
|
|
scoped to the `executors` namespace this task owns).
|
|
- Followed the `ssh-agent-readiness-card.tsx` precedent for the card shape
|
|
(a `useReachabilityState` hook separating fetch/refresh/probe-now from a
|
|
thin view component) and the `ssh-connection-card.test.tsx` /
|
|
`archive-confirmation-settings.test.tsx` precedent for real React Testing
|
|
Library component coverage (`StateProvider` + `useAppStoreApi`) rather than
|
|
pure-helper-only tests — justified here because the acceptance criteria are
|
|
about store-integration behavior (live WS update without reload, timer
|
|
arm/no-arm, reconciliation-through-render) that a pure helper test cannot
|
|
exercise.
|
|
|
|
Verification (all from `apps/web`, after `pnpm install --frozen-lockfile`
|
|
from `apps/`):
|
|
|
|
```bash
|
|
pnpm vitest run components/settings/ssh-reachability-card.test.tsx lib/state/slices/settings/settings-slice.test.ts lib/api/domains/ssh-api.test.ts
|
|
# 3 files, 32 tests passed
|
|
|
|
pnpm run typecheck
|
|
# clean
|
|
|
|
pnpm run lint
|
|
# clean (0 warnings; fixed sonarjs/no-duplicate-string, max-lines-per-function,
|
|
# and no-nested-ternary findings during the refactor step)
|
|
|
|
pnpm run i18n:check
|
|
# ✓ all 6 sub-checks pass; pt-pt/zh-cn/zh-hk/zh-tw complete, pseudo in sync
|
|
# (135 pre-existing unrelated orphan-key warnings, unchanged by this task)
|
|
|
|
pnpm run i18n:ratchet
|
|
# ✓ 0 added + 9 modified file(s) clean; guard allowlist intact
|
|
```
|